ros2_console_tools

ros2_console_tools is a terminal-first toolbox for ROS 2 runtime inspection, visualization, and operator workflows.

Current package release: 1.5.3.

Quick Start

Build the package:

colcon build --packages-select ros2_console_tools
source install/setup.bash

Launch a tool:

ros2 run ros2_console_tools node_commander
ros2 run ros2_console_tools topic_monitor

Toolset

ROS graph and runtime tools

Binary	Purpose	Highlights
node_commander	Browse the live ROS 2 graph.	Node list, graph interface details, parameter service reachability, launcher hub for other ROS tools.
parameter_commander	Inspect and edit parameters on a selected node.	Namespace-folded parameter tree, scalar and array editing, descriptor and constraint display.
topic_monitor	Inspect topics and monitor live traffic.	Rate and bandwidth stats, decoded message view, topic search, braille-capable numeric plots, embedded visualizers for map, image, joystick, IMU, and LaserScan topics.
service_commander	Inspect and call ROS 2 services.	Generic introspection-based request/response view, scalar request editing, interactive calls.
action_commander	Inspect ROS 2 actions.	Protocol endpoint breakdown, server/client node lists, action graph visibility.
log_viewer	Read /rosout in the terminal.	Source filtering, severity filtering, text filter, detail popup, local source-code inspection when paths are available.
diagnostics_viewer	Monitor /diagnostics and /diagnostics_agg.	Status list, severity filtering, key/value detail view, search.
tf_monitor	Inspect the live TF tree.	Transform freshness, stale highlighting, relative transform popup between selected frames.
urdf_inspector	Inspect robot_description.	Tree view of links and joints, details pane, XML inspection popup with syntax highlighting.

Visualization tools

Binary	Purpose	Highlights
map_viewer	Render nav_msgs/msg/OccupancyGrid in the terminal.	Rotated map rendering, costmap-style block default, braille Unicode mode, legend and monochrome controls.
image_viewer	Render sensor_msgs/msg/Image in the terminal.	Fast mono shade default, optional color and braille modes, zoom, pan, invert, frame freeze.
joy_viewer	Visualize sensor_msgs/msg/Joy in the terminal.	Axis bars, button states, generic stick pads, frame freeze.
imu_viewer	Visualize sensor_msgs/msg/Imu in the terminal.	Angular velocity and acceleration bars, orientation readout, orientation-derived tilt, covariance state.
laser_scan_viewer	Visualize sensor_msgs/msg/LaserScan in the terminal.	Braille top-down polar scan plot on Unicode terminals, point-glyph mode, range zoom, invalid range markers, frame freeze.

Common Interaction Model

Most tools share the same ncurses foundation and keybinding style:

• F10: exit
• Esc: back or close the current popup
• Enter: inspect, open, or focus the selected item
• Alt+S: incremental search where list search is supported
• F4: refresh the current scope
• Alt+T: toggle the embedded terminal pane where available

The exact action keys vary by tool, but the overall interaction model is intentionally consistent across the package.

Architecture

Most tools follow the same structure:

• public header: include/ros2_console_tools/<tool>.hpp
• backend implementation: src/<tool>_backend.cpp
• screen/controller: src/<tool>_screen.cpp
• thin executable wrapper: src/<tool>.cpp

Shared TUI infrastructure lives in:

• include/ros2_console_tools/tui.hpp
• src/tui.cpp

That shared layer provides:

• ncurses session setup and teardown
• theme and color roles
• status and help bars
• popup help bars
• layout helpers
• incremental search helpers
• an embedded PTY-backed terminal pane

ROS-backed tools use rclcpp::Node backends for subscriptions, clients, graph queries, and cached runtime state.

Notable Integration Points

• node_commander is the main ROS entry point and launcher hub.
• topic_monitor can open map_viewer for occupancy grids, image_viewer for image topics, joy_viewer for joystick topics, imu_viewer for IMU topics, and laser_scan_viewer for LaserScan topics.

Notes

• service_commander is currently strongest for scalar request editing; richer structured editing still needs dedicated UI work.
• action_commander is currently inspection-focused and does not yet provide full interactive goal execution.

Changelog

1.6.0

• Added shared Unicode braille rendering helpers for terminal visualizations.
• Added braille render modes for map_viewer, laser_scan_viewer, image_viewer, and numeric plots in topic_monitor.
• Kept map_viewer on costmap-style block rendering by default, with braille available through render mode switching.
• Changed image_viewer Auto mode to prefer fast mono shade rendering on Unicode terminals.
• Added image_viewer color decoding for RGB/BGR/RGBA/BGRA/YUY2 streams and a C toggle for optional colorized rendering.
• Preserved existing ASCII and block/point glyph modes as selectable fallbacks.