Scenario view

Reference data flow for the thermal scenario. The dashboard pairs each console command with an explanation and expected result; the live interface supplies discovered sensor paths.

Build and open the guide

First complete Install and connect so the ROS installation and local machine/board configuration are ready. The dashboard packages are optional examples in the same repository. If rebuilding while drivers or visualisers are running, stop their acquisition and processes first, then restart them after the build.

On the Linux ROS host, use the checkout's actual absolute path in place of /path/to/axiom-ros2 below. Run pwd at the repository root to find it:

cd "/path/to/axiom-ros2"
source scripts/setup_env.sh
rosdep install --from-paths src examples/scenarios-dashboard/src --ignore-src -r -y
colcon build --base-paths src examples/scenarios-dashboard/src --symlink-install
source scripts/setup_env.sh
bash examples/scenarios-dashboard/scripts/dashboard.sh

Open http://127.0.0.1:8083 in a browser on that Linux machine, or use the port in machine.env. The guide wrapper loads the same machine settings and board file as the consoles. Starting it does not start Axiom drivers or request measurements. The wrapper stays in the foreground; leave that terminal running and use another terminal or pane for ROS commands. The web server listens on the host's loopback address by default. To view it from another computer while keeping that default, use an SSH tunnel from the viewer computer:

ssh -N -L 8083:127.0.0.1:8083 USER@ROS_HOST_IP

Replace USER and ROS_HOST_IP with your SSH login and the ROS host's address. Open http://127.0.0.1:8083 on the viewer computer while the tunnel runs. If you changed the dashboard port, substitute that port in both the tunnel and URL. Viewing from the ROS host itself needs no tunnel.

The example has COLCON_IGNORE so a default recursive build skips it. Supplying examples/scenarios-dashboard/src explicitly includes it. The dashboard's package name is axiom_marty_dashboard, and the RViz example package is axiom_marty_demo; neither requires a Marty for Axiom-only scenarios.

Dashboard tabs

The board selector scopes command examples to a configured namespace. Read each recipe before running it: example sensor paths, USB ports or Wi-Fi addresses must match your hardware. The USB + Wi-Fi scenario uses its own generated configuration with automatic connection and acquisition; the normal automatic startup also connects and acquires by default. Recipes that teach manual connection must explicitly set all three startup flags false. Do not run it alongside another driver connected to either board. Before running that scenario's configuration recipe, set your endpoints in the same terminal that will run the recipe:

export AXIOM_ROS_TRANSPORT=serial
export AXIOM_ROS_SERIAL_PORT='/dev/serial/by-id/REPLACE_WITH_USB_AXIOM'
export AXIOM_WIFI_IP='REPLACE_WITH_WIFI_AXIOM_IP'

The recipe writes ~/usb_wifi_axioms.yaml with axiom/front and axiom/rear namespaces. Review that file before launching it; the recipe does not automatically reuse the two endpoints from your usual boards.yaml. Click ⓘ beside a command or interface for its purpose, arguments or message/service details.

Sensor paths in copied commands

Current sensor measurements use /<board>/<model>_b<bus>_<hex-address>/<output>, for example /robot/front/lsm6ds_b1_76a/data_raw. Per-sensor commands use the same root followed by /commands/<command>. The interface catalogue uses MODEL, BUS and ADDRESS placeholders; copy actual paths from the board's inventory or running graph.

When one matching live sensor is available, measurement recipes select its canonical public_topics path. Multiple matching sensors require choosing a sensor explicitly. Optional aliases are not counted as extra sensors. The Device command topics recipes use live command_topics entries to generate ros2 topic pub –once commands: Float64 radians for angles and ColorRGBA for RGB/pixels. The Device commands recipes follow the remaining acknowledged services in commands. Former angle/colour services are removed; rebuild the optional dashboard packages after updating. See output contracts for units, enable and acknowledgement behaviour. Existing board-level connection and acquisition service names remain unchanged.

Aliases in generated configurations use source: data_raw, source: range or source: image as appropriate. Use the migration steps for existing local board files and rebuild the optional packages after pulling updates.

The static reference catalogue and prepared scenarios illustrate selected interfaces, not every descriptor-defined scalar. Running graph can show actual Illuminance/scalar publishers even when there is no dedicated scenario for them. Use Standard messages and mappings to inspect their fields and units, and Foxglove scalar plots to visualise numeric readings. The host driver processes optional descriptor mappings; the dashboard does not enable or configure them.

