Flightops user guide

Use Flightops to inspect a running ROS 2 system, start and inspect a launch file, or review saved results in a desktop browser. This guide takes you through those tasks. AI assistance is optional.

New to Flightops? Install the beta, then follow your first live session. No running ROS system? Try the recording quickstart with the sample Nav2 recordings that ship with Flightops.

Find the task you need

Install the beta

Flightops is in beta (0.2.0b1) for invited ROS 2 teams. There is one archive for Ubuntu 22.04 with ROS 2 Humble and one for Ubuntu 24.04 with ROS 2 Jazzy, both x86_64. Flightops does not install ROS. Follow installation, then activate this device once:

flightops license activate

Activation needs the internet and the key from your beta email. See activate this device for what it asks and what the license covers. Use a laptop or desktop terminal at least 120 columns by 36 rows. In the terminal, press ? for the available controls; flightops --help lists the commands. What is in the beta lists its known limits.

Run your first live session

Goal: see a harmless ROS node, close Flightops, and reopen it while the node keeps running. You need Flightops and ROS installed, plus the ROS demo_nodes_cpp package for this example. If it is unavailable, use a node from your own system and substitute its name below.

1. Start a node in terminal A

On Ubuntu 22.04 with Humble:

source /opt/ros/humble/setup.bash
ros2 run demo_nodes_cpp talker

On Ubuntu 24.04 with Jazzy, use this block instead:

source /opt/ros/jazzy/setup.bash
ros2 run demo_nodes_cpp talker

Expected: the talker prints messages. Leave terminal A running.

2. Check Flightops in terminal B

Open a second terminal. Source the same ROS installation as terminal A. If you have not activated this device yet, run flightops license activate first (details):

source /opt/ros/humble/setup.bash
export PATH="$HOME/.local/bin:$PATH"
flightops doctor

For Jazzy, replace the first line with source /opt/ros/jazzy/setup.bash. If your nodes come from a built workspace, also source its install/local_setup.bash before running doctor. This is a ROS overlay.

Expected: doctor reports the ROS environment, discovery, terminal, and writable session storage. An idle system can have zero nodes; in this example you should see the talker after discovery completes.

If it fails, use the recovery table before continuing. If your normal ROS terminal sets ROS_DOMAIN_ID or RMW_IMPLEMENTATION, use matching settings in terminal B. See ROS domain and RMW for these terms.

3. Open Flightops and find the talker

In terminal B:

flightops

1. Press 1 for Health and check the node and topic counts under System at a glance.
2. Press 4 for Nodes and look for /talker.
3. Press 3 for Topics and look for /chatter.
4. Press ? to see the available controls. Close help with Esc.

Expected: the node and topic appear. If discovery is still catching up, wait a few seconds and press r in Health. If they remain absent, compare with ros2 node list --no-daemon in a separate shell with the same environment.

4. Close, reopen, and finish

1. In Flightops, press q to close the view.
2. Check terminal A. The talker should still be printing messages.
3. In terminal B, run flightops attach to reopen observation.
4. Confirm the talker appears, then press q again.
5. In terminal A, press Ctrl+C to stop the example talker.

Expected: attached nodes survive closing Flightops. flightops and flightops attach open the same observation mode. Reopening restores view preferences for this environment and collects fresh observations.

Launch a system

Goal: let Flightops start a launch file and inspect its output. You need a launch file that works in your sourced ROS environment. The package and file names below are placeholders; replace them with your own.

1. Choose an installed or local launch file

For a launch file installed in a ROS package:

flightops launch my_robot bringup.launch.py use_sim_time:=true

For a file in your project, run from the directory containing launch/:

flightops launch ./launch/robot.launch.py use_sim_time:=true

Python, XML, and YAML ROS 2 launch files are supported. Pass each launch argument as NAME:=VALUE. Quote an argument if its value contains spaces.

Optional startup options go before launch or attach. For example:

flightops --project ~/ros2_ws/src/my_robot launch my_robot bringup.launch.py

2. Inspect startup

1. In Health, read the problems list, then the launch state and graph counts under System at a glance.
2. Press L to open the owned launch log.
3. Read the error or startup messages. Press Esc to close the log. The launch log guide explains search and filters.
4. Use Nodes, Topics, and Graph to inspect what appeared.

