Skip to content

Commit 7169f77

Browse files
civerachb-cprciverachb-cpr
authoredJan 16, 2025··
Remove nested section titles (#29)
* Fix duplicate TOC entries for Create3 Republisher * Remove duplicate TOC entries for Discovery Server * Remove duplicate TOC entries for simple discovery
1 parent e6e9c9e commit 7169f77

File tree

3 files changed

+101
-86
lines changed

3 files changed

+101
-86
lines changed
 

‎setup/discovery_server.md

+56-44
Original file line numberDiff line numberDiff line change
@@ -339,30 +339,49 @@ You may also need to call `ros2 topic list` twice to get a full list of topics.
339339

340340
## Example Configuration
341341

342+
### 2 Robots and 1 User Computer
343+
344+
#### Recommended Architecture
345+
342346
{% tabs discovery %}
343347
{% tab discovery galactic %}
344348
```warning
345349
**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release
346350
```
347351

348352
There is currently no example for Galactic.
349-
350353
{% endtab %}
351354
{% tab discovery humble %}
355+
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`.
352356

353-
### 2 Robots and 1 User Computer
357+
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.
354358

355-
#### Recommended Architecture
359+
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.
360+
361+
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.
362+
{% endtab %}
363+
{% tab discovery jazzy %}
356364
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`.
357365

358366
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.
359367

360368
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.
361369

362370
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.
371+
{% endtab %}
372+
{% endtabs %}
363373

364374
#### Example Robot Setup
365375

376+
{% tabs example21 %}
377+
{% tab example21 galactic %}
378+
```warning
379+
**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release
380+
```
381+
382+
There is currently no example for Galactic.
383+
{% endtab %}
384+
{% tab example21 humble %}
366385
<table>
367386
<tr style="text-align:center">
368387
<th>Robot 1</th>
@@ -417,46 +436,8 @@ Although one could run another discovery server on the user computer, this would
417436
</td>
418437
</tr>
419438
</table>
420-
421-
422-
#### Example User Computer Setup
423-
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:
424-
425-
```
426-
ROS_DOMAIN_ID [0]: 0
427-
Enter the information for the first discovery server
428-
Discovery Server ID [0]: 0
429-
Discovery Server IP: 192.168.131.5
430-
Discovery Server Port [11811]:
431-
Re-enter the last server (r), add another server (a), or done (d): a
432-
Enter the information for the next discovery server
433-
Discovery Server ID [0]: 1
434-
Discovery Server IP: 192.168.131.6
435-
Discovery Server Port [11811]:
436-
Re-enter the last server (r), add another server (a), or done (d): d
437-
Configuring:
438-
ROS_DOMAIN_ID=0
439-
ROS_DISCOVERY_SERVER="192.168.131.5:11811;192.168.131.6:11811;"
440-
[sudo] password for cpr-1234:
441-
Source your ~/.bashrc file to apply changes
442-
```
443-
444439
{% endtab %}
445-
{% tab discovery jazzy %}
446-
447-
### 2 Robots and 1 User Computer
448-
449-
#### Recommended Architecture
450-
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`.
451-
452-
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.
453-
454-
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.
455-
456-
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.
457-
458-
#### Example Robot Setup
459-
440+
{% tab example21 jazzy %}
460441
<table>
461442
<tr style="text-align:center">
462443
<th>Robot 1</th>
@@ -511,9 +492,19 @@ Although one could run another discovery server on the user computer, this would
511492
</td>
512493
</tr>
513494
</table>
514-
495+
{% endtab %}
496+
{% endtabs %}
515497

516498
#### Example User Computer Setup
499+
{% tabs computer21 %}
500+
{% tab computer21 galactic %}
501+
```warning
502+
**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release
503+
```
504+
505+
There is currently no example for Galactic.
506+
{% endtab %}
507+
{% tab computer21 humble %}
517508
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:
518509

519510
```
@@ -534,6 +525,27 @@ Configuring:
534525
[sudo] password for cpr-1234:
535526
Source your ~/.bashrc file to apply changes
536527
```
528+
{% endtab %}
529+
{% tab computer21 jazzy %}
530+
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:
537531

532+
```
533+
ROS_DOMAIN_ID [0]: 0
534+
Enter the information for the first discovery server
535+
Discovery Server ID [0]: 0
536+
Discovery Server IP: 192.168.131.5
537+
Discovery Server Port [11811]:
538+
Re-enter the last server (r), add another server (a), or done (d): a
539+
Enter the information for the next discovery server
540+
Discovery Server ID [0]: 1
541+
Discovery Server IP: 192.168.131.6
542+
Discovery Server Port [11811]:
543+
Re-enter the last server (r), add another server (a), or done (d): d
544+
Configuring:
545+
ROS_DOMAIN_ID=0
546+
ROS_DISCOVERY_SERVER="192.168.131.5:11811;192.168.131.6:11811;"
547+
[sudo] password for cpr-1234:
548+
Source your ~/.bashrc file to apply changes
549+
```
538550
{% endtab %}
539-
{% endtabs %}
551+
{% endtabs %}

‎setup/simple_discovery.md

+22-27
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,10 @@ To use the TurtleBot 4 with Simple Discovery, the Create® 3 should be connected
1818
The Create® 3 can only be connected to 2.4 GHz Wi-Fi networks.
1919
```
2020

21-
{% tabs wifi %}
22-
{% tab wifi galactic %}
23-
2421
### Wi-Fi Setup
2522

23+
{% tabs wifi %}
24+
{% tab wifi galactic %}
2625
Access the [Create® 3 webserver](./basic.md#accessing-the-create-3-webserver), then navigate to the <b>Connect</b> tab.
2726
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 <b>Connect</b> 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.
2827

@@ -34,22 +33,8 @@ If the Create® 3 is unable to connect to your 2.4 GHz WiFi network and the ligh
3433
<img src="media/create3_connect.png" alt="Create® 3 connect" style="width: 100%"/>
3534
<figcaption>Connecting the Create® 3 to Wi-Fi</figcaption>
3635
</figure>
37-
38-
### Application Configuration
39-
40-
Access the [Create® 3 webserver](./basic.md#accessing-the-create-3-webserver), then navigate to the <b>Application Configuration</b> tab.
41-
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
42-
sure that the Fast DDS discovery server is disabled.
43-
44-
<figure class="aligncenter">
45-
<img src="media/webserver_config.png" alt="Create® 3 config" style="width: 80%"/>
46-
<figcaption>Configuring the Create® 3 application for Galactic</figcaption>
47-
</figure>
4836
{% endtab %}
4937
{% tab wifi humble %}
50-
51-
### Wi-Fi Setup
52-
5338
Access the [Create® 3 webserver](./basic.md#accessing-the-create-3-webserver), then navigate to the <b>Connect</b> tab.
5439
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 <b>Connect</b> 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.
5540

@@ -61,9 +46,28 @@ If the Create® 3 is unable to connect to your 2.4 GHz WiFi network and the ligh
6146
<img src="media/create3_connect.png" alt="Create® 3 connect" style="width: 100%"/>
6247
<figcaption>Connecting the Create® 3 to Wi-Fi</figcaption>
6348
</figure>
49+
{% endtab %}
50+
{% tab wifi jazzy %}
51+
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.
52+
53+
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.
54+
{% endtab %}
55+
{% endtabs %}
6456

6557
### Application Configuration
6658

59+
{% tabs application %}
60+
{% tab application galactic %}
61+
Access the [Create® 3 webserver](./basic.md#accessing-the-create-3-webserver), then navigate to the <b>Application Configuration</b> tab.
62+
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
63+
sure that the Fast DDS discovery server is disabled.
64+
65+
<figure class="aligncenter">
66+
<img src="media/webserver_config.png" alt="Create® 3 config" style="width: 80%"/>
67+
<figcaption>Configuring the Create® 3 application for Galactic</figcaption>
68+
</figure>
69+
{% endtab %}
70+
{% tab application humble %}
6771
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 <b>Application Configuration</b> tab to confirm the configuration as follows:
6872
- ROS 2 Domain ID is `0`
6973
- ROS 2 Namespace is empty
@@ -75,16 +79,7 @@ Use the [`turtlebot4-setup`](../software/turtlebot4_setup.md) tool to configure
7579
<figcaption>Configuring the Create® 3 application for Humble</figcaption>
7680
</figure>
7781
{% endtab %}
78-
{% tab wifi jazzy %}
79-
80-
### Wi-Fi Setup
81-
82-
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.
83-
84-
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.
85-
86-
### Application Configuration
87-
82+
{% tab application jazzy %}
8883
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 <b>Application Configuration</b> tab to confirm the configuration as follows:
8984
- ROS 2 Domain ID is `0`
9085
- ROS 2 Namespace is `/_do_not_use`

‎software/create3.md

+23-15
Original file line numberDiff line numberDiff line change
@@ -108,21 +108,6 @@ See [irobot_create_msgs](https://github.com/iRobotEducation/irobot_create_msgs)
108108
```note
109109
When publishing or subscribing to topics, make sure that the [QoS](https://docs.ros.org/en/humble/Concepts/About-Quality-of-Service-Settings.html) that you use matches that of the topic.
110110
```
111-
112-
## Create® 3 Republisher {#create-3-republisher}
113-
114-
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.
115-
116-
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.
117-
118-
```note
119-
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.
120-
121-
All other ROS nodes, shell commands (e.g. `ros2 topic echo ...`) should use the republished topics, actions, and services.
122-
```
123-
124-
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.
125-
126111
{% endtab %}
127112
{% tab create3 jazzy %}
128113

@@ -174,9 +159,20 @@ See [irobot_create_msgs](https://github.com/iRobotEducation/irobot_create_msgs)
174159
```note
175160
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.
176161
```
162+
{% endtab %}
163+
{% endtabs %}
177164

178165
## Create® 3 Republisher {#create-3-republisher}
179166

167+
{% tabs republisher %}
168+
{% tab republisher galactic %}
169+
```warning
170+
**ROS 2 Galactic is no longer supported.** Please consider upgrading to a newer release
171+
```
172+
173+
Create® 3 Republisher is not available for ROS 2 Galactic.
174+
{% endtab %}
175+
{% tab republisher humble %}
180176
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.
181177

182178
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.
@@ -188,6 +184,18 @@ All other ROS nodes, shell commands (e.g. `ros2 topic echo ...`) should use the
188184
```
189185

190186
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.
187+
{% endtab %}
188+
{% tab republisher jazzy %}
189+
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.
190+
191+
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.
192+
193+
```note
194+
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.
191195
196+
All other ROS nodes, shell commands (e.g. `ros2 topic echo ...`) should use the republished topics, actions, and services.
197+
```
198+
199+
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.
192200
{% endtab %}
193201
{% endtabs %}

0 commit comments

Comments
 (0)
Please sign in to comment.