diff --git a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/actions.mdx b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/actions.mdx index 4816c208..5c45e80c 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/actions.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/actions.mdx @@ -51,10 +51,10 @@ The message is divided into 3 parts: * the result (what the robot sends back to us when the action completes), and * feedback (what the robot sends to us while the action is still in-progress). -## Determine the goal location {#goal-position} +### Determine the goal location {#goal-position} First we must determine where we want the robot to drive to. The easiest way to do this is to -use the [publish point](nav2.mdx#publish-point) tool. +use the [publish point](rviz#publish-point) tool. Suppose we receve this point on the on the `/a300_0000/clicked_point` topic: ```yaml @@ -89,7 +89,7 @@ These alternate ways to determine the robot's goal are outside the scope of this ::: -## Determine the goal orientation {#goal-orientation} +### Determine the goal orientation {#goal-orientation} The `navigate_to_pose` action requires a `PoseStamped` object. A `Pose` in ROS consists of an 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})$$ $$W = cos(\frac{\theta}{2})$$ -## Sending the Action Goal +### Sending the Action Goal :::tip @@ -213,4 +213,4 @@ Result: error_msg: '' Goal finished with status: SUCCEEDED -``` \ No newline at end of file +``` diff --git a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/localization.mdx b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/localization.mdx index 2e6b1fb5..67321c7a 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/localization.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/localization.mdx @@ -21,6 +21,8 @@ Make sure you have installed the simulator before starting this tutorial. Take a ## Launching Localization +See [Launching Nav2](nav2) for instructions on launching localization + :::note When using the simulation, it is important to add `use_sim_time:=true` to the Nav2, SLAM, and @@ -29,16 +31,30 @@ to `false`. ::: -To start localization using [AMCL](https://docs.nav2.org/configuration/packages/configuring-amcl.html) -[follow the steps](nav2.mdx#launching-the-simulation-and-nav2) described in the Nav2 -startup. When you get to step 4, run -```bash -ros2 launch clearpath_nav2_demos localization.launch.py use_sim_time:=true -``` - -The default map used by `localization.launch.py` is a -[map](https://github.com/clearpathrobotics/clearpath_nav2_demos/blob/jazzy/maps/warehouse.yaml) of the simulated warehouse world. -If you are using a custom map, pass it in with the `map` launch argument: -```bash -ros2 launch clearpath_nav2_demos localization.launch.py use_sim_time:=true map:=/path/to/my/map.yaml -``` +## Setting the 2D Pose Estimate + +When starting localization, the robot will be `lost` -- no transform from `base_link` to the `map` frame will be published. +To fix this you must manually set an initial 2D pose estimate. + +The **2D Pose Estimate** tool in Rviz allows you to provide Nav2 with the robot's approximate initial position on the map. +This is a necessary step before you can navigate with the robot. +This step connects the `map` frame to the rest of the robot's TF tree. + +To set the robot's initial position, click and hold the mouse button on the map in the robot's approximate location. +While holding the left mouse button, drag the green arrow to set the robot's orientation. Releasing the left +mouse button will set the robot's position and orientation relative to the `map` frame. + +If you are using SLAM and there is no map yet, simply click on the centre of the screen and drag up. + +Once you have set the robot's initial pose you should see red markers representing the lidar data as well +as coloured gradients indicating collision zones around walls and obstacles. + +
+
+ +
Setting the initial pose estimate
+
+
diff --git a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/nav2.mdx b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/nav2.mdx index 91b144be..04fcd52b 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/nav2.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/nav2.mdx @@ -1,6 +1,6 @@ --- -title: Nav2 -sidebar_label: Nav2 +title: Launching Navigation +sidebar_label: Launching Nav2 sidebar_position: 2 toc_min_heading_level: 2 toc_max_heading_level: 5 @@ -18,128 +18,165 @@ to `false`. ::: -## Launching the simulation and Nav2 +:::note + +Clearpath's Nav2 demos are written to support 2D lidars. If your robot has a 3D lidar on it, you can use the +[3d lidar's `scan` topic](../../api/sensors_api#3d-lidar-topics) to provide the necessary 2d `laserscan` input by +using the `scan_topic` argument, e.g. `scan_topic:=/a300_0000/sensors/lidar3d_0/scan`. + +::: + +:::warning + +Some lidars, especially 3D lidars, can have a minimum range that is _larger_ than the robot's footprint. +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. +Always keep an eye on the robot and be ready to press the emergency stop if necessary. + +::: + +## Launching Nav2 and SLAM on a physical robot -**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). +The following commands can be run on the robot itself, or on an [offboard computer](../../installation/offboard_pc). +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. -**2.** Open a terminal and launch the simulation: +**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 +**2.** Start Nav2 by running +```bash +ros2 launch clearpath_nav2_demos nav2.launch.py ``` -ros2 launch clearpath_gz simulation.launch.py +If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument: +```bash +ros2 launch clearpath_nav2_demos nav2.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan ``` -If the simulation does not start automatically, press the large orange "play" button in the bottom left corner. +**3.** Start SLAM by running: +```bash +ros2 launch clearpath_nav2_demos slam.launch.py +``` +If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument: +```bash +ros2 launch clearpath_nav2_demos slam.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan +``` -**3.** Open a second terminal and start Rviz. If you are using a physical robot or running the simulation -on an external server, this step should be done on your workstation, not on the robot or simulation server itself. +**4.** On your laptop, start Rviz to view the map by running +```bash +ros2 launch clearpath_viz view_navigation namespace:=/a300_0000 ``` -ros2 launch clearpath_viz view_navigation.launch.py namespace:=a300_0000 use_sim_time:=true + +**5.** Drive the robot around manually, or by sending it Nav2 goals. + +See [SLAM](slam) for more information about interacting with SLAM. + +See [Nav2 Goals](rviz#nav2-goal) for more information about sending navigation goals. + +## Launching Nav2 and SLAM in simulation + +**1.** Start the simulation by running +```bash +ros2 launch clearpath_gz simulation.launch setup_path:=/path/to/robot_setup +``` +The `setup_path` should point to the folder you have your [`robot.yaml`](../../config/yaml/overview) file, +e.g. `/home/username/clearpath` or `/etc/clearpath` + +**2.** Start Nav2 by running +```bash +ros2 launch clearpath_nav2_demos nav2.launch.py use_sim_time:=true setup_path:=/path/to/robot_setup +``` +If your simulated robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument: +```bash +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 +``` + +**3.** Start SLAM by running: +```bash +ros2 launch clearpath_nav2_demos slam.launch.py use_sim_time:=true setup_path:=/path/to/robot_setup +``` +If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument: +```bash +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 +``` + +**4.** Start Rviz to view the map by running +```bash +ros2 launch clearpath_viz view_navigation namespace:=/a300_0000 use_sim_time:=true ``` -**4.** Open a third terminal and start either [SLAM](slam.mdx) or [Localization](localization.mdx), depending on -whether or not you want to create a new map or use a pre-existing map. +**5.** Drive the robot around manually, or by sending it 2D nav goals. -**5.** Set the initial pose of the robot using the [**2D Pose Estimate**](#2d-pose-estimate) tool in RViz. +See [SLAM](slam) for more information about interacting with SLAM. -**6.** Open fourth terminal and launch nav2: +See [Nav2 Goals](rviz#nav2-goal) for more information about sending navigation goals. +## Launching Nav2 and Localization on a physical robot + +The following commands can be run on the robot itself, or on an [offboard computer](../../installation/offboard_pc). +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. + +**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 + +**2.** Start Nav2 by running +```bash +ros2 launch clearpath_nav2_demos nav2.launch.py +``` +If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument: +```bash +ros2 launch clearpath_nav2_demos nav2.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan +``` + +**3.** Start localization by running: +```bash +ros2 launch clearpath_nav2_demos localization.launch.py map:=/path/to/map.yaml +``` +If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument: +```bash +ros2 launch clearpath_nav2_demos localization.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan map:=/path/to/map.yaml +``` + +**4.** On your laptop, start Rviz to view the map by running +```bash +ros2 launch clearpath_viz view_navigation namespace:=/a300_0000 +``` + +**5.** Use Rviz to [set the 2D pose estimate](localization#setting-the-2d-pose-estimate). + +**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). + +## Launching Nav2 and Localization in simulation + +The following commands can be run on the robot itself, or on an [offboard computer](../../installation/offboard_pc). +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. + +**1.** Start the simulation by running +```bash +ros2 launch clearpath_gz simulation.launch setup_path:=/path/to/robot_setup ``` +The `setup_path` should point to the folder you have your [`robot.yaml`](../../config/yaml/overview) file, +e.g. `/home/username/clearpath` or `/etc/clearpath` + +**2.** Start Nav2 by running +```bash ros2 launch clearpath_nav2_demos nav2.launch.py use_sim_time:=true ``` +If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument: +```bash +ros2 launch clearpath_nav2_demos nav2.launch.py scan_topic:=/a300_0000/sensors/lidar3d_0/scan use_sim_time:=true +``` + +**3.** Start localization by running: +```bash +ros2 launch clearpath_nav2_demos localization.launch.py map:=/path/to/map.yaml use_sim_time:=true +``` +If your robot uses a 3D lidar instead of a 2D lidar, specify the `scan_topic` argument: +```bash +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 +``` + +**4.** On your laptop, start Rviz to view the map by running +```bash +ros2 launch clearpath_viz view_navigation namespace:=/a300_0000 +``` + +**5.** Use Rviz to [set the 2D pose estimate](localization#setting-the-2d-pose-estimate). -**7.** Give the robot a navigation goal using the [**Nav2 Goal**](#nav2-goal) tool in RViz. - -## Nav2 Tools in Rviz - -The Rviz configuration used by the `clearpath_viz view_navigation.launch.py` file includes several -tools for interacting with Nav2. These tools require Rviz's **Fixed Frame** to be set to `map`. To -set the fixed frame, use the toolbar on the left and open Displays > Global Options > Fixed Frame. - -Initially the `map` frame may not be connected to the rest of the **TF Tree**. This is normal, and -will be fixed when we use the **2D Pose Estimate** tool. If `map` does not appear in the frame drop-down -simply type the word `map` into the box and press `ENTER`. - -To select a Nav2 tool, simply click on the button on the toolbar at the top of Rviz's main window - -
-
- -
Rviz's toolbar with Nav2 tools
-
-
- -### 2D Pose Estimate - -The **2D Pose Estimate** tool allows you to provide Nav2 with the robot's approximate initial position on -the map. This is a necessary step before you can navigate with the robot. This step connects the `map` -frame to the rest of the robot's TF tree. - -To set the robot's initial position, click and hold the mouse button on the map in the robot's approximate location. -While holding the left mouse button, drag the green arrow to set the robot's orientation. Releasing the left -mouse button will set the robot's position and orientation relative to the `map` frame. - -If you are using SLAM and there is no map yet, simply click on the centre of the screen and drag up. - -Once you have set the robot's initial pose you should see red markers representing the lidar data as well -as coloured gradients indicating collision zones around walls and obstacles. - -
-
- -
Setting the initial pose estimate
-
-
- -### Publish Point - -The **Publish Point** tool allows you to click on the map and publish the XYZ coordinates of that -point to the `clicked_point` topic. In a terminal run the command -```bash -ros2 topic echo /a300_0000/clicked_point -``` -Then select the Publish Point tool and click somewhere on the map. In the terminal you will see -the location you clicked as a `geometry_msgs/msg/PointStamped` message: -```yaml -header: - stamp: - sec: 1747855824 - nanosec: 867726206 - frame_id: map -point: - x: -0.12474524974822998 - y: 0.002330044750124216 - z: -0.001434326171875 -``` - -
-
- -
Publishing a point
-
-
- -### Nav2 Goal - -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 -and attempt to drive the robot there. - -You will see a red path line appear, indicating the robot's planned path, and the robot will start to drive along this path. - -
-
- -
Navigation in simulation
-
-
+**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). diff --git a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/rviz.mdx b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/rviz.mdx new file mode 100644 index 00000000..24f06764 --- /dev/null +++ b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/rviz.mdx @@ -0,0 +1,79 @@ +--- +title: Rviz Nav2 Tools +sidebar_label: Rviz Nav2 Tools +sidebar_position: 7 +toc_min_heading_level: 2 +toc_max_heading_level: 5 +--- + +The Rviz configuration used by the `clearpath_viz view_navigation.launch.py` file includes several +tools for interacting with Nav2. These tools require Rviz's **Fixed Frame** to be set to `map`. To +set the fixed frame, use the toolbar on the left and open Displays > Global Options > Fixed Frame. + +Initially the `map` frame may not be connected to the rest of the **TF Tree**. This is normal, and +will be fixed when we use the **2D Pose Estimate** tool. If `map` does not appear in the frame drop-down +simply type the word `map` into the box and press `ENTER`. + +To select a Nav2 tool, simply click on the button on the toolbar at the top of Rviz's main window + +
+
+ +
Rviz's toolbar with Nav2 tools
+
+
+ +## 2D Pose Estimate + +See [Localization](localization#setting-the-2d-pose-estimate). + +## Publish Point + +The **Publish Point** tool allows you to click on the map and publish the XYZ coordinates of that +point to the `clicked_point` topic. In a terminal run the command +```bash +ros2 topic echo /a300_0000/clicked_point +``` +Then select the Publish Point tool and click somewhere on the map. In the terminal you will see +the location you clicked as a `geometry_msgs/msg/PointStamped` message: +```yaml +header: + stamp: + sec: 1747855824 + nanosec: 867726206 + frame_id: map +point: + x: -0.12474524974822998 + y: 0.002330044750124216 + z: -0.001434326171875 +``` + +
+
+ +
Publishing a point
+
+
+ +## Nav2 Goal + +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 +and attempt to drive the robot there. + +You will see a red path line appear, indicating the robot's planned path, and the robot will start to drive along this path. + +
+
+ +
Navigation in simulation
+
+
diff --git a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/slam.mdx b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/slam.mdx index fbcd3e7e..15826b55 100644 --- a/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/slam.mdx +++ b/docs_versioned_docs/version-ros2jazzy/ros/tutorials/navigation_demos/slam.mdx @@ -24,19 +24,7 @@ Make sure you have installed the simulator before starting this tutorial. Take a ## Launching SLAM -:::note - -When using the simulation, it is important to add `use_sim_time:=true` to the Nav2, SLAM, and -Localization launch files. When using a physical robot, either omit `use_sim_time` or set it -to `false`. - -::: - -To start SLAM, [follow the steps](nav2.mdx#launching-the-simulation-and-nav2) described in the Nav2 -startup. When you get to step 4, run -```bash -ros2 launch clearpath_nav2_demos slam.launch.py use_sim_time:=true -``` +See [launch instructions](nav2) for instructions on how to launch SLAM. ### Building the map