ROS 2: install and connect

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. It 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. A compatible Raspberry Pi can serve as the host just as a desktop computer can.

Use the current host firmware variant from the Axiom updater. It must recognise the connected sensors and supply their descriptors; see the Device Library guides to manage profiles. Native ROS/Zenoh firmware is a separate option and is not needed for this workflow. With normal DDS-based ROS middleware, no Zenoh router is required. If you select another middleware, follow its own setup instructions.

Updating an existing installation: follow the naming migration before launching with an older board file. Alias sources and exact QoS keys need updating; local ignored configuration files are not changed by Git pulls. Rebuild and restart affected ROS processes.

The examples use user-chosen namespaces and illustrative addresses. Replace paths, addresses and discovered sensor topics with the values for your hardware. Run one firmware acquisition client per Axiom and let other consumers subscribe to its ROS topics.

The published user guides cover the same workflow. Repository walkthroughs:

• tmux consoles and clipboard controls
• Sensor discovery, aliases, reconnecting and multiple boards
• Illuminance, scalar fallbacks and optional descriptor mappings
• Direct servo and LED command topics
• RViz lighting controls and stack patterns
• Servo slider and optional right-leg preview
• AMG8833 thermal camera in RViz
• Foxglove thermal heatmap, IMU and scalar plots
• Sound layout and custom spectrum panel
• Console tools, diagnostics and recording
• Movement teaching demo and replay
• Optional scenarios dashboard
• Driver parameters and interface contracts

1. Install and build

The installation example uses Ubuntu 24.04, ROS 2 Jazzy and Bash. Install ROS first using the official Ubuntu instructions, including its package repositories. If using another compatible ROS distribution, follow its installation instructions and substitute its setup path below. Use one distribution per terminal and build workspace.

Install Git and the build tools:

sudo apt update
sudo apt install git ros-dev-tools
sudo rosdep init  # Once per machine; skip if already initialized.
rosdep update

Choose a writable directory for the checkout. For an existing clone, change to its root and skip the clone commands:

git clone https://github.com/robotical/axiom-ros2.git
cd axiom-ros2
source /opt/ros/jazzy/setup.bash
rosdep install --from-paths src --ignore-src -r -y
colcon build --base-paths src --symlink-install

The dependency step also installs the core visualisation dependencies, including the servo slider/preview tools. A graphical desktop is needed on the computer running RViz or a viewer; the driver can run without a desktop. Foxglove Bridge is installed separately in its walkthrough. Optional example packages have their own build commands.

For Kilted, source /opt/ros/kilted/setup.bash instead and use matching packages throughout. When creating config/machine.env later, set ROS_SETUP_FILE to that same distribution. Do not mix build overlays from different ROS distributions. After building, optional software checks can run against simulated devices.

2. Start automatically

Connect a host-firmware Axiom over USB, or power a Wi-Fi Axiom on the same local network. From the checkout:

source scripts/setup_env.sh
ros2 launch axiom_driver axiom.launch.py

No board file, serial path or IP address is required. With no boards, discovery waits quietly. Verified boards connect and start acquisition automatically; each gets a stable namespace /axiom_<firmware-MAC>. Multiple boards run independently, and a board visible over USB and Wi-Fi gets one bridge, preferring USB.

Shared Wi-Fi: this default can connect every verified Axiom visible to the host. For independent robots or demos, use board-ID selection with include_unconfigured: false and a separate ROS domain per demo. See shared-network setup. For USB-only, Wi-Fi-only or explicit endpoints, choose a startup mode before launching.

For USB, ensure your account can access the port. On systems using dialout:

ls -l /dev/serial/by-id/
id -nG
# Only if your account is missing the device's group:
sudo usermod -aG dialout "$USER"

Log out and back in after changing groups. Close updaters, serial monitors and USB routers using the same board. Wi-Fi discovery uses the firmware's mDNS HTTP advertisement; the network must allow multicast. An explicit endpoint remains available when multicast is blocked.

