Use an Axiom IMU to show how one ROS measurement stream can feed several independent applications. A shake detector publishes typed events; a separate robot-face node reacts to those events. A local teaching dashboard adds live plots, recording and replay. A clearly labelled synthetic clip is available when hardware is absent.
The example is included in the core axiom_shake_detector package. Complete the host setup first. It is separate from the scenarios dashboard: the teaching platform manages its own ROS applications and can own an Axiom connection.
For a simple subscriber-only demonstration, leave your normal driver acquiring and select its actual sensor_msgs/msg/Imu topic:
# Load the current workspace in a second terminal.
source scripts/setup_env.sh
# Copy the full IMU path from your running driver.
IMU_TOPIC='PASTE_FULL_IMU_TOPIC_HERE'
# Detect shakes under a separate example namespace, without another Axiom connection.
ros2 run axiom_shake_detector shake_detector --ros-args \
-r __ns:=/movement_demo -p imu_topic:="$IMU_TOPIC" -p dashboard_port:=0
In another prepared terminal:
# Inspect typed events; a message appears only when a gesture is detected.
ros2 topic echo /movement_demo/shake/events axiom_interfaces/msg/ShakeEvent
An optional independent consumer can run in a further prepared terminal:
# React to shake events and publish face/state; this opens no hardware connection.
ros2 run axiom_shake_detector robot_face --ros-args -r __ns:=/movement_demo
The face's JSON state is on /movement_demo/face/state. Stopping the face leaves the detector and sensor driver running. This standalone sequence exposes ROS messages; use the managed platform below for the browser-rendered face and guided controls.
First inspect and note the board's USB path or Wi-Fi endpoint and canonical IMU topic. Stop acquisition, disconnect and stop any existing driver for that physical board before using the managed launch. It starts its own driver, with automatic connection and acquisition, and uses its launch arguments rather than your discovery board entry.
From the repository root in a prepared terminal, replacing both placeholders:
# Load the installed ROS distribution and rebuilt core packages.
source scripts/setup_env.sh
# Choose the full canonical IMU topic for the managed /axiom driver namespace.
IMU_TOPIC='/axiom/PASTE_SENSOR_INSTANCE_HERE/data_raw'
# Choose the stable USB device path for this Axiom.
SERIAL_PORT='/dev/serial/by-id/REPLACE_WITH_AXIOM_DEVICE'
# Start the local teaching platform and its own serial-connected host driver.
ros2 launch axiom_shake_detector shake_lab.launch.py \
transport:=serial serial_port:="$SERIAL_PORT" imu_topic:="$IMU_TOPIC"
The managed driver uses namespace /axiom. If discovery previously used /axiom_<MAC>, keep the same sensor-instance suffix but replace that board prefix with /axiom in IMU_TOPIC. No alias is installed by this launch.
For Wi-Fi, use this alternative instead of the serial launch:
# Select this board's actual reachable framed WebSocket endpoint.
AXIOM_URI='ws://REPLACE_WITH_AXIOM_IP/ws'
# Keep IMU_TOPIC set for the managed /axiom namespace in this terminal.
ros2 launch axiom_shake_detector shake_lab.launch.py \
transport:=ws device_uri:="$AXIOM_URI" imu_topic:="$IMU_TOPIC"
Open http://127.0.0.1:8080 on the ROS host. The loopback server is a local teaching tool. From a different viewer computer, an SSH tunnel keeps that default:
# Run on the viewer computer, replacing the ROS host's SSH login and address.
ssh -N -L 8080:127.0.0.1:8080 USER@ROS_HOST_IP
Open the same localhost URL on the viewer while the tunnel runs. Do not run the standalone detector/face from the first section in the managed platform's /axiom namespace at the same time. The launch also accepts dashboard_host, dashboard_port and recordings_dir; the default recording directory is ~/axiom-recordings.
| Step | Demonstrate | ROS concept |
|---|---|---|
| See measurements | Keep Axiom still, then tilt it; show acceleration and rotation. | Standard sensor messages and topics. |
| Recognise a shake | Move the board back and forth; show the typed event and count. | A separate processing node. |
| Add robot face | Add the face in the browser, trigger another gesture, then stop it. | Independent subscribers; detection continues. |
| Record an experiment | Record 10, 15 or 30 seconds; wait for the saved nonzero IMU count. | A recorder is another consumer of the same topic. |
| Unplug and replay | Finish recording, unplug Axiom, then replay the selected clip. | Recorded input drives the same processing interfaces. |
The browser has presentation view and presenter notes. Recordings retain original message timestamps. Replaying stops the managed live driver and starts a bag player; only the IMU input is replayed, while detector and face outputs are recomputed. Switching source restarts the consumers for a fresh experiment. Finishing a recording is required before changing source.
Play synthetic sample creates a six-second demonstration with two programmed gestures. Add the face before playing to see its reactions. Adding the strict detector and replaying from the beginning demonstrates two independent heuristics: the supplied clip produces two standard events and no strict events. It is synthetic sensor data, not captured hardware motion.
With with_driver:=false, the managed platform starts without a live hardware owner and can be used for the synthetic/replay exercise. Stop other publishers on the selected IMU topic before replay. This mode does not automatically take over an externally managed live driver.
The managed workflow uses these example /axiom outputs:
| Topic | Type | Meaning |
|---|---|---|
| Selected IMU input | sensor_msgs/msg/Imu | Acceleration m/s² and gyro rad/s. |
| /axiom/shake/events | axiom_interfaces/msg/ShakeEvent | Event number, triggering sample time, motion and pulse count. |
| /axiom/shake/motion | std_msgs/msg/Float64 | Motion magnitude after estimating slow gravity changes. |
| /axiom/shake/count | std_msgs/msg/UInt64 | Detector event count. |
| /axiom/face/state | std_msgs/msg/String JSON | Expression, reactions and latest event number. |
| /axiom/strict/events, /axiom/strict/count | Same event/count types | Optional high-threshold detector. |
The face counts events since it was added and does not receive earlier events. The standard detector uses three pulses above 3 m/s² within 0.8 seconds, release below 1.2 m/s² and a 1.5-second cooldown. The filter warms up after startup or timestamp discontinuities. Rotations, impacts and cable movement can also trigger it; this is an educational gesture heuristic, not a calibrated motion classifier.
Finish any recording, stop playback, then stop the launch with Ctrl+C. It owns and cleans up its managed processes. No service is installed at login or boot. Keep only one firmware acquisition owner for each Axiom when returning to normal discovery.
For macOS with Docker Desktop, the repository also provides scripts/shake_lab.sh with live USB-relay and synthetic modes. Those commands and recording locations are specific to that optional host workflow; use the repository teaching-platform guide instead of mixing its relay instructions with native Linux. The native Linux instructions above require no Mac relay.
Return to inspection and recording tools or Axiom with ROS 2.