Axiom with ROS 2
Connect Axiom to a Linux computer over USB or Wi-Fi and use its sensors in ROS 2. The host driver runs on that computer, discovers supported connected devices, publishes measurements as ROS topics, accepts servo-angle and LED-colour targets on command topics, and exposes discrete enable/configuration operations as acknowledged ROS services.
These guides use the host-driver architecture and the host firmware variant. Axiom communicates with the driver using its usual serial or WebSocket protocol. Native ROS/Zenoh firmware is a separate option and is not needed for these workflows. A Raspberry Pi running a compatible Linux/ROS installation can act as the host, just as a desktop computer can.
Start here
1. Install and connect — build on Linux, prepare the environment/tmux consoles and inspect the first measurement.
2. Automatic startup and discovery — choose USB, Wi-Fi, selected-board, explicit-endpoint or manual operation; separate demos on a shared network.
3. Sensors and multiple boards — generated topic names, aliases, hot swapping, descriptor commands and multiple Axioms.
4. Standard messages and mappings — Illuminance, numeric/boolean/text fallbacks, units, validity and optional descriptor mappings.
5. Servo and LED command topics — publish standard radian/RGB targets, inspect inputs and migrate former angle/colour services.
6. Servo slider and right-leg preview — use Marty's joint-slider GUI, startup enable, an optional hip model and its live visibility toggle.
7. Lighting controls in RViz — discover a supported light, set whole colour/brightness, switch Off and apply four-tier stack patterns.
8. Thermal camera in RViz — a four-terminal AMG8833 heatmap workflow with per-pixel temperatures.
9. Foxglove sensor dashboards — thermal/multizone Image panels, two-board IMU plots and direct scalar plots.
10. Sound sensor and spectrum — ready-made scalar/spectrum layout, optional custom coloured-bar panel, extension installation and dummy data.
11. Inspect, plot and record — console monitors, local Matplotlib plots, diagnostics, QoS, recording/replay and software checks.
12. Movement, recording and replay demo — independent shake/face nodes and a managed teaching workflow with synthetic or live data.
13. Optional scenarios dashboard — console recipes, discovered interfaces, ROS graphs and optional Axiom/Marty scenarios.
RViz thermal heatmap with temperatures in °C. This illustration uses synthetic data; the workflows use a real Axiom.
For Marty with an onboard Pi and camera, see Onboard Pi, camera and RViz. The Pi runs Marty's driver; the workstation runs the camera receiver/viewer and can independently host Axiom's driver.
Keep the ROS consoles together with tmux
The tmux setup and controls explain how to open four panes, preload the ROS environment, switch/zoom panes, copy output and reattach. The helper lives in scripts/ros_tmux.sh; start discovery in a pane to connect and acquire automatically.
Requirements
| Requirement | Details |
|---|---|
| Linux with ROS 2 | The installation example uses Ubuntu 24.04 and ROS 2 Jazzy. If using another compatible ROS distribution, install its matching packages and set its setup-file path in the local configuration. |
| Axiom firmware | Choose the current host firmware variant in the Axiom updater. It must support the connected sensor and supply its descriptor; see the Device Library guides to manage profiles. |
| Connection | USB serial, or Axiom already connected to a Wi-Fi network with a reachable IP address. |
| Source code | robotical/axiom-ros2 |
Normal startup discovers USB and Wi-Fi boards and enables connection, recovery and acquisition automatically. Automatic startup and board selection explains stable names, optional aliases, shared-network allowlists and explicit manual control. On a shared network, default discovery makes every verified Axiom eligible to connect. Select only your demo's board IDs with include_unconfigured: false and use a distinct ROS domain for each independent demo. Domains isolate ROS traffic but do not prevent computers connecting to the same physical board. See multiple demos on the same Wi-Fi. Example board namespaces, sensor identities and connection addresses are illustrative: use the values from your own configuration and discovery results. A graphical desktop is needed on the computer running RViz or the browser viewer; the driver itself can run without a desktop.
The host driver works with ROS 2 middleware on the host. The normal DDS-based ROS setup needs no Zenoh router. If you deliberately configure a different middleware, follow its own setup instructions and use matching settings for every ROS process in this session.
How the pieces fit together
| Piece | Job |
|---|---|
| Axiom firmware | Detects and reads devices, supplies descriptors and sends measurement packets. |
| axiom_driver | Maintains one connection per board, decodes packets, manages device lifetime and publishes ROS interfaces. |
| axiom_interfaces | Defines custom messages and the driver's connection, acquisition and device-command services. |
| ROS topics and services | Measurement topics feed consumers; command topics feed the driver; acknowledged services handle discrete requests. |
| axiom_thermal_viz and RViz | Convert thermal grids into coloured markers and temperature labels. |
| foxglove_bridge and Foxglove | Expose ROS topics over WebSocket for Images, IMU/scalar plots and the optional sound spectrum panel. |
| axiom_light_panel | RViz plugin: discovered whole-light RGB, brightness, Off, four-tier patterns and reported module status. |
| axiom_servo_demo | Connects a joint-slider GUI to the direct angle topic, manages enable acknowledgement and shows an optional RViz target preview. |
| Optional dashboard | Shows commands, available interfaces, scenarios and the current ROS graph. |
The driver and visualisation work without the dashboard. Run one firmware acquisition client per Axiom and let other consumers subscribe to its ROS topics.
ROS graph
These diagrams describe the project's interfaces, rather than a live session. Ovals are ROS nodes; rectangles group related topics. A data arrow runs from a publisher, through a topic, to a subscriber. The grey box is hardware. MODEL, BUS and ADDRESS are illustrative placeholders for a discovered sensor instance. The diagrams use the example board namespace /axiom; use your actual namespace and paths.
The driver publishes measurements under /<board>/<model>_b<bus>_<hex-address>/<output>. Examples are /axiom/lsm6ds_b1_76a/data_raw, /axiom/vl53l4cd_b1_129/range and /axiom/amg8833_b1_169/image. The model comes from the firmware descriptor. The location suffix is always present, so adding another sensor of the same type does not rename the first.
The measurement diagram shows selected topic families. Direct command inputs run in the opposite direction, from a ROS publisher to the driver; they are shown below.
Outputs include data_raw, range, image, grid, temperature, humidity, joint_states and battery, when supported by the descriptor and ROS adapter. Recognised scalar light attributes publish Illuminance in lux; other supported numeric, boolean and text scalars publish Float64, Bool and String. Standard messages and mappings explains the rules, output_info units/types and optional descriptor mappings. sample contains the generic decoded measurement; data is its JSON view. Thermal images use Celsius and multizone distance images use metres. A descriptor providing both image kinds uses thermal/image and range/image beneath its sensor root to distinguish them.
Read actual paths from the topic list or public_topics in a board's devices inventory. Publishers retire when sensors go offline or stale. See sensor naming for repeated sensor types, groups and metadata, and migration instructions when updating an older installation. Old generated bus/device paths are removed; there is no compatibility setting.
The dashed dashboard connection is optional. /dashboard subscribes to /axiom/devices, queries get_connection_state and inspects ROS discovery to draw its live graph. It does not start the driver or acquisition.
Service calls
Connection, acquisition and discrete descriptor operations use request/response services. Supported servo-angle and LED-colour targets use subscribed ROS topics. Solid arrows below show target-message flow; dashed two-way arrows show acknowledged service calls.
publish_data_subscription starts or stops firmware delivery. ros2 topic echo only creates a ROS subscriber; it does not start acquisition. Descriptor commands use /<board>/<sensor-instance>/commands/<command>, for example /axiom/lsm6ds_b1_76a/commands/set_sample_rate. Board-level connection and acquisition services keep their existing names. Remaining discrete descriptor services appear in inventory commands; success reports a firmware acknowledgement, not physical completion. Servo targets use std_msgs/msg/Float64 radians and RGB targets use std_msgs/msg/ColorRGBA with normalized channels, advertised in command_topics. Their former services are removed. See output topic contracts and migration and the slider walkthrough. The supported four-tier StackLight command is another acknowledged descriptor service; see lighting controls. A descriptor's word actions does not imply ROS action servers.
Optional nodes
The normal axiom.launch.py starts axiom_discovery, which owns one axiom_bridge_node per physical board. The diagrams show the resulting measurement interfaces. Explicit endpoint launches remain available. These additional nodes appear when the corresponding tool is explicitly launched. The names below omit the namespace, which is chosen by the launch or __ns remapping.
| Package | Node names | Inputs and outputs |
|---|---|---|
| axiom_debug_tools | axiom_imu_monitor, axiom_range_monitor, axiom_env_monitor, axiom_topic_sniff | Read an IMU, range, environmental or explicitly selected topic and print measurements. |
| axiom_plotter | dynamic_grapher | Discovers matching measurement topics and plots numeric values. |
| axiom_thermal_viz | thermal_grid_visualizer | Sensor grid → heatmap Marker and temperature-label MarkerArray topics → RViz. See the thermal graph and walkthrough. |
| axiom_shake_detector | shake_detector, robot_face, teaching_dashboard | IMU → shake events/motion/count; face consumes events. The teaching platform adds managed recording and replay. |
| axiom_servo_demo and its launch dependencies | servo_adapter, joint_controls, robot_state_publisher, servo_rviz | JointState slider input → radian angle-topic publisher and separate enable service; RViz shows the requested target. |
| axiom_marty_demo (examples) | sensor_view, accelerometer_view | Inventory/IMU/range or two selected IMU topics → RViz markers and display-layout static transforms. |
| axiom_marty_dashboard (examples) | dashboard | Observes board inventory, connection state and the discovered ROS graph; serves the optional scenarios guide. |
| rviz2 | rviz2 | Subscribes to the selected visualisation topics and transforms. |
| foxglove_bridge | foxglove_bridge | Makes ROS topics available to Foxglove over WebSocket; the browser or desktop Image panel displays a sensor's image output, optionally through a configured alias. See the Foxglove walkthrough. |
axiom_interfaces supplies message and service definitions. The single-board and multi-board launches used in these guides belong to axiom_driver; axiom_bringup provides an optional wrapper with additional visualisation tools. Launch files are instructions for starting nodes, not separate running nodes. ROS logging, parameter interfaces and temporary CLI nodes are omitted from the overview.
More than one Axiom
Run one driver per board in its own namespace. For example, /axiom/front/axiom_bridge_node owns /axiom/front/devices, measurements and services; /axiom/rear/axiom_bridge_node owns the corresponding /axiom/rear/… interfaces. Each board has its own transport, acquisition state and sensor identities. See Sensors and multiple boards.
Source and reference
Repository and build instructions
Driver parameters, topics and services
Start with Install and connect.