Read the graph

Reference graph for the current naming scheme. Use Running graph in the dashboard to see your own active publishers and subscribers.

The graph shows ROS discovery. A visible node or topic is not proof that a command succeeded or measurements are valid. Check service responses and use ros2 topic echo to confirm messages. A subscriber can keep a topic name present even when its sensor publisher disappears.

Configured boards can appear before their drivers start. Driver offline means no driver has been discovered for that namespace; it does not mean the USB cable or Wi-Fi hardware has been tested. Connected describes the running driver's reported state.

Four console panes with tmux

From a normal terminal at the repository root:

sudo apt install tmux
bash scripts/ros_tmux.sh

The shared helper is in scripts and works with the core packages. It opens four consoles and loads the configured ROS environment in new panes. Start the discovery launch yourself; it connects and acquires automatically unless the selected configuration disables those defaults. Manual teaching recipes explicitly disable the three startup flags before using connection and acquisition services.

If a thermal scenario needs both a marker visualiser and RViz, keep the dashboard in an extra outer terminal and use the four panes as shown in the RViz walkthrough.

Press Ctrl+b, release it, then an arrow to switch panes, z to zoom or d to detach. To return, rerun:

bash scripts/ros_tmux.sh

For copying output and refreshing reused panes, see tmux setup and controls.

For cleanup, stop viewers or echoes first, call each driver's stop-acquisition and disconnect services while that driver is still running, then stop the drivers and dashboard with Ctrl+C. A Start from scratch control depends on an optional workstation reset adapter and is not part of the standard Linux setup.

The Axiom · thermal camera + RViz scenario implements the thermal-camera walkthrough. Other Axiom scenarios cover accelerometer data, distance-sensor hot swapping and multiple boards. Back to Axiom with ROS 2.

Optional Marty scenarios

Axiom-only scenarios do not require a Marty. For the combined examples, install the separate marty-ros2 checkout beside axiom-ros2 and follow its firmware/connection instructions. From the Axiom repository root, include both repositories in the build:

# Load the same ROS distribution and workspace used by both drivers.
source scripts/setup_env.sh
# Install dependencies for the core, optional examples and sibling Marty checkout.
rosdep install --from-paths src examples/scenarios-dashboard/src ../marty-ros2/src --ignore-src -r -y
# Install the Python environment tools for the combined build.
sudo apt install python3-venv python3-pip
# Keep the build environment outside either source checkout.
MARTY_BUILD_VENV="$HOME/.venvs/axiom-marty-ros"
/usr/bin/python3 -m venv --system-site-packages "$MARTY_BUILD_VENV"
# Activate it and install MartyPy plus the build entrypoints.
source "$MARTY_BUILD_VENV/bin/activate"
python -m pip install -r ../marty-ros2/requirements.txt colcon-common-extensions
# Build through that Python so the Marty executable uses the correct interpreter.
python "$(command -v colcon)" build --base-paths src examples/scenarios-dashboard/src ../marty-ros2/src --symlink-install
# Load the resulting overlay before starting the guide or either driver.
source scripts/setup_env.sh

The combined build needs python3-venv/python3-pip as in Marty setup. Keep that virtual environment available for its built executable; rosdep alone does not install MartyPy. If Marty's driver already runs on a Pi, do not launch a second physical driver on the workstation.

The architecture has one host ROS driver for Axiom and a separate host ROS driver for Marty. A demo adapter or application consumes their selected topics and uses Marty's own motion interfaces when needed. The dual-accelerometer view combines two IMU inputs; it does not make Axiom firmware control Marty or fuse their poses. Their display frames are illustrative layouts, not measured mounting transforms. Use the actual Marty connection settings and review motion requests before sending them.

For a standalone servo connected to Axiom, a full Marty and its driver are unnecessary: use the core servo-slider demo. The movement teaching platform is another separate workflow and manages its own applications; it is not started by this scenarios guide.

Marty on a Pi and a camera viewer

Marty's driver can instead run on its onboard Pi while Axiom's driver runs on the workstation. The Pi's camera video takes a separate TCP path to a workstation receiver, which publishes /marty/camera/image_raw for RViz. This does not require this dashboard or a second Marty driver. Follow Onboard Pi, camera and RViz for its two-machine setup, matching ROS domain, different camera/telemetry QoS and restart commands. Axiom's lighting panel is another independent RViz consumer. The full-robot simulation, Axiom hip preview and physical camera view remain separate workflows.