​
Basic Commands

Run

Run Robot
uv run src/run.py turtlebot4

​
Identity and Keys

API_KEY Go to portal to get a free API key. Enter this API key in the “api_key” field in the /config/turtlebot4.json5 file. You can also provide this API key via your .env - just enter it as:

OM_API_KEY=om1_live_e4252f1cf005af...

UNIVERSAL_ROBOT_ID (URID) Go to”Hello Robots, come join us” to join a decentralized machine<>machine coordination and communication system (FABRIC). Enter machine metadata - currently an arbitrary string - and click “join”. The system will provide a unique URID for your robot. The URIDs all share the same format: they begin with OM, then 12 alphanumeric characters (numerals and letters), adding up to 14 characters in total. They’re not case sensitive. A unique URID allows multiple robots to communicate with one another, similar to how humans use different phone numbers to help them communicate and coordinate.

Enter the URID in the “URID” field in the /config/turtlebot4.json5 file. You can also provide the URID via your .env - just enter it as:

URID=OM742d35Cc6634 # yours will be different!

​
Suggested Operating System Versions

The TurtleBot4 contains two entirely separate computers, the Raspberry Pi (RPi) and the Create3. These computers are accessed in different ways, run different software, and have different roles. Different combinations of software versions running on those computers give somewhat differing capabilities.

Raspberry Pi
Ubuntu 22.04.4 LTS (GNU/Linux 5.15.0-1073-raspi aarch64)
turtlebot4_standard_humble_1.0.4.img (2024-08-19 16:59 2.2G)

Suitable images can be installed via a flashed SD card. Note that instructions given are needlessly complex - basically, download the image, unzip it, flash a SD card with that image using your favorite tool/platform (e.g. for mac use the Disk Utility to unmount the drive and then sudo dcfldd if=tb.img sizeprobe=if bs=1M of=/dev/disk4), insert the flashed SD card into the RPi, and turn it on.

Create3
H.2.6 (Humble)

​
TurtleBot4 Set Up

OM1 connects to TurtleBot4 using Zenoh. To correctly set up your TurtleBot4, follow these steps.

  1. Set up your TurtleBot4 following the Basic Setup.
  2. Please then become familiar with the Turtlebot4 ecosystem - there are extensive educational materials to help you get started.
  3. If you are not familiar with the TurtleBot4, please see the excellent documentation.

NOTE: Please update the Raspberry Pi’s OS (use sudo apt update && sudo apt upgrade).

NOTE: Please update the TurtleBot4’s internal Create3 computer to iRobot® Create® 3 Release H.2.6 via the Create3’s html “Update” page.

NOTE: Make sure to remember the TurtleBots’ IP address in your local network. If you do not know it, scan your local network for “Raspberry Pi”.

NOTE: In the remainder of this writeup, we assume you are generally familiar with the ROS2/TurtleBot4 ecosystem, including ssh-ing to the Raspberry Pi command line, the use of the turtlebot4-setup program, and interacting with the internal Create3 via its webpage at IP:8080.

  1. As you have just experienced first-hand, there are numerous issues connecting to a TurtleBot4 in a university/enterprise network. To solve many of those, we follow the dual Zenoh bridge approach developed by theconstruct.ai, which is to give the Raspberry Pi and the Create3 their own ROS2 DOMAIN_IDs, and then use Zenoh bridges to filter message traffic between the RPi and the Create3. This allows you to filter messages on a per topic level (see the config_create3.json5 file for an example of how this is done).

Make the following ROS_DOMAIN_ID changes to the TurtleBot4. Use the turtlebot4-setup tool to access ROS Setup:Bash Setup and set it to the following:

ROBOT_NAMESPACE=/_your_robot_URID_/pi 
# example: ROBOT_NAMESPACE=/OM742d35Cc6634/pi
ROS_DOMAIN_ID=0
RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
CYCLONEDDS_URI=[] # Empty

Click “Save”, “Esc”, and then “Apply Settings”. The TurtleBot4 will reboot. Once the reboot is complete (wait for chime, 1 min), access the Create3’s App config page at its web server (e.g. 192.168.1.XXX:8080/ros-config). Change the ROS_DOMAIN_ID to 1. The correct settings are:

ROS 2 Domain ID (default 0): 1
ROS 2 Namespace: /_your_robot_URID_/c3 
# example: /OM742d35Cc6634/c3
RMW_IMPLEMENTATION: rmv_cyclonedds_cpp

