TurtleBot 4 Setup

The turtlebot4_setup repository contains scripts, configurations, and tools used for setting up and configuring the TurtleBot 4.

Source code is available here.

Install Scripts

Warning

ROS 2 Galactic is no longer supported. Please consider upgrading to a newer release

There are several install scripts that are used to set up the TurtleBot 4 image.

Script	Usage	Description
turtlebot4_setup.sh	`bash turtlebot4_setup.sh -m [model]`	This script should be used on a clean Ubuntu 20.04 Server image. It sets up installs ROS 2 Galactic as well as other dependencies of the TurtleBot 4. It will also install configuration files to their appropriate locations.
galactic.sh	`bash galactic.sh`	Installs ros-galactic-ros-base as well as other useful packages. It is called from turtlebot4_setup.sh.
bluetooth.sh	`bash bluetooth.sh`	Installs bluetooth packages.
sd_flash.sh	`sudo sd_flash.sh /path/to/image`	Flashes a RPi image to a microSD card. It is used from a PC.
install.py	`install.py [domain]` (v0.1.2) `install.py --domain [domain] --rmw [rmw]` (v0.1.3)	Installs the robot_upstart job.
uninstall.py	`uninstall.py`	Uninstalls the robot_upstart job.
create_update.sh	`create_update.sh /path/to/firmware.swu`	Send a firmware file to the Create® 3 to update it.

Note

TurtleBot 4’s come with an already set up RPi4 image, so these scripts will not be needed for most users.

There are several install scripts that are used to set up the TurtleBot 4 image.

Script	Usage	Description
turtlebot4_setup.sh	`bash turtlebot4_setup.sh -m [model]`	This script should be used on a clean Ubuntu 22.04 Server image. It sets up installs ROS 2 Humble as well as other dependencies of the TurtleBot 4.
humble.sh	`bash humble.sh`	Installs ros-humble-ros-base as well as other useful packages. It is called from turtlebot4_setup.sh.
bluetooth.sh	`bash bluetooth.sh`	Installs bluetooth packages.
sd_flash.sh	`sudo sd_flash.sh /path/to/image`	Flashes a RPi image to a microSD card. It is used from a PC.
create_update.sh	`create_update.sh /path/to/firmware.swu`	Send a firmware file to the Create® 3 to update it.

Note

TurtleBot 4’s come with an already set up RPi4 image, so these scripts will not be needed for most users.

There are several install scripts that are used to set up the TurtleBot 4 image.

Script	Usage	Description
turtlebot4_setup.sh	`bash turtlebot4_setup.sh -m [model]`	This script should be used on a clean Ubuntu 24.04 Server image. It sets up installs ROS 2 Jazzy as well as other dependencies of the TurtleBot 4.
jazzy.sh	`bash jazzy.sh`	Installs ros-jazzy-ros-base as well as other useful packages. It is called from turtlebot4_setup.sh.
bluetooth.sh	`bash bluetooth.sh`	Installs bluetooth packages.
sd_flash.sh	`sudo sd_flash.sh /path/to/image`	Flashes a RPi image to a microSD card. It is used from a PC.
create_update.sh	`create_update.sh /path/to/firmware.swu`	Send a firmware file to the Create® 3 to update it.

Note

TurtleBot 4’s come with an already set up RPi4 image, so these scripts will not be needed for most users.

Configuration Tools

Warning

ROS 2 Galactic is no longer supported. Please consider upgrading to a newer release

Configuration Scripts

These scripts are installed in the /usr/local/bin folder and are used to configure the robot.

Script	Usage	Description
wifi.sh	`sudo wifi.sh -s [ssid] -p [password] -r [regulatory domain]`	Set up netplan to connect to a Wi-Fi network.
swap_on.sh	`swap_on.sh`	Add 4 GB of swap memory. Useful when building packages from source.
swap_off.sh	`swap_off.sh`	Remove swap memory.
ros_config.sh (v0.1.3 only)	`ros_config.sh`	Configure ROS_DOMAIN_ID and RMW.

Setup Tool

In Humble, the TurtleBot 4 has a new command line setup tool that simplifies the configuration process. The tool can be run on the TurtleBot 4 by calling:

