Skip to content

Commit f0d53fe

Browse files
civerachb-cprciverachb-cpr
authored
Update navigation tutorials with scan_topic argument (#480)
* Update the navigation tutorial to include the new scan_topic argument, add a new page for Rviz tools, update the launching page to include steps for Nav2+SLAM and Nav2+Localization instructions for simulation & physical robots. Add a warning about the minumum range of some 3D lidars * Fix broken link * Another link
1 parent a5138cd commit f0d53fe

File tree

5 files changed

+261
-141
lines changed

5 files changed

+261
-141
lines changed

‎docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/actions.mdx‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -51,10 +51,10 @@ The message is divided into 3 parts:
5151
* the result (what the robot sends back to us when the action completes), and
5252
* feedback (what the robot sends to us while the action is still in-progress).
5353

54-
## Determine the goal location {#goal-position}
54+
### Determine the goal location {#goal-position}
5555

5656
First we must determine where we want the robot to drive to. The easiest way to do this is to
57-
use the [publish point](nav2.mdx#publish-point) tool.
57+
use the [publish point](rviz#publish-point) tool.
5858

5959
Suppose we receve this point on the on the `/a300_0000/clicked_point` topic:
6060
```yaml
@@ -89,7 +89,7 @@ These alternate ways to determine the robot's goal are outside the scope of this
8989

9090
:::
9191

92-
## Determine the goal orientation {#goal-orientation}
92+
### Determine the goal orientation {#goal-orientation}
9393

9494
The `navigate_to_pose` action requires a `PoseStamped` object. A `Pose` in ROS consists of an
9595
XYZ location in space and a [**Quaternion**](https://docs.ros.org/en/jazzy/Tutorials/Intermediate/Tf2/Quaternion-Fundamentals.html)
@@ -144,7 +144,7 @@ $$Z = sin(\frac{\theta}{2})$$
144144

145145
$$W = cos(\frac{\theta}{2})$$
146146

147-
## Sending the Action Goal
147+
### Sending the Action Goal
148148

149149
:::tip
150150

@@ -213,4 +213,4 @@ Result:
213213
error_msg: ''
214214
215215
Goal finished with status: SUCCEEDED
216-
```
216+
```

‎docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/localization.mdx‎

Lines changed: 29 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ Make sure you have installed the simulator before starting this tutorial. Take a
2121

2222
## Launching Localization
2323

24+
See [Launching Nav2](nav2) for instructions on launching localization
25+
2426
:::note
2527

2628
When using the simulation, it is important to add `use_sim_time:=true` to the Nav2, SLAM, and
@@ -29,16 +31,30 @@ to `false`.
2931

3032
:::
3133

32-
To start localization using [AMCL](https://docs.nav2.org/configuration/packages/configuring-amcl.html)
33-
[follow the steps](nav2.mdx#launching-the-simulation-and-nav2) described in the Nav2
34-
startup. When you get to step 4, run
35-
```bash
36-
ros2 launch clearpath_nav2_demos localization.launch.py use_sim_time:=true
37-
```
38-
39-
The default map used by `localization.launch.py` is a
40-
[map](https://github.com/clearpathrobotics/clearpath_nav2_demos/blob/jazzy/maps/warehouse.yaml) of the simulated warehouse world.
41-
If you are using a custom map, pass it in with the `map` launch argument:
42-
```bash
43-
ros2 launch clearpath_nav2_demos localization.launch.py use_sim_time:=true map:=/path/to/my/map.yaml
44-
```
34+
## Setting the 2D Pose Estimate
35+
36+
When starting localization, the robot will be `lost` -- no transform from `base_link` to the `map` frame will be published.
37+
To fix this you must manually set an initial 2D pose estimate.
38+
39+
The **2D Pose Estimate** tool in Rviz allows you to provide Nav2 with the robot's approximate initial position on the map.
40+
This is a necessary step before you can navigate with the robot.
41+
This step connects the `map` frame to the rest of the robot's TF tree.
42+
43+
To set the robot's initial position, click and hold the mouse button on the map in the robot's approximate location.
44+
While holding the left mouse button, drag the green arrow to set the robot's orientation. Releasing the left
45+
mouse button will set the robot's position and orientation relative to the `map` frame.
46+
47+
If you are using SLAM and there is no map yet, simply click on the centre of the screen and drag up.
48+
49+
Once you have set the robot's initial pose you should see red markers representing the lidar data as well
50+
as coloured gradients indicating collision zones around walls and obstacles.
51+
52+
<center>
53+
<figure>
54+
<img
55+
src={require("./img/pose_estimate.gif").default}
56+
width="900"
57+
/>
58+
<figcaption>Setting the initial pose estimate</figcaption>
59+
</figure>
60+
</center>

‎docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/nav2.mdx‎

Lines changed: 147 additions & 110 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Nav2
3-
sidebar_label: Nav2
2+
title: Launching Navigation
3+
sidebar_label: Launching Nav2
44
sidebar_position: 2
55
toc_min_heading_level: 2
66
toc_max_heading_level: 5
@@ -18,128 +18,165 @@ to `false`.
1818

1919
:::
2020

21-
## Launching the simulation and Nav2
21+
:::note
22+
23+
Clearpath's Nav2 demos are written to support 2D lidars. If your robot has a 3D lidar on it, you can use the
24+
[3d lidar's `scan` topic](../../api/sensors_api#3d-lidar-topics) to provide the necessary 2d `laserscan` input by
25+
using the `scan_topic` argument, e.g. `scan_topic:=/a300_0000/sensors/lidar3d_0/scan`.
26+
27+
:::
28+
29+
:::warning
30+
31+
Some lidars, especially 3D lidars, can have a minimum range that is _larger_ than the robot's footprint.
32+
In this case it is possible for an obstacle to be so close to the robot that the lidar cannot detect it, potentially causing damage or injury.
33+
Always keep an eye on the robot and be ready to press the emergency stop if necessary.
34+
35+
:::
36+
37+
## Launching Nav2 and SLAM on a physical robot
2238

23-
**1.** Move the `robot.yaml` file to your setup folder (`$HOME/clearpath` by default for the simulation or `/etc/clearpath/robot.yaml` on a physical robot).
39+
The following commands can be run on the robot itself, or on an [offboard computer](../../installation/offboard_pc).
40+
Running on the robot will result in less latency, but can also result in high CPU usage on the robot, depending what other nodes are running.
2441

25-
**2.** Open a terminal and launch the simulation:
42+
**1.** Ensure the `clearpath-platform` and `clearpath-sensors` services are running. Run `ros2 topic list` to make sure the robot's `scan` topic is visible
2643

44+
**2.** Start Nav2 by running
45+
```bash
46+
ros2 launch clearpath_nav2_demos nav2.launch.py
2747
```
28-
ros2 launch clearpath_gz simulation.launch.py
48+
If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument:
49+
```bash
50+
ros2 launch clearpath_nav2_demos nav2.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan
2951
```
3052

31-
If the simulation does not start automatically, press the large orange "play" button in the bottom left corner.
53+
**3.** Start SLAM by running:
54+
```bash
55+
ros2 launch clearpath_nav2_demos slam.launch.py
56+
```
57+
If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument:
58+
```bash
59+
ros2 launch clearpath_nav2_demos slam.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan
60+
```
3261

33-
**3.** Open a second terminal and start Rviz. If you are using a physical robot or running the simulation
34-
on an external server, this step should be done on your workstation, not on the robot or simulation server itself.
62+
**4.** On your laptop, start Rviz to view the map by running
63+
```bash
64+
ros2 launch clearpath_viz view_navigation namespace:=/a300_0000
3565
```
36-
ros2 launch clearpath_viz view_navigation.launch.py namespace:=a300_0000 use_sim_time:=true
66+
67+
**5.** Drive the robot around manually, or by sending it Nav2 goals.
68+
69+
See [SLAM](slam) for more information about interacting with SLAM.
70+
71+
See [Nav2 Goals](rviz#nav2-goal) for more information about sending navigation goals.
72+
73+
## Launching Nav2 and SLAM in simulation
74+
75+
**1.** Start the simulation by running
76+
```bash
77+
ros2 launch clearpath_gz simulation.launch setup_path:=/path/to/robot_setup
78+
```
79+
The `setup_path` should point to the folder you have your [`robot.yaml`](../../config/yaml/overview) file,
80+
e.g. `/home/username/clearpath` or `/etc/clearpath`
81+
82+
**2.** Start Nav2 by running
83+
```bash
84+
ros2 launch clearpath_nav2_demos nav2.launch.py use_sim_time:=true setup_path:=/path/to/robot_setup
85+
```
86+
If your simulated robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument:
87+
```bash
88+
ros2 launch clearpath_nav2_demos nav2.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan use_sim_time:=true setup_path:=/path/to/robot_setup
89+
```
90+
91+
**3.** Start SLAM by running:
92+
```bash
93+
ros2 launch clearpath_nav2_demos slam.launch.py use_sim_time:=true setup_path:=/path/to/robot_setup
94+
```
95+
If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument:
96+
```bash
97+
ros2 launch clearpath_nav2_demos slam.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan use_sim_time:=true setup_path:=/path/to/robot_setup
98+
```
99+
100+
**4.** Start Rviz to view the map by running
101+
```bash
102+
ros2 launch clearpath_viz view_navigation namespace:=/a300_0000 use_sim_time:=true
37103
```
38104

39-
**4.** Open a third terminal and start either [SLAM](slam.mdx) or [Localization](localization.mdx), depending on
40-
whether or not you want to create a new map or use a pre-existing map.
105+
**5.** Drive the robot around manually, or by sending it 2D nav goals.
41106

42-
**5.** Set the initial pose of the robot using the [**2D Pose Estimate**](#2d-pose-estimate) tool in RViz.
107+
See [SLAM](slam) for more information about interacting with SLAM.
43108

44-
**6.** Open fourth terminal and launch nav2:
109+
See [Nav2 Goals](rviz#nav2-goal) for more information about sending navigation goals.
45110

111+
## Launching Nav2 and Localization on a physical robot
112+
113+
The following commands can be run on the robot itself, or on an [offboard computer](../../installation/offboard_pc).
114+
Running on the robot will result in less latency, but can also result in high CPU usage on the robot, depending what other nodes are running.
115+
116+
**1.** Ensure the `clearpath-platform` and `clearpath-sensors` services are running. Run `ros2 topic list` to make sure the robot's `scan` topic is visible
117+
118+
**2.** Start Nav2 by running
119+
```bash
120+
ros2 launch clearpath_nav2_demos nav2.launch.py
121+
```
122+
If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument:
123+
```bash
124+
ros2 launch clearpath_nav2_demos nav2.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan
125+
```
126+
127+
**3.** Start localization by running:
128+
```bash
129+
ros2 launch clearpath_nav2_demos localization.launch.py map:=/path/to/map.yaml
130+
```
131+
If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument:
132+
```bash
133+
ros2 launch clearpath_nav2_demos localization.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan map:=/path/to/map.yaml
134+
```
135+
136+
**4.** On your laptop, start Rviz to view the map by running
137+
```bash
138+
ros2 launch clearpath_viz view_navigation namespace:=/a300_0000
139+
```
140+
141+
**5.** Use Rviz to [set the 2D pose estimate](localization#setting-the-2d-pose-estimate).
142+
143+
**6.** Send 2D a nav goal to the robot [using Rviz' 2D Nav Goal tool](rviz#nav2-goal) or [the Navigation to Pose action](actions#the-navigate-to-pose-action).
144+
145+
## Launching Nav2 and Localization in simulation
146+
147+
The following commands can be run on the robot itself, or on an [offboard computer](../../installation/offboard_pc).
148+
Running on the robot will result in less latency, but can also result in high CPU usage on the robot, depending what other nodes are running.
149+
150+
**1.** Start the simulation by running
151+
```bash
152+
ros2 launch clearpath_gz simulation.launch setup_path:=/path/to/robot_setup
46153
```
154+
The `setup_path` should point to the folder you have your [`robot.yaml`](../../config/yaml/overview) file,
155+
e.g. `/home/username/clearpath` or `/etc/clearpath`
156+
157+
**2.** Start Nav2 by running
158+
```bash
47159
ros2 launch clearpath_nav2_demos nav2.launch.py use_sim_time:=true
48160
```
161+
If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument:
162+
```bash
163+
ros2 launch clearpath_nav2_demos nav2.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan use_sim_time:=true
164+
```
165+
166+
**3.** Start localization by running:
167+
```bash
168+
ros2 launch clearpath_nav2_demos localization.launch.py map:=/path/to/map.yaml use_sim_time:=true
169+
```
170+
If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument:
171+
```bash
172+
ros2 launch clearpath_nav2_demos localization.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan map:=/path/to/map.yaml use_sim_time:=true
173+
```
174+
175+
**4.** On your laptop, start Rviz to view the map by running
176+
```bash
177+
ros2 launch clearpath_viz view_navigation namespace:=/a300_0000
178+
```
179+
180+
**5.** Use Rviz to [set the 2D pose estimate](localization#setting-the-2d-pose-estimate).
49181

50-
**7.** Give the robot a navigation goal using the [**Nav2 Goal**](#nav2-goal) tool in RViz.
51-
52-
## Nav2 Tools in Rviz
53-
54-
The Rviz configuration used by the `clearpath_viz view_navigation.launch.py` file includes several
55-
tools for interacting with Nav2. These tools require Rviz's **Fixed Frame** to be set to `map`. To
56-
set the fixed frame, use the toolbar on the left and open Displays > Global Options > Fixed Frame.
57-
58-
Initially the `map` frame may not be connected to the rest of the **TF Tree**. This is normal, and
59-
will be fixed when we use the **2D Pose Estimate** tool. If `map` does not appear in the frame drop-down
60-
simply type the word `map` into the box and press `ENTER`.
61-
62-
To select a Nav2 tool, simply click on the button on the toolbar at the top of Rviz's main window
63-
64-
<center>
65-
<figure>
66-
<img
67-
src={require("./img/rviz_nav2_tools.png").default}
68-
width="600"
69-
/>
70-
<figcaption>Rviz's toolbar with Nav2 tools</figcaption>
71-
</figure>
72-
</center>
73-
74-
### 2D Pose Estimate
75-
76-
The **2D Pose Estimate** tool allows you to provide Nav2 with the robot's approximate initial position on
77-
the map. This is a necessary step before you can navigate with the robot. This step connects the `map`
78-
frame to the rest of the robot's TF tree.
79-
80-
To set the robot's initial position, click and hold the mouse button on the map in the robot's approximate location.
81-
While holding the left mouse button, drag the green arrow to set the robot's orientation. Releasing the left
82-
mouse button will set the robot's position and orientation relative to the `map` frame.
83-
84-
If you are using SLAM and there is no map yet, simply click on the centre of the screen and drag up.
85-
86-
Once you have set the robot's initial pose you should see red markers representing the lidar data as well
87-
as coloured gradients indicating collision zones around walls and obstacles.
88-
89-
<center>
90-
<figure>
91-
<img
92-
src={require("./img/pose_estimate.gif").default}
93-
width="900"
94-
/>
95-
<figcaption>Setting the initial pose estimate</figcaption>
96-
</figure>
97-
</center>
98-
99-
### Publish Point
100-
101-
The **Publish Point** tool allows you to click on the map and publish the XYZ coordinates of that
102-
point to the `clicked_point` topic. In a terminal run the command
103-
```bash
104-
ros2 topic echo /a300_0000/clicked_point
105-
```
106-
Then select the Publish Point tool and click somewhere on the map. In the terminal you will see
107-
the location you clicked as a `geometry_msgs/msg/PointStamped` message:
108-
```yaml
109-
header:
110-
stamp:
111-
sec: 1747855824
112-
nanosec: 867726206
113-
frame_id: map
114-
point:
115-
x: -0.12474524974822998
116-
y: 0.002330044750124216
117-
z: -0.001434326171875
118-
```
119-
120-
<center>
121-
<figure>
122-
<img
123-
src={require("./img/publish_point.gif").default}
124-
width="900"
125-
/>
126-
<figcaption>Publishing a point</figcaption>
127-
</figure>
128-
</center>
129-
130-
### Nav2 Goal
131-
132-
The **Nav2 Goal** tool allows you to set a goal pose for the robot. The Nav2 stack will then plan a path to the goal pose
133-
and attempt to drive the robot there.
134-
135-
You will see a red path line appear, indicating the robot's planned path, and the robot will start to drive along this path.
136-
137-
<center>
138-
<figure>
139-
<img
140-
src={require("./img/nav_goal.gif").default}
141-
width="900"
142-
/>
143-
<figcaption>Navigation in simulation</figcaption>
144-
</figure>
145-
</center>
182+
**6.** Send 2D a nav goal to the robot [using Rviz' 2D Nav Goal tool](rviz#nav2-goal) or [the Navigation to Pose action](actions#the-navigate-to-pose-action).

0 commit comments

Comments
 (0)