---json
{"name": "Install and connect"}
---
====== 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 [[https://updates.robotical.io|Axiom updater]]. It must recognise the connected sensors and supply their descriptors; see the [[https://userguides.robotical.io/axiom/device_library/start|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 [[:axiom:ros2:sensors_and_boards#updating_an_existing_installation|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 [[https://userguides.robotical.io/axiom/ros2/start|published user guides]] cover the same workflow. Repository walkthroughs:
* [[:axiom:ros2:getting_started#use_tmux_for_the_ros_consoles|tmux consoles and clipboard controls]]
* [[:axiom:ros2:sensors_and_boards|Sensor discovery, aliases, reconnecting and multiple boards]]
* [[:axiom:ros2:standard_messages|Illuminance, scalar fallbacks and optional descriptor mappings]]
* [[:axiom:ros2:output_topics|Direct servo and LED command topics]]
* [[:axiom:ros2:lighting|RViz lighting controls and stack patterns]]
* [[:axiom:ros2:servo_slider|Servo slider and optional right-leg preview]]
* [[:axiom:ros2:thermal_camera|AMG8833 thermal camera in RViz]]
* [[:axiom:ros2:foxglove|Foxglove thermal heatmap, IMU and scalar plots]]
* [[:axiom:ros2:sound_sensor|Sound layout and custom spectrum panel]]
* [[:axiom:ros2:tools_and_recording|Console tools, diagnostics and recording]]
* [[:axiom:ros2:shake_demo|Movement teaching demo and replay]]
* [[:axiom:ros2:dashboard|Optional scenarios dashboard]]
* [[https://github.com/robotical/axiom-ros2/blob/main/src/axiom_driver/README.md|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 [[https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debs.html|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 [[:axiom:ros2:foxglove|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 [[:axiom:ros2:tools_and_recording#run_software_checks_after_an_update|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_%%''. 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 [[:axiom:ros2:automatic_startup#multiple_demos_on_the_same_wi-fi|shared-network setup]]. For USB-only, Wi-Fi-only or explicit endpoints, choose a [[:axiom:ros2:automatic_startup#choose_a_startup_mode|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 [[:axiom:ros2:automatic_startup|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 [[:axiom:ros2:getting_started#use_tmux_for_the_ros_consoles|tmux controls]].
==== tmux controls ====
For a tmux shortcut, press **Ctrl+b**, release both keys, then press the listed key. Use lowercase d and z.
^Action ^Keys ^
|Switch panes |Ctrl+b, then an arrow; mouse clicks also work|
|Zoom the selected pane |Ctrl+b, then z; repeat to restore the layout |
|Detach to the outer terminal |Ctrl+b, then d |
|Enter scrollback |Ctrl+b, then [; use arrows/Page Up; q exits |
|Paste the tmux copy buffer |Ctrl+b, then ] |
|Interrupt the selected foreground command|Ctrl+C |
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 [[https://userguides.robotical.io/axiom/ros2/getting_started#use_tmux_for_the_ros_consoles|published tmux guide]] and [[https://github.com/tmux/tmux/wiki/Getting-Started|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_%%'' rather than ''/axiom''.
The pattern is ''%%//_b_/