Architecture¶
This page is a tour of the codebase, in the order you'd encounter the layers when tracing a single keystroke from the user to a ROS message.
┌──────────────────────────────────────────────────────────────────────┐
│ Keyboard │
│ │ │
│ ▼ │
│ Textual main loop (asyncio) ── never calls rclpy synchronously │
│ │ panels read O(1) snapshots on timers; slow calls → workers │
│ ▼ │
│ Widgets ────► panels (TopicsPanel, PlotPanel, GraphListPanel …) │
│ │ │
│ ▼ │
│ RosBackend (thread-safe facade) │
│ ├── GraphMonitor thread ── collects the graph once per period │
│ ├── executor thread ────── SingleThreadedExecutor.spin() │
│ │ raw subscriptions: store bytes only │
│ └── worker threads ─────── service calls, params, action goals, │
│ domain switch / reconnect │
│ ▼ │
│ DDS / wire │
└──────────────────────────────────────────────────────────────────────┘
Threads and who does what¶
Textual's event loop is single-threaded asyncio; anything that blocks it freezes the UI. Rosight keeps rclpy off that loop entirely:
| Thread | Work | Talks to the UI via |
|---|---|---|
| Textual loop | rendering, key handling, timers | — |
Executor (rosight-ros-executor) |
SingleThreadedExecutor.spin(); subscription callbacks |
Subscription fields under a lock |
Graph monitor (rosight-graph-monitor) |
list_topics/nodes/services/actions once per ui.discovery_period |
immutable GraphSnapshot |
Workers (asyncio.to_thread / run_worker) |
service calls, parameter get/set, action goals, :domain, :reconnect, publish |
awaited results; call_from_thread for live action feedback |
Raw subscriptions and lazy decoding¶
Subscriptions are created with raw=True. The executor callback
(Subscription.ingest_raw) only
- ticks the
RateMonitor, - adds
len(bytes)to theBandwidthMonitor(exact size, no work), - stores the bytes and the receive time, and appends them to a bounded history ring (100 messages / 16 MB).
Nothing is deserialized there. When a widget wants the message it calls
Subscription.snapshot(), which runs deserialize_message once per
received message and caches the result; repeated reads are free and a
100 Hz topic shown at 4 Hz is decoded 4 times a second, not 100.
On rclpy builds without raw / event_callbacks support the backend falls
back step by step (raw + QoS events → raw → decoded + events → decoded); in
decoded mode the size estimate is throttled to once per second.
Incompatible-QoS events are recorded on the subscription and surfaced in
the Topics panel.
Graph discovery¶
GraphMonitor (ros/discovery.py) collects the whole graph on its own
thread and publishes a frozen GraphSnapshot with a generation counter
that only increases when the content changes. The status bar and every
list panel read ros.graph_snapshot() in O(1) and skip re-rendering when
the generation is unchanged. r wakes the monitor for an immediate
collection. Generation 0 means "nothing discovered yet" and drives the
discovering… empty state.
ROS layer¶
rosight.ros is importable without rclpy; heavy imports happen in
RosBackend.start().
| Module | Purpose |
|---|---|
backend.py |
RosBackend (lifecycle, subscriptions, publish, services, parameters, action goals, health) and Subscription (raw ingest, lazy decode, history, QoS events). The only module that imports rclpy. |
discovery.py |
GraphMonitor thread and GraphSnapshot. |
qos.py |
Plain-data QoSSpec + negotiate() to derive a subscriber QoS that matches every publisher. |
stats.py |
RateMonitor / BandwidthMonitor — thread-safe sliding windows. |
introspection.py |
iter_fields(msg) walks any ROS message (or duck-typed object) and yields FieldEntry(path, value, type, is_numeric, is_array_numeric). |
yaml_msg.py |
Message ↔ YAML for the publish / call / goal forms (rosidl_runtime_py when available). |
Utilities¶
utils/datatable.py—sync_table()updates aDataTablein place (only changed cells; rebuild only when rows are added/removed, keeping the cursor on the same key) andfit_last_column().utils/fuzzy.py— subsequence, multi-term filter used by every panel.utils/ringbuffer.py—RingBuffer/TimedRingBufferfor plot data.utils/path.py— dotted/bracketed field paths, parsed once and cached.utils/formatting.py—format_bytes,format_rate,sparkline, …
Widgets¶
Each panel is a self-contained Textual container with its own
compose(), BINDINGS and DEFAULT_CSS. Cross-panel actions go through
RosightApp (add_plot_series, goto_topic, goto_service,
unsubscribe_topic, export_path).
GraphListPanel(widgets/_base.py) — Nodes, Services and Actions: filterable table over one kind of graph entity, empty states, generation skipping. Subclasses only describe columns and the detail pane.MessageTree— any message as a tree. Same structure → labels updated in place (changed values flash); new structure → rebuild that keeps expanded nodes and the cursor path. Search (/,n,N) and copy (y,Y).PlotView— wrapsplotext; time-series and snapshot subplots on a 15 Hz tick.YamlFormScreen— modal YAML editor with inline validation, shared by publish, service call, action goal and parameter set.CommandPalette+CommandSuggester—:commands with completion and history.
Configuration and state¶
config.py defines a strict dataclass schema loaded from TOML; unknown
keys are dropped for forward compatibility. Runtime state (theme, last
tab, filters, plot series, command history) lives in a separate
state.toml so the hand-written config is never rewritten.
Lifecycle¶
RosightApp.on_mount
├── ros.start() → executor thread + graph monitor start
├── restore state.toml → tab, filters, plot series (plot resubscribes
│ until its topics are discovered)
└── set_interval(...) → status ticker (also watches executor health)
q / :quit
├── confirm if a bag is recording / playing
└── save state.toml
RosightApp.on_unmount
├── BagsPanel stops children (SIGINT → SIGTERM → SIGKILL, bounded)
└── ros.stop() → graph thread, executor.shutdown(timeout),
spin-thread join(timeout): never hangs
If ros.start() raises RosUnavailable the app stays up in degraded mode
with a notification. If the executor thread dies later, the status bar
turns red and :reconnect restarts the backend.
Testing strategy¶
- Pure-python tests — utilities, QoS, stats, introspection, YAML conversion, config / state files.
- Fake-node backend tests — subscription fallback ladder, raw ingest
and decode counts, QoS events, bounded shutdown, service timeouts,
action goals (fake
rclpy.action), real child processes for bag stop. - Headless UI tests — boot the app with
App.run_testand drive keys: panels, forms, navigation, palette completion, state restore. - Help sync —
test_help_in_syncfails if a binding or palette command is added without being documented in the help overlay. - ROS integration job (CI) — the whole suite plus a headless launch
inside
ros:humbleandros:jazzycontainers with real rclpy.
Extending Rosight¶
To add a new panel:
- Create
src/rosight/widgets/foo_panel.py. If it lists a kind of graph entity, subclassGraphListPanel; otherwise a TextualVertical. - Register it in
RosightApp.composeinside theTabbedContentblock and add a number-key binding. - Keep rclpy out of the widget: add a
RosBackendmethod, and run anything that can block in a worker. - Document its keys in
widgets/help_screen.py(the help-sync test will remind you) and add tests undertests/.
See development.md for the full dev loop.