ros2_tui

A powerful Terminal User Interface (TUI) for monitoring and managing ROS2 topics and parameters in real-time.

Screenshots

Namespace-aware topic tree with live publisher/subscriber counts, Hz, and delay.	Fuzzy search to instantly filter topics across the graph.	Per-topic detail view with Hz/delay history charts and live message echo.

Prerequisites

• ROS2 installed and sourced
• ros2 topic and ros2 param commands available in your shell

Installation

From pypi

pip install ros2-tui

From crates.io

cargo install ros2_tui

From Source

git clone https://github.com/TillBeemelmanns/ros2_tui.git
cd ros2_tui
cargo build --release

The binaries topics and params will be available at target/release/.

Try it in Docker (no local ROS2 needed)

A self-contained ROS2 environment (Humble by default) with dummy publishers and parameters is provided for quickly trying the TUIs:

./docker/run.sh topics   # build the image and launch the topics TUI
./docker/run.sh params   # launch the params TUI
./docker/run.sh shell    # drop into a ROS2 shell with the binaries on PATH

ROS_DISTRO=lyrical ./docker/run.sh topics   # use another distro, e.g. Lyrical

The container starts the ros2_tui_test dummy publishers automatically, so both TUIs come up populated with topics and parameters.

Topics TUI (topics)

Highlights

• 📊 Real-time Hz/Delay monitoring backed by streaming ros2 topic hz / delay
• 🌳 Namespace-aware topic tree with collapsible groups and instant search
• 🎯 Watch-only metrics so large graphs stay responsive and low overhead
• 🎨 Status indicators, Bollinger-band charts, and debug logging for on-call triage

Usage

# Start monitoring with default settings
topics

# Custom refresh rate (topics list updates every 5 seconds by default)
topics --refresh 10

Toggling a row with Enter starts Hz/Delay measurement. Unwatched topics stay lightweight, ensuring responsive navigation even with hundreds of topics.

Navigation & Controls

• ↑/↓ or j/k move between topics; ←/→ or h/l collapse and expand namespaces
• Enter toggles watching on the focused topic or expands/collapses a group
• d opens the detail view, where Tab switches between the info and echo panes; c collapses/expands all groups at once
• s toggles simulation time when measuring delay metrics
• F4 opens live search with auto-expansion; Space, r, or F5 refresh immediately
• q, Esc, or Ctrl+C quit; --verbose writes detailed logs to topics_debug.log

Command-Line Options

• --refresh <SECONDS> – Topic list refresh cadence (default: 5)
• --detail-refresh <SECONDS> – Legacy detail polling interval (still accepted)
• --no-initial-fetch – Skip the initial ros2 topic list call
• --help, --version – Standard metadata flags

Architecture Highlights

• Background workers keep ros2 topic list -v, ros2 topic hz, and ros2 topic delay streaming without blocking the UI
• Crossbeam channels drive a non-blocking event loop that renders at ~5 FPS and processes input instantly
• Watched topics maintain FIFO histories (including std dev) to power Bollinger-band charts and statistical readouts
• Selective monitoring conserves system resources by spawning measurement processes only when needed

Params TUI (params)

Highlights

• 🧭 Node/namespace browser that mirrors ros2 param list hierarchies
• 🔄 Live value polling keeps displayed values fresh without manual refreshes
• ✏️ In-terminal editing with type validation plus YAML dump/load workflows
• 🧰 Built-in search, success/error banners, and contextual help overlays

Usage

# Parameter dashboard with 5 second refresh
params

# Faster poll rate for parameters
params --refresh 2

The app groups dotted parameter names into expandable namespaces so large graphs stay navigable. Value edits, dumps, and loads run through the ROS2 CLI and report their outcome inline.

Navigation & Controls

• ↑/↓ or j/k move through nodes and parameters; ←/→ or h/l collapse/expand namespaces
• ? opens the help overlay; F4 enters search mode with persistent filtering
• Space, r, or F5 refresh on demand; Esc exits dialogs, cancels search, or quits

Parameter Actions

• s edits the selected parameter (array values are normalised for ROS2 compatibility)
• d dumps the current node to YAML via ros2 param dump
• Ctrl+l loads YAML into the active node using ros2 param load
• Inline success/error banners acknowledge operations and fade automatically

Command-Line Options

• --refresh <SECONDS> – Parameter polling cadence (default: 5)
• --no-initial-fetch – Skip the initial ros2 param list scan
• --verbose / -v – Emit detailed logs to params_debug.log
• --help, --version – Standard metadata flags

Architecture Highlights

• A primary watcher repeatedly shells out to ros2 param list, building a ParamTree that mirrors node hierarchies
• A secondary watcher streams value lookups to populate the table without blocking the UI thread
• Dump/load/edit workflows wrap the ROS2 CLI while scheduling delayed refreshes to reflect state changes
• All ROS2 interaction happens on background threads, keeping the Crossterm-driven interface responsive under load

Development

Building

cargo build --release

Testing

cargo test
cargo check

Before Pushing

Check formatting

cargo fmt --all -- --check

Lint code

cargo clippy --all-targets --all-features -- -D warnings

Release Safety Check

Configure Git once so the bundled pre-push hook runs before release pushes:

git config core.hooksPath .githooks

When you push a tag such as v0.3.0, the hook calls scripts/check-release-version.sh and verifies the tag matches the Cargo.toml version. The push is rejected if they diverge, keeping release tags in sync with the crate metadata.

Comparison with Other Tools

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by turm - A TUI for the Slurm Workload Manager
• Built with ratatui - A Rust library for building rich terminal interfaces

Roadmap

Planned features, improvements, and fixes are tracked in ROADMAP.md.