Note the use of the “/c3” to create an unique namespace for the c3.

Click Save and Restart Application.

NOTE: Do not forget to click Restart Application, otherwise the changes will not be applied. Wait for chime (1 min) indicating Create3 reboot.

Finally, on the TurtleBot4’s RPi, install Docker and run sudo docker compose -f docker-compose.yaml up -d. The docker-compose should be:

docker-compose.yaml
services:
  zenoh-bridge-turtlebot4:
    image: openmindagi/turtlebridge
    container_name: zenoh-bridge-turtlebot4
    network_mode: "host"
    restart: always # Ensures the container restarts on reboot

The TurtleBot4 will now be more stable, can discover other computers running Zenoh, send them Zenoh messages, and also, accept Zenoh messages and forward them to ROS2.

  1. On the TurtleBot4 command line, test the system:
ros2 topic list
ros2 action list
ros2 topic echo /$URID/pi/scan

To spin the robot, for example, on the TurtleBot4 command line issue:

ros2 topic pub /$URID/c3/cmd_vel geometry_msgs/msg/Twist "linear:
  x: -0.5
  y: 0.0
  z: 0.0
angular:
  x: 0.0
  y: 0.0
  z: 0.1"

To debug movement, use ros2 topic info /$URID/pi/cmd_vel --verbose.

​
Enable full motion control

To enable full range of motion, set /$URID/c3/motion_control safety_override to the desired value. This removes the cliff protection, which limits backwards movements to 1 cm.

The best way to change this setting is via the Create3’s App config page at its web server (e.g. 192.168.1.XXX:8080/ros-config). In the Application ROS 2 Parameters File window, add your Create3 ROS2 namespace, such as /OM123435Cc1234/c3/ and then select your desired safety_override options. For example, an Application ROS 2 Parameters File could look like this:

/OM123435Cc1234/c3/motion_control:
  ros__parameters:
    # safety_override options are 
    # "none" - standard safety profile, robot cannot backup more than an inch because of lack of cliff protection in rear, max speed 0.306m/s
    # "backup_only" - allow backup without cliff safety, but keep cliff safety forward and max speed at 0.306m/s
    # "full" - no cliff safety, robot will ignore cliffs and set max speed to 0.46m/s
    safety_override: "full"

​
Run OM1 on the Internal RPi4

Important: Make sure your Raspberry Pi 4 is running Ubuntu 22.04.4 LTS and that the Create 3 is running H.2.6/Create3-H.2.6.swu (see Suggested Operating System Versions). Among other possible problems, running Ubuntu 24 will create compatibility issues with the version of ROS2 and CycloneDDS on the Create 3.

On the RPi terminal command line, follow instructions 1 - 3 above. When you see all the right topics listed in ros2 topic list, your TurtleBot4 is set up and you are ready to install OM1.

  • Install uv - use curl -LsSf https://astral.sh/uv/install.sh | sh.

  • Install portaudio and other dependencies

sudo apt install pulseaudio pulseaudio-utils ffmpeg portaudio19-dev python-all-dev

  • Connect a Logitech 270 Webcam (or equivalent).

  • Unplug the standard TurtleBot4 Depth Camera.

  • Connect a speaker to RPi with a 3.5 mm audio patch cable (or use bluetooth, depending on your pain threshold and patience with debugging bluetooth issues).

  • Create a .env file

cp env.example .env

and then use vim to set your OM_API_KEY and URID

  • Set Default Input and Output Audio devices

Use pactl to set your default microphone and speaker.

If you get pa_context_connect() failed: Connection refused, then start the audio daemon manually via pulseaudio --start -D.

pactl list sources short                             # List input (microphone) devices
pactl list sinks short                               # List output (speaker) devices

pactl set-default-sink [SINK_NAME || SINK_ID]        # Set default output device
pactl set-default-source [SOURCE_NAME || SOURCE_ID]  # Set default input device
pactl set-sink-volume @DEFAULT_SINK@ 100%            # Set default output volume

# for example,
pactl set-default-source alsa_input.usb-046d_C270_HD_WEBCAM_2CD9A910-02.mono-fallback
pactl set-default-sink alsa_output.platform-bcm2835_audio.stereo-fallback
  • Boot OM1

Finally, run

Run Robot
uv run src/run.py turtlebot4

On the RPi4, there will be a lengthy delay before OM1 runs.

​
Run OM1 on an External Development Computer (e.g. Mac Laptop)

Install Zenoh on your Mac, PC, or Linux box, following Installing the Zenoh router