The optional config/machine.env selects a host's ROS setup, workspace and domain:

# Create only if you need host-specific settings; preserve an existing file.
if [[ ! -e config/machine.env ]]; then
  cp config/machine.env.example config/machine.env
fi

Edit ROS_SETUP_FILE for your installed distribution, for example /opt/ros/kilted/setup.bash or /opt/ros/jazzy/setup.bash. All participating ROS terminals must share a domain and compatible middleware settings. Sourcing the setup script prepares a terminal without starting nodes. It also selects an existing config/boards.yaml when AXIOM_ROS_BOARDS_FILE is unset; an explicitly supplied boards_file:=... selects a different file. Restart the ROS processes after changing their domain or startup configuration.

See automatic startup for optional board names, aliases, shared-network board selection, explicit endpoints and manual startup. Existing board files can still name configured endpoints. New identity rules need no endpoint. For example, a rule named axiom makes a selected board use /axiom for the optional viewer examples below.

Use tmux for the ROS consoles

sudo apt install tmux
bash scripts/ros_tmux.sh

The helper opens four prepared consoles without starting a driver. Run the launch above in Terminal 1. New panes load the ROS environment automatically; after a rebuild, source scripts/setup_env.sh in reused panes. See tmux controls.

tmux controls

For a tmux shortcut, press Ctrl+b, release both keys, then press the listed key. Use lowercase d and z.

Detach keeps commands running. To return, run bash scripts/ros_tmux.sh again from the repository root. It uses the dedicated axiom-ros tmux socket and axiom session, so use this helper for reattaching rather than a bare tmux attach. After a host reboot, restart the helper and the ROS commands.

Copy and paste

In the Ubuntu desktop terminal, hold Shift while dragging to use the terminal's selection, then Ctrl+Shift+C to copy and Ctrl+Shift+V to paste. The right-click menu also works. Zooming a pane first makes long output easier to select. Ctrl+C interrupts a process; use the copy shortcut for selected output.

For automatic mouse-drag copying to an X11 desktop clipboard, the helper supports xclip. Install it in a desktop terminal on the host:

sudo apt install xclip

If the session is already open, reload its configuration from the repository root:

tmux -L axiom-ros source-file scripts/tmux.conf

The helper's default copy-mode binding pipes mouse selections to xclip. It needs a desktop display; a plain SSH terminal needs its own clipboard workflow. Remote desktop clipboard sharing also depends on the client. The desktop clipboard and tmux copy buffer are separate.

Refresh or finish a session

Reattaching preserves existing shells and commands. After rebuilding or changing config/machine.env, stop affected ROS processes and reload each reused pane:

source scripts/setup_env.sh

Restart those processes with the refreshed settings. All ROS terminals need the same domain and compatible middleware settings. Before finishing, use the driver's stop-acquisition and disconnect services while it is still running, then stop the remaining foreground processes. Detach alone does not perform cleanup.

See the published tmux guide and official tmux introduction.

3. Inspect a measurement

Leave discovery running. In a second prepared terminal:

source scripts/setup_env.sh
ros2 topic echo /axiom_discovery/boards std_msgs/msg/String \
  --qos-reliability reliable --qos-durability transient_local \
  --qos-depth 1 --full-length --once
ros2 topic list -t --no-daemon

The board inventory reports each ID, namespace, transport and connection state. Sensors are discovered automatically; they do not need entries in a board file. Find the supported IMU topic of type sensor_msgs/msg/Imu, for example /axiom/lsm6ds_b1_76a/data_raw, and copy its complete path. With default discovery, the board part will normally be /axiom_<firmware-MAC> rather than /axiom.

The pattern is /<board>/<lowercase-model>_b<bus>_<hex-address>/<output>. Use the actual path, including the location suffix. Sensor naming and inventory explains duplicate sensor types, images and groups.

