diff --git a/.debug.yml b/.debug.yml index 42d0416..9b98f1a 100644 --- a/.debug.yml +++ b/.debug.yml @@ -1,8 +1,4 @@ -remote_theme: false - debug: compress: false dist: true - shortcodes: true - -theme: jekyll-rtd-theme \ No newline at end of file + shortcodes: true \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/1-bug.yml b/.github/ISSUE_TEMPLATE/1-bug.yml index e1d2ea5..e80731e 100644 --- a/.github/ISSUE_TEMPLATE/1-bug.yml +++ b/.github/ISSUE_TEMPLATE/1-bug.yml @@ -30,6 +30,7 @@ body: - Select One - Galactic - Humble + - Jazzy validations: required: true - type: dropdown @@ -52,6 +53,7 @@ body: - Select One - Ubuntu 20.04 - Ubuntu 22.04 + - Ubuntu 24.04 - Other Linux - Windows / MAC validations: diff --git a/README.md b/README.md index 4c575fe..7044c80 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ This repository contains the source code for building the Turtlebot4 User Manual ## Build -To build the Turtlebot4's User Manual locally, first [install Ruby version 2.7.7](https://gorails.com/setup/ubuntu/22.04) +To build the Turtlebot4's User Manual locally, first [install Ruby version 3.2](https://gorails.com/setup/ubuntu/24.04) You can check your ruby the version using: ```bash @@ -14,26 +14,24 @@ Ensure that it is showing the correct version.