turtlebot4-setup

ros2 run turtlebot4_setup turtlebot4_setup

You will be greeted by a menu with several submenus. From here you can navigate between the menus and configure your robot.

Usage

Warning

You must select the Apply Settings option and press Enter before quitting to apply any changes you have made to the robot. Quitting without applying the settings will discard any changes you have staged.

You can navigate up and down between the menus by using the up and down arrow keys, or j and k. To select a menu, press Enter. To return or exit from a menu, you can press q, Esc, or CTRL+C. Some menus may only be exited with CTRL+C.

Menu items that indicate a variable and its value will prompt you for an input. Type in your input and press Enter to set the value. You may press Enter without any input to set the value to an empty string. You can also press CTRL+C to return without changing the value. Some input prompts such as ROS_DOMAIN_ID may check that your input is valid.

Once you have input all of your changes, you will need to select Save to apply the settings to your configuration files. You can also select Apply Defaults to revert all values for this menu to defaults.

After you have saved all of the changes that you wanted, you can view the configuration files by selecting View Settings in the main "TurtleBot4 Setup" menu. When you are happy with the changes, select Apply Settings. This will open a new menu that will show you all of the changes that were saved, and prompt you for confirmation. If confirmed, the setup tool will run various commands based on which settings were changed.

Note

Changes to the ROS_DOMAIN_ID, ROBOT_NAMESPACE, RMW_IMPLEMENTATION or ROS_DISCOVERY_SERVER environment variables will be applied to the Create® 3 as well, causing it to reboot. This includes all changes made in the Discovery Server menu.

Changes made to Wi-Fi settings will cause your SSH session to hang, and the RPi4 to reboot. This will look like the Raspberry Pi stopped communicated but is expected. You will need to close the terminal, wait for the robot to fully reboot and then initiate a new SSH connection.

ROS Setup

The ROS Setup menu is used to configure the ROS environment. ROS and system configuration files are located in the /etc/turtlebot4/ folder on the RPi4.

File	Description
aliases.bash	Contains helpful bash aliases
cyclonedds_rpi.xml	Default CycloneDDS configuration
discovery.sh	Script that starts a discovery server
fastdds_discovery_create3.xml	FastDDS configuration for the Create 3 in Discovery Server
fastdds_rpi.xml	Default FastDDS configuration
setup.bash	Bash file that exports environment variables to configure ROS 2. This file is sourced in .bashrc such that the environment is applied to all terminals
system	Text file with system information such as version number and TurtleBot 4 model

There are currently 3 ROS Setup submenus: Bash Setup, Discovery Server, and Robot Upstart.

Bash Setup

The Bash Setup menu allows the user to make changes to the /etc/turtlebot4/setup.bash file. This file sets environment variables that affect ROS 2.

Environment Variable	Description	Default
CYCLONEDDS_URI	Path to CycloneDDS configuration	/etc/turtlebot4/cyclonedds_rpi.xml
FASTRTPS_DEFAULT_PROFILES_FILE	Path to FastDDS configuration	/etc/turtlebot4/fastdds_rpi.xml
ROBOT_NAMESPACE	Sets the robots namespace.
ROS_DOMAIN_ID	Sets the robots domain ID. Defaults to 0.	0
RMW_IMPLEMENTATION	Set the RMW implementation (rmw_fastrtps_cpp, rmw_cyclonedds_cpp)	rmw_fastrtps_cpp
TURTLEBOT4_DIAGNOSTICS	Enable or disable TurtleBot 4 diagnostics	1
WORKSPACE_SETUP	Path to the workspace setup.bash file	/opt/ros/humble/setup.bash

Discovery Server

The Discovery Server menu allows the user to enable or disable the onboard discovery server, as well as set the Server ID and Port for the onboard server. The menu also allows for selecting one additional discovery server for the robot to connect to although it is not advisable for beginners. See the discovery server page for an example on how to set up a two robot system.