Please make sure that your development machine (e.g. your laptop) is running the same version of the Zenoh bridge (e.g. 1.2.1) as the RPi otherwise you will get errors.

Set up OM1 on your machine, for example, following the spot example. Then, run

Run Robot
uv run src/run.py turtlebot4

Congratulations - Your laptop is now controlling the TurtleBot4!

​
Interacting with TurtleBot4 from a Remote Computer using Zenoh

Inside system_hw_test, there are several scripts for you to interact with the TurtleBot4. For all these scripts, please provide/update the topic names to include your specific namespace. If you do not update the namespaces, the scripts will fail.

Steer the TurtleBot4 with your keyboard:

uv run turtlebot4_keyboard_movement.py
  • W - Move Forward
  • S - Move Backward
  • A - Turn Left
  • D - Turn Right

Read TurtleBot4 laser scan, collision, and battery data:

uv run turtlebot4_laserscan.py

Read TurtleBot4 Camera PREVIEW (250x250RGB) data:

uv run turtlebot4_camera_opencv.py

​
Expected ROS2 Topics for a Correctly Configured System

On the TurtleBot4 command line, run ros2 topic list. Topics with a pi prefix originate from the RPi, and topics without a prefix are from the Create3. If you do not see any non-prefixed topics, your Create3 is not talking correctly to the RPi.

/OM742d35Cc6634/c3/battery_state
/OM742d35Cc6634/c3/cmd_vel
/OM742d35Cc6634/c3/dock_status
/OM742d35Cc6634/c3/hazard_detection
/OM742d35Cc6634/c3/imu
/OM742d35Cc6634/c3/odom
/OM742d35Cc6634/c3/robot_state/transition_event
/OM742d35Cc6634/c3/static_transform/transition_event
/OM742d35Cc6634/c3/tf
/OM742d35Cc6634/c3/tf_static

/OM742d35Cc6634/pi/battery_state
/OM742d35Cc6634/pi/cmd_vel
/OM742d35Cc6634/pi/diagnostics
/OM742d35Cc6634/pi/diagnostics_agg
/OM742d35Cc6634/pi/diagnostics_toplevel_state
/OM742d35Cc6634/pi/dock_status
/OM742d35Cc6634/pi/function_calls
/OM742d35Cc6634/pi/hazard_detection
/OM742d35Cc6634/pi/hmi/buttons
/OM742d35Cc6634/pi/hmi/display
/OM742d35Cc6634/pi/hmi/display/message
/OM742d35Cc6634/pi/hmi/led
/OM742d35Cc6634/pi/imu
/OM742d35Cc6634/pi/interface_buttons
/OM742d35Cc6634/pi/ip
/OM742d35Cc6634/pi/joint_states
/OM742d35Cc6634/pi/joy
/OM742d35Cc6634/pi/joy/set_feedback
/OM742d35Cc6634/pi/mouse
/OM742d35Cc6634/pi/oakd/imu/data
/OM742d35Cc6634/pi/oakd/rgb/preview/camera_info
/OM742d35Cc6634/pi/oakd/rgb/preview/image_raw
/OM742d35Cc6634/pi/oakd/rgb/preview/image_raw/compressed
/OM742d35Cc6634/pi/oakd/rgb/preview/image_raw/compressedDepth
/OM742d35Cc6634/pi/oakd/rgb/preview/image_raw/theora
/OM742d35Cc6634/pi/robot_description
/OM742d35Cc6634/pi/scan
/OM742d35Cc6634/pi/tf
/OM742d35Cc6634/pi/tf_static
/OM742d35Cc6634/pi/wheel_status

/diagnostics
/parameter_events
/rosout

​
Building the Docker Dual Bridge Images

You can build your own dual bridge docker images using the provided Dockerfile (see /system_hw_test/turtlebot_zenoh/Dockerfile):

docker build -t my-username/my-image .
docker push my-username/my-image

Useful docker commands

sudo docker compose pull # pull latest image

# Images
sudo docker images
sudo docker rmi IMAGE_ID --force

# Containers
sudo docker ps -a
sudo docker attach CONTAINER_ID # to stream logs
sudo docker exec -it CONTAINER_ID sh # to get a shell
sudo docker kill CONTAINER_ID

​
Debugging Commands

Webcam debugging:

lsusb
sudo apt install v4l-utils
v4l2-ctl --list-devices
v4l2-ctl -d /dev/video0 --stream-mmap --all

Was this page helpful?