Metadata-Version: 2.5
Name: ros2-term
Version: 0.2.0
Summary: A terminal UI for inspecting ROS2 topics and nodes
Project-URL: Homepage, https://github.com/bigdiehl/ros2-term
Project-URL: Repository, https://github.com/bigdiehl/ros2-term
Project-URL: Issues, https://github.com/bigdiehl/ros2-term/issues
Author-email: Spencer Diehl <docdiehl@gmail.com>
License: MIT
License-File: LICENSE
Keywords: robotics,ros2,terminal,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: numpy<2.0
Requires-Dist: pyopengl>=3.1
Requires-Dist: pyqtgraph>=0.13.7
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: textual-plotext>=1.0
Requires-Dist: textual<9,>=8.2.3
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: isort; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Description-Content-Type: text/markdown

# ROS2 Explorer TUI

A Terminal User Interface (TUI) app for exploring ROS2 nodes, topics, services, actions, and message types.

## Requirements

- ROS2 Humble, Iron, or Jazzy already installed on system
- pipx (`sudo apt install pipx`)

## Installation

Source your ROS2 installation first, then install with pipx:

    source /opt/ros/humble/setup.bash   # or iron, jazzy, etc.
    pipx install --system-site-packages ros2-term

`--system-site-packages` lets the apps use ROS2's apt-installed Python dependencies.

Then run:

    ros2-term        # Explorer
    ros2-log-view    # Log viewer

**Note:** ROS2 must be sourced in any shell where you run `ros2-term`.

The image and point cloud viewers (`o`) use Qt from the system. ROS desktop installs
have it; otherwise: `sudo apt install python3-pyqt5 python3-pyqt5.qtopengl`. The `.deb`
installs it (Recommends). Without it, everything else works.

### Debian package (Ubuntu 24.04 / Jazzy)

Each [GitHub release](https://github.com/bigdiehl/ros2-term/releases) also has a `.deb`:

    sudo apt install ./ros2-term_0.2.0_all.deb

It bundles its own Textual, so it doesn't need pipx. Use one install method, not both:
whichever is first on `PATH` wins (pipx's `~/.local/bin` usually comes first).

### Command Line Options

    ros2-term [--profile NAME] [--continue] [--refresh-rate SECONDS]

- `--profile NAME` - Load specific profile on startup
- `--continue` - Resume last used profile
- `--refresh-rate SECONDS` - Set refresh interval (default: 2.0)
- `--help` - Show available profiles and config location


## ROS2 Log Viewer

`ros2-log-view` is a companion app for viewing `/rosout` log messages, with node and
severity filtering, regex search, and color rules. See [README-log-view.md](README-log-view.md).

## Troubleshooting

If you have multiple Python versions installed and see import errors related
to ROS2 packages, force pipx to use the system Python explicitly:

    pipx install --system-site-packages ros2-term --python $(which python3)

## Development

Dev setup, tests, demo system, and design notes: [doc/](doc/README.md).

## Features

- Tree views for nodes/topics with expandable details; flat lists of services, actions, types
- **Topic watching** (`w`): a propeller turns with each topic's traffic; `z` adds its live rate
- **Topic inspection**: Hz (`h`), delay (`d`), echo (`e`), sample (`s`); histograms of period and delay (`g`)
- **Viewers** (`o`): image and point cloud topics in their own windows (pyqtgraph; needs Qt, see below)
- **Profile system**: Auto-save/load watched topics and views
- Clickable links between entities (node → topic → type)
- History navigation (`b`/`f`)
- Search with regex support
- Native `rclpy` integration (no subprocess overhead)

## Keyboard Shortcuts

| Key | Action | Visible in Footer |
|-----|--------|-------------------|
| `?` | Show help screen | ✓ |
| `w` | Watch/unwatch topic | ✓ |
| `W` | Unwatch all topics | |
| `z` | Toggle live rate next to watched topics | |
| `h` | Show Hz for topic | ✓ |
| `d` | Show delay (header.stamp to arrival) | ✓ |
| `g` | Histogram of periods (Hz) / delays | |
| `o` | Open image / point cloud viewer | |
| `e` | Echo topic (continuous) | ✓ |
| `s` | Sample topic (single msg) | ✓ |
| `a` | Toggle array visibility | ✓ |
| `r` | Reload current view | ✓ |
| `b` | Navigate back in history | |
| `f` | Navigate forward in history | |
| `v` | Toggle verbose mode | |
| `c` | Collapse all tree nodes | |
| `p` | Save profile | |
| `1` | View nodes | |
| `2` | View topics | |
| `3` | View services | |
| `4` | View actions | |
| `5` | View message types (of discovered topics) | |
| `q` | Quit | |

## Navigation

- Arrow keys navigate tree, Enter expands/collapses
- Click entity names in info panel to navigate
- `b`/`f` for history navigation
- Tree state preserved when switching views
