install.py --domain [domain] --rmw [rmw]
(v0.1.3) uninstall.py
create_update.sh /path/to/firmware.swu
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. |
TurtleBot 4’s come with an already set up RPi4 image, so these scripts will not be needed for most users.
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
or
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
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.
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 |
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.
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.
Changing the model to not match the physical robot model is not recommended.