IMU_TOPIC='PASTE_DISCOVERED_IMU_TOPIC_HERE'
ros2 topic echo "$IMU_TOPIC" sensor_msgs/msg/Imu \
  --field linear_acceleration --qos-reliability best_effort --once
ros2 topic hz "$IMU_TOPIC"

Acceleration is in m/s², including gravity; gyroscope values are in rad/s. The IMU has no fused orientation. Packet delivery defaults to 10 Hz; a sensor's message rate can differ because its sampling and firmware batching are independent. Stop the rate command with Ctrl+C. Viewers subscribe to ROS topics and need no additional connection or acquisition calls.

The remaining examples use a configured board name /axiom. Replace it with your actual namespace, or add that optional name through the board file. See sensors and multiple boards for services and aliases.

If using another sensor, inspect its actual message type rather than assuming every topic is an IMU. Current host-driver sources publish recognised light values as Illuminance and remaining supported scalars as Float64, Bool or String. LTR-390 uses ambient.illuminance in lux and UVI.data in index units. Inventory output_info reports published types and units; sample retains timing and validity. See Standard messages and mappings for availability, fields and optional descriptor mappings.

4. Optional acceleration display in RViz

Keep the driver and acquisition running. In Terminal 3, build the optional marker adapter from the repository root:

source scripts/setup_env.sh
rosdep install --from-paths src examples/scenarios-dashboard/src/axiom_marty_demo --ignore-src -r -y
colcon build --base-paths src examples/scenarios-dashboard/src/axiom_marty_demo \
  --packages-select axiom_marty_demo --symlink-install
source scripts/setup_env.sh
BOARD_NS='PASTE_DISCOVERED_BOARD_NAMESPACE_HERE'
ros2 run axiom_marty_demo sensor_view --ros-args \
  -r __ns:=/sensing -p axiom_namespace:="$BOARD_NS"

In Terminal 3, replace BOARD_NS with the full board namespace from /axiom_discovery/boards, including its leading slash. Leave the adapter running. It reads that board's devices inventory and subscribes to the actual public_topics paths as they appear, then publishes markers. It requires neither the dashboard nor a Marty.

In Terminal 4:

source scripts/setup_env.sh
ros2 run rviz2 rviz2 \
  -d "$(ros2 pkg prefix --share axiom_marty_demo)/config/sensors.rviz"

The supplied layout uses the display frame sensor_view and topic /sensing/visualization/markers. The acceleration arrow includes gravity; it is not a position or orientation estimate. For an AMG8833, follow the separate RViz thermal guide or single-camera Foxglove guide.

More workflows

The core build also includes debug monitors and local plotting, the servo slider and the movement teaching platform. A sound sensor can use the bundled Foxglove layout or optional spectrum extension. These visualisation/controller tools are started explicitly; sourcing the environment or opening tmux does not start them.

5. Stop

If controlling an actuator, first issue its disable request and wait for success while the driver is connected; see servo shutdown. Then close viewers and stop echoes or adapters with Ctrl+C. While the driver is still running, in Terminal 2:

BOARD_NS='PASTE_DISCOVERED_BOARD_NAMESPACE_HERE'
ros2 service call "$BOARD_NS/publish_data_subscription" \
  axiom_interfaces/srv/PublishedDataSubscription '{rate_hz: 0.0}'
ros2 service call "$BOARD_NS/disconnect" axiom_interfaces/srv/Disconnect '{}'

Then stop the driver with Ctrl+C in Terminal 1. Detaching tmux or stopping an echo alone leaves the running processes and acquisition active.

If a package or service is missing, check the successful build, sourced workspace, driver process, namespace, ROS domain and middleware settings. For USB, also check device permissions and port ownership. For Wi-Fi, check the current address and /api/v response. Use the exact discovered topic and compatible best-effort QoS when checking sensor messages.

Development and dated test evidence are in validation.md. The firmware contract notes describe decoding, timing and transport limits. Historical test versions are not installation requirements.