Expected: you see the launch process state and its output. If launch fails, keep the printed log path and the session's launch.json.

A visible node means it was discovered. It does not establish that the robot is ready. Without declared readiness checks, readiness remains unknown. A passing declared check confirms its specific observation; overall robot readiness still remains unknown because Flightops cannot prove that the observed entity belongs to this launch. Health's System at a glance and the L log header therefore show unknown (declared checks passed; not a readiness claim) beside checks: passed.

3. Stop or launch again

Close the log or help panel, then press q or Ctrl+C.

Expected: Flightops stops the launch process tree it started. Nodes started elsewhere remain under their original owner's control. Flightops first sends SIGINT, as Ctrl+C does in ros2 launch, and allows up to 6 seconds for a clean shutdown, one second more than ros2 launch waits by default. Only then does Flightops send SIGTERM, followed by SIGKILL if needed. Closing the terminal window or losing an SSH connection also stops the owned launch and any recording it owns.

Attach and launch keep separate default sessions, so flightops opens a fresh attach session that observes the current system. To return to this launch's retained record and log, reopen its session. Run flightops launch ... explicitly when you want to start the launch again. Reopening a saved session never repeats a launch.

Inspect the terminal views

Start with Health, then choose the view for your question. The views rail on the left shows each view's key and a badge, such as the number of problems. The terminal's ? help lists the controls for the current view.

Some views require a project, saved evidence, or an enabled recording/playback workflow. An empty view does not by itself mean the application has failed. The advanced guide covers those workflows.

Start from Health

Health (1) lists what needs attention, most severe first:

• Launch evidence: a failed or exited launch, the first error line and child failures from the retained log, and failed declared checks.
• Graph checks: seven of onscope's 16 doctor detectors run on every capture without extra ROS calls. They find incompatible QoS, a missing /clock publisher, topics without a publisher, one name under two namespaces, namespaced TF topics, frames with two parents, and unusual topic names. An eighth, sim_time_mismatch, runs when fresh use_sim_time values were read from the nodes; it reports nodes that disagree on simulation time.
• Rate checks: when a readiness file declares an expected rate for a topic, Health reports sampled rates below the declared minimum or above the declared maximum.

Select a problem to read its evidence, a likely fix, and a ros2 command that checks it. y copies that command; Enter opens the topic or frame it names, and Backspace returns. A graph snapshot shows likely causes, not proof. onscope's other detectors need the ROS environment report, a live delivery probe, or a single-topic diagnosis, so Health lists them as not run; use onscope doctor for those. Time sources of nodes that were not read, live message delivery, and the ROS environment are not checked here. Problems describe the current capture only.

Health also lists sampled received rates (with the declared range when a readiness file uses schema /1), how many nodes answered the use_sim_time read, and the processes of an owned launch with their exit codes. Rates are one-second samples at the Flightops observer, not a measurement of the publisher.

Press : to jump to any view, problem, topic, node, or frame by name, or to run an action such as refresh.

Find an item and read its details

1. Open Topics (3) or Nodes (4).
2. Press /, type part of the name, then press Enter to finish filtering.
3. Use ↑/↓ or j/k to select an item.
4. Press Tab to move between the list and details.
5. Press Esc outside filter editing to clear the filter.

During filter editing, Esc ends editing. Clear a filter before concluding that an expected item is missing. Use Enter to follow a selected connection and Backspace to return where the view offers that action.

In Health, r refreshes observations and reruns the graph checks. In Project, r refreshes project declarations and g runs a configured check when enabled. Read the current view's help before using an action key.

Investigate a concrete fault

Follow the Nav2, Panda, and Go2 examples for screenshots, commands, observed failures, and verification steps.

Close and reopen a session

A session stores view preferences, observations, and references to retained evidence for a project and ROS environment. It is not a running copy of your robot system.

By default, sessions live under ${XDG_STATE_HOME:-$HOME/.local/state}/flightops. One process can write a session at a time. To use a known session or start a separate one:

flightops --session-dir ./my-session attach
flightops --new-session attach

Keep the session and original evidence files if you need to return to them. If another terminal holds the session, close it or choose a new session. See session troubleshooting.

Reopen a launch session

Attach and launch keep separate default sessions, so a plain flightops after a launch opens a fresh observation session. To return to a launch's retained record, declared-check results, and log, reopen its session directory explicitly. The directory is easiest to find if you choose it when you launch:

