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

    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.

    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

    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.

    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). 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

    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.


    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.