- Using Ruby 3+ - Ruby 3+ isn't recommended due to [this issue](https://talk.jekyllrb.com/t/error-no-implicit-conversion-of-hash-into-integer/5890/2). Unfortunately, Ruby 3+ is required for `sass-converter` to be installed; a dependency of jekyll. If you don't want to (or can't) juggle multiple Ruby versions, you can run this patch to fix Ruby 3+ such that it works with Github Pages. - -```shell -sudo sed -i.bak 's/, kwd/, **kwd/' $(gem which pathutil) -``` + Configuring Ubuntu 24.04 + By default, Ubuntu 24.04 uses a debian-packaged version of Ruby, which installs gems to a root-owned path. This makes installing additional gems problematic. + To work around this issue, run the following commands: + ```shell + mkdir $HOME/.ruby + echo 'export GEM_HOME=$HOME/.ruby/' >> $HOME/.bashrc + echo 'export PATH="$PATH:$HOME/.ruby/bin"' >> $HOME/.bashrc + source $HOME/.bashrc + ``` + This will make the `gem` command install Ruby gems to your local user's `.ruby` directory.

-If you get the warning "No version is set for command ruby" then you need to set the active ruby version in asdf: -```bash -asdf global ruby 2.7.7 -``` Ensure your Ruby gems are up to date: -```bash +```shell gem update --system ``` -Next [install Jekyll and the rest of the prerequisites](https://jekyllrb.com/docs/). Be careful to not overwrite the Ruby version. - Clone this repository: ```bash @@ -45,7 +43,8 @@ Build and start a local server: ```bash cd turtlebot4-user-manual make +make update make server ``` -The webpage will now be available at `127.0.0.1:4000` +The webpage will now be available at `http://127.0.0.1:4000/turtlebot4-user-manual` diff --git a/_includes/templates/addons.liquid b/_includes/templates/addons.liquid index 74b2f33..fc44fa1 100644 --- a/_includes/templates/addons.liquid +++ b/_includes/templates/addons.liquid @@ -5,7 +5,7 @@
- v1.0.0 + v2.0.0
diff --git a/changelogs/galactic.md b/changelogs/galactic.md index 8a0a3ad..b000d32 100644 --- a/changelogs/galactic.md +++ b/changelogs/galactic.md @@ -4,6 +4,10 @@ sort: 1 # TurtleBot 4 Galactic +```warning +**ROS 2 Galactic is no longer supported.** Please consider updating to a newer release +``` + TurtleBot 4 RPi4 image changelogs. Latest images are available [here](http://download.ros.org/downloads/turtlebot4/). ## v0.1.3 @@ -19,7 +23,7 @@ TurtleBot 4 RPi4 image changelogs. Latest images are available [here](http://dow - Added a service to forward the Create® 3 webserver through the RPi4 - Users can now access the Create® 3 webserver by navigating to the IP address of their TurtleBot 4 with the port 8080 on a web browser. - The Create® 3 does not need to be placed into AP mode to access the webserver. - - Example: TurtleBot 4 with an IP address of `192.168.0.187`. + - Example: TurtleBot 4 with an IP address of `192.168.0.187`. - Enter `192.168.0.187:8080` into your browser:
Webserver diff --git a/changelogs/jazzy.md b/changelogs/jazzy.md new file mode 100644 index 0000000..93e35b4 --- /dev/null +++ b/changelogs/jazzy.md @@ -0,0 +1,83 @@ +--- +sort: 3 +--- + +# TurtleBot 4 Jazzy + +TurtleBot 4 RPi4 image changelogs. Latest images are available [here](http://download.ros.org/downloads/turtlebot4/). + +## v2.0.0 + +**OS**: Ubuntu Server 24.04.5 LTS + +**ROS**: Jazzy + +**Create® 3 Firmware**: I.0.0 + +### General + +- Due to technical limitations, the Create3 firmware only supports FastRTPS or CycloneDDS; changing + RMW implementations requires installing the correct firwmare version on the Create3 +- Updated `install.py` to support Jazzy +- Use `create3_republisher` by default to expose base platform topics from the RPi4 +- ROS Control changes to use `TwistStamped` messages for velocity control instead of `Twist` +- Renamed `ignition` and `ign` packages & launch files to use preferred `gz` nomenclature + +### TurtleBot 4 Packages + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
PackageVersionChanges
turtlebot4_base2.0.0-
turtlebot4_bringup2.0.0-
turtlebot4_description2.0.0-
turtlebot4_diagnostics2.0.0-
turtlebot4_msgs2.0.0-
turtlebot4_navigation2.0.0-
turtlebot4_node2.0.0-
turtlebot4_robot2.0.0-
turtlebot4_tests2.0.0-
diff --git a/overview/resources.md b/overview/resources.md index 0c5513b..73d8c03 100644 --- a/overview/resources.md +++ b/overview/resources.md @@ -9,6 +9,7 @@ sort: 2 ### Ubuntu - Ubuntu 20.04 LTS Desktop (Focal Fossa): - Ubuntu 22.04 LTS Desktop (Jammy Jellyfish): + - Ubuntu 24.04 LTS Desktop (Noble Numbat): ### Raspberry Pi - Raspberry Pi Imager: @@ -17,7 +18,7 @@ sort: 2 ### ROS 2 - Documentation: - Ubuntu (Debian) Install: - - Nav2 Documentation: + - Nav2 Documentation: - Nav2 Github: - SLAM Toolbox: diff --git a/setup/basic.md b/setup/basic.md index 5a71a59..7a9dbf8 100644 --- a/setup/basic.md +++ b/setup/basic.md @@ -15,6 +15,10 @@ To interface with the robot, it is recommended to use a remote PC running the ap {% tabs installation %} {% tab installation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` + Required OS: [Ubuntu 20.04](https://releases.ubuntu.com/20.04/) Follow [these instructions](https://docs.ros.org/en/galactic/Installation/Ubuntu-Install-Debians.html) to install ROS 2 Galactic on your PC. @@ -38,6 +42,19 @@ Once ROS 2 is installed, install `turtlebot4_desktop`: sudo apt update && sudo apt install ros-humble-turtlebot4-desktop ``` +{% endtab %} +{% tab installation jazzy %} + +Required OS: [Ubuntu 24.04](https://releases.ubuntu.com/24.04/) + +Follow [these instructions](https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debians.html) to install ROS 2 Jazzy on your PC. + +Once ROS 2 is installed, install `turtlebot4_desktop`: + +```bash +sudo apt update && sudo apt install ros-jazzy-turtlebot4-desktop +``` + {% endtab %} {% endtabs %} @@ -61,7 +78,7 @@ The TurtleBot 4 AP network is a 5GHz network. Your computer will need to support ### SSH into the Raspberry Pi -Once connected, you can SSH into the Raspberry Pi to configure its Wi-Fi. Open a terminal on your PC and call: +Once connected, you can SSH into the Raspberry Pi to configure its Wi-Fi. Open a terminal on your PC and call: ```bash ssh ubuntu@10.42.0.1 @@ -80,6 +97,10 @@ Connect the Raspberry Pi to a 5GHz Wi-Fi network for optimal performance. {% tabs wifi %} {% tab wifi galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` + In your SSH session, call: ```bash @@ -110,12 +131,32 @@ This will start the TurtleBot 4 setup tool. Navigate to the "Wi-Fi Setup" menu a Change your Wi-Fi mode to 'Client' when connecting to an existing network. ``` +{% endtab %} +{% tab wifi jazzy %} + +In your SSH session, run the [TurtleBot 4 setup tool](../software/turtlebot4_setup.md#configuration-tools): + +```bash +turtlebot4-setup +``` + +This will start the TurtleBot 4 setup tool. Navigate to the "Wi-Fi Setup" menu and configure your connection. When you have finished, save and apply the settings. + +
+ Wi-Fi setup +
Wi-Fi Setup using the TurtleBot 4 Setup tool
+
+ +```note +Change your Wi-Fi mode to 'Client' when connecting to an existing network. +``` + {% endtab %} {% endtabs %} ### Find the new Raspberry Pi IP -Once the Wi-Fi settings are applied, the Raspberry Pi will reboot and connect to your network. DHCP will assign it a new IP address. On the TurtleBot 4, this IP address will be shown at the top of the display. +Once the Wi-Fi settings are applied, the Raspberry Pi will reboot and connect to your network. DHCP will assign it a new IP address. On the TurtleBot 4, this IP address will be shown at the top of the display.
IP Address @@ -127,6 +168,10 @@ For the TurtleBot 4 Lite, you will need to check the `/ip` topic for the new add {% tabs ip %} {% tab ip galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` + On your PC, run the following commands: ```bash @@ -148,6 +193,18 @@ export ROS_DOMAIN_ID=0 ros2 topic echo /ip ``` +{% endtab %} +{% tab ip jazzy %} + +On your PC, run the following commands: + +```bash +source /opt/ros/humble/setup.bash +export RMW_IMPLEMENTATION=rmw_fastrtps_cpp +export ROS_DOMAIN_ID=0 +ros2 topic echo /ip +``` + {% endtab %} {% endtabs %} @@ -197,6 +254,34 @@ It is recommended to update both the Create® 3 and the Raspberry Pi when you fi Check the [Create® 3 software releases](https://iroboteducation.github.io/create3_docs/releases/overview/) to see if a newer firmware version is available. You can check the firmware version of your Create® 3 by visiting the webserver. +{% tabs firmware %} +{% tab firmware galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` + +```note +If you are using ROS 2 Galactic, make sure you install firmware with version `G.*.*`; firmware versions starting with `H` or `I` are _not_ compatible with Galactic. +``` +{% endtab %} +{% tab firmware humble %} +```note +If you are using ROS 2 Humble, make sure you install firmware with version `H.*.*`; firmware versions starting with `G` or `I` are _not_ compatible with Humble. +``` +{% endtab %} +{% tab firmware jazzy %} +```note +If you are using ROS 2 Jazzy, make sure you install firmware with version `I.*.*`; firmware versions starting with `G` or `H` are _not_ compatible with Jazzy. +``` + +```warning +Unlike previous versions, the Create® 3 firmware `I.*.*` does _not_ support switching between FastDDS and CycloneDDS. Instead there are two separate versions of the firmware available, each supporting one RMW implementation. When installing the firmware on your Create® 3 you _must_ use the firmware that corresponds to the middleware you intend to use. + +For ROS 2 Jazzy, the default is FastDDS. Unless you have specific reasons for using CycloneDDS, it is recommended to use the FastDDS firmware on your Create® 3. +``` +{% endtab %} +{% endtabs %} + If new firmware is available, download it, then access the [webserver](./basic.md#accessing-the-create-3-webserver). Go to the Update tab, upload the firmware, then update your robot. #### Raspberry Pi packages @@ -253,6 +338,9 @@ Placing the Raspberry Pi into Access Point mode can be useful when using the rob {% tabs ap %} {% tab ap galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` SSH into the Raspberry Pi and call: @@ -279,13 +367,22 @@ turtlebot4-setup Go to Wi-Fi Setup and select Apply Defaults. Optionally you can set your own SSID and password before saving and applying the new settings. +{% endtab %} +{% tab ap jazzy %} + +SSH into the Raspberry Pi and run the [TurtleBot 4 setup tool](../software/turtlebot4_setup.md#configuration-tools): + +```bash +turtlebot4-setup +``` + +Go to Wi-Fi Setup and select Apply Defaults. Optionally you can set your own SSID and password before saving and applying the new settings. + {% endtab %} {% endtabs %} ```tip -If you are moving your TurtleBot 4 to a new location with a different Wi-Fi network, -reconfigure the Raspberry Pi to connect to that network beforehand or place it into AP mode. -Otherwise it will continue trying to connect to your current network. +If you are moving your TurtleBot 4 to a new location with a different Wi-Fi network, reconfigure the Raspberry Pi to connect to that network beforehand or place it into AP mode. Otherwise it will continue trying to connect to your current network. ``` ## Troubleshooting @@ -327,8 +424,8 @@ Installing a new image on the Raspberry Pi will delete any changes you may have Find the latest TurtleBot 4 Raspberry Pi images at . -- Download the latest image for the given ROS distribution and robot model. -- Extract the zip file to get the `.img` file +- Download the latest image for the given ROS distribution and robot model. +- Extract the zip file to get the `.img` file - Power off your robot and then remove the microSD card from the Raspberry Pi. - Insert the microSD card into your PC. You may need an adapter. - Install the imaging tool `dcfldd` @@ -357,12 +454,31 @@ IMAGE_PATH is the path to where you want the image saved -- e.g., `~/turtlebot4_ ``` - Get the SD flash script from `turtlebot4_setup` and flash the SD card: +{% tabs sd_flash %} +{% tab sd_flash galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` +```bash +wget https://raw.githubusercontent.com/turtlebot/turtlebot4_setup/galactic/scripts/sd_flash.sh +bash sd_flash.sh /path/to/downloaded/image.img +``` +{% endtab %} +{% tab sd_flash humble %} ```bash wget https://raw.githubusercontent.com/turtlebot/turtlebot4_setup/humble/scripts/sd_flash.sh bash sd_flash.sh /path/to/downloaded/image.img ``` -- Follow the instructions and wait for the SD card to be flashed. +{% endtab %} +{% tab sd_flash jazzy %} +```bash +wget https://raw.githubusercontent.com/turtlebot/turtlebot4_setup/jazzy/scripts/sd_flash.sh +bash sd_flash.sh /path/to/downloaded/image.img +``` +{% endtab %} +{% endtabs %} +- Follow the instructions and wait for the SD card to be flashed. - Remove the SD card from your PC. - Ensure your Raspberry Pi 4 is not powered on before inserting the flashed SD card. - Follow the [Robot Setup](#robot) to configure your TurtleBot 4. \ No newline at end of file diff --git a/setup/discovery_server.md b/setup/discovery_server.md index 0376f7c..4266c66 100644 --- a/setup/discovery_server.md +++ b/setup/discovery_server.md @@ -14,7 +14,9 @@ See [Networking](./networking.md) for details. {% tabs discovery %} {% tab discovery galactic %} - +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` ```warning The Turtlebot 4 discovery server Galactic implementation does not support more than one robot in the system. Please upgrade to Humble. @@ -71,7 +73,7 @@ The Create® 3 needs to be updated to the latest firmware and have its Wi-Fi dis Setup instructions: - Update to the [latest firmware](https://iroboteducation.github.io/create3_docs/releases/overview/) using the webserver. -- Once updated, perform a [factory reset](https://iroboteducation.github.io/create3_docs/webserver/about/#:~:text=set%20to%20USB.-,Factory%20Reset,-A%20hyperlink%20to) to disconnect the Create® 3 from any Wi-Fi networks. +- Once updated, perform a [factory reset](https://iroboteducation.github.io/create3_docs/webserver/about/#:~:text=set%20to%20USB.-,Factory%20Reset,-A%20hyperlink%20to) to disconnect the Create® 3 from any Wi-Fi networks. ```note Ensure that this factory reset is done before the remaining setup as it will clear out the settings that are written to the Create® 3 by the Raspberry Pi. @@ -102,8 +104,56 @@ turtlebot4-setup - When the Create® 3 chimes, call `ros2 topic list` to view topics ```tip -When a network change occurs or a robot ROS service or robot is rebooted, you may need to restart the ros2 daemon to see the changes with the ROS 2 command line tools (ros2cli). -You may also need to call `ros2 topic list` twice to get a full list of topics. This is because the first time that you run the command, it starts the daemon which will record all of the available topics. If there are a lot of ROS nodes then it may take some time before the full topic list is available. +When a network change occurs or a robot ROS service or robot is rebooted, you may need to restart the ros2 daemon to see the changes with the ROS 2 command line tools (ros2cli). + +You may also need to call `ros2 topic list` twice to get a full list of topics. This is because the first time that you run the command, it starts the daemon which will record all of the available topics. If there are a lot of ROS nodes then it may take some time before the full topic list is available. +``` + +{% endtab %} +{% tab discovery jazzy %} + +Create® 3 + +The Create® 3 needs to be updated to the latest firmware and have its Wi-Fi disabled. + +Setup instructions: +- Update to the [latest firmware](https://iroboteducation.github.io/create3_docs/releases/overview/) using the webserver. +- Once updated, perform a [factory reset](https://iroboteducation.github.io/create3_docs/webserver/about/#:~:text=set%20to%20USB.-,Factory%20Reset,-A%20hyperlink%20to) to disconnect the Create® 3 from any Wi-Fi networks. + +```note +Ensure that this factory reset is done before the remaining setup as it will clear out the settings that are written to the Create® 3 by the Raspberry Pi. +``` + +Raspberry Pi + +The Raspberry Pi needs to be configured to host a discovery server, and the TurtleBot 4 upstart job needs to be reinstalled with the new configuration. During this step, the Raspberry Pi will also write the discovery server details to the Create® 3. + +Unlike ROS 2 Humble, the Jazzy version always uses the `create3_republisher` node to broadcast the Create® 3 topics, services, and actions from the Raspberry Pi. For more information on the `create3_republisher` see the [Create® 3 Republisher section of the Create® 3 page](../software/create3.md#create-3-republisher). + +Setup instructions: +- SSH into the Raspberry Pi +- Run the [TurtleBot 4 setup tool](../software/turtlebot4_setup.md#configuration-tools): + +```bash +turtlebot4-setup +``` +- Enter the Discovery Server menu via ROS Setup. +- Set Enabled to `True`. +- Onboard Discovery Server: This is the primary server that will connect the onboard robot nodes. + - Leave onboard server port as `11811`. + - Set the onboard server ID as a unique number in the system. If there is only one robot then this can be left as `0`. If there is more than one robot then give each robot a unique number between 0 and 255. +- Offboard Server: This allows support for the robots to communicate on an offboard server but is not recommended for beginners because it can overload the network when there are too many robots. + - Leave all of these as default. When the offboard IP address is blank then all offboard server settings will be ignored. +- Save the settings, navigate to the main menu, and apply settings. +- Exit the setup tool +- In your terminal, call `turtlebot4-source` to apply the new settings to your terminal. +- Restart the ROS 2 daemon with `turtlebot4-daemon-restart` or `ros2 daemon stop; ros2 daemon start` +- When the Create® 3 chimes, call `ros2 topic list` to view topics + +```tip +When a network change occurs or a robot ROS service or robot is rebooted, you may need to restart the ros2 daemon to see the changes with the ROS 2 command line tools (ros2cli). + +You may also need to call `ros2 topic list` twice to get a full list of topics. This is because the first time that you run the command, it starts the daemon which will record all of the available topics. If there are a lot of ROS nodes then it may take some time before the full topic list is available. ``` {% endtab %} @@ -113,6 +163,9 @@ You may also need to call `ros2 topic list` twice to get a full list of topics. {% tabs discovery %} {% tab discovery galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Because the Create® 3 is not on the same network as the user PC, an IP route has to be added on the user PC to reach the Create® 3, through the Raspberry Pi. This route must be up at all times to maintain a connection between the PC and the Create® 3. Additionally, every device in the system must use `rmw_fastrtps_cpp` as their DDS and must define the `ROS_DISCOVERY_SERVER` environment variable to inform FastDDS of the IP and port of the server. @@ -162,8 +215,9 @@ ros2 topic list ``` ```note -When a network change occurs or a robot ROS service or robot is rebooted, you may need to restart the ros2 daemon to see the changes with the ROS 2 command line tools (ros2cli). -You may also need to call `ros2 topic list` twice to get a full list of topics. This is because the first time that you run the command, it starts the daemon which will record all of the available topics. If there are a lot of ROS nodes then it may take some time before the full topic list is available. +When a network change occurs or a robot ROS service or robot is rebooted, you may need to restart the ros2 daemon to see the changes with the ROS 2 command line tools (ros2cli). + +You may also need to call `ros2 topic list` twice to get a full list of topics. This is because the first time that you run the command, it starts the daemon which will record all of the available topics. If there are a lot of ROS nodes then it may take some time before the full topic list is available. ``` {% endtab %} @@ -219,9 +273,67 @@ ros2 topic list ``` ```note -When a network change occurs or a robot ROS service or robot is rebooted, you may need to restart the ros2 daemon to see the changes with the ROS 2 command line tools (ros2cli). You may also need to call `ros2 topic list` twice to get a full list of topics. This is because the first time that you run the command, it starts the daemon which will record all of the available topics. If there are a lot of ROS nodes then it may take some time before the full topic list is available. +When a network change occurs or a robot ROS service or robot is rebooted, you may need to restart the ros2 daemon to see the changes with the ROS 2 command line tools (ros2cli). + +You may also need to call `ros2 topic list` twice to get a full list of topics. This is because the first time that you run the command, it starts the daemon which will record all of the available topics. If there are a lot of ROS nodes then it may take some time before the full topic list is available. ``` +{% endtab %} +{% tab discovery jazzy %} +In order to see all of the nodes and topics, any computer, including the user PC has to use `rmw_fastrtps_cpp` as their DDS and must define the `ROS_DISCOVERY_SERVER` environment variable to inform FastDDS of where to contact the discovery servers. + +```note +Previously the user PC needed routing configured to access the Create® 3 through the Raspberry Pi. This route is no longer necessary/used and can be removed. +``` + +A convenient script to configure the user PC exists in the [turtlebot4_setup](https://github.com/turtlebot/turtlebot4_setup/blob/jazzy/turtlebot4_discovery/configure_discovery.sh) repo. + +To download and run the script, call: + +```bash +wget -qO - https://raw.githubusercontent.com/turtlebot/turtlebot4_setup/jazzy/turtlebot4_discovery/configure_discovery.sh | bash <(cat) +#### Example User Computer Setup +From the robot configuration the robot server IDs and the ROS Domain ID are known, and from the robots themselves or the router the IP addresses are known. It is recommended that the robot IPs be reserved on the router so that they always remain the same and this process does not need to be repeated. Running the user computer configuration script as described above, would look as follows: + +``` +ROS_DOMAIN_ID [0]: 0 +Enter the information for the first discovery server +Discovery Server ID [0]: 0 +Discovery Server IP: 192.168.131.5 +Discovery Server Port [11811]: +Re-enter the last server (r), add another server (a), or done (d): a +Enter the information for the next discovery server +Discovery Server ID [0]: 1 +Discovery Server IP: 192.168.131.6 +Discovery Server Port [11811]: +Re-enter the last server (r), add another server (a), or done (d): d +Configuring: + ROS_DOMAIN_ID=0 + ROS_DISCOVERY_SERVER="192.168.131.5:11811;192.168.131.6:11811;" +[sudo] password for cpr-1234: +Source your ~/.bashrc file to apply changes +``` + +{% endtab %} +{% tab discovery jazzy %} + +### 2 Robots and 1 User Computer + +#### Recommended Architecture +Each robot is always configured with its own discovery server. This allows each robot to operate independently even if the WiFi is disconnected. Since there are two robots and therefore two discovery servers in the system, the discovery servers must be assigned unique server IDs. In this case, the first robot will be assigned server ID 0 and the second robot will be assigned server ID 1. Similarly, the robots need unique namespaces in order for their topics to be distinguished from each other. In this case they will be assigned as `/robot1` and `/robot2`. + +Although both robots are present in the same system, this example will not include direct inter-robot communication. Each robot's discovery server will be isolated from the other. Instead, the robots will both communicate with the user computer which can be thought of as a command center. This allows for the number of robots to be scaled up while minimizing the load on the network. + +The user computer will connect to both discovery servers, allowing the user computer to see all of the ROS nodes / topics from each of the robots. Each of the robots will be able to see all of the ROS nodes / topics from the user computer as well. This allows the user computer to send commands to each of the robots, coordinating the system and sharing information across the fleet as necessary. + +Although one could run another discovery server on the user computer, this would add significant load on all of the robots unless done in such a way that the server was isolated from the robot servers. This is not recommended for most use cases. + +#### Example Robot Setup + + + + + + + + + + +
Robot 1Robot 2
+ +

ROS SetupBash Setup

+
ROBOT_NAMESPACE                    [/robot1]
+
+

ROS SetupDiscovery Server

+
  Enabled                         [True]
+  Onboard Server - Port           [11811]
+  Onboard Server - Server ID      [0]
+  Offboard Server - IP            []
+  Offboard Server - Port          [11811]
+  Offboard Server - Server ID     [1]
+
+

Wi-Fi Setup

+
  Wi-Fi Mode            [Client]
+  SSID                  [my_ttb4_network]
+  Password              [secure_password]
+  Band                  [5GHz]
+  IP Address            []
+  DHCP                  [True]
+
+ +
+ +

ROS SetupBash Setup

+
ROBOT_NAMESPACE                    [/robot2]
+
+

ROS SetupDiscovery Server

+
  Enabled                         [True]
+  Onboard Server - Port           [11811]
+  Onboard Server - Server ID      [1]
+  Offboard Server - IP            []
+  Offboard Server - Port          [11811]
+  Offboard Server - Server ID     [1]
+
+

Wi-Fi Setup

+
  Wi-Fi Mode            [Client]
+  SSID                  [my_ttb4_network]
+  Password              [secure_password]
+  Band                  [5GHz]
+  IP Address            []
+  DHCP                  [True]
+
+ +
+ + #### Example User Computer Setup From the robot configuration the robot server IDs and the ROS Domain ID are known, and from the robots themselves or the router the IP addresses are known. It is recommended that the robot IPs be reserved on the router so that they always remain the same and this process does not need to be repeated. Running the user computer configuration script as described above, would look as follows: diff --git a/setup/media/webserver_config_jazzy.png b/setup/media/webserver_config_jazzy.png new file mode 100644 index 0000000..3dd5954 Binary files /dev/null and b/setup/media/webserver_config_jazzy.png differ diff --git a/setup/networking.md b/setup/networking.md index 9e0f528..1e05cca 100644 --- a/setup/networking.md +++ b/setup/networking.md @@ -6,6 +6,10 @@ sort: 2 The TurtleBot 4 consists of two computing units: the Create® 3, and the Raspberry Pi. They connect to each other over a USB-C cable, which is used to both power the Raspberry Pi, and establish a ethernet connection between the units. Both units also have Wi-Fi cards. The Create® 3 is able to connect to only 2.4 GHz networks, while the Raspberry Pi can connect to both 2.4 and 5 GHz networks. The user can also use their PC to communicate with the robot over Wi-Fi. +```note +For best performance you will need a router capable of supporting 2.4 and 5 GHz. Older wireless equipment, such as routers that only support 802.11b/g, may have bandwidth limitations that will result in poor performance. +``` + ## DDS ROS 2 has multiple [DDS](https://docs.ros.org/en/humble/Concepts/About-Different-Middleware-Vendors.html) vendors, but the TurtleBot 4 only supports [CycloneDDS](https://github.com/ros2/rmw_cyclonedds) and [FastDDS](https://github.com/ros2/rmw_fastrtps) out of the box. In Galactic, CycloneDDS is the default while in Humble, FastDDS is the default. The TurtleBot 4 can switch between the two DDS implementations on both versions of ROS 2. @@ -18,16 +22,40 @@ For ROS 2 networking, the TurtleBot 4 can function with two different configurat Simple Discovery is the default protocol that ROS 2 uses, and is available with both FastDDS and CycloneDDS. Simple Discovery uses multicasting to allow each ROS 2 participant to contact every other ROS 2 participant at the same time. This allows for all devices on the network to automatically discover each other's ROS 2 nodes. -To use the TurtleBot 4 in the multicast configuration, both the RPi4 and the Create® 3 should be connected to the same Wi-Fi network. It is recommended that the RPi4 is connected to a 5GHz network for improved performance, so the network must bridge the 2.4 GHz and 5 GHz bands. Networks that provide 2.4 GHz and 5 GHz on the same SSID may not work properly with the Create3. This issue can be avoided by using Discovery Server. - ```note Connecting the Raspberry Pi using a 2.4 GHz network or over a network with very limited bandwidth can limit functionality including navigation and sending/receiving images. ``` +{% tabs wifi_simple %} +{% tab wifi_simple galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` + +To use the TurtleBot 4 in the multicast configuration, both the RPi4 and the Create® 3 should be connected to the same Wi-Fi network. It is recommended that the RPi4 is connected to a 5GHz network for improved performance, so the network must bridge the 2.4 GHz and 5 GHz bands. Networks that provide 2.4 GHz and 5 GHz on the same SSID may not work properly with the Create3. This issue can be avoided by using [Discovery Server](#discovery-server). +
simple_discovery -
TurtleBot 4 Simple Discovery configuration
+
TurtleBot 4 Simple Discovery configuration for ROS 2 Galactic
+
+{% endtab %} +{% tab wifi_simple humble %} +To use the TurtleBot 4 in the multicast configuration, both the RPi4 and the Create® 3 should be connected to the same Wi-Fi network. It is recommended that the RPi4 is connected to a 5GHz network for improved performance, so the network must bridge the 2.4 GHz and 5 GHz bands. Networks that provide 2.4 GHz and 5 GHz on the same SSID may not work properly with the Create3. This issue can be avoided by using [Discovery Server](#discovery-server). + +
+ simple_discovery +
TurtleBot 4 Simple Discovery configuration for ROS 2 Humble
+
+{% endtab %} +{% tab wifi_simple jazzy %} +To use the TurtleBot 4 in the multicast configuration, the RPi4 should be connected to the Wi-Fi network, but the Create® 3 should be left offline. It is recommended that the RPi4 is connected to a 5GHz network for improved performance. Note that this is the network topology as used with [Discovery Server](#discovery-server). + +
+ simple_discovery +
TurtleBot 4 Simple Discovery configuration for ROS 2 Jazzy. Note that the Create® 3 is not connected to wi-fi.
+{% endtab %} +{% endtabs %} ### Discovery Server diff --git a/setup/simple_discovery.md b/setup/simple_discovery.md index 66092af..b783bfc 100644 --- a/setup/simple_discovery.md +++ b/setup/simple_discovery.md @@ -5,7 +5,8 @@ sort: 3 # Simple Discovery ```note -The TurtleBot 4 should be configured for either Simple Discovery or Discovery Server, not both. +The TurtleBot 4 should be configured for either Simple Discovery or Discovery Server, not both. + See [Networking](./networking.md) for details. ``` @@ -17,6 +18,9 @@ To use the TurtleBot 4 with Simple Discovery, the Create® 3 should be connected The Create® 3 can only be connected to 2.4 GHz Wi-Fi networks. ``` +{% tabs wifi %} +{% tab wifi galactic %} + ### Wi-Fi Setup Access the [Create® 3 webserver](./basic.md#accessing-the-create-3-webserver), then navigate to the Connect tab. @@ -37,18 +41,72 @@ Access the [Create® 3 webserver](./basic.md#accessing-the-create-3-webserver), Set ROS 2 Domain ID to 0, ROS 2 Namespace to an empty string, and RMW_IMPLEMENTATION to the [default](networking.md#dds) for your ROS 2 version. Additionally, make sure that the Fast DDS discovery server is disabled. +
+ Create® 3 config +
Configuring the Create® 3 application for Galactic
+
+{% endtab %} +{% tab wifi humble %} + +### Wi-Fi Setup + +Access the [Create® 3 webserver](./basic.md#accessing-the-create-3-webserver), then navigate to the Connect tab. +Enter your Wi-Fi SSID and password, and then click 'Connect'. Wait for it to initiate the WiFi connection, and then play a "happy sound" to signal successful connection. This may take a couple minutes. Click on the Connect tab once again and it should now show an IP address if the connection was successful. If the light ring turns yellow during this process, it indicates an error in connection. See [the Create® 3 documentation](https://iroboteducation.github.io/create3_docs/hw/face/) to understand what the different light ring colors indicate. + +```note +If the Create® 3 is unable to connect to your 2.4 GHz WiFi network and the light ring does not show any particular error color, press and hold both [Buttons 1 and 2](https://iroboteducation.github.io/create3_docs/hw/face/) on the Create® 3 for about 5 seconds until the light ring shows spinning blue light. Now, reload the Connect page and try again. You may hear several chimes, but you must wait until the light ring color changes. +``` + +
+ Create® 3 connect +
Connecting the Create® 3 to Wi-Fi
+
+ +### Application Configuration + +Use the [`turtlebot4-setup`](../software/turtlebot4_setup.md) tool to configure the Create® 3. You can access the [Create® 3 webserver](./basic.md#accessing-the-create-3-webserver) and navigate to the Application Configuration tab to confirm the configuration as follows: +- ROS 2 Domain ID is `0` +- ROS 2 Namespace is empty +- RMW Implementation is set to the [default](networking.md#dds) for your ROS 2 version +- Fast DDS Discovery Server is disabled +
Create® 3 config
Configuring the Create® 3 application for Humble
+{% endtab %} +{% tab wifi jazzy %} + +### Wi-Fi Setup + +The Create® 3 must _not_ be connected to Wifi when using ROS 2 Jazzy. All communication between the Raspberry Pi and the Create® 3 is done over the internal wired connection. The [`create3_republisher`](../software/create3.md#create-3-republisher) node ensures that all ROS 2 topics, services, and actions from the Create® 3 are accessible by other computers on the same wireless network. + +To disconnect the Create® 3 from wi-fi, access the [Create® 3 webserver](./basic.md#accessing-the-create-3-webserver) and choose the "Forget wi-fi settings" item from the menu at the top of the screen. + +### Application Configuration + +Use the [`turtlebot4-setup`](../software/turtlebot4_setup.md) tool to configure the Create® 3. You can access the [Create® 3 webserver](./basic.md#accessing-the-create-3-webserver) and navigate to the Application Configuration tab to confirm the configuration as follows: +- ROS 2 Domain ID is `0` +- ROS 2 Namespace is `/_do_not_use` +- RMW Implementation is set to the [default](networking.md#dds) for your firmware +- Fast DDS Discovery Server is disabled + +
+ Create® 3 config +
Configuring the Create® 3 application for Jazzy
+
+{% endtab %} +{% endtabs %} ## User PC -The user PC should be configured to use the same [DDS vendor](./networking.md#dds) and [ROS_DOMAIN_ID](../tutorials/multiple_robots.md#rosdomainid) as the robot. It is -recommended to use the default DDS for your ROS 2 version. +The user PC should be configured to use the same [DDS vendor](./networking.md#dds) and [ROS_DOMAIN_ID](../tutorials/multiple_robots.md#rosdomainid) as the robot. It is recommended to use the default DDS for your ROS 2 version. {% tabs simple %} {% tab simple galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Create a file called `setup.bash` in a convenient location: @@ -111,6 +169,38 @@ source /etc/turtlebot4/setup.bash Call `source ~/.bashrc` to apply these settings to your current terminal. ``` +{% endtab %} +{% tab simple jazzy %} + +Create a file called `setup.bash` in a convenient location: + +```bash +sudo mkdir /etc/turtlebot4/ +sudo touch /etc/turtlebot4/setup.bash +``` + +Add the following lines to `setup.bash` with your favourite text editor: + +```bash +source /opt/ros/jazzy/setup.bash +export ROS_DOMAIN_ID=0 +export RMW_IMPLEMENTATION=rmw_fastrtps_cpp +``` + +```tip +Source your workspaces and export any other environment variables in this file. +``` + +Finally, add the following line in `~/.bashrc` to apply the settings to every new terminal: + +```bash +source /etc/turtlebot4/setup.bash +``` + +```note +Call `source ~/.bashrc` to apply these settings to your current terminal. +``` + {% endtab %} {% endtabs %} @@ -123,7 +213,7 @@ wget https://raw.githubusercontent.com/turtlebot/turtlebot4_setup/galactic/conf/ ``` ```note -The `DontRoute` setting is required to see the Create® 3 topics. +The `DontRoute` setting is required to see the Create® 3 topics. ``` Move the xml file to a convenient location: diff --git a/software/create3.md b/software/create3.md index 75322c7..0a1bfc3 100644 --- a/software/create3.md +++ b/software/create3.md @@ -8,6 +8,9 @@ The TurtleBot 4 can also use all of the actions, messages, and services that the {% tabs create3 %} {% tab create3 galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` **Actions** @@ -108,11 +111,83 @@ When publishing or subscribing to topics, make sure that the [QoS](https://docs. ## Create® 3 Republisher {#create-3-republisher} -In certain network configurations it is beneficial to isolate the Create® 3 from the remainder of the ROS 2 network traffic. The Create® 3 has limited resources and can be overwhelmed with too many topics to discover. The Create® 3 Republisher is used to achieve this. All communication to the Create® 3 is routed through the Raspberry Pi via the republished ROS 2 topics, action and services. This allows nodes to interact with the Create® 3 ROS 2 elements normally while only needing communication with the Raspberry Pi. +In certain network configurations it is beneficial to isolate the Create® 3 from the remainder of the ROS 2 network traffic. The Create® 3 has limited resources and can be overwhelmed with too many topics to discover. The Create® 3 Republisher is used to achieve this. All communication to the Create® 3 is routed through the Raspberry Pi via the republished ROS 2 topics, action and services. This allows nodes to interact with the Create® 3 ROS 2 elements normally while only needing communication with the Raspberry Pi. This is achieved by having the Create® 3 on its own unique namespace which is a combination of the robot namespace and `_do_not_use`. This results in all of its topics being hidden and indicates clearly that these topics, actions and services are not to be used directly by the user. The Create® 3 only communicates with the single Raspberry Pi that is present on the same robot. All of the Create® 3 topics, actions and services are then republished and relayed by the Raspberry Pi `create3_republisher` node with just the robot namespace so they are fully visible and available to the rest of the ROS 2 network. In order to interact with the Create® 3, any given node will interact with the topics, actions, and servers generated by the Raspberry Pi, and the republisher node on the Raspberry Pi will relay that information back to the Create® 3. +```note +The `_do_not_use` namespace, as the name suggests, should _not_ be used by any other nodes. The only place this namespace should ever be referenced is inside the configuration file for the `create3_republisher` node and within the Create® 3's application configuration. + +All other ROS nodes, shell commands (e.g. `ros2 topic echo ...`) should use the republished topics, actions, and services. +``` + In order to prevent overloading the system with too many topics, the number of topics, actions and services that are relayed through the republisher node are limited. The default list of topics, actions and services that are being relayed can be found in the [`create3_republisher` launch parameters](https://github.com/iRobotEducation/create3_examples/blob/humble/create3_republisher/bringup/params.yaml). To optimize the system, update this list to only include the necessary topics, actions and services that are needed. +{% endtab %} +{% tab create3 jazzy %} + +```note +When using the Create® 3 with the Discovery Server network configuration, these topics, actions and services must be enabled in the [`create3_republisher` launch parameters](https://github.com/iRobotEducation/create3_examples/blob/jazzy/create3_republisher/bringup/params.yaml). For more information see the [Create® 3 Republisher section](#create-3-republisher) +``` + +**Actions** + +* [AudioNoteSequence](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/action/AudioNoteSequence.action): Play a given set of notes from the speaker for a given number of iterations. +* [Dock](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/action/Dock.action): Command the robot to dock into its charging station. +* [DriveArc](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/action/DriveArc.action): Command the robot to drive along an arc defined by radius. +* [DriveDistance](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/action/DriveDistance.action): Command the robot to drive a defined distance in a straight line. +* [LedAnimation](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/action/LedAnimation.action): Command the lights to perform specified animation. +* [NavigateToPosition](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/action/NavigateToPosition.action): Command the robot to drive to a goal odometry position using simple approach that rotates to face goal position then translates to goal position then optionally rotates to goal heading. +* [RotateAngle](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/action/RotateAngle.action): Command the robot to rotate in place a specified amount. +* [Undock](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/action/Undock.action): Command the robot to undock from its charging station. +* [WallFollow](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/action/WallFollow.action): Command the robot to wall follow on left or right side using bump and IR sensors. + +**Messages** + +* [AudioNote](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/AudioNote.msg): Command the robot to play a note. +* [AudioNoteVector](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/AudioNoteVector.msg): Command the robot to play a sequence of notes. +* [Button](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/Button.msg): Status for a button. +* [DockStatus](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/DockStatus.msg): Information about the robot sensing the its dock charging station. +* [HazardDetection](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/HazardDetection.msg): An hazard or obstacle detected by the robot. +* [HazardDetectionVector](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/HazardDetectionVector.msg): All the hazards and obstacles detected by the robot. +* [InterfaceButtons](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/InterfaceButtons.msg): Status of the 3 interface buttons on the Create® robot faceplate. +* [IrIntensity](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/IrIntensity.msg): Reading from an IR intensity sensor. +* [IrIntensityVector](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/IrIntensityVector.msg): Vector of current IR intensity readings from all sensors. +* [IrOpcode](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/IrOpcode.msg): Opcode detected by the robot IR receivers. Used to detect the dock and virtual walls. +* [KidnapStatus](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/KidnapStatus.msg): Whether the robot has been picked up off the ground. +* [LedColor](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/LedColor.msg): RGB values for an LED. +* [LightringLeds](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/LightringLeds.msg): Command RGB values of 6 lightring lights. +* [Mouse](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/Mouse.msg): Reading from a mouse sensor. +* [SlipStatus](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/SlipStatus.msg): Whether the robot is currently slipping or not. +* [StopStatus](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/StopStatus.msg): Whether the robot is currently stopped or not. +* [WheelStatus](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/WheelStatus.msg): Current/PWM readings from the robot's two wheels in addition to whether wheels are enabled. +* [WheelTicks](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/WheelTicks.msg): Reading from the robot two wheels encoders. +* [WheelVels](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/msg/WheelVels.msg): Indication about the robot two wheels current speed. + +**Services** + +* [EStop](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/srv/EStop.srv): Set system EStop on or off, cutting motor power when on and enabling motor power when off. +* [RobotPower](https://github.com/iRobotEducation/irobot_create_msgs/blob/main/srv/RobotPower.srv): Power off robot. + +See [irobot_create_msgs](https://github.com/iRobotEducation/irobot_create_msgs) for more details. + +```note +When publishing or subscribing to topics, make sure that the [QoS](https://docs.ros.org/en/jazzy/Concepts/About-Quality-of-Service-Settings.html) that you use matches that of the topic. +``` + +## Create® 3 Republisher {#create-3-republisher} + +By default, the Turtlebot 4 uses the `create3_republisher` node to isolate the Create® 3 from the remainder of the ROS 2 network traffic. This helps limit the network traffic that reaches the Create® 3 when it is connected to the wireless network, especially when multiple robots are connected. All ROS 2 traffic is routed via the Turtlebot 4's Raspberry Pi computer, and the `create3_republisher` node exposes the Create® 3's topics, services, and actions the robot's main namespace. This allows external workstations and other robots to interact with the robot via the Raspberry Pi's wireless connection. + +The Create® 3's topics, services, and actions are all available inside a namespace called `_do_not_use`. This results in the topics being hidden, and clearly indicates that they should not be used directly by the user. The Create® 3 only communicates with the single Raspberry Pi that is present on the same robot. All of the Create® 3 topics, actions and services are then republished and relayed by the Raspberry Pi `create3_republisher` node with just the robot namespace so they are fully visible and available to the rest of the ROS 2 network. In order to interact with the Create® 3, any given node will interact with the topics, actions, and servers generated by the Raspberry Pi, and the republisher node on the Raspberry Pi will relay that information back to the Create® 3. + +```note +The `_do_not_use` namespace, as the name suggests, should _not_ be used by any other nodes. The only place this namespace should ever be referenced is inside the configuration file for the `create3_republisher` node and within the Create® 3's application configuration. + +All other ROS nodes, shell commands (e.g. `ros2 topic echo ...`) should use the republished topics, actions, and services. +``` + +In order to prevent overloading the system with too many topics, the number of topics, actions and services that are relayed through the republisher node are limited. The default list of topics, actions and services that are being relayed can be found in the [`create3_republisher` launch parameters](https://github.com/iRobotEducation/create3_examples/blob/jazzy/create3_republisher/bringup/params.yaml). To optimize the system, update this list to only include the necessary topics, actions and services that are needed. + {% endtab %} {% endtabs %} \ No newline at end of file diff --git a/software/sensors.md b/software/sensors.md index fb3d2f6..c6e1beb 100644 --- a/software/sensors.md +++ b/software/sensors.md @@ -8,54 +8,33 @@ sort: 8 ### Connecting -The RPLIDAR connects to the TurtleBot 4 with a micro USB to USB-A cable. The sensor does not require high data throughput, so using a USB 2.0 port is sufficient. +The RPLIDAR connects to the TurtleBot 4 with a micro USB to USB-A cable. The sensor does not require high data throughput, so using a USB 2.0 port is sufficient. -{% tabs udev %} -{% tab udev galactic %} - -Once connected, the RPLIDAR should register on the Raspberry PI as a USB device. If the [udev rules](https://github.com/turtlebot/turtlebot4_setup/blob/galactic/udev/turtlebot4.rules) are installed, the RPLIDAR will appear as `/dev/RPLIDAR`. Otherwise it will be `/dev/ttyUSB0`. - - -{% endtab %} -{% tab udev humble %} - -Once connected, the RPLIDAR should register on the Raspberry PI as a USB device. If the [udev rules](https://github.com/turtlebot/turtlebot4_setup/blob/humble/udev/50-turtlebot4.rules) are installed, the RPLIDAR will appear as `/dev/RPLIDAR`. Otherwise it will be `/dev/ttyUSB0`. - - -{% endtab %} -{% endtabs %} +Once connected, the RPLIDAR should register on the Raspberry PI as a USB device. If the [udev rules](https://github.com/turtlebot/turtlebot4_setup/blob/jazzy/udev/turtlebot4.rules) are installed, the RPLIDAR will appear as `/dev/RPLIDAR`. Otherwise it will be `/dev/ttyUSB0`. To check that the USB device exists, use the command ```bash -ls /dev/RPLIDAR +ls -l /dev/RPLIDAR ``` -If the device exists, the terminal will echo `/dev/RPLIDAR`. - -### Installing - -{% tabs rplidar %} -{% tab rplidar galactic %} - -The RPLIDAR drivers are installed by default on all TurtleBot 4's. To manually install, run: - -```bash -sudo apt install ros-galactic-rplidar-ros +If the device exists, the command will print something of the form +``` +lrwxrwxrwx 1 root root 7 Oct 10 13:49 /dev/RPLIDAR -> ttyUSB0 +``` +If the device does not exist, the command will print +``` +ls: cannot access '/dev/RPLIDAR': No such file or directory ``` -{% endtab %} -{% tab rplidar humble %} +### Installing The RPLIDAR drivers are installed by default on all TurtleBot 4's. To manually install, run: ```bash -sudo apt install ros-humble-rplidar-ros +sudo apt install ros-${ROS_DISTRO}-rplidar-ros ``` -{% endtab %} -{% endtabs %} - ### Running The RPLIDAR drivers run on boot up as part of the TurtleBot4 service on the robot. The following command should only be used on the computer that the lidar is actively plugged into and only if the automatically starting RPLIDAR node has been stopped or disabled. @@ -102,27 +81,12 @@ The OAK-D cameras are connected to the Raspberry Pi with a USB-C to USB-A cable. ### Installing -{% tabs rplidar %} -{% tab rplidar galactic %} - The OAK-D drivers are installed by default on all TurtleBot 4's. To manually install, run: ```bash -sudo apt install ros-galactic-depthai-ros +sudo apt install ros-${ROS_DISTRO}-depthai-ros ``` -{% endtab %} -{% tab rplidar humble %} - -The OAK-D drivers are installed by default on all TurtleBot 4's. To manually install, run: - -```bash -sudo apt install ros-humble-depthai-ros -``` - -{% endtab %} -{% endtabs %} - ### Running The OAK-D drivers run on boot up as part of the TurtleBot4 service on the robot. The following command should only be used on the computer that the OAK-D camera is actively plugged into and only if the automatically starting OAK-D node has been stopped or disabled. @@ -141,10 +105,9 @@ For example: ros2 launch depthai_examples mobile_publisher.launch.py ``` -AI examples are available on the DepthAI [github](https://github.com/luxonis/depthai-python). To view the images from these examples you will need to ssh into the robot with a `-X` flag. - +AI examples are available on the DepthAI [github](https://github.com/luxonis/depthai-python). To view the images from these examples you will need to ssh into the robot with a `-X` flag: ```bash -ssh ubuntu@192.168.0.15 -X +ssh -X ubuntu@10.42.0.1 ``` ## Create® 3 @@ -167,12 +130,12 @@ The wheeldrop is the spring on which the Create® 3 wheels sit. When the robot i ### IR Proximity -The IR proxmity sensors are located on the front of the bumper and are used for the wall follow action. The sensor data can be viewed on the */ir_intensity* topic. +The IR proxmity sensors are located on the front of the bumper and are used for the wall follow action. The sensor data can be viewed on the `/ir_intensity` topic. ### Slip and Stall -Wheel slip and stall is also detected by the Create® 3. The status can be viewed on the */slip_status* and */stall_status* topics. +Wheel slip and stall is also detected by the Create® 3. The status can be viewed on the `/slip_status` and `/stall_status` topics. ### Kidnap -The robot uses a fusion of sensor data to detect when it has been picked up and "kidnapped". Motors will be disabled in this state, and will re-enable when placed on the ground again. The */kidnap_status* topic shows the current kidnap state. \ No newline at end of file +The robot uses a fusion of sensor data to detect when it has been picked up and "kidnapped". Motors will be disabled in this state, and will re-enable when placed on the ground again. The `/kidnap_status` topic shows the current kidnap state. \ No newline at end of file diff --git a/software/simulation.md b/software/simulation.md index 0dda07c..36cbb71 100644 --- a/software/simulation.md +++ b/software/simulation.md @@ -7,31 +7,42 @@ sort: 10 The simulator allows the user to test the robot without the need for a physical robot. It has all of the same functionality as the real robot. The TurtleBot 4 can be simulated using [Gazebo](http://gazebosim.org/) (previously known as Ignition Gazebo). Unlike [Gazebo Classic](https://classic.gazebosim.org/), Gazebo does not natively support ROS. Instead, it has its own transport stack with a similar topic and node implementation. To communicate with ROS, we can use the [ros_ign_bridge](https://github.com/gazebosim/ros_gz/tree/humble/ros_gz_bridge). This ROS node translates data from ROS to Ignition, and vice versa. -## Installing Ignition Gazebo +## Installing Gazebo +{% tabs requirements %} +{% tab requirements galactic %} Requirements: - Ubuntu 20.04 - ROS 2 Galactic - -or - +{% endtab %} +{% tab requirements humble %} +Requirements: - Ubuntu 22.04 - ROS 2 Humble - +{% endtab %} +{% tab requirements jazzy %} +Requirements: +- Ubuntu 24.04 +- ROS 2 Jazzy +{% endtab %} +{% endtabs %} Recommended: - PC with dedicated GPU Follow the installation instructions described [here](./turtlebot4_simulator.md#installation). -## Launching Ignition Gazebo +## Launching Gazebo For a full tutorial using Gazebo, see the [Navigation tutorial](../tutorials/navigation.md) {% tabs ignition %} {% tab ignition galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` -The `ignition.launch.py` launch file has several [launch configurations](turtlebot4_simulator.md#ignition-bringup) that allow the user to customize the simulation. +The `ignition.launch.py` launch file has several [launch configurations](turtlebot4_simulator.md#gazebo-bringup) that allow the user to customize the simulation. Default TurtleBot 4 launch: @@ -60,7 +71,7 @@ ros2 launch turtlebot4_ignition_bringup ignition.launch.py model:=lite {% endtab %} {% tab ignition humble %} -The `turtlebot4_ignition.launch.py` launch file has several [launch configurations](turtlebot4_simulator.md#ignition-bringup) that allow the user to customize the simulation. +The `turtlebot4_ignition.launch.py` launch file has several [launch configurations](turtlebot4_simulator.md#gazebo-bringup) that allow the user to customize the simulation. Default TurtleBot 4 launch: @@ -86,5 +97,34 @@ ros2 launch turtlebot4_ignition_bringup turtlebot4_ignition.launch.py model:=lit
TurtleBot 4 Lite in Ignition Gazebo
+{% endtab %} +{% tab ignition jazzy %} + +The `turtlebot4_gz.launch.py` launch file has several [launch configurations](turtlebot4_simulator.md#gazebo-bringup) that allow the user to customize the simulation. + +Default TurtleBot 4 launch: + +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py +``` + +Gazebo will launch and spawn the TurtleBot 4 in the default world along with all of the necessary nodes. + +
+ Gazebo +
TurtleBot 4 in Gazebo
+
+ +TurtleBot 4 Lite launch: + +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py model:=lite +``` + +
+ Gazebo Lite +
TurtleBot 4 Lite in Gazebo
+
+ {% endtab %} {% endtabs %} diff --git a/software/turtlebot4_common.md b/software/turtlebot4_common.md index af381ad..59ba7e6 100644 --- a/software/turtlebot4_common.md +++ b/software/turtlebot4_common.md @@ -18,6 +18,9 @@ The `turtlebot4` packages are automatically installed when either of `turtlebot4 {% tabs debian %} {% tab debian galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Individual packages can be installed through apt: @@ -42,6 +45,19 @@ ros-humble-turtlebot4-navigation \ ros-humble-turtlebot4-node ``` +{% endtab %} +{% tab debian jazzy %} + +Individual packages can be installed through apt: + +```bash +sudo apt update +sudo apt install ros-jazzy-turtlebot4-description \ +ros-jazzy-turtlebot4-msgs \ +ros-jazzy-turtlebot4-navigation \ +ros-jazzy-turtlebot4-node +``` + {% endtab %} {% endtabs %} @@ -53,6 +69,9 @@ Source installation is an alternative to the debian package and should only be u {% tabs source %} {% tab source galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` To manually install this metapackage from source, clone the git repository: @@ -103,6 +122,32 @@ colcon build --symlink-install Next, the workspace must be sourced. If implemented on the robot, source the workspace on the robot by running the `turtlebot4-setup` tool and under `ROS Setup` set the workspace as the path to your workspace's setup.bash (`/home/ubuntu/turtlebot4_ws/install/setup.bash`). If being installed on a user computer then this path must be sourced in the terminal or in the user's `.bashrc` file. +{% endtab %} +{% tab source jazzy %} + +To manually install this metapackage from source, clone the git repository: + +```bash +cd ~/turtlebot4_ws/src +git clone https://github.com/turtlebot/turtlebot4.git -b jazzy +``` + +Install dependencies: + +```bash +cd ~/turtlebot4_ws +rosdep install --from-path src -yi --rosdistro jazzy +``` + +Build the packages: + +```bash +source /opt/ros/jazzy/setup.bash +colcon build --symlink-install +``` + +Next, the workspace must be sourced. If implemented on the robot, source the workspace on the robot by running the `turtlebot4-setup` tool and under `ROS Setup` set the workspace as the path to your workspace's setup.bash (`/home/ubuntu/turtlebot4_ws/install/setup.bash`). If being installed on a user computer then this path must be sourced in the terminal or in the user's `.bashrc` file. + {% endtab %} {% endtabs %} @@ -127,6 +172,9 @@ The `turtlebot4_navigation` packages contains launch and configuration files for {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Launch files: @@ -183,6 +231,39 @@ ros2 launch turtlebot4_navigation nav2.launch.py Nav2 requires either SLAM or localization to already be running. ``` +{% endtab %} +{% tab navigation jazzy %} + +Launch files: + +* [Nav2](https://github.com/turtlebot/turtlebot4/blob/jazzy/turtlebot4_navigation/launch/nav2.launch.py): Launches the Nav2 stack. +* [SLAM](https://github.com/turtlebot/turtlebot4/blob/jazzy/turtlebot4_navigation/launch/slam.launch.py): Launches `slam_toolbox` with online mapping. +* [Localization](https://github.com/turtlebot/turtlebot4/blob/jazzy/turtlebot4_navigation/launch/localization.launch.py): Launches localization on a given map. + +Running synchronous SLAM: +```bash +ros2 launch turtlebot4_navigation slam.launch.py +``` + +Running asynchronous SLAM: +```bash +ros2 launch turtlebot4_navigation slam.launch.py sync:=false +``` + +Running localization with an existing map: +```bash +ros2 launch turtlebot4_navigation localization.launch.py map:=/path/to/map.yaml +``` + +Running the Nav2 stack: +```bash +ros2 launch turtlebot4_navigation nav2.launch.py +``` + +```note +Nav2 requires either SLAM or localization to already be running. +``` + {% endtab %} {% endtabs %} @@ -198,6 +279,9 @@ The `turtlebot4_node` package contains the source code for the [rclcpp](https:// {% tabs turtlebot4_node %} {% tab turtlebot4_node galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` **Publishers** @@ -495,6 +579,158 @@ The `turtlebot4_node` package contains the source code for the [rclcpp](https://
+{% endtab %} +{% tab turtlebot4_node jazzy %} + +**Publishers** + +
+ + + + + + + + + + + + + + + + + + + + + + + + + +
TopicMessage TypeDescription
hmi/displayturtlebot4_msgs/msg/UserDisplayThe current information that is to be displayed (TurtleBot 4 model only)
ipstd_msgs/msg/StringThe IP address of the Wi-Fi interface
function_callsstd_msgs/msg/StringPublishes the name of a button or menu function when it is called
+
+ +**Subscribers** + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TopicMessage TypeDescription
battery_statesensor_msgs/msg/BatteryStateCurrent battery state of the Create® 3
hmi/buttonsturtlebot4_msgs/msg/UserButtonButton states of the TurtleBot 4 HMI (TurtleBot 4 model only)
hmi/display/messagestd_msgs/msg/StringUser topic to print custom message to display (TurtleBot 4 model only)
hmi/ledturtlebot4_msgs/msg/UserLedUser topic to control User LED 1 and 2 (TurtleBot 4 model only)
interface_buttonsirobot_create_msgs/msg/InterfaceButtonsButton states of Create® 3 buttons
joysensor_msgs/msg/JoyBluetooth controller button states
wheel_statusirobot_create_msgs/msg/WheelStatusWheel status reported by Create® 3
+
+ +**Service Clients** + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ServiceService TypeDescription
e_stopirobot_create_msgs/srv/EStopEnable or disable motor stop
robot_powerirobot_create_msgs/srv/RobotPowerPower off the robot
start_motorstd_srvs/srv/EmptyStart the RPLIDAR motor
stop_motorstd_srvs/srv/EmptyStop the RPLIDAR motor
+
+ +**Action Clients** + +
+ + + + + + + + + + + + + + + + + + + + + + + + + +
ActionAction TypeDescription
dockirobot_create_msgs/action/DockCommand the robot to dock into its charging station
wall_followirobot_create_msgs/action/WallFollowCommand the robot to wall follow on left or right side using bump and IR sensors
undockirobot_create_msgs/action/UndockCommand the robot to undock from its charging station
+
+ {% endtab %} {% endtabs %} @@ -561,7 +797,7 @@ The node has a set of static functions that can be used either with a button or ### Configuration -This node can be configured using a parameter *.yaml* file. The default robot parameters can be found [here](https://github.com/turtlebot/turtlebot4_robot/blob/galactic/turtlebot4_bringup/config/turtlebot4.yaml). +This node can be configured using a parameter *.yaml* file. The default robot parameters can be found [here](https://github.com/turtlebot/turtlebot4_robot/blob/galactic/turtlebot4_bringup/config/turtlebot4.yaml). **Parameters** @@ -657,7 +893,7 @@ Use your favourite text editor and paste the following into `example.yaml`: ```yaml turtlebot4_node: ros__parameters: - buttons: + buttons: create3_1: ["EStop"] hmi_1: ["Wall Follow Left", "Wall Follow Right", "3000"] @@ -834,9 +1070,9 @@ The menu can have any number of entries. If there are more than 5 entries, the u #### Menu Control -The TurtleBot 4 display has a simple scrolling menu. There are 4 control functions for the menu: Scroll up, Scroll down, Select, and Back. +The TurtleBot 4 display has a simple scrolling menu. There are 4 control functions for the menu: Scroll up, Scroll down, Select, and Back. -* Scroll up and down allow the users to navigate through the menu entries and by default are mapped to user buttons 3 and 4 respectively. +* Scroll up and down allow the users to navigate through the menu entries and by default are mapped to user buttons 3 and 4 respectively. * The select function will call the currently selected menu entry. This can trigger an action such as docking, a service such as EStop, or display a message such as the Help message. This function is mapped to user button 1 by default. * The back function allows the user to return back to the menu from a message screen. If the menu is already showing the menu entries, it will return to showing the first 5 menu entries and the first entry will be highlighted. diff --git a/software/turtlebot4_desktop.md b/software/turtlebot4_desktop.md index a225469..42d8f80 100644 --- a/software/turtlebot4_desktop.md +++ b/software/turtlebot4_desktop.md @@ -14,34 +14,30 @@ This package is installed when following the [user computer setup instructions]( ### Debian package -{% tabs debian %} -{% tab debian galactic %} - -```note -The `turtlebot4_desktop` metapackage can be installed on a PC running Ubuntu Desktop 20.04 with ROS 2 Galactic. -``` +The Turtlebot4 desktop metapackage can be installed as a debian package: +* Ubuntu 24.04 with ROS 2 Jazzy +* Ubuntu 22.04 with ROS 2 Humble +* Ubuntu 20.04 with ROS 2 Galactic _end-of-life, not recommended_ To install the metapackage through apt: - +{% tabs install_apt %} +{% tab install_apt galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` ```bash -sudo apt update sudo apt install ros-galactic-turtlebot4-desktop ``` - {% endtab %} -{% tab debian humble %} - -```note -The `turtlebot4_desktop` metapackage can be installed on a PC running Ubuntu Desktop 22.04 with ROS 2 Humble. -``` - -To install the metapackage through apt: - +{% tab install_apt humble %} ```bash -sudo apt update sudo apt install ros-humble-turtlebot4-desktop ``` - +{% endtab %} +{% tab install_apt jazzy %} +```bash +sudo apt install ros-jazzy-turtlebot4-desktop +``` {% endtab %} {% endtabs %} @@ -53,6 +49,9 @@ Source installation is an alternative to the debian package and should only be u {% tabs source %} {% tab source galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` To manually install this metapackage from source, clone the git repository: @@ -103,6 +102,32 @@ colcon build --symlink-install Next, the workspace must be sourced by running `source ~/turtlebot4_ws/install/setup.bash` in the terminal or by adding that command in the `.bashrc` file and sourcing the `.bashrc` file. +{% endtab %} +{% tab source jazzy %} + +To manually install this metapackage from source, clone the git repository: + +```bash +cd ~/turtlebot4_ws/src +git clone https://github.com/turtlebot/turtlebot4_desktop.git -b jazzy +``` + +Install dependencies: + +```bash +cd ~/turtlebot4_ws +rosdep install --from-path src -yi +``` + +Build the packages: + +```bash +source /opt/ros/jazzy/setup.bash +colcon build --symlink-install +``` + +Next, the workspace must be sourced by running `source ~/turtlebot4_ws/install/setup.bash` in the terminal or by adding that command in the `.bashrc` file and sourcing the `.bashrc` file. + {% endtab %} {% endtabs %} @@ -112,6 +137,9 @@ The `turtlebot4_viz` package contains launch files and configurations for viewin {% tabs debian %} {% tab debian galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Launch files: * [View Diagnostics](https://github.com/turtlebot/turtlebot4_desktop/blob/galactic/turtlebot4_viz/launch/view_diagnostics.launch.py): Launches `rqt_robot_monitor` to view diagnostic data. @@ -156,6 +184,33 @@ If your robot is using a namespace, use it as a launch argument: ros2 launch turtlebot4_viz view_model.launch.py namespace:=/my_robot_namespace ``` +{% endtab %} +{% tab debian jazzy %} + +Launch files: +* [View Diagnostics](https://github.com/turtlebot/turtlebot4_desktop/blob/jazzy/turtlebot4_viz/launch/view_diagnostics.launch.py): Launches `rqt_robot_monitor` to view diagnostic data. +* [View Model](https://github.com/turtlebot/turtlebot4_desktop/blob/jazzy/turtlebot4_viz/launch/view_model.launch.py): Launches `rviz2`. Used to view the model. +* [View Robot](https://github.com/turtlebot/turtlebot4_desktop/blob/jazzy/turtlebot4_viz/launch/view_robot.launch.py): Launches `rviz2`. Used to view the robot model and sensor data +* [View Navigation](https://github.com/turtlebot/turtlebot4_desktop/blob/jazzy/turtlebot4_viz/launch/view_navigation.launch.py): Launches `rviz2`. Used to view the robot model and sensor data while navigating. Allows setting 2D pose estimates & goal poses. + +Viewing the robot while mapping: + +```bash +ros2 launch turtlebot4_viz view_navigation.launch.py +``` + +Viewing diagnostics: + +```bash +ros2 launch turtlebot4_viz view_diagnostics.launch.py +``` + +If your robot is using a namespace, use it as a launch argument: + +```bash +ros2 launch turtlebot4_viz view_model.launch.py namespace:=/my_robot_namespace +``` + {% endtab %} {% endtabs %} diff --git a/software/turtlebot4_robot.md b/software/turtlebot4_robot.md index 4904441..5e30fa4 100644 --- a/software/turtlebot4_robot.md +++ b/software/turtlebot4_robot.md @@ -24,6 +24,9 @@ To manually install this metapackage from source: {% tabs install %} {% tab install galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Clone the repository into your workspace: @@ -74,12 +77,38 @@ colcon build --symlink-install Next, the workspace must be sourced. Source the workspace on the robot by running the `turtlebot4-setup` tool and under `ROS Setup` set the workspace as the path to your workspace's setup.bash (`/home/ubuntu/turtlebot4_ws/install/setup.bash`). +{% endtab %} +{% tab install jazzy %} + +Clone the repository into your workspace: + +```bash +cd ~/turtlebot4_ws/src +git clone https://github.com/turtlebot/turtlebot4_robot.git -b jazzy +``` + +Install dependencies: + +```bash +cd ~/turtlebot4_ws +rosdep install --from-path src -yi +``` + +Build the packages: + +```bash +source /opt/ros/jazzy/setup.bash +colcon build --symlink-install +``` + +Next, the workspace must be sourced. Source the workspace on the robot by running the `turtlebot4-setup` tool and under `ROS Setup` set the workspace as the path to your workspace's setup.bash (`/home/ubuntu/turtlebot4_ws/install/setup.bash`). + {% endtab %} {% endtabs %} ## Base -The `turtlebot4_base` package contains the source code for the [rclcpp](https://github.com/ros2/rclcpp) node `turtlebot4_base_node` which runs on the physical robot. This node interfaces with the GPIO lines of the Raspberry Pi which allows it to read the state of the buttons, as well as write to the LEDs and display. +The `turtlebot4_base` package contains the source code for the [rclcpp](https://github.com/ros2/rclcpp) node `turtlebot4_base_node` which runs on the physical robot. This node interfaces with the GPIO lines of the Raspberry Pi which allows it to read the state of the buttons, as well as write to the LEDs and display. ```note This node is only used on the standard TurtleBot 4 model. @@ -201,6 +230,9 @@ The robot uses the [robot_upstart](https://github.com/clearpathrobotics/robot_up {% tabs upstart %} {% tab upstart galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Robot upstart commands: @@ -231,7 +263,7 @@ Robot upstart commands: Install - install.py model [ROS_DOMAIN_ID] (v0.1.2)
+ install.py model [ROS_DOMAIN_ID] (v0.1.2)
install.py model --domain [ROS_DOMAIN_ID] (v0.1.3) Install the service. Optionally, set the ROS_DOMAIN_ID. @@ -279,6 +311,25 @@ Use the various menu options to start, stop, uninstall, or reinstall the upstart The setup tool will automatically reinstall the `robot_upstart` job when certain settings are changed. +{% endtab %} +{% tab upstart jazzy %} + +Use the TurtleBot 4 setup tool to manage `robot_upstart`: + +```bash +turtlebot4-setup +``` + +Navigate to 'ROS Setup', then 'Robot Upstart'. +Use the various menu options to start, stop, uninstall, or reinstall the upstart job. + +
+ robot_upstart +
Manage robot_upstart with the TurtleBot 4 setup tool
+
+ +The setup tool will automatically reinstall the `robot_upstart` job when certain settings are changed. + {% endtab %} {% endtabs %} @@ -296,6 +347,9 @@ The [diagnostics updater](https://github.com/turtlebot/turtlebot4_robot/blob/gal {% tabs diagnostics %} {% tab diagnostics galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Diagnostic topics: @@ -408,6 +462,63 @@ Diagnostic topics: +{% endtab %} +{% tab diagnostics jazzy %} + +Diagnostic topics: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TopicMessage TypeDescription
battery_statesensor_msgs/msg/BatteryStateBattery voltage and percentage
color/preview/imagesensor_msgs/msg/ImageOAK-D color camera data
dockirobot_create_msgs/msg/DockStatusDock status
hazard_detectionirobot_create_msgs/msg/HazardDetectionVectorCreate® 3 Hazards
imusensor_msgs/msg/ImuIMU data
mouseirobot_create_msgs/msg/MouseMouse sensor data
scansensor_msgs/msg/LaserScanRPLIDAR laser scan data
wheel_statusirobot_create_msgs/msg/WheelStatusWheels enabled status
+ {% endtab %} {% endtabs %} diff --git a/software/turtlebot4_setup.md b/software/turtlebot4_setup.md index f4e070d..7ac5157 100644 --- a/software/turtlebot4_setup.md +++ b/software/turtlebot4_setup.md @@ -12,6 +12,9 @@ Source code is available [here](https://github.com/turtlebot/turtlebot4_setup). {% tabs install %} {% tab install galactic %} +```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. @@ -124,6 +127,55 @@ There are several install scripts that are used to set up the TurtleBot 4 image. TurtleBot 4's come with an already set up RPi4 image, so these scripts will not be needed for most users. ``` +{% endtab %} +{% tab install jazzy %} + +There are several install scripts that are used to set up the TurtleBot 4 image. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ScriptUsageDescription
turtlebot4_setup.shbash 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.shbash jazzy.shInstalls ros-jazzy-ros-base as well as other useful packages. It is called from turtlebot4_setup.sh.
bluetooth.shbash bluetooth.shInstalls bluetooth packages.
sd_flash.shsudo sd_flash.sh /path/to/imageFlashes 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. +``` + {% endtab %} {% endtabs %} @@ -131,6 +183,9 @@ TurtleBot 4's come with an already set up RPi4 image, so these scripts will not {% tabs configuration %} {% tab configuration galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Configuration Scripts @@ -213,7 +268,7 @@ Changes made to Wi-Fi settings will cause your SSH session to hang, and the RPi4
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. +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. @@ -495,6 +550,338 @@ The "About" menu displays system information and has menu options to change the Changing the model to not match the physical robot model is not recommended. ``` +{% endtab %} +{% tab configuration jazzy %} + +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: + +```bash +turtlebot4-setup +``` + +or + +```bash +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. + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FileDescription
aliases.bashContains helpful bash aliases
cyclonedds_rpi.xmlDefault CycloneDDS configuration
discovery.shScript that starts a discovery server
fastdds_discovery_create3.xmlFastDDS configuration for the Create 3 in Discovery Server
fastdds_rpi.xmlDefault FastDDS configuration
setup.bashBash file that exports environment variables to configure ROS 2. + This file is sourced in .bashrc such that the environment is applied to all terminals
systemText 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 VariableDescriptionDefault
CYCLONEDDS_URIPath to CycloneDDS configuration/etc/turtlebot4/cyclonedds_rpi.xml
FASTRTPS_DEFAULT_PROFILES_FILEPath to FastDDS configuration/etc/turtlebot4/fastdds_rpi.xml
ROBOT_NAMESPACESets the robots namespace.
ROS_DOMAIN_IDSets the robots domain ID. Defaults to 0.0
RMW_IMPLEMENTATIONSet 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 platformrmw_fastrtps_cpp
TURTLEBOT4_DIAGNOSTICSEnable or disable TurtleBot 4 diagnostics1
WORKSPACE_SETUPPath 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](../setup/discovery_server.md#example-configuration) for an example on how to set up a two robot system. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SettingDescriptionDefault
EnabledWhether to use Discovery Server modeFalse
Onboard Server - PortDiscovery server port for the onboard server11811
Onboard Server - Server IDDiscovery server ID for the onboard server0
Offboard Server - IPIP address of an optional offboard Discovery Server to connect to (disabled if set as blank)blank
Offboard Server - PortDiscovery server port for the offboard server11811
Offboard Server - Server IDDiscovery server ID for the offboard server1
+ +```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 OptionDescriptionBash equivalent
RestartRestart the robot_upstart job.sudo systemctl restart turtlebot4.service
StartStart the robot_upstart job if it is not running.sudo systemctl start turtlebot4.service
StopStop the robot_upstart job if it is running.sudo systemctl stop turtlebot4.service
InstallInstall or reinstall the robot_upstart job with current ROS settings.install.py [model]
UninstallUninstall 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 OptionDescriptionDefault
Wi-Fi ModeSet the RPi4 to act as a Wi-Fi access point or clientAccess Point
SSIDThe SSID of the Wi-Fi network.
In access point mode, this is the name of the network that will be broadcasted.
Turtlebot4
PasswordThe password of the Wi-Fi network. This can be left empty.Turtlebot4
BandWhich Wi-Fi band to use. Set to 'Any' if unsure.5GHz
IP AddressSets a static IP address for the `wlan0` interface.
DHCPWhether 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](../setup/basic.md#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 run +`sudo 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. +``` + {% endtab %} {% endtabs %} diff --git a/software/turtlebot4_simulator.md b/software/turtlebot4_simulator.md index 4001998..3074056 100644 --- a/software/turtlebot4_simulator.md +++ b/software/turtlebot4_simulator.md @@ -10,9 +10,34 @@ Source code is available [here](https://github.com/turtlebot/turtlebot4_simulato ## Installation -```note -The `turtlebot4_simulator` metapackage can be installed on a PC running Ubuntu Desktop 20.04 with ROS 2 Galactic or Ubuntu Desktop 22.04 with ROS 2 Humble. +The recommended way to install the Turtlebot4 simulator is to install the debian metapackage, which is available on: +* Ubuntu 24.04 with ROS 2 Jazzy +* Ubuntu 22.04 with ROS 2 Humble +* Ubuntu 20.04 with ROS 2 Galactic _end-of-life, not recommended_ + +by running +{% tabs install_apt %} +{% tab install_apt galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` +```bash +sudo apt install ros-galactic-turtlebot4-simulator ros-galactic-irobot-create-nodes ``` +{% endtab %} +{% tab install_apt humble %} +```bash +sudo apt install ros-humble-turtlebot4-simulator ros-humble-irobot-create-nodes +``` +{% endtab %} +{% tab install_apt jazzy %} +```bash +sudo apt install ros-jazzy-turtlebot4-simulator ros-jazzy-irobot-create-nodes +``` +{% endtab %} +{% endtabs %} + +For installation from source code, see [below](#source-installation). ### Dev Tools @@ -22,10 +47,13 @@ Install useful development tools: sudo apt install ros-dev-tools ``` -### Ignition Gazebo +### Gazebo {% tabs ignition %} {% tab ignition galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Ignition Edifice must be installed: @@ -49,28 +77,16 @@ sudo apt-get update && sudo apt-get install ignition-fortress ``` {% endtab %} -{% endtabs %} - -### Debian package - -{% tabs debian %} -{% tab debian galactic %} - -To install the metapackage through apt: - -```bash -sudo apt update -sudo apt install ros-galactic-turtlebot4-simulator ros-galactic-irobot-create-nodes -``` - -{% endtab %} -{% tab debian humble %} +{% tab ignition jazzy %} -To install the metapackage through apt: +Gazebo Harmonic [must be installed](https://gazebosim.org/docs/latest/install_ubuntu/): ```bash -sudo apt update -sudo apt install ros-humble-turtlebot4-simulator +sudo apt-get install curl +sudo curl https://packages.osrfoundation.org/gazebo.gpg --output /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg +echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null +sudo apt-get update +sudo apt-get install gz-harmonic ``` {% endtab %} @@ -84,6 +100,9 @@ Source installation is an alternative to the debian package and should only be u {% tabs setup %} {% tab setup galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` To manually install this metapackage from source, clone the git repository: @@ -135,6 +154,32 @@ colcon build --symlink-install Next, the workspace must be sourced by running `source ~/turtlebot4_ws/install/setup.bash` in the terminal or by adding that command in the `.bashrc` file and sourcing the `.bashrc` file. +{% endtab %} +{% tab setup jazzy %} + +To manually install this metapackage from source, clone the git repository: + +```bash +cd ~/turtlebot4_ws/src +git clone https://github.com/turtlebot/turtlebot4_simulator.git -b jazzy +``` + +Install dependencies: + +```bash +cd ~/turtlebot4_ws +rosdep install --from-path src -yi +``` + +Build the packages: + +```bash +source /opt/ros/jazzy/setup.bash +colcon build --symlink-install +``` + +Next, the workspace must be sourced by running `source ~/turtlebot4_ws/install/setup.bash` in the terminal or by adding that command in the `.bashrc` file and sourcing the `.bashrc` file. + {% endtab %} {% endtabs %} @@ -148,12 +193,15 @@ The simulation can be run in discovery server mode but the discovery server refe Simulated robots and physical robots should not be combined in the same system. ``` -## Ignition Bringup - -The `turtlebot4_ignition_bringup` package contains launch files and configurations to launch Ignition Gazebo. +## Gazebo Bringup {% tabs bringup %} {% tab bringup galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` + +The `turtlebot4_ignition_bringup` package contains launch files and configurations to launch Ignition Gazebo. Launch files: @@ -193,6 +241,7 @@ ros2 launch turtlebot4_ignition_bringup ignition.launch.py slam:=sync nav2:=true {% endtab %} {% tab bringup humble %} +The `turtlebot4_ignition_bringup` package contains launch files and configurations to launch Ignition Gazebo. Launch files: @@ -248,22 +297,89 @@ ros2 launch turtlebot4_ignition_bringup turtlebot4_ignition.launch.py slam:=true ``` {% endtab %} -{% endtabs %} +{% tab bringup jazzy %} +The `turtlebot4_gz_bringup` package contains launch files and configurations to launch Gazebo. -## Ignition GUI Plugins +Launch files: -The `turtlebot4_ignition_gui_plugins` package contains the source code for the TurtleBot 4 HMI GUI plugin. +* [Turtlebot 4 Gazebo Launch](https://github.com/turtlebot/turtlebot4_simulator/blob/jazzy/turtlebot4_gz_bringup/launch/turtlebot4_gz.launch.py): Launches Gazebo and all required nodes to run the simulation. +* [Gazebo](https://github.com/turtlebot/turtlebot4_simulator/blob/jazzy/turtlebot4_gz_bringup/launch/sim.launch.py): Launches Gazebo only. +* [ROS Gazebo Bridge](https://github.com/turtlebot/turtlebot4_simulator/blob/jazzy/turtlebot4_gz_bringup/launch/ros_gz_bridge.launch.py): Launches all of the required `ros_gz_bridge` nodes to bridge Ignition topics with ROS topics. +* [TurtleBot 4 Nodes](https://github.com/turtlebot/turtlebot4_simulator/blob/jazzy/turtlebot4_gz_bringup/launch/turtlebot4_nodes.launch.py): Launches the `turtlebot4_node` and `turtlebot4_ignition_hmi_node` required to control the HMI plugin and robot behaviour. + +Turtlebot 4 Gazebo launch configuration options: + +- **model**: Which TurtleBot 4 model to use + - options: *standard, lite* + - default: *standard* +- **rviz**: Whether to launch rviz + - options: *true, false* + - default: *false* +- **localization**: Whether to launch localization + - options: *true, false* + - default: *false* +- **slam**: Whether to launch SLAM + - options: *true, false* + - default: *false* +- **nav2**: Whether to launch Nav2 + - options: *true, false* + - default: *false* +- **world**: Which world to use for simulation + - options: *depot, maze, warehouse* + - default: *warehouse* +- **namespace**: Optional robot namespace + - options: Any valid ROS 2 name as a string + - default: blank ("") +- **x**: x coordinate of the robot and dock spawn location in the gazebo world + - options: float representing a valid free location in the map + - default: *0.0* +- **y**: y coordinate of the robot and dock spawn location in the gazebo world + - options: float representing a valid free location in the map + - default: *0.0* +- **z**: z coordinate of the robot and dock spawn location in the gazebo world + - options: float representing a valid free location in the map + - default: *0.0* +- **yaw**: robot and dock orientation at spawn in the gazebo world + - options: float representing a valid free location in the map + - default: *0.0* + +Running the simulator with default settings: +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py +``` + +Running synchronous SLAM with Nav2: +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py slam:=true nav2:=true rviz:=true +``` + +{% endtab %} +{% endtabs %} + +## Gazebo GUI Plugins {% tabs bringup %} {% tab bringup galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` + +The `turtlebot4_ignition_gui_plugins` package contains the source code for the TurtleBot 4 HMI GUI plugin. The [TurtleBot 4 HMI GUI plugin](https://github.com/turtlebot/turtlebot4_simulator/tree/galactic/turtlebot4_ignition_gui_plugins/Turtlebot4Hmi) is only used for the standard model. The lite model uses the [Create® 3 HMI GUI plugin](https://github.com/iRobotEducation/create3_sim/tree/main/irobot_create_ignition/irobot_create_ignition_plugins/Create3Hmi). {% endtab %} {% tab bringup humble %} +The `turtlebot4_ignition_gui_plugins` package contains the source code for the TurtleBot 4 HMI GUI plugin. The [TurtleBot 4 HMI GUI plugin](https://github.com/turtlebot/turtlebot4_simulator/tree/humble/turtlebot4_ignition_gui_plugins/Turtlebot4Hmi) is only used for the standard model. The lite model uses the [Create® 3 HMI GUI plugin](https://github.com/iRobotEducation/create3_sim/tree/main/irobot_create_ignition/irobot_create_ignition_plugins/Create3Hmi). +{% endtab %} +{% tab bringup jazzy %} +The `turtlebot4_gz_gui_plugins` package contains the source code for the TurtleBot 4 HMI GUI plugin. + +The [TurtleBot 4 HMI GUI plugin](https://github.com/turtlebot/turtlebot4_simulator/tree/jazzy/turtlebot4_gz_gui_plugins/Turtlebot4Hmi) is only used for the standard model. The lite model uses the [Create® 3 HMI GUI plugin](https://github.com/iRobotEducation/create3_sim/tree/jazzy/irobot_create_gz/irobot_create_gz_plugins/Create3Hmi). + {% endtab %} {% endtabs %} @@ -272,7 +388,20 @@ The [TurtleBot 4 HMI GUI plugin](https://github.com/turtlebot/turtlebot4_simulat
TurtleBot 4 HMI GUI plugin
-## Ignition Toolbox +## Gazebo Toolbox -The `turtlebot4_ignition_toolbox` package contains the source code for the TurtleBot 4 HMI node. The TurtleBot 4 HMI node acts as a bridge between the `turtlebot4_node` and `ros_ign_bridge` to convert the custom [TurtleBot 4 messages](./turtlebot4_common.md#messages) into standard messages such as `Int32` and `String`. +{% tabs toolbox %} +{% tab toolbox galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` +The `turtlebot4_ignition_toolbox` package contains the source code for the TurtleBot 4 HMI node. The TurtleBot 4 HMI node acts as a bridge between the `turtlebot4_node` and `ros_ign_bridge` to convert the custom [TurtleBot 4 messages](./turtlebot4_common.md#messages) into standard messages such as `Int32` and `String`. +{% endtab %} +{% tab toolbox humble %} +The `turtlebot4_ignition_toolbox` package contains the source code for the TurtleBot 4 HMI node. The TurtleBot 4 HMI node acts as a bridge between the `turtlebot4_node` and `ros_ign_bridge` to convert the custom [TurtleBot 4 messages](./turtlebot4_common.md#messages) into standard messages such as `Int32` and `String`. +{% endtab %} +{% tab toolbox jazzy %} +The `turtlebot4_gz_toolbox` package contains the source code for the TurtleBot 4 HMI node. The TurtleBot 4 HMI node acts as a bridge between the `turtlebot4_node` and `ros_gz_bridge` to convert the custom [TurtleBot 4 messages](./turtlebot4_common.md#messages) into standard messages such as `Int32` and `String`. +{% endtab %} +{% endtabs %} \ No newline at end of file diff --git a/troubleshooting/diagnostics.md b/troubleshooting/diagnostics.md index d67755b..241e06e 100644 --- a/troubleshooting/diagnostics.md +++ b/troubleshooting/diagnostics.md @@ -17,13 +17,13 @@ You should see a node called `turtlebot4_diagnostics`. Additionally, calling ```bash ros2 topic list ``` -should list topics such as `/diagnostics`, `/diagnostics_agg`, and `/diagnostics_toplevel_state`. If diagnostics are not running, you can manually run them by calling +should list topics such as `/diagnostics`, `/diagnostics_agg`, and `/diagnostics_toplevel_state`. If diagnostics are not running, you can manually run them by calling -```bash +```bash ros2 launch turtlebot4_diagnostics diagnostics.launch.py -``` +``` -Once diagnostics are running, you can view them with `rqt_robot_monitor`. Ensure that [turtlebot4_desktop](../software/turtlebot4_packages.md#installation-2) is installed on your PC, then call +Once diagnostics are running, you can view them with `rqt_robot_monitor`. Ensure that [turtlebot4_desktop](../software/turtlebot4_packages.md#installation-2) is installed on your PC, then call ```bash ros2 launch turtlebot4_viz view_diagnostics.launch.py @@ -34,7 +34,7 @@ ros2 launch turtlebot4_viz view_diagnostics.launch.py
rqt_robot_monitor with TurtleBot 4 diagnostics
-The monitor will display any errors in the first window, any warnings in the second window, and a summary of all topics in the "All devices" section at the bottom. Each topic has a status level of OK, WARNING, ERROR, or STALE. There is also a more detailed message included as well. You can click on each topic to view more information. +The monitor will display any errors in the first window, any warnings in the second window, and a summary of all topics in the "All devices" section at the bottom. Each topic has a status level of OK, WARNING, ERROR, or STALE. There is also a more detailed message included as well. You can click on each topic to view more information. In this example, the OAK-D node is not running, so the camera topics are not being published. @@ -47,13 +47,16 @@ In this example, the OAK-D node is not running, so the camera topics are not bei For systems experiencing high CPU usage issues or limited bandwidth, it can help to disable the diagnostics whenever they are not actively in use. -{% tabs navigation %} -{% tab navigation galactic %} +{% tabs disable_diagnostics %} +{% tab disable_diagnostics galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Instructions are not currently available for Galactic. {% endtab %} -{% tab navigation humble %} +{% tab disable_diagnostics humble %} To disable diagnostics, SSH into your TurtleBot 4 and run the turtlebot4 setup tool: @@ -62,7 +65,23 @@ To disable diagnostics, SSH into your TurtleBot 4 and run the turtlebot4 setup t turtlebot4-setup ``` -Navigate to 'Bash Setup' in the 'ROS Setup' menu, then change the `DIAGNOSTICS` setting to `False`. +Navigate to 'Bash Setup' in the 'ROS Setup' menu, then change the `DIAGNOSTICS` setting to `False`. + +Save the settings, then apply settings in the main menu. + + +{% endtab %} +{% tab disable_diagnostics jazzy %} + + +To disable diagnostics, SSH into your TurtleBot 4 and run the turtlebot4 setup tool: + +```bash +turtlebot4-setup +``` + +Navigate to 'Bash Setup' in the 'ROS Setup' menu, then change the `DIAGNOSTICS` setting to `False`. + Save the settings, then apply settings in the main menu. diff --git a/troubleshooting/faq.md b/troubleshooting/faq.md index a280396..1e7bf2f 100644 --- a/troubleshooting/faq.md +++ b/troubleshooting/faq.md @@ -84,6 +84,9 @@ There is an automatic power-saving mode that shuts down the OAK-D topics when th {% tabs source %} {% tab source galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Make sure you have sourced ROS 2 Galactic: @@ -100,6 +103,15 @@ Make sure you have sourced ROS 2 Humble: source /opt/ros/humble/setup.bash ``` +{% endtab %} +{% tab source jazzy %} + +Make sure you have sourced ROS 2 Jazzy: + +```bash +source /opt/ros/jazzy/setup.bash +``` + {% endtab %} {% endtabs %} @@ -111,6 +123,45 @@ source /path/to/ws/install/setup.bash ### 2. Create® 3 topics are not visible +{% tabs create3_topics %} +{% tab create3_topics galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` + +First, check that the Create® 3 is connected to your WiFi network. You should be able to access the Create® 3 portal by entering the Create® 3 IP address in a browser. For information on how to connect the Create® 3 to WiFi, check the [Wi-Fi Setup Guide](../setup/simple_discovery.md#wi-fi-setup). + +If it is connected to WiFi, check if you can see Create® 3 topics on the Raspberry Pi. + +If topics are visible on the Raspberry Pi, ensure that your PC has the following configuration set for CycloneDDS: + +```xml + + + + true + + + +``` + +To set this configuration automatically, add the following line to your `~/.bashrc` file. + +```bash +export CYCLONEDDS_URI='true' +``` + +If you have set a `ROS_DOMAIN_ID` for the Create® 3, your terminal will have to have the same ID. You can set the ID by using this command: + +```bash +export ROS_DOMAIN_ID=# +``` + +Replace `#` with the ID. + +If topics are not visible on the Raspberry Pi, you may need to restart the Create® 3 application through the portal, or reboot the robot. +{% endtab %} +{% tab create3_topics humble %} First, check that the Create® 3 is connected to your WiFi network. You should be able to access the Create® 3 portal by entering the Create® 3 IP address in a browser. For information on how to connect the Create® 3 to WiFi, check the [Wi-Fi Setup Guide](../setup/simple_discovery.md#wi-fi-setup). If it is connected to WiFi, check if you can see Create® 3 topics on the Raspberry Pi. @@ -124,7 +175,7 @@ If topics are visible on the Raspberry Pi, ensure that your PC has the following true - + ``` To set this configuration automatically, add the following line to your `~/.bashrc` file. @@ -142,6 +193,53 @@ export ROS_DOMAIN_ID=# Replace `#` with the ID. If topics are not visible on the Raspberry Pi, you may need to restart the Create® 3 application through the portal, or reboot the robot. +{% endtab %} +{% tab create3_topics jazzy %} +First, make sure that the Raspberry Pi's `RMW_IMPLEMENTATION` matches the one supported by your Create® 3 firmware and that your Create® 3's firmware is version `I.*.*`. Reinstall the Create® 3 firmware or change the Raspberry Pi's RMW if needed. + +Check that the Create® 3's topics are visible in the `_do_not_use` namespace. SSH into the Turtlebot 4 and run the following command: +```bash +ros2 topic list --include-hidden-topics | grep _do_not_use +``` +you should see the following topics: +``` +/_do_not_use/audio_note_sequence/_action/feedback +/_do_not_use/audio_note_sequence/_action/status +/_do_not_use/battery_state +/_do_not_use/cmd_audio +/_do_not_use/cmd_lightring +/_do_not_use/cmd_vel +/_do_not_use/cmd_vel_stamped +/_do_not_use/dock/_action/feedback +/_do_not_use/dock/_action/status +/_do_not_use/dock_status +/_do_not_use/drive_arc/_action/feedback +/_do_not_use/drive_arc/_action/status +/_do_not_use/drive_distance/_action/feedback +/_do_not_use/drive_distance/_action/status +/_do_not_use/imu +/_do_not_use/interface_buttons +/_do_not_use/led_animation/_action/feedback +/_do_not_use/led_animation/_action/status +/_do_not_use/navigate_to_position/_action/feedback +/_do_not_use/navigate_to_position/_action/status +/_do_not_use/odom +/_do_not_use/rotate_angle/_action/feedback +/_do_not_use/rotate_angle/_action/status +/_do_not_use/tf +/_do_not_use/tf_static +/_do_not_use/undock/_action/feedback +/_do_not_use/undock/_action/status +/_do_not_use/wall_follow/_action/feedback +/_do_not_use/wall_follow/_action/status +/_do_not_use/wheel_status +``` + +If these topics are not visible, run the `turtlebot4-setup` command and use the "Reset Create3" option to reconfigure the Create® 3's domain ID, namespace, and discovery server settings. + +Once the Create® 3 resets, check if the topics are visible again. If they are still not visible, reboot the robot by removing it from the dock and holding the power button. +{% endtab %} +{% endtabs %} ## Replacement Components for the Create® 3 diff --git a/tutorials/driving.md b/tutorials/driving.md index a9dd666..a19ceba 100644 --- a/tutorials/driving.md +++ b/tutorials/driving.md @@ -18,43 +18,35 @@ The simplest way to get your robot driving is to use a keyboard application on y In order to control the Turtlebot 4 while running the application on your pc, you must set up the [networking](../setup/networking.md) between your robot and your pc, so that they can communicate over ros topics. ``` -{% tabs keyboard %} -{% tab keyboard galactic %} - You can install the `teleop_twist_keyboard` package on your PC by running the following commands: +{% tabs install_apt %} +{% tab install_apt galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` ```bash -sudo apt update sudo apt install ros-galactic-teleop-twist-keyboard ``` - -Once installed, run the node by calling: - +{% endtab %} +{% tab install_apt humble %} ```bash -source /opt/ros/galactic/setup.bash -ros2 run teleop_twist_keyboard teleop_twist_keyboard +sudo apt install ros-humble-teleop-twist-keyboard ``` - {% endtab %} -{% tab keyboard humble %} - -You can install the `teleop_twist_keyboard` package on your PC by running the following commands: - +{% tab install_apt jazzy %} ```bash -sudo apt update -sudo apt install ros-humble-teleop-twist-keyboard +sudo apt install ros-jazzy-teleop-twist-keyboard ``` +{% endtab %} +{% endtabs %} Once installed, run the node by calling: ```bash -source /opt/ros/humble/setup.bash ros2 run teleop_twist_keyboard teleop_twist_keyboard ``` -{% endtab %} -{% endtabs %} - This will start a CLI interface which allows you to press keys to command the robot to drive.
diff --git a/tutorials/first_node_cpp.md b/tutorials/first_node_cpp.md index 5f8dd5a..1493b35 100644 --- a/tutorials/first_node_cpp.md +++ b/tutorials/first_node_cpp.md @@ -8,6 +8,9 @@ This tutorial will go through the steps of creating a ROS 2 package and writing {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` These steps are similar to the [ROS 2 Tutorial](https://docs.ros.org/en/galactic/Tutorials/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html), but focus on interacting with the TurtleBot 4. For source code, click [here](https://github.com/turtlebot/turtlebot4_tutorials/tree/galactic/turtlebot4_cpp_tutorials). @@ -16,6 +19,11 @@ These steps are similar to the [ROS 2 Tutorial](https://docs.ros.org/en/galactic These steps are similar to the [ROS 2 Tutorial](https://docs.ros.org/en/humble/Tutorials/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html), but focus on interacting with the TurtleBot 4. For source code, click [here](https://github.com/turtlebot/turtlebot4_tutorials/tree/humble/turtlebot4_cpp_tutorials). +{% endtab %} +{% tab navigation jazzy %} + + These steps are similar to the [ROS 2 Tutorial](https://docs.ros.org/en/jazzy/Tutorials/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html), but focus on interacting with the TurtleBot 4. For source code, click [here](https://github.com/turtlebot/turtlebot4_tutorials/tree/jazzy/turtlebot4_cpp_tutorials). + {% endtab %} {% endtabs %} @@ -35,6 +43,9 @@ mkdir ~/turtlebot4_ws/src -p {% tabs package %} {% tab package galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` You will need to create a ROS 2 package to hold your files. For this tutorial, we will create a package called `turtlebot4_cpp_tutorials` with a node called `turtlebot4_first_cpp_node`. @@ -55,6 +66,17 @@ cd ~/turtlebot4_ws/src ros2 pkg create --build-type ament_cmake --node-name turtlebot4_first_cpp_node turtlebot4_cpp_tutorials ``` +{% endtab %} +{% tab package jazzy %} + +You will need to create a ROS 2 package to hold your files. For this tutorial, we will create a package called `turtlebot4_cpp_tutorials` with a node called `turtlebot4_first_cpp_node`. + +```bash +source /opt/ros/jazzy/setup.bash +cd ~/turtlebot4_ws/src +ros2 pkg create --build-type ament_cmake --node-name turtlebot4_first_cpp_node turtlebot4_cpp_tutorials +``` + {% endtab %} {% endtabs %} @@ -117,7 +139,7 @@ public: }; ``` -Notice that our class calls the `Node` constructor and passes it the name of our node, `turtlebot4_first_cpp_node`. +Notice that our class calls the `Node` constructor and passes it the name of our node, `turtlebot4_first_cpp_node`. We can now create our node in the `main` function and spin it. Since our node is empty, the node will be created but it won't do anything. @@ -396,7 +418,7 @@ Now we can connect our interface button subscription to our lightring publisher. } ``` -Test this out by building the package and running the node like before. +Test this out by building the package and running the node like before. Press button 1 and the lightring light should look like this: diff --git a/tutorials/first_node_python.md b/tutorials/first_node_python.md index 09bba34..f263cc4 100644 --- a/tutorials/first_node_python.md +++ b/tutorials/first_node_python.md @@ -4,10 +4,13 @@ sort: 3 # Creating your first node (Python) -This tutorial will go through the steps of creating a ROS 2 package and writing a ROS 2 node in Python. For a C++ example, click [here](./first_node_cpp.html#creating-your-first-node-c). +This tutorial will go through the steps of creating a ROS 2 package and writing a ROS 2 node in Python. For a C++ example, click [here](./first_node_cpp.html#creating-your-first-node-c). {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` These steps are similar to the [ROS 2 Tutorial](https://docs.ros.org/en/galactic/Tutorials/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html), but focus on interacting with the TurtleBot 4. For source code, click [here](https://github.com/turtlebot/turtlebot4_tutorials/tree/galactic/turtlebot4_cpp_tutorials). @@ -16,6 +19,11 @@ These steps are similar to the [ROS 2 Tutorial](https://docs.ros.org/en/galactic These steps are similar to the [ROS 2 Tutorial](https://docs.ros.org/en/humble/Tutorials/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html), but focus on interacting with the TurtleBot 4. For source code, click [here](https://github.com/turtlebot/turtlebot4_tutorials/tree/humble/turtlebot4_cpp_tutorials). +{% endtab %} +{% tab navigation jazzy %} + + These steps are similar to the [ROS 2 Tutorial](https://docs.ros.org/en/jazzy/Tutorials/Writing-A-Simple-Cpp-Publisher-And-Subscriber.html), but focus on interacting with the TurtleBot 4. For source code, click [here](https://github.com/turtlebot/turtlebot4_tutorials/tree/jazzy/turtlebot4_cpp_tutorials). + {% endtab %} {% endtabs %} @@ -35,6 +43,9 @@ mkdir ~/turtlebot4_ws/src -p {% tabs package %} {% tab package galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` You will need to create a ROS 2 package to hold your files. For this tutorial, we will create a package called `turtlebot4_python_tutorials` with a node called `turtlebot4_first_python_node`. @@ -55,6 +66,17 @@ cd ~/turtlebot4_ws/src ros2 pkg create --build-type ament_python --node-name turtlebot4_first_python_node turtlebot4_python_tutorials ``` +{% endtab %} +{% tab package jazzy %} + +You will need to create a ROS 2 package to hold your files. For this tutorial, we will create a package called `turtlebot4_python_tutorials` with a node called `turtlebot4_first_python_node`. + +```bash +source /opt/ros/jazzy/setup.bash +cd ~/turtlebot4_ws/src +ros2 pkg create --build-type ament_python --node-name turtlebot4_first_python_node turtlebot4_python_tutorials +``` + {% endtab %} {% endtabs %} @@ -95,7 +117,7 @@ class TurtleBot4FirstNode(Node): super().__init__('turtlebot4_first_python_node') ``` -Notice that our class calls the `super()` constructor and passes it the name of our node, `turtlebot4_first_python_node`. +Notice that our class calls the `super()` constructor and passes it the name of our node, `turtlebot4_first_python_node`. We can now create our node in the `main` function and spin it. Since our node is empty, the node will be created but it won't do anything. @@ -131,7 +153,7 @@ class TurtleBot4FirstNode(Node): '/interface_buttons', self.interface_buttons_callback, qos_profile_sensor_data) - + # Interface buttons subscription callback def interface_buttons_callback(self, create3_buttons_msg: InterfaceButtons): ``` @@ -337,7 +359,7 @@ def interface_buttons_callback(self, create3_buttons_msg: InterfaceButtons): self.button_1_function() ``` -Test this out by running the node like before. +Test this out by running the node like before. Press button 1 and the lightring light should look like this: diff --git a/tutorials/generate_map.md b/tutorials/generate_map.md index 66cbfd0..1c8ceab 100644 --- a/tutorials/generate_map.md +++ b/tutorials/generate_map.md @@ -14,6 +14,9 @@ Remember to always source your ROS 2 environment before trying to launch a node. {% tabs slam %} {% tab slam galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` First, install `turtlebot4_navigation`: @@ -60,6 +63,33 @@ To change map resolution or other SLAM parameters, copy the [default config](htt ros2 launch turtlebot4_navigation slam.launch.py params:=/full/path/to/slam.yaml ``` +{% endtab %} +{% tab slam jazzy %} + +First, install `turtlebot4_navigation`: + +```bash +sudo apt install ros-jazzy-turtlebot4-navigation +``` + +Then run SLAM. It is recommended to run synchronous SLAM on a remote PC to get a higher resolution map. + +```bash +ros2 launch turtlebot4_navigation slam.launch.py +``` + +Asynchronous SLAM can be used as well. + +```bash +ros2 launch turtlebot4_navigation slam.launch.py sync:=false +``` + +To change map resolution or other SLAM parameters, copy the [default config](https://github.com/turtlebot/turtlebot4/blob/jazzy/turtlebot4_navigation/config/slam.yaml) and modify it. Then, pass the parameters in as a launch argument. + +```bash +ros2 launch turtlebot4_navigation slam.launch.py params:=/full/path/to/slam.yaml +``` + {% endtab %} {% endtabs %} @@ -68,9 +98,27 @@ ros2 launch turtlebot4_navigation slam.launch.py params:=/full/path/to/slam.yaml To visualise the map, launch Rviz2 with the `view_robot` launch file on the user computer. This requires a desktop version of Ubuntu with a display and therefore cannot be run on the robot itself. +{% tabs view_map %} +{% tab view_map galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` + ```bash ros2 launch turtlebot4_viz view_robot.launch.py ``` +{% endtab %} +{% tab view_map humble %} +```bash +ros2 launch turtlebot4_viz view_robot.launch.py +``` +{% endtab %} +{% tab view_map jazzy %} +```bash +ros2 launch turtlebot4_viz view_navigation.launch.py +``` +{% endtab %} +{% endtabs %}
RVIZ SLAM diff --git a/tutorials/multiple_robots.md b/tutorials/multiple_robots.md index 28e7325..696e04a 100644 --- a/tutorials/multiple_robots.md +++ b/tutorials/multiple_robots.md @@ -24,6 +24,9 @@ There are four locations in which the **ROS_DOMAIN_ID** environment variable mus {% tabs domain %} {% tab domain galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` For RPi4 images v0.1.3 or higher, a script `ros_config.sh` has been installed which will conveniently set the **ROS_DOMAIN_ID** in the first 3 locations. If you are using an earlier version, you can copy the [script](https://github.com/turtlebot/turtlebot4_setup/blob/galactic/scripts/ros_config.sh) to `/usr/local/bin/` on your RPi4. You will also need to update your `install.py` script by downloading it from [here](https://github.com/turtlebot/turtlebot4_setup/blob/galactic/scripts/install.py) and replacing the existing script in `/usr/local/bin`. @@ -91,7 +94,31 @@ SSH into your TurtleBot 4 and run the turtlebot4 setup tool: turtlebot4-setup ``` -Navigate to 'Bash Setup' in the 'ROS Setup' menu, then change your `ROS_DOMAIN_ID`. Save the settings, then apply settings in the main menu. +Navigate to 'Bash Setup' in the 'ROS Setup' menu, then change your `ROS_DOMAIN_ID`. + +Save the settings, then apply settings in the main menu. + +
+ ROS_DOMAIN_ID +
Setting the ROS_DOMAIN_ID
+
+ +This will apply the new `ROS_DOMAIN_ID` to the Create® 3, RPi4 Terminal, and RPi4 Robot Upstart job. + +On the user PC, set the `ROS_DOMAIN_ID` in your *setup.bash* file and source it. See [Installing ROS 2](../setup/basic.md#installing-ros-2) for more details. + +{% endtab %} +{% tab domain jazzy %} + +SSH into your TurtleBot 4 and run the turtlebot4 setup tool: + +```bash +turtlebot4-setup +``` + +Navigate to 'Bash Setup' in the 'ROS Setup' menu, then change your `ROS_DOMAIN_ID`. + +Save the settings, then apply settings in the main menu.
ROS_DOMAIN_ID @@ -110,12 +137,9 @@ Once the Create® 3 application has restarted, try calling `ros2 topic list` on ## Namespacing -Namespacing is a method of adding a prefix to topic names to group certain topics, or to make them unique. -By namespacing all topics on a TurtleBot 4, we can have a full set of unique topics for that robot. This allows -us to run multiple robots on the same `ROS_DOMAIN_ID`. +Namespacing is a method of adding a prefix to topic names to group certain topics, or to make them unique. By namespacing all topics on a TurtleBot 4, we can have a full set of unique topics for that robot. This allows us to run multiple robots on the same `ROS_DOMAIN_ID`. -It is common to use the name of the robot as the namespace. For example, -if we have a robot named `robot1`, the namespaced topics would look like: +It is common to use the name of the robot as the namespace. For example, if we have a robot named `robot1`, the namespaced topics would look like: ```bash ubuntu@ubuntu:~$ ros2 topic list @@ -156,6 +180,9 @@ ubuntu@ubuntu:~$ ros2 topic list {% tabs namespacing %} {% tab namespacing galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Namespacing is not supported in Galactic. @@ -168,7 +195,8 @@ To set the robot namespace, SSH into your TurtleBot 4 and run the turtlebot4 set turtlebot4-setup ``` -Navigate to 'Bash Setup' in the 'ROS Setup' menu, then change the `ROBOT_NAMESPACE` setting. +Navigate to 'Bash Setup' in the 'ROS Setup' menu, then change the `ROBOT_NAMESPACE` setting. + Save the settings, then apply settings in the main menu.
@@ -214,7 +242,65 @@ ros2 launch turtlebot4_navigation localization.launch.py map:=office.yaml namesp ros2 launch turtlebot4_navigation nav2.launch.py namespace:=/robot1 ``` -Replace `robot1` with the desired robot namespace. +Replace `robot1` with the desired robot namespace. + +{% endtab %} +{% tab namespacing jazzy %} + +To set the robot namespace, SSH into your TurtleBot 4 and run the turtlebot4 setup tool: + +```bash +turtlebot4-setup +``` + +Navigate to 'Bash Setup' in the 'ROS Setup' menu, then change the `ROBOT_NAMESPACE` setting. + +Save the settings, then apply settings in the main menu. + +
+ namespace +
Setting the robot namespace
+
+ +This will apply the new namespace to the Create® 3, RPi4 Terminal, and RPi4 Robot Upstart job. + +### Viewing the Robot in RViz + +On the user PC, `turtlebot4_desktop` launch files can use a `namespace` argument to view a specific robot: + +```bash +ros2 launch turtlebot4_viz view_robot.launch.py namespace:=/robot1 +``` + +### Launching Robots in Simulation + +The first robot can be launched normally, with the addition of a `namespace`. All other parameters are still available as shown below: + +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py namespace:=/robot1 nav2:=true slam:=false localization:=true rviz:=true +``` + +Any additional robots must be launched using the `turtlebot4_spawn` launch file, a unique `namespace` and a unique spawn location: + +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_spawn.launch.py namespace:=/robot2 x:=0.0 y:=1.0 nav2:=true slam:=false localization:=true rviz:=true +``` + +```note +Not all functionality is currently fully supported in multi-robot simulation. +``` + +### Launching Navigation + +The SLAM, Localization and Nav2 launch files all support namespacing and can be launched as follows: + +```bash +ros2 launch turtlebot4_navigation slam.launch.py namespace:=/robot1 +ros2 launch turtlebot4_navigation localization.launch.py map:=office.yaml namespace:=/robot1 +ros2 launch turtlebot4_navigation nav2.launch.py namespace:=/robot1 +``` + +Replace `robot1` with the desired robot namespace. {% endtab %} {% endtabs %} \ No newline at end of file diff --git a/tutorials/navigation.md b/tutorials/navigation.md index 231b862..ff9a287 100644 --- a/tutorials/navigation.md +++ b/tutorials/navigation.md @@ -12,7 +12,7 @@ There are two localization methods we can use to figure out where the robot is o ### SLAM -SLAM is useful for generating a new map, or navigating in unknown or dynamic environments. It updates the map as it detects and changes, but cannot see areas of the environment that it has not discovered yet. +SLAM is useful for generating a new map, or navigating in unknown or dynamic environments. It updates the map as it detects and changes, but cannot see areas of the environment that it has not discovered yet. ### Localization @@ -22,7 +22,7 @@ For this tutorial, we will be using localization to navigate on a map [generated ## Nav2 -The TurtleBot 4 uses the [Nav2](https://navigation.ros.org/) stack for navigation. +The TurtleBot 4 uses the [Nav2](https://docs.nav2.org/) stack for navigation. ```note Remember to always source your ROS 2 environment before trying to launch a node. @@ -32,6 +32,9 @@ Remember to always source your ROS 2 environment before trying to launch a node. {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` For this tutorial we can launch navigation with [Nav Bringup](https://github.com/turtlebot/turtlebot4/blob/galactic/turtlebot4_navigation/launch/nav_bringup.launch.py). @@ -65,7 +68,7 @@ For this tutorial we can launch navigation with the [turtlebot4_navigation](http **For a physical TurtleBot 4:** -If you do not have a map of the environment, [generate a map](./generate_map.md) first. +If you do not have a map of the environment, [generate a map](./generate_map.md) first. Open a terminal and launch [localization](https://github.com/turtlebot/turtlebot4/blob/humble/turtlebot4_navigation/launch/localization.launch.py): @@ -95,7 +98,7 @@ Once the Gazebo window loads, ensure to press the "Play" button to start the sim This will launch the simulation in the default `warehouse` world and will use the existing [`warehouse.yaml`](https://github.com/turtlebot/turtlebot4/blob/humble/turtlebot4_navigation/maps/warehouse.yaml) file for the map. -To launch a different supported world, see the [simulation package](../software/turtlebot4_simulator.md#ignition-bringup) for a list of supported worlds. You must pass the name of the chosen world and the path to the map file. +To launch a different supported world, see the [simulation package](../software/turtlebot4_simulator.md#gazebo-bringup) for a list of supported worlds. You must pass the name of the chosen world and the path to the map file. For example: ```bash @@ -111,6 +114,59 @@ ros2 launch turtlebot4_ignition_bringup turtlebot4_ignition.launch.py nav2:=true rviz:=true world:=classroom map:=path/to/classroom.yaml ``` +{% endtab %} +{% tab navigation jazzy %} + +For this tutorial we can launch navigation with the [turtlebot4_navigation](https://github.com/turtlebot/turtlebot4/tree/jazzy/turtlebot4_navigation) package. + +**For a physical TurtleBot 4:** + +If you do not have a map of the environment, [generate a map](./generate_map.md) first. + +Open a terminal and launch [localization](https://github.com/turtlebot/turtlebot4/blob/jazzy/turtlebot4_navigation/launch/localization.launch.py): + +```bash +ros2 launch turtlebot4_navigation localization.launch.py map:=office.yaml +``` + +Replace `office.yaml` with the path to your own map. + +Then, in another terminal, launch [nav2](https://github.com/turtlebot/turtlebot4/blob/jazzy/turtlebot4_navigation/launch/nav2.launch.py): + +```bash +ros2 launch turtlebot4_navigation nav2.launch.py +``` + +```note +If using multiple robots through the namespacing method, an additional `namespace` parameter must be passed to both the Localization and Nav2 launch files. For example: `namespace:=/robot1` See [Multiple robots](./multiple_robots.md) for more details. +``` + +**If you are using the simulator, call:** + +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py nav2:=true slam:=false localization:=true rviz:=true +``` + +Once the Gazebo window loads, ensure to press the "Play" button to start the simulation. + +This will launch the simulation in the default `warehouse` world and will use the existing [`warehouse.yaml`](https://github.com/turtlebot/turtlebot4/blob/jazzy/turtlebot4_navigation/maps/warehouse.yaml) file for the map. + +To launch a different supported world, see the [simulation package](../software/turtlebot4_simulator.md#gazebo-bringup) for a list of supported worlds. You must pass the name of the chosen world and the path to the map file. + +For example: +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py nav2:=true slam:=false localization:=true \ +rviz:=true world:=depot map:=/opt/ros/jazzy/share/turtlebot4_navigation/maps/depot.yaml +``` + +If you are using a custom world you will need to build the [turtlebot4_simulator package](../software/turtlebot4_simulator.md#source-installation) from source and place your world file [alongside the others](https://github.com/turtlebot/turtlebot4_simulator/tree/jazzy/turtlebot4_gz_bringup/worlds). You will then need to create a map for it and pass both the world name and the map file path in as launch arguments. + +For example: +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py nav2:=true slam:=false localization:=true \ +rviz:=true world:=classroom map:=path/to/classroom.yaml +``` + {% endtab %} {% endtabs %} @@ -122,9 +178,26 @@ An initial pose is required before navigation can begin. If you are using the physical robot: In a new terminal launch Rviz so that you can view the map and interact with navigation: +{% tabs view_nav %} +{% tab view_nav galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` ```bash ros2 launch turtlebot4_viz view_robot.launch.py ``` +{% endtab %} +{% tab view_nav humble %} +```bash +ros2 launch turtlebot4_viz view_robot.launch.py +``` +{% endtab %} +{% tab view_nav jazzy %} +```bash +ros2 launch turtlebot4_viz view_navigation.launch.py +``` +{% endtab %} +{% endtabs %} ```note If using multiple robots through the namespacing method, an additional `namespace` parameter must be passed. For example: `namespace:=/robot1` See [Multiple robots](./multiple_robots.md) for more details. diff --git a/tutorials/turtlebot4_navigator.md b/tutorials/turtlebot4_navigator.md index 4ee0be4..816a707 100644 --- a/tutorials/turtlebot4_navigator.md +++ b/tutorials/turtlebot4_navigator.md @@ -6,6 +6,9 @@ sort: 6 {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` The [TurtleBot 4 Navigator](https://github.com/turtlebot/turtlebot4/blob/galactic/turtlebot4_navigation/turtlebot4_navigation/turtlebot4_navigator.py) is a Python node that adds on to the [Nav2 Simple Commander](https://github.com/ros-planning/navigation2/blob/galactic/nav2_simple_commander/nav2_simple_commander/robot_navigator.py). It includes TurtleBot 4 specific features such as docking and undocking, as well as easy to use methods for navigating. @@ -14,6 +17,11 @@ The [TurtleBot 4 Navigator](https://github.com/turtlebot/turtlebot4/blob/galacti The [TurtleBot 4 Navigator](https://github.com/turtlebot/turtlebot4/blob/humble/turtlebot4_navigation/turtlebot4_navigation/turtlebot4_navigator.py) is a Python node that adds on to the [Nav2 Simple Commander](https://github.com/ros-planning/navigation2/blob/humble/nav2_simple_commander/nav2_simple_commander/robot_navigator.py). It includes TurtleBot 4 specific features such as docking and undocking, as well as easy to use methods for navigating. +{% endtab %} +{% tab navigation jazzy %} + +The [TurtleBot 4 Navigator](https://github.com/turtlebot/turtlebot4/blob/jazzy/turtlebot4_navigation/turtlebot4_navigation/turtlebot4_navigator.py) is a Python node that adds on to the [Nav2 Simple Commander](https://github.com/ros-planning/navigation2/blob/jazzy/nav2_simple_commander/nav2_simple_commander/robot_navigator.py). It includes TurtleBot 4 specific features such as docking and undocking, as well as easy to use methods for navigating. + {% endtab %} {% endtabs %} @@ -35,6 +43,9 @@ This example demonstrates the same behaviour as [Nav2 Goal](./navigation.md/#nav {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` To run this example, start the Ignition Gazebo simulation: @@ -67,6 +78,23 @@ Next, open another terminal and run: ros2 run turtlebot4_python_tutorials nav_to_pose ``` +{% endtab %} +{% tab navigation jazzy %} + +To run this example, start the Gazebo simulation: + +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py nav2:=true slam:=false localization:=true rviz:=true +``` + +Once the simulation has started, ensure to press the "Play" button on Gazebo to start the simulation. + +Next, open another terminal and run: + +```bash +ros2 run turtlebot4_python_tutorials nav_to_pose +``` + {% endtab %} {% endtabs %} @@ -75,6 +103,9 @@ ros2 run turtlebot4_python_tutorials nav_to_pose {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/galactic/turtlebot4_python_tutorials/turtlebot4_python_tutorials/nav_to_pose.py). @@ -118,6 +149,45 @@ def main(): The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/humble/turtlebot4_python_tutorials/turtlebot4_python_tutorials/nav_to_pose.py). +Let's take a look at the main function. + +```py +def main(): + rclpy.init() + + navigator = TurtleBot4Navigator() + + # Start on dock + if not navigator.getDockedStatus(): + navigator.info('Docking before initialising pose') + navigator.dock() + + # Set initial pose + initial_pose = navigator.getPoseStamped([0.0, 0.0], TurtleBot4Directions.NORTH) + navigator.setInitialPose(initial_pose) + + # Wait for Nav2 + navigator.waitUntilNav2Active() + + # Set goal poses + goal_pose = navigator.getPoseStamped([-13.0, 9.0], TurtleBot4Directions.EAST) + + # Undock + navigator.undock() + + # Go to each goal pose + navigator.startToPose(goal_pose) + + rclpy.shutdown() +``` + +{% endtab %} +{% tab navigation jazzy %} + + +The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/jazzy/turtlebot4_python_tutorials/turtlebot4_python_tutorials/nav_to_pose.py). + + Let's take a look at the main function. ```py @@ -217,6 +287,9 @@ This call will block until Nav2 is ready. Make sure you have launched Nav2. {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` Now we can create a [geometry_msgs/PoseStamped](https://github.com/ros2/common_interfaces/blob/galactic/geometry_msgs/msg/PoseStamped.msg) message. The `getPoseStamped` method makes it easy for us. All we have to do is pass in a list describing the x and y position that we want to drive to on the map, and the direction that we want the robot to be facing when it reaches that point. @@ -233,6 +306,15 @@ Now we can create a [geometry_msgs/PoseStamped](https://github.com/ros2/common_i goal_pose = navigator.getPoseStamped([-13.0, 9.0], TurtleBot4Directions.EAST) ``` +{% endtab %} +{% tab navigation jazzy %} + +Now we can create a [geometry_msgs/PoseStamped](https://github.com/ros2/common_interfaces/blob/jazzy/geometry_msgs/msg/PoseStamped.msg) message. The `getPoseStamped` method makes it easy for us. All we have to do is pass in a list describing the x and y position that we want to drive to on the map, and the direction that we want the robot to be facing when it reaches that point. + +```py +goal_pose = navigator.getPoseStamped([-13.0, 9.0], TurtleBot4Directions.EAST) +``` + {% endtab %} {% endtabs %} @@ -258,6 +340,9 @@ ros2 launch turtlebot4_viz view_robot.launch.py {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +```
Nav to pose @@ -275,6 +360,17 @@ ros2 launch turtlebot4_viz view_robot.launch.py
Navigate to a pose (3x speed)
+{% endtab %} +{% tab navigation jazzy %} + +
+ +
Navigate to a pose (3x speed)
+
+ {% endtab %} {% endtabs %} @@ -282,8 +378,11 @@ ros2 launch turtlebot4_viz view_robot.launch.py {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` -This example demonstrates the [Navigate Through Poses](https://navigation.ros.org/behavior_trees/trees/nav_through_poses_recovery.html) behaviour tree. The Nav2 stack is given a set of poses on the map and creates a path that goes through each pose in order until the last pose is reached. The robot then attempts to drive along the path. This example is demonstrated in the `depot` world of the TurtleBot 4 simulation. +This example demonstrates the [Navigate Through Poses](https://docs.nav2.org/behavior_trees/trees/nav_through_poses_recovery.html) behaviour tree. The Nav2 stack is given a set of poses on the map and creates a path that goes through each pose in order until the last pose is reached. The robot then attempts to drive along the path. This example is demonstrated in the `depot` world of the TurtleBot 4 simulation. To run this example, start the Ignition Gazebo simulation: @@ -318,6 +417,25 @@ Next, open another terminal and run: ros2 run turtlebot4_python_tutorials nav_through_poses ``` +{% endtab %} +{% tab navigation jazzy %} + +This example demonstrates the [Navigate Through Poses](https://navigation.ros.org/behavior_trees/trees/nav_through_poses_recovery.html) behaviour tree. The Nav2 stack is given a set of poses on the map and creates a path that goes through each pose in order until the last pose is reached. The robot then attempts to drive along the path. This example is demonstrated in the `warehouse` world of the TurtleBot 4 simulation. + +To run this example, start the Gazebo simulation: + +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py nav2:=true slam:=false localization:=true rviz:=true +``` + +Once the simulation has started, ensure to press the "Play" button on Gazebo to start the simulation. + +Next, open another terminal and run: + +```bash +ros2 run turtlebot4_python_tutorials nav_through_poses +``` + {% endtab %} {% endtabs %} @@ -325,6 +443,9 @@ ros2 run turtlebot4_python_tutorials nav_through_poses {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/galactic/turtlebot4_python_tutorials/turtlebot4_python_tutorials/nav_through_poses.py). @@ -377,6 +498,53 @@ def main(): The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/humble/turtlebot4_python_tutorials/turtlebot4_python_tutorials/nav_through_poses.py). +Let's take a look at the main function. + +```py +def main(): + rclpy.init() + + navigator = TurtleBot4Navigator() + + # Start on dock + if not navigator.getDockedStatus(): + navigator.info('Docking before initialising pose') + navigator.dock() + + # Set initial pose + initial_pose = navigator.getPoseStamped([0.0, 0.0], TurtleBot4Directions.NORTH) + navigator.setInitialPose(initial_pose) + + # Wait for Nav2 + navigator.waitUntilNav2Active() + + # Set goal poses + goal_pose = [] + goal_pose.append(navigator.getPoseStamped([-3.0, -0.0], TurtleBot4Directions.EAST)) + goal_pose.append(navigator.getPoseStamped([-3.0, -3.0], TurtleBot4Directions.NORTH)) + goal_pose.append(navigator.getPoseStamped([3.0, -3.0], TurtleBot4Directions.NORTH_WEST)) + goal_pose.append(navigator.getPoseStamped([9.0, -1.0], TurtleBot4Directions.WEST)) + goal_pose.append(navigator.getPoseStamped([9.0, 1.0], TurtleBot4Directions.SOUTH)) + goal_pose.append(navigator.getPoseStamped([-1.0, 1.0], TurtleBot4Directions.EAST)) + + # Undock + navigator.undock() + + # Navigate through poses + navigator.startThroughPoses(goal_pose) + + # Finished navigating, dock + navigator.dock() + + rclpy.shutdown() +``` + +{% endtab %} +{% tab navigation jazzy %} + +The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/jazzy/turtlebot4_python_tutorials/turtlebot4_python_tutorials/nav_through_poses.py). + + Let's take a look at the main function. ```py @@ -429,6 +597,9 @@ The next step is to create a list of `PoseStamped` messages which represent the {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` ```py goal_pose = [] @@ -452,6 +623,19 @@ goal_pose.append(navigator.getPoseStamped([9.0, 1.0], TurtleBot4Directions.SOUTH goal_pose.append(navigator.getPoseStamped([-1.0, 1.0], TurtleBot4Directions.EAST)) ``` +{% endtab %} +{% tab navigation jazzy %} + +```py +goal_pose = [] +goal_pose.append(navigator.getPoseStamped([-3.0, -0.0], TurtleBot4Directions.EAST)) +goal_pose.append(navigator.getPoseStamped([-3.0, -3.0], TurtleBot4Directions.NORTH)) +goal_pose.append(navigator.getPoseStamped([3.0, -3.0], TurtleBot4Directions.NORTH_WEST)) +goal_pose.append(navigator.getPoseStamped([9.0, -1.0], TurtleBot4Directions.WEST)) +goal_pose.append(navigator.getPoseStamped([9.0, 1.0], TurtleBot4Directions.SOUTH)) +goal_pose.append(navigator.getPoseStamped([-1.0, 1.0], TurtleBot4Directions.EAST)) +``` + {% endtab %} {% endtabs %} @@ -476,6 +660,9 @@ ros2 launch turtlebot4_viz view_robot.launch.py ``` {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +```
Nav through pose @@ -493,6 +680,17 @@ ros2 launch turtlebot4_viz view_robot.launch.py
Navigate through a set of poses
+{% endtab %} +{% tab navigation jazzy %} + +
+ +
Navigate through a set of poses
+
+ {% endtab %} {% endtabs %} @@ -500,6 +698,9 @@ ros2 launch turtlebot4_viz view_robot.launch.py {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` This example demonstrates how to follow waypoints. The Nav2 stack is given a set of waypoints on the map and creates a path that goes through each waypoint in order until the last waypoint is reached. The robot then attempts to drive along the path. The difference between this example and Navigating Through Poses is that when following waypoints the robot will plan to reach each waypoint individually, rather than planning to reach the last pose by driving through the other poses. This example is demonstrated in the `depot` world of the TurtleBot 4 simulation. @@ -536,6 +737,25 @@ Next, open another terminal and run: ros2 run turtlebot4_python_tutorials follow_waypoints ``` +{% endtab %} +{% tab navigation jazzy %} + +This example demonstrates how to follow waypoints. The Nav2 stack is given a set of waypoints on the map and creates a path that goes through each waypoint in order until the last waypoint is reached. The robot then attempts to drive along the path. The difference between this example and Navigating Through Poses is that when following waypoints the robot will plan to reach each waypoint individually, rather than planning to reach the last pose by driving through the other poses. This example is demonstrated in the `depot` world of the TurtleBot 4 simulation. + +To run this example, start the Gazebo simulation: + +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py nav2:=true slam:=false localization:=true rviz:=true +``` + +Once the simulation has started, ensure to press the "Play" button on Gazebo to start the simulation. + +Next, open another terminal and run: + +```bash +ros2 run turtlebot4_python_tutorials follow_waypoints +``` + {% endtab %} {% endtabs %} @@ -544,6 +764,9 @@ ros2 run turtlebot4_python_tutorials follow_waypoints {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/galactic/turtlebot4_python_tutorials/turtlebot4_python_tutorials/follow_waypoints.py). @@ -552,6 +775,11 @@ The source code for this example is available [here](https://github.com/turtlebo The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/humble/turtlebot4_python_tutorials/turtlebot4_python_tutorials/follow_waypoints.py). +{% endtab %} +{% tab navigation jazzy %} + +The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/jazzy/turtlebot4_python_tutorials/turtlebot4_python_tutorials/follow_waypoints.py). + {% endtab %} {% endtabs %} @@ -607,6 +835,9 @@ ros2 launch turtlebot4_viz view_robot.launch.py {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +```
Follow Waypoints @@ -624,6 +855,17 @@ ros2 launch turtlebot4_viz view_robot.launch.py
Follow a set of Waypoints
+{% endtab %} +{% tab navigation jazzy %} + +
+ +
Follow a set of Waypoints
+
+ {% endtab %} {% endtabs %} @@ -650,6 +892,9 @@ ros2 launch turtlebot4_viz view_robot.launch.py {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/galactic/turtlebot4_python_tutorials/turtlebot4_python_tutorials/create_path.py). @@ -658,6 +903,11 @@ The source code for this example is available [here](https://github.com/turtlebo The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/humble/turtlebot4_python_tutorials/turtlebot4_python_tutorials/create_path.py). +{% endtab %} +{% tab navigation jazzy %} + +The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/jazzy/turtlebot4_python_tutorials/turtlebot4_python_tutorials/create_path.py). + {% endtab %} {% endtabs %} @@ -754,6 +1004,9 @@ Running this example will look something like this: {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +```
Create Path @@ -771,6 +1024,17 @@ Running this example will look something like this:
Creating a path and following it
+{% endtab %} +{% tab navigation jazzy %} + +
+ +
Creating a path and following it
+
+ {% endtab %} {% endtabs %} @@ -782,8 +1046,11 @@ As the path is created, you will see the robot being placed at the position you {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` -This tutorial is only available in Humble +This tutorial is not available in Galactic. {% endtab %} {% tab navigation humble %} @@ -804,6 +1071,25 @@ Next, open another terminal and run: ros2 run turtlebot4_python_tutorials mail_delivery ``` +{% endtab %} +{% tab navigation jazzy %} + +This example demonstrates how to create an interactive delivery route. The user is able to send the robot to different pre-defined locations on demand using the terminal interface. It then uses the [Navigate to Pose](#navigate-to-pose) behaviour to navigate to the pose. + +To run this example, start the Gazebo simulation: + +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py nav2:=true slam:=false localization:=true rviz:=true +``` + +Once the simulation has started, ensure to press the "Play" button on Gazebo to start the simulation. + +Next, open another terminal and run: + +```bash +ros2 run turtlebot4_python_tutorials mail_delivery +``` + {% endtab %} {% endtabs %} @@ -811,8 +1097,11 @@ ros2 run turtlebot4_python_tutorials mail_delivery {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` -This tutorial is only available in Humble +This tutorial is not available in Galactic. {% endtab %} {% tab navigation humble %} @@ -927,9 +1216,9 @@ goal_options = [ #### Select the Goal Pose -The remainder of the program is repeated in a loop. +The remainder of the program is repeated in a loop. -A list of goals is compiled and displayed on the terminal as a prompt and the program will wait for input from the user. +A list of goals is compiled and displayed on the terminal as a prompt and the program will wait for input from the user. ```py # Create a list of the goals for display @@ -947,7 +1236,7 @@ The terminal will display:
Mail Delivery Terminal Prompt
-The user will then enter a number and press enter. +The user will then enter a number and press enter. #### User Input Validation @@ -979,30 +1268,221 @@ elif goal_options[selected_index]['name'] == 'Exit': ``` {% endtab %} -{% endtabs %} +{% tab navigation jazzy %} -### Watch navigation progress in Rviz +The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/jazzy/turtlebot4_python_tutorials/turtlebot4_python_tutorials/mail_delivery.py). -{% tabs navigation %} -{% tab navigation galactic %} +Let's take a look at the main function. -This tutorial is only available in Humble +```py +def main(args=None): + rclpy.init(args=args) -{% endtab %} -{% tab navigation humble %} + navigator = TurtleBot4Navigator() -
- -
Mail Delivery (3x speed)
-
+ # Start on dock + if not navigator.getDockedStatus(): + navigator.info('Docking before initialising pose') + navigator.dock() + # Set initial pose + initial_pose = navigator.getPoseStamped([0.0, 0.0], TurtleBot4Directions.NORTH) + navigator.setInitialPose(initial_pose) -#### Navigate + # Wait for Nav2 + navigator.waitUntilNav2Active() -Finally, navigate to the selected position. + # Undock + navigator.undock() + + # Prepare goal pose options + goal_options = [ + {'name': 'Home', + 'pose': navigator.getPoseStamped([-1.0, 1.0], TurtleBot4Directions.EAST)}, + + {'name': 'Position 1', + 'pose': navigator.getPoseStamped([10.0, 6.0], TurtleBot4Directions.EAST)}, + + {'name': 'Position 2', + 'pose': navigator.getPoseStamped([-9.0, 9.0], TurtleBot4Directions.NORTH)}, + + {'name': 'Position 3', + 'pose': navigator.getPoseStamped([-12.0, 2.0], TurtleBot4Directions.NORTH_WEST)}, + + {'name': 'Position 4', + 'pose': navigator.getPoseStamped([3.0, -7.0], TurtleBot4Directions.WEST)}, + + {'name': 'Exit', + 'pose': None} + ] + + navigator.info('Welcome to the mail delivery service.') + + while True: + # Create a list of the goals for display + options_str = 'Please enter the number corresponding to the desired robot goal position:\n' + for i in range(len(goal_options)): + options_str += f' {i}. {goal_options[i]["name"]}\n' + + # Prompt the user for the goal location + raw_input = input(f'{options_str}Selection: ') + + selected_index = 0 + + # Verify that the value input is a number + try: + selected_index = int(raw_input) + except ValueError: + navigator.error(f'Invalid goal selection: {raw_input}') + continue + + # Verify that the user input is within a valid range + if (selected_index < 0) or (selected_index >= len(goal_options)): + navigator.error(f'Goal selection out of bounds: {selected_index}') + + # Check for exit + elif goal_options[selected_index]['name'] == 'Exit': + break + + else: + # Navigate to requested position + navigator.startToPose(goal_options[selected_index]['pose']) + + rclpy.shutdown() +``` +This example starts the same as [navigate to pose](#navigate-to-pose). We initialise the node, make sure the robot is docked, and set the initial pose. Then we wait for Nav2 to become active. + +#### Prepare Goal Poses + +The next step is to create a list of `PoseStamped` messages which represent all possible poses that the robot can be sent to. + +```py +goal_options = [ + {'name': 'Home', + 'pose': navigator.getPoseStamped([-1.0, 1.0], TurtleBot4Directions.EAST)}, + + {'name': 'Position 1', + 'pose': navigator.getPoseStamped([10.0, 6.0], TurtleBot4Directions.EAST)}, + + {'name': 'Position 2', + 'pose': navigator.getPoseStamped([-9.0, 9.0], TurtleBot4Directions.NORTH)}, + + {'name': 'Position 3', + 'pose': navigator.getPoseStamped([-12.0, 2.0], TurtleBot4Directions.NORTH_WEST)}, + + {'name': 'Position 4', + 'pose': navigator.getPoseStamped([3.0, -7.0], TurtleBot4Directions.WEST)}, + + {'name': 'Exit', + 'pose': None} +] +``` + +#### Select the Goal Pose + +The remainder of the program is repeated in a loop. + +A list of goals is compiled and displayed on the terminal as a prompt and the program will wait for input from the user. + +```py +# Create a list of the goals for display +options_str = 'Please enter the number corresponding to the desired robot goal position:\n' +for i in range(len(goal_options)): + options_str += f' {i}. {goal_options[i]["name"]}\n' + +# Prompt the user for the goal location +raw_input = input(f'{options_str}Selection: ') +``` +The terminal will display: + +
+ Mail Delivery Terminal +
Mail Delivery Terminal Prompt
+
+ +The user will then enter a number and press enter. + +#### User Input Validation + +The user input is verified to be an integer which is within the allowable range. If it is not a number or if the number does not correspond to a valid option then the loop will restart, prompting the user for a new input. + +```py +selected_index = 0 + +# Verify that the value input is a number +try: + selected_index = int(raw_input) +except ValueError: + navigator.error(f'Invalid goal selection: {raw_input}') + continue + +# Verify that the user input is within a valid range +if (selected_index < 0) or (selected_index >= len(goal_options)): + navigator.error(f'Goal selection out of bounds: {selected_index}') +``` + +#### Check for exit + +If the user selected to exit the program then the loop is terminated and the program will exit. + +```py +# Check for exit +elif goal_options[selected_index]['name'] == 'Exit': + break +``` + +{% endtab %} +{% endtabs %} + +### Watch navigation progress in Rviz + +{% tabs navigation %} +{% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` + +This tutorial is not available in Galactic. + +{% endtab %} +{% tab navigation humble %} + +
+ +
Mail Delivery (3x speed)
+
+ + +#### Navigate + +Finally, navigate to the selected position. + +```py +else: + # Navigate to requested position + navigator.startToPose(goal_options[selected_index]['pose']) +``` + +The loop then repeats, prompting the user for the next goal position. + +{% endtab %} +{% tab navigation jazzy %} + +
+ +
Mail Delivery (3x speed)
+
+ + +#### Navigate + +Finally, navigate to the selected position. ```py else: @@ -1020,8 +1500,11 @@ The loop then repeats, prompting the user for the next goal position. {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` -This tutorial is only available in Humble +This tutorial is not available in Galactic. {% endtab %} {% tab navigation humble %} @@ -1042,6 +1525,25 @@ Next, open another terminal and run: ros2 run turtlebot4_python_tutorials patrol_loop ``` +{% endtab %} +{% tab navigation jazzy %} + +This example demonstrates how to create an infinite patrol loop with auto-charging. The robot will continuously drive through a set of poses until the charge is low and then it will go charge. Once the robot is sufficiently charged, it will start driving through the set of poses again. It uses the [Navigate to Pose](#navigate-to-pose) behaviour to navigate to the pose. + +To run this example, start the Gazebo simulation: + +```bash +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py nav2:=true slam:=false localization:=true rviz:=true +``` + +Once the simulation has started, ensure to press the "Play" button on Gazebo to start the simulation. + +Next, open another terminal and run: + +```bash +ros2 run turtlebot4_python_tutorials patrol_loop +``` + {% endtab %} {% endtabs %} @@ -1049,8 +1551,11 @@ ros2 run turtlebot4_python_tutorials patrol_loop {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` -This tutorial is only available in Humble +This tutorial is not available in Galactic. {% endtab %} {% tab navigation humble %} @@ -1085,7 +1590,276 @@ class BatteryMonitor(Node): executor.add_node(self) executor.spin() ``` -This class serves to monitor the Create3® battery charge percentage and to make it available for decision making. +This class serves to monitor the Create3® battery charge percentage and to make it available for decision making. + +##### Subscription + +The class contains a subscriber that listens on the `battery_state` topic for the latest battery state published by the Create3® and calls the `battery_state_callback` function whenever new information has been published. + +```py +# Subscribe to the /battery_state topic +self.battery_state_subscriber = self.create_subscription( + BatteryState, + 'battery_state', + self.battery_state_callback, + qos_profile_sensor_data) +``` + +##### Battery State Callback + +Whenever a `battery_state` message is received, the battery charge percentage is saved in a member variable. + +A Global Interpreter Lock (GIL) is used to ensure that the main function and battery monitoring functions do not access or modify that member variable at the same time. The process will queue until the lock is available. + +```py +# Callbacks +def battery_state_callback(self, batt_msg: BatteryState): + with self.lock: + self.battery_percent = batt_msg.percentage +``` + +##### Prepare Threading + +In order to listen for new messages and run callbacks, a node must be actively spinning. To simultaneously spin the node and run the navigation code, multi-threading is used. Here the battery node is prepared to spin in a separate thread which is created in the main function (see below). + +```py +def thread_function(self): + executor = SingleThreadedExecutor() + executor.add_node(self) + executor.spin() + +``` + +#### Main Function +Let's take a look at the main function. + +```py +def main(args=None): + rclpy.init(args=args) + + lock = Lock() + battery_monitor = BatteryMonitor(lock) + + navigator = TurtleBot4Navigator() + battery_percent = None + position_index = 0 + + thread = Thread(target=battery_monitor.thread_function, daemon=True) + thread.start() + + # Start on dock + if not navigator.getDockedStatus(): + navigator.info('Docking before initialising pose') + navigator.dock() + + # Set initial pose + initial_pose = navigator.getPoseStamped([0.0, 0.0], TurtleBot4Directions.NORTH) + navigator.setInitialPose(initial_pose) + + # Wait for Nav2 + navigator.waitUntilNav2Active() + + # Undock + navigator.undock() + + # Prepare goal poses + goal_pose = [] + goal_pose.append(navigator.getPoseStamped([-5.0, 1.0], TurtleBot4Directions.EAST)) + goal_pose.append(navigator.getPoseStamped([-5.0, -23.0], TurtleBot4Directions.NORTH)) + goal_pose.append(navigator.getPoseStamped([9.0, -23.0], TurtleBot4Directions.NORTH_WEST)) + goal_pose.append(navigator.getPoseStamped([10.0, 2.0], TurtleBot4Directions.WEST)) + + while True: + with lock: + battery_percent = battery_monitor.battery_percent + + if (battery_percent is not None): + navigator.info(f'Battery is at {(battery_percent*100):.2f}% charge') + + # Check battery charge level + if (battery_percent < BATTERY_CRITICAL): + navigator.error('Battery critically low. Charge or power down') + break + elif (battery_percent < BATTERY_LOW): + # Go near the dock + navigator.info('Docking for charge') + navigator.startToPose(navigator.getPoseStamped([-1.0, 1.0], + TurtleBot4Directions.EAST)) + navigator.dock() + + if not navigator.getDockedStatus(): + navigator.error('Robot failed to dock') + break + + # Wait until charged + navigator.info('Charging...') + battery_percent_prev = 0 + while (battery_percent < BATTERY_HIGH): + sleep(15) + battery_percent_prev = floor(battery_percent*100)/100 + with lock: + battery_percent = battery_monitor.battery_percent + + # Print charge level every time it increases a percent + if battery_percent > (battery_percent_prev + 0.01): + navigator.info(f'Battery is at {(battery_percent*100):.2f}% charge') + + # Undock + navigator.undock() + position_index = 0 + + else: + # Navigate to next position + navigator.startToPose(goal_pose[position_index]) + + position_index = position_index + 1 + if position_index >= len(goal_pose): + position_index = 0 + + battery_monitor.destroy_node() + rclpy.shutdown() +``` +This example starts with many of the same steps as [navigate to pose](#navigate-to-pose). We initialise the node, make sure the robot is docked, and set the initial pose. Then we wait for Nav2 to become active. The additional steps are discussed below. + +##### Multi-threading + + A Global Interpreter Lock (GIL) is used to ensure that the main function and battery monitoring functions do not access or modify that member variable at the same time. + + The lock is created as well as the battery monitor node being created. The lock is passed into the battery monitor node to ensure that both processes are using the same lock. + + +```py +lock = Lock() +battery_monitor = BatteryMonitor(lock) +``` + +A thread is created to run the battery monitor thread function that was created earlier. This thread is started. + +```py +thread = Thread(target=battery_monitor.thread_function, daemon=True) +thread.start() +``` + +##### Prepare Goal Pose Loop + +The robot poses that make up the robot's patrol loop are assembled into a list. + +```py +# Prepare goal poses +goal_pose = [] +goal_pose.append(navigator.getPoseStamped([-5.0, 1.0], TurtleBot4Directions.EAST)) +goal_pose.append(navigator.getPoseStamped([-5.0, -23.0], TurtleBot4Directions.NORTH)) +goal_pose.append(navigator.getPoseStamped([9.0, -23.0], TurtleBot4Directions.NORTH_WEST)) +goal_pose.append(navigator.getPoseStamped([10.0, 2.0], TurtleBot4Directions.WEST)) +``` + +##### Operating Loop +The remainder of the code continues until it is interrupted. + +The battery percentage is updated when it is granted access by the lock. + +```py +with lock: + battery_percent = battery_monitor.battery_percent +``` +Initially when the processes are not ready, the battery percent may be None. The program continues to check until the battery percent is not None. + +```py +if (battery_percent is not None): + +``` + +Based on the battery charge level, the program chooses an action: + +If the battery is at critical levels, it breaks the loop, ending the program. + +```py +navigator.info(f'Battery is at {(battery_percent*100):.2f}% charge') + +# Check battery charge level +if (battery_percent < BATTERY_CRITICAL): + navigator.error('Battery critically low. Charge or power down') + break +``` + +If the battery is low then it navigates near the charger, docks and then waits for full charge. While charging it continues to periodically use the lock to update the battery percentage. Once full, it undocks and prepares to start the patrol loop again from the first position. + +```py +elif (battery_percent < BATTERY_LOW): + # Go near the dock + navigator.info('Docking for charge') + navigator.startToPose(navigator.getPoseStamped([-1.0, 1.0], + TurtleBot4Directions.EAST)) + navigator.dock() + + if not navigator.getDockedStatus(): + navigator.error('Robot failed to dock') + break + + # Wait until charged + navigator.info('Charging...') + battery_percent_prev = 0 + while (battery_percent < BATTERY_HIGH): + sleep(15) + battery_percent_prev = floor(battery_percent*100)/100 + with lock: + battery_percent = battery_monitor.battery_percent + + # Print charge level every time it increases a percent + if battery_percent > (battery_percent_prev + 0.01): + navigator.info(f'Battery is at {(battery_percent*100):.2f}% charge') + + # Undock + navigator.undock() + position_index = 0 +``` + +Finally, if the battery was not critical or low then the robot navigates to the next position in the loop. This position is tracked by the 'position_index' variable + +```py +else: + # Navigate to next position + navigator.startToPose(goal_pose[position_index]) + + position_index = position_index + 1 + if position_index >= len(goal_pose): + position_index = 0 +``` + +{% endtab %} +{% tab navigation jazzy %} + +The source code for this example is available [here](https://github.com/turtlebot/turtlebot4_tutorials/blob/jazzy/turtlebot4_python_tutorials/turtlebot4_python_tutorials/patrol_loop.py). + +#### Battery Monitoring Node +Let's take a look at the battery monitoring node class. + +```py +class BatteryMonitor(Node): + + def __init__(self, lock): + super().__init__('battery_monitor') + + self.lock = lock + + # Subscribe to the /battery_state topic + self.battery_state_subscriber = self.create_subscription( + BatteryState, + 'battery_state', + self.battery_state_callback, + qos_profile_sensor_data) + + # Callbacks + def battery_state_callback(self, batt_msg: BatteryState): + with self.lock: + self.battery_percent = batt_msg.percentage + + def thread_function(self): + executor = SingleThreadedExecutor() + executor.add_node(self) + executor.spin() +``` +This class serves to monitor the Create3® battery charge percentage and to make it available for decision making. ##### Subscription @@ -1102,9 +1876,9 @@ self.battery_state_subscriber = self.create_subscription( ##### Battery State Callback -Whenever a `battery_state` message is received, the battery charge percentage is saved in a member variable. +Whenever a `battery_state` message is received, the battery charge percentage is saved in a member variable. -A Global Interpreter Lock (GIL) is used to ensure that the main function and battery monitoring functions do not access or modify that member variable at the same time. The process will queue until the lock is available. +A Global Interpreter Lock (GIL) is used to ensure that the main function and battery monitoring functions do not access or modify that member variable at the same time. The process will queue until the lock is available. ```py # Callbacks @@ -1214,13 +1988,13 @@ def main(args=None): battery_monitor.destroy_node() rclpy.shutdown() ``` -This example starts with many of the same steps as [navigate to pose](#navigate-to-pose). We initialise the node, make sure the robot is docked, and set the initial pose. Then we wait for Nav2 to become active. The additional steps are discussed below. +This example starts with many of the same steps as [navigate to pose](#navigate-to-pose). We initialise the node, make sure the robot is docked, and set the initial pose. Then we wait for Nav2 to become active. The additional steps are discussed below. ##### Multi-threading A Global Interpreter Lock (GIL) is used to ensure that the main function and battery monitoring functions do not access or modify that member variable at the same time. - The lock is created as well as the battery monitor node being created. The lock is passed into the battery monitor node to ensure that both processes are using the same lock. + The lock is created as well as the battery monitor node being created. The lock is passed into the battery monitor node to ensure that both processes are using the same lock. ```py @@ -1228,7 +2002,7 @@ lock = Lock() battery_monitor = BatteryMonitor(lock) ``` -A thread is created to run the battery monitor thread function that was created earlier. This thread is started. +A thread is created to run the battery monitor thread function that was created earlier. This thread is started. ```py thread = Thread(target=battery_monitor.thread_function, daemon=True) @@ -1257,14 +2031,14 @@ The battery percentage is updated when it is granted access by the lock. with lock: battery_percent = battery_monitor.battery_percent ``` -Initially when the processes are not ready, the battery percent may be None. The program continues to check until the battery percent is not None. +Initially when the processes are not ready, the battery percent may be None. The program continues to check until the battery percent is not None. ```py if (battery_percent is not None): ``` -Based on the battery charge level, the program chooses an action: +Based on the battery charge level, the program chooses an action: If the battery is at critical levels, it breaks the loop, ending the program. @@ -1328,8 +2102,10 @@ else: {% tabs navigation %} {% tab navigation galactic %} - -This tutorial is only available in Humble +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` +This tutorial is not available in Galactic. {% endtab %} {% tab navigation humble %} @@ -1342,6 +2118,17 @@ This tutorial is only available in Humble
Patrol Loop (9x speed)
+{% endtab %} +{% tab navigation jazzy %} + +
+ +
Patrol Loop (9x speed)
+
+ {% endtab %} {% endtabs %} @@ -1365,20 +2152,28 @@ Before using this as the basis for a product, please consult the substantial lis {% tabs navigation %} {% tab navigation galactic %} +```warning +**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release +``` -To run this example, first start the Gazebo simulation: +This tutorial is not available in Galactic. + +{% endtab %} +{% tab navigation humble %} + +To run this example, first start the Gazebo simulation, specifying the 'depot' world: ```bash -ros2 launch turtlebot4_ignition_bringup ignition.launch.py nav2:=true slam:=false localization:=true rviz:=true +ros2 launch turtlebot4_ignition_bringup turtlebot4_ignition.launch.py nav2:=true slam:=false localization:=true rviz:=true world:=depot map:=/opt/ros/humble/share/turtlebot4_navigation/maps/depot.yaml ``` {% endtab %} -{% tab navigation humble %} +{% tab navigation jazzy %} To run this example, first start the Gazebo simulation, specifying the 'depot' world: ```bash -ros2 launch turtlebot4_ignition_bringup turtlebot4_ignition.launch.py nav2:=true slam:=false localization:=true rviz:=true world:=depot map:=/opt/ros/humble/share/turtlebot4_navigation/maps/depot.yaml +ros2 launch turtlebot4_gz_bringup turtlebot4_gz.launch.py nav2:=true slam:=false localization:=true rviz:=true world:=depot map:=/opt/ros/humble/share/turtlebot4_navigation/maps/depot.yaml ``` {% endtab %}