Setting	Description	Default
Enabled	Whether to use Discovery Server mode	False
Onboard Server - Port	Discovery server port for the onboard server	11811
Onboard Server - Server ID	Discovery server ID for the onboard server	0
Offboard Server - IP	IP address of an optional offboard Discovery Server to connect to (disabled if set as blank)	blank
Offboard Server - Port	Discovery server port for the offboard server	11811
Offboard Server - Server ID	Discovery server ID for the offboard server	1

Note

Enabling the discovery server will also set RMW_IMPLEMENTATION to rmw_fastrtps_cpp.

Discovery server settings are applied to the DISCOVERY_SERVER environment variable in /etc/turtlebot4/setup.bash.

Robot Upstart

The robot upstart menu has menu options for interacting with the robot_upstart job that runs the TurtleBot 4 nodes as a background service.

Menu Option	Description	Bash equivalent
Restart	Restart the `robot_upstart` job.	`sudo systemctl restart turtlebot4.service`
Start	Start the `robot_upstart` job if it is not running.	`sudo systemctl start turtlebot4.service`
Stop	Stop the `robot_upstart` job if it is running.	`sudo systemctl stop turtlebot4.service`
Install	Install or reinstall the `robot_upstart` job with current ROS settings.	`install.py [model]`
Uninstall	Uninstall the `robot_upstart` job. The service will no longer run on boot.	`uninstall.py`

Wi-Fi Setup

The Wi-Fi Setup menu allows users to easily connect the TurtleBot 4 to their Wi-Fi network, as well as configure the connection.

Menu Option	Description	Default
Wi-Fi Mode	Set the RPi4 to act as a Wi-Fi access point or client	Access Point
SSID	The SSID of the Wi-Fi network. In access point mode, this is the name of the network that will be broadcasted.	Turtlebot4
Password	The password of the Wi-Fi network. This can be left empty.	Turtlebot4
Band	Which Wi-Fi band to use. Set to 'Any' if unsure.	5GHz
IP Address	Sets a static IP address for the `wlan0` interface.
DHCP	Whether to use DHCP to dynamically set an IP address.	True

Bluetooth Setup

This menu option launches bluetoothctl and allows you to pair and connect to a bluetooth device. See TurtleBot 4 Controller Setup for details.

View Settings

The View Settings menu lists the TurtleBot 4 configuration files and allows you to preview them by navigating to each file.

Changes you saved in other menus will be reflected here.

Apply Settings

Selecting "Apply Settings" will prompt the user to confirm that they want to apply these settings. It will also list all of the changes that will be applied. When confirmed, the setup tool will run various commands based on which settings were changed.

Note

If settings that affect the Create® 3 were changed, those changes will be sent to the base over USB-C,and the Create® 3 will then reboot to apply the settings. Changes to the Wi-Fi network will cause the tool to runsudo netplan apply && sudo reboot, causing the RPi4 to update its network settings before rebooting. This will cause any SSH session to hang.

Once settings have been applied, you can exit the setup tool. If there were changes made to environment variables, you will need to run turtlebot4-source or source $ROBOT_SETUP to apply them to your current terminal. Changes will be automatically applied to any new terminals.

About

The "About" menu displays system information and has menu options to change the TurtleBot 4 model and hostname.

Warning

Changing the model to not match the physical robot model is not recommended.

Setup Tool

In Jazzy, the TurtleBot 4 has a command line setup tool that simplifies the configuration process. The tool can be run on the TurtleBot 4 by calling:

turtlebot4-setup

ros2 run turtlebot4_setup turtlebot4_setup

You will be greeted by a menu with several submenus. From here you can navigate between the menus and configure your robot.

Usage

Warning

Note

ROS Setup

The ROS Setup menu is used to configure the ROS environment. ROS and system configuration files are located in the /etc/turtlebot4/ folder on the RPi4.

File	Description
aliases.bash	Contains helpful bash aliases
cyclonedds_rpi.xml	Default CycloneDDS configuration
discovery.sh	Script that starts a discovery server
fastdds_discovery_create3.xml	FastDDS configuration for the Create 3 in Discovery Server
fastdds_rpi.xml	Default FastDDS configuration
setup.bash	Bash file that exports environment variables to configure ROS 2. This file is sourced in .bashrc such that the environment is applied to all terminals
system	Text file with system information such as version number and TurtleBot 4 model

