---json
{"name": "Scenarios dashboard"}
---
====== ROS 2: optional scenarios dashboard ======

Use the browser guide to learn commands, inspect interfaces and follow the ROS graph. Run the commands in the console; **the driver, acquisition and RViz work independently of the dashboard**.

===== Scenario view =====

{{ :axiom:ros2:ros2-thermal-graph-7e5bec9.png?nolink&760 |Thermal sensor grid through the visualiser to RViz}}

//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 [[:axiom:ros2:getting_started|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:

<code bash>
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
</code>

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:

<code bash>
ssh -N -L 8083:127.0.0.1:8083 USER@ROS_HOST_IP
</code>

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 =====

^ Tab ^ Use it for ^
| **Available** | The interface catalogue: what the packages can expose and how topics, services and nodes relate. |
| **Running graph** | Nodes and endpoints discovered in this ROS session, including publisher/subscriber arrows. |
| **Commands** | Console commands grouped by purpose. Copy a command, then run it in a terminal. |
| **Scenarios** | Workflows from setup to cleanup. Start with one expanded step or choose Expand all. |

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 [[:axiom:ros2:automatic_startup|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**:

<code bash>
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'
</code>

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 [[:axiom:ros2:output_topics|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 [[:axiom:ros2:sensors_and_boards#updating_an_existing_installation|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 [[:axiom:ros2:standard_messages|Standard messages and mappings]] to inspect their fields and units, and [[:axiom:ros2:foxglove#illuminance_and_scalar_plots|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 =====

{{ :axiom:ros2:ros2-overview-graph-7e5bec9.png?nolink&760 |Current Axiom topic families and ROS consumers}}

//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:

<code bash>
sudo apt install tmux
bash scripts/ros_tmux.sh
</code>

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.

^ Pane ^ Suggested use ^
| Terminal 1 | Host driver launch. |
| Terminal 2 | Service calls and sensor checks copied from the dashboard. |
| Terminal 3 | Dashboard process, or the visualiser for the selected scenario. |
| Terminal 4 | RViz or extra ROS commands. |

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:

<code bash>
bash scripts/ros_tmux.sh
</code>

For copying output and refreshing reused panes, see [[:axiom:ros2:getting_started#use_tmux_for_the_ros_consoles|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 [[:axiom:ros2:thermal_camera|thermal-camera walkthrough]]. Other Axiom scenarios cover accelerometer data, distance-sensor hot swapping and multiple boards. Back to [[:axiom:ros2:start|Axiom with ROS 2]].

===== Optional Marty scenarios =====

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

<code bash>
# 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
</code>

The combined build needs ''python3-venv''/''python3-pip'' as in [[:martyv2:ros2:getting_started|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 [[:axiom:ros2:servo_slider|the core servo-slider demo]]. The [[:axiom:ros2:shake_demo|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 [[:martyv2:ros2:onboard_pi_camera|Onboard Pi, camera and RViz]] for its two-machine setup, matching ROS domain, different camera/telemetry QoS and restart commands. Axiom's [[:axiom:ros2:lighting|lighting panel]] is another independent RViz consumer. The full-robot simulation, Axiom hip preview and physical camera view remain separate workflows.