flightops --session-dir ./robot-session launch my_robot bringup.launch.py

Press q to stop the launch. Later, reopen that session:

flightops --session-dir ./robot-session attach

Run the reopen command on the same host and from the same directory as the launch. Use the same --project (if any) and the same ROS environment: sourced setup files, domain, middleware and discovery settings, and Gazebo partition. Flightops then reopens the session read-only for the launch: it leaves the launch record unchanged, shows the retained launch state, declared-check results, and log, and adds new observations. It starts no launch and takes ownership of no process. If the working directory, project, or environment differs, Flightops leaves the launch's records intact. It opens a separate sibling session named DIR-<key>/default instead, prints a note naming both directories before the terminal opens, and repeats that note under SESSION in Health (1) under System at a glance, where Launch reads none · no owned launch in this session. --new-session always starts a fresh session.

For a launch in a default session, open Capture (9) before quitting. Its Runtime details list the directory as session directory. If a launch fails, the log and launch.json paths that Flightops prints are inside that directory.

Review saved results

Goal: make an offline desktop report from a saved Flightops JSON result. You need a supported result file; an arbitrary JSON file or MCAP recording is not a result input. ROS and AI are not required.

1. Generate and open the report

Replace ./result.json with your saved result path:

flightops results ./result.json --open

Expected: Flightops prints the generated HTML path and asks your default browser to open it. If no browser opens, open the printed file manually. The report needs no web server.

Without -o, the report is written next to the first input with .flightops.html in place of its extension, here ./result.flightops.html. Running the command again regenerates that file from the saved JSON.

To choose a new output path explicitly:

flightops results ./result.json -o ./review.html --open

Flightops never overwrites an explicit -o path; choose a new filename for another report. It also refuses an output that is a symlink or one of the input files. See supported result types and limits if an input is refused.

2. Read and retain the evidence

1. Check the result's outcome, recorded inputs, and observation limits.
2. Open referenced artifacts when you need the underlying evidence.
3. Keep the source JSON and those artifacts with the report.

Press Ctrl K in the report to jump to another result by name. The report opens in the dark theme; the theme button switches to light and remembers the choice.

A saved pass describes the recorded check. It does not establish the current state of a robot. Missing, partial, or refused evidence must keep its stated limits when you explain the result.

Optional sample: the results tutorial opens a sample incident JSON that ships with the offline documentation. The recording quickstart creates a result from the sample Nav2 recordings. Both show the commands and what to expect.

Work with recordings

An MCAP file holds recorded messages. A result JSON holds a tool's analysis of those messages. Analyze the recording first, then open its result.

splashdown --help lists the recording commands. A recording query's outcome and complete fields say whether it covered the requested window. Retain those fields when making a claim.

Use optional AI assistance

Goal: connect an assistant, explicitly enable it, and ask about selected evidence. You can use the live and saved-result workflows without AI.

1. Run flightops ai setup and follow the connection wizard.
2. Run flightops ai status to inspect local connection status.
3. If you want to test the connection, run flightops ai test.
4. Run flightops --ai to enable the configured connection for this session.
5. In the terminal, press A, attach the evidence you want to discuss, and review the request before sending it.

Expected: setup and enabling are separate actions. ai status makes no provider call. ai test sends a synthetic greeting; provider tests and assistant requests can incur usage. Check what will be sent during review.

For a step-by-step first question, use the AI setup tutorial and using the assistant. The ChatGPT account route is a preview. It has additional runtime, Linux bubblewrap, sign-in, and connection checks. Sign-in alone does not prove that a model request works.

Jev evidence priority and offline selector comparisons are optional. The Jev and assistant requests have separate reviews. Verify any explanation against the original evidence before changing your system; an assistant answer is not a measured result.

Solve common problems

Start with flightops doctor for live startup and discovery problems. Find your symptom below, perform the first check, then use the linked procedure if it remains unresolved.

To report a problem, write to beta@flightops.dev (see feedback and support). Include the exact command, the error, the relevant log path, flightops doctor output, flightops --version, your Ubuntu and ROS versions, the ROS domain, and the terminal size. Remove credentials and private data before sharing.

Continue with a deeper workflow

The advanced guide explains the component commands and workflow boundaries. The documentation index lists all component and technical references.