There are currently 3 ROS Setup submenus: Bash Setup, Discovery Server, and Robot Upstart.

Bash Setup

The Bash Setup menu allows the user to make changes to the /etc/turtlebot4/setup.bash file. This file sets environment variables that affect ROS 2.

Environment Variable	Description	Default
CYCLONEDDS_URI	Path to CycloneDDS configuration	/etc/turtlebot4/cyclonedds_rpi.xml
FASTRTPS_DEFAULT_PROFILES_FILE	Path to FastDDS configuration	/etc/turtlebot4/fastdds_rpi.xml
ROBOT_NAMESPACE	Sets the robots namespace.
ROS_DOMAIN_ID	Sets the robots domain ID. Defaults to 0.	0
RMW_IMPLEMENTATION	Set the RMW implementation (rmw_fastrtps_cpp, rmw_cyclonedds_cpp). The selected implementation must match the one supported by the Create® 3 firmware installed on the base platform	rmw_fastrtps_cpp
TURTLEBOT4_DIAGNOSTICS	Enable or disable TurtleBot 4 diagnostics	1
WORKSPACE_SETUP	Path to the workspace setup.bash file	/opt/ros/jazzy/setup.bash

Discovery Server

Setting	Description	Default
Enabled	Whether to use Discovery Server mode	False
Onboard Server - Port	Discovery server port for the onboard server	11811
Onboard Server - Server ID	Discovery server ID for the onboard server	0
Offboard Server - IP	IP address of an optional offboard Discovery Server to connect to (disabled if set as blank)	blank
Offboard Server - Port	Discovery server port for the offboard server	11811
Offboard Server - Server ID	Discovery server ID for the offboard server	1

Note

Enabling the discovery server will also set RMW_IMPLEMENTATION to rmw_fastrtps_cpp.

Discovery server settings are applied to the DISCOVERY_SERVER environment variable in /etc/turtlebot4/setup.bash.

Robot Upstart

The robot upstart menu has menu options for interacting with the robot_upstart job that runs the TurtleBot 4 nodes as a background service.

Menu Option	Description	Bash equivalent
Restart	Restart the `robot_upstart` job.	`sudo systemctl restart turtlebot4.service`
Start	Start the `robot_upstart` job if it is not running.	`sudo systemctl start turtlebot4.service`
Stop	Stop the `robot_upstart` job if it is running.	`sudo systemctl stop turtlebot4.service`
Install	Install or reinstall the `robot_upstart` job with current ROS settings.	`install.py [model]`
Uninstall	Uninstall the `robot_upstart` job. The service will no longer run on boot.	`uninstall.py`

Wi-Fi Setup

The Wi-Fi Setup menu allows users to easily connect the TurtleBot 4 to their Wi-Fi network, as well as configure the connection.

Menu Option	Description	Default
Wi-Fi Mode	Set the RPi4 to act as a Wi-Fi access point or client	Access Point
SSID	The SSID of the Wi-Fi network. In access point mode, this is the name of the network that will be broadcasted.	Turtlebot4
Password	The password of the Wi-Fi network. This can be left empty.	Turtlebot4
Band	Which Wi-Fi band to use. Set to 'Any' if unsure.	5GHz
IP Address	Sets a static IP address for the `wlan0` interface.
DHCP	Whether to use DHCP to dynamically set an IP address.	True

Bluetooth Setup

This menu option launches bluetoothctl and allows you to pair and connect to a bluetooth device. See TurtleBot 4 Controller Setup for details.

View Settings

The View Settings menu lists the TurtleBot 4 configuration files and allows you to preview them by navigating to each file.

Changes you saved in other menus will be reflected here.

Apply Settings

Note

Reset Create3

Selecting "Reset Create3" will reconfigure the Create® 3's domain ID, namespace, and discovery server settings to match the current Raspberry Pi configuration. No changes are made to the Raspberry Pi itself: only the Create® 3 settings are modified.

About

The "About" menu displays system information and has menu options to change the TurtleBot 4 model and hostname.

Warning

Changing the model to not match the physical robot model is not recommended.