raspbot_v2
ROS 2 package for the Yahboom Raspbot V2 platform — differential-drive motor control and pan/tilt camera orientation.
Architecture
Both nodes share the same I²C bus. The Linux kernel serialises individual transactions, so they can run as separate processes without additional locking.
Motor controller
┌───────────────────────────────────┐
│ MotorControllerNode │
│ │
/cmd_vel ──────────>│ Twist → differential kinematics │
(geometry_msgs/Twist)│ left = linear − (angular × wb/2)│
│ right = linear + (angular × wb/2)│
│ │
/wheel_speeds ──────>│ Direct per-wheel override │
(Float32MultiArray │ [FL, FR, RL, RR] │
4 × float32) │ │
│ ▼ │
│ raspbot_v2_interface │
│ I²C bus 1, addr 0x2B │
│ ▼ │
│ /dev/i2c-1 ─────────> Motors │
│ │
/current_wheel_speeds│<─ telemetry @ 10 Hz │
(Float32MultiArray) │ [FL, FR, RL, RR] │
└───────────────────────────────────┘
Topics
| Topic | Direction | Type | Description |
|---|---|---|---|
/cmd_vel |
Subscribed | geometry_msgs/Twist |
Velocity command — linear.x (m/s) and angular.z (rad/s) |
/wheel_speeds |
Subscribed | std_msgs/Float32MultiArray |
Direct per-wheel speed override [FL, FR, RL, RR] in library units (0–255) |
/current_wheel_speeds |
Published | std_msgs/Float32MultiArray |
Current wheel speeds read from hardware, published at 10 Hz |
Parameters
| Parameter | Default | Description |
|---|---|---|
wheel_base |
0.3 |
Distance between left and right wheels in metres |
max_speed |
1.0 |
Maximum motor speed in library units |
Camera orientation controller
┌──────────────────────────────────────┐
│ CameraOrientationNode │
│ │
/joint_command ────────>│ JointState (names: pan, tilt) │
(sensor_msgs/ │ position in radians │
JointState) │ │
│ pan → servo 1 (0°–180°) │
│ tilt → servo 2 (0°–110°) │
│ │
│ ▼ │
│ raspbot_v2_interface │
│ I²C bus 1, addr 0x2B │
│ ▼ │
│ /dev/i2c-1 ──────> Pan/tilt servos │
│ │
/joint_states <────────│ current angles @ 10 Hz │
(sensor_msgs/ │ position in radians │
JointState) │ │
└──────────────────────────────────────┘
Topics
| Topic | Direction | Type | Description |
|---|---|---|---|
/joint_command |
Subscribed | sensor_msgs/JointState |
Commanded pan/tilt angles. Joint names "pan" and "tilt", positions in radians. Unknown joint names are ignored. |
/joint_states |
Published | sensor_msgs/JointState |
Current angles reflected from the last command, published at 10 Hz |
Parameters
| Parameter | Default | Description |
|---|---|---|
pan_servo_id |
1 |
Raspbot servo channel for pan |
tilt_servo_id |
2 |
Raspbot servo channel for tilt |
pan_min_deg |
0.0 |
Pan lower limit (degrees) |
pan_max_deg |
180.0 |
Pan upper limit (degrees) |
tilt_min_deg |
0.0 |
Tilt lower limit (degrees) |
tilt_max_deg |
110.0 |
Tilt upper limit (degrees) — hardware cap |
pan_center_deg |
90.0 |
Startup and shutdown park position for pan |
tilt_center_deg |
60.0 |
Startup and shutdown park position for tilt |
state_rate_hz |
10.0 |
~/joint_states publish rate |
Hardware interface
The node drives the pan and tilt servos over I²C bus 1 (device address 0x2B). The same /dev/i2c-1 device used by the motor controller is sufficient — no additional device node is required.
Ultrasonic range sensor
┌──────────────────────────────────────┐
│ UltrasonicNode │
│ │
│ Sensor off when no subscribers │
│ Sensor on when subscribers > 0 │
│ 1 s warm-up after power-on │
│ │
│ ▼ │
│ raspbot_v2_interface │
│ I²C bus 1, addr 0x2B │
│ ▼ │
│ /dev/i2c-1 ──────> HC-SR04 sensor │
│ │
/ultrasonic/range <────│ Range @ configurable rate │
(sensor_msgs/Range) │ radiation_type = ULTRASOUND │
│ range in metres (REP-117) │
└──────────────────────────────────────┘
Topics
| Topic | Direction | Type | Description |
|---|---|---|---|
/ultrasonic/range |
Published | sensor_msgs/Range |
Distance in metres. +inf when beyond max range, -inf when closer than min range (REP-117). Only published while subscribers are connected. |
Parameters
| Parameter | Default | Description |
|---|---|---|
publish_rate_hz |
10.0 |
Sensor poll and publish rate |
frame_id |
'ultrasonic' |
header.frame_id on published messages |
min_range_m |
0.02 |
Minimum valid range in metres |
max_range_m |
4.0 |
Maximum valid range in metres |
field_of_view |
0.2618 |
Sensor cone width in radians (~15°) |
warmup_s |
1.0 |
Seconds to wait after powering the sensor on before publishing |
Verifying range readings
ros2 topic echo /ultrasonic/range
The sensor will activate automatically when this command runs and deactivate when it is stopped.
RPLIDAR A1
Runs in a separate container built from lidar/Dockerfile.
┌──────────────────────────────────────┐
│ sllidar_ros2 (rplidar_node) │
│ │
│ serial 115200 baud │
│ angle_compensate = true │
│ scan_mode = Sensitivity │
│ ▼ │
│ /dev/ttyUSB0 ──────> RPLIDAR A1 │
│ │
/scan <───────│ LaserScan @ ~10 Hz │
(sensor_msgs/ │ 360° scan, range 0.15–12 m │
LaserScan) │ │
└──────────────────────────────────────┘
Topics
| Topic | Direction | Type | Description |
|---|---|---|---|
/scan |
Published | sensor_msgs/LaserScan |
360° laser scan in the laser frame |
Configuration
The LIDAR container is configured via environment variables in .env or docker-compose.yml. See the Launching section for details.
Verifying LIDAR data
ros2 topic echo /scan
Setting up the robot
1. Flash Raspberry Pi OS
Use the Raspberry Pi Imager to write Raspberry Pi OS (64-bit, Lite recommended) to a microSD card.
Before writing, open the imager's Advanced options (⚙) and configure:
| Setting | Value |
|---|---|
| Hostname | raspbot-v2.local |
| SSH | Enabled |
| Username / Password | Your preferred credentials |
| Wi-Fi | Your network SSID and password (if not using Ethernet) |
Write the image, insert the card, and power on the Pi. Once it has booted and is reachable on the network (test with ping raspbot-v2.local), proceed to the next step.
2. Provision with Ansible
The ansible/ directory contains a playbook that handles the remaining setup (enabling SPI, installing Docker). See ansible/README.md for full instructions.
Building
Prerequisites
-
Docker (with BuildKit enabled)
-
For cross-compilation from an amd64 host, QEMU user-space emulation must be registered with the kernel. If you haven't done this before, run once:
docker run --rm --privileged tonistiigi/binfmt --install arm64
Build with Docker Compose (recommended)
Both images are defined in docker-compose.yml. Build them together:
docker compose build
Or build a single service:
docker compose build robot
docker compose build lidar
The builds are split into two stages each:
- builder — compiles the ROS package(s) with
colcon; the lidar builder also clonessllidar_ros2from GitHub - runtime — copies only the install overlay into a clean
ros:kilted-ros-corebase; no build tools in the final image
Build images individually
# Robot controller
docker build --platform linux/arm64 -f robot/Dockerfile -t raspbot_v2:latest .
# LIDAR
docker build --platform linux/arm64 -f lidar/Dockerfile -t raspbot_v2_lidar:latest .
Deploying
Pipe both images directly to the target over SSH — no intermediate file or registry needed:
docker save raspbot_v2:latest raspbot_v2_lidar:latest \
| ssh matt@raspbot-v2.local docker load
Then copy the compose file to the target:
scp docker-compose.yml matt@raspbot-v2.local:~/
Replace matt with the username configured in ansible/inventory.ini.
Launching
Start everything with Docker Compose (recommended)
docker compose up
This starts both the robot controller and LIDAR containers. Logs from both are interleaved in the terminal, each line prefixed with the service name. To run in the background:
docker compose up -d
docker compose logs -f # follow logs
docker compose down # stop and remove containers
Environment variables
Create a .env file in the same directory as docker-compose.yml to override defaults:
ROS_DOMAIN_ID=0
LIDAR_PORT=/dev/ttyUSB0
LIDAR_FRAME_ID=laser
| Variable | Default | Description |
|---|---|---|
ROS_DOMAIN_ID |
0 |
ROS 2 domain — must match on all nodes |
LIDAR_PORT |
/dev/ttyUSB0 |
Host device node for the RPLIDAR |
LIDAR_FRAME_ID |
laser |
frame_id in published LaserScan messages |
Run containers individually
# Robot controller
docker run --rm \
--network=host \
--device /dev/i2c-1 \
--env ROS_DOMAIN_ID=0 \
raspbot_v2:latest
# LIDAR
docker run --rm \
--network=host \
--device /dev/ttyUSB0 \
--env ROS_DOMAIN_ID=0 \
raspbot_v2_lidar:latest
Overriding robot launch parameters
Launch arguments can be appended after the image name:
docker run --rm \
--network=host \
--device /dev/i2c-1 \
--env ROS_DOMAIN_ID=0 \
raspbot_v2:latest \
ros2 launch raspbot_v2 robot.launch.py \
wheel_base:=0.25 max_speed:=0.8 tilt_center_deg:=45.0
Available launch arguments:
| Argument | Default | Description |
|---|---|---|
wheel_base |
0.3 |
Distance between left and right wheels (m) |
max_speed |
1.0 |
Maximum motor speed in library units |
pan_center_deg |
90.0 |
Pan angle at startup and shutdown (degrees) |
tilt_center_deg |
60.0 |
Tilt angle at startup and shutdown (degrees) |
ultrasonic_rate_hz |
10.0 |
Ultrasonic sensor publish rate (Hz) |
LIDAR device permissions
The RPLIDAR connects as a USB serial device. If the user running Docker is not in the dialout group, add them and log back in:
sudo usermod -aG dialout $USER
Sending velocity commands from the host
With the container running, publish from another terminal (requires ROS 2 on the host or a second container on the same network):
# Drive forward at 0.2 m/s
ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist \
"{linear: {x: 0.02}, angular: {z: 0.0}}"
# Turn on the spot
ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist \
"{linear: {x: 0.0}, angular: {z: 0.5}}"
# Stop
ros2 topic pub --once /cmd_vel geometry_msgs/msg/Twist \
"{linear: {x: 0.0}, angular: {z: 0.0}}"
Commanding the camera from the host
Pan to centre (90°) and tilt to 30°:
ros2 topic pub --once /joint_command sensor_msgs/msg/JointState \
"{name: ['pan', 'tilt'], position: [1.5708, 0.5236]}"
A single axis can be commanded by omitting the other joint name:
# Pan only
ros2 topic pub --once /joint_command sensor_msgs/msg/JointState \
"{name: ['pan'], position: [0.0]}"
Verifying telemetry
# Wheel speeds
ros2 topic echo /current_wheel_speeds
# Camera orientation
ros2 topic echo /joint_states
Project layout
.
├── docker-compose.yml # Launches robot and lidar containers together
├── docker-entrypoint.sh # Sources ROS overlays before exec (shared by both images)
├── robot/
│ ├── Dockerfile # Robot controller image (two-stage)
│ ├── src/
│ │ └── raspbot_v2/
│ │ ├── package.xml # ROS package manifest
│ │ ├── setup.py # ament_python build definition
│ │ ├── launch/
│ │ │ └── robot.launch.py # Starts all robot nodes together
│ │ └── raspbot_v2/
│ │ ├── __init__.py
│ │ ├── motor_controller_node.py # Differential-drive motor control
│ │ ├── camera_orientation_node.py # Pan/tilt servo control
│ │ └── ultrasonic_node.py # HC-SR04 range sensor
│ └── raspbot_v2_interface/ # Vendored Yahboom hardware library
│ └── Raspbot_Lib/
│ └── Raspbot_Lib.py # I²C driver (smbus, bus 1, addr 0x2B)
└── lidar/
└── Dockerfile # RPLIDAR A1 image (two-stage, clones sllidar_ros2)