How to use advanced docking functionalities¶

🏁 Goal of this tutorial

By the end of this tutorial, you will know how to make the robot learn a dock location and autonomously navigate to a previously learned dock location.

Pre-requisites¶

You should be able to remotely connect to your robot Set up ROS 2 communication with the robot.

You should be familiar with ROS’s RViz

You should first have completed the How to use the dockstation

You should first have completed the How to create and annotate your Environment

Caution

This tutorial requires the robot to be equipped with a dockstation and that the dockstation is properly powered.

Learn a Dock location using RViz¶

The easiest way to make the robot learn a dock location, is by using the RViz GUI. This requires that you first establish the communication with the robot as explained in Set up ROS 2 communication with the robot.

Then, in the same terminal that is connected to the robot, you can start RViz with the command:

rviz2 -d /opt/pal/$PAL_DISTRO/share/<ROBOT>_2dnav/config/rviz/navigation.rviz

Attention

Make sure to replace the <ROBOT> placeholder with the name of your robot (e.g. pmb2, omni_base, ari, etc.). If you are using a TIAGo-Family robot, use the base_type name (either, pmb2 or omni_base).

Otherwise, if you want to use the simulation, you can use the following command:

source /opt/pal/${PAL_DISTRO}/setup.bash
ros2 launch <robot>_gazebo <robot>_gazebo.launch.py navigation:=True advanced_navigation:=True docking:=True world_name:=pal_office_w_docks

This starts the simulation in a virtual environment with several dockstations available.

Once RViz is running and is connected to the robot or to the simulation, you can learn a dock location by following these steps:

Ensure Localization: Make sure the robot is well-localized to prevent errors in learned dock poses.
Position the Robot: Place the robot near the docking station in a staging pose as shown below:

Staging Pose for Dock Detection¶
Executes the /learn_dock:

Attention

Ensure the robot is well-localized during the /learn_dock process. Poor localization can lead to incorrect dock poses being stored in the database.

Use the following command to learn a dock station:
```
ros2 action send_goal /learn_dock pal_docking_msgs/action/LearnDock "target_id: <TARGET_ID>
dock_id: '<DOCK_ID>'
dock_type: <DOCK_TYPE>
execute_dock_maneuver: true
dock_charging_plugin: pal_charging_dock"
```
Warning

Remember to replace the <TARGET_ID>, <DOCK_ID> and <DOCK_TYPE> placeholders for your specific values.

Tip

Setting execute_dock_maneuver to true allows the robot to validate the docking station’s position during the learning phase.
Validate: Once completed, the dock station is stored in the database. Use the following command to list all available docks:
```
ros2 service call /docking_manager/get_docks eulero_msgs/srv/GetAnchors "parent_key: '<BUILDING_NAME>'"
```
Warning

Remember to replace the <BUILDING_NAME> placeholder for your specific building.

You can also use rviz to learn dock stations interactively as shown below:
Interactive :term:`rviz` Demo for Learning a Dock Station

Navigate to a previously learned Dock location¶

Verify Dock Availability: Check if the desired dock is in the database:
```
ros2 service call /docking_manager/get_docks eulero_msgs/srv/GetAnchors "parent_key: '<BUILDING_NAME>'"
```
Warning

Remember to replace the <BUILDING_NAME> placeholder for your specific building.
Executes the /go_and_dock: Use the following command to perform the docking maneuver:
```
ros2 action send_goal /go_and_dock pal_docking_msgs/action/GoAndDock "dock_id: '<FULL_DOCK_ID>'
dock_charging_plugin: pal_charging_dock"
```
Attention

Remember to replace the <FULL_DOCK_ID> placeholder for your specific value. This corresponds with /<BUILDING_NAME>/<FLOOR_NAME>/<DOCK_ID>. It is necessary to be able to navigate to charging stations that are located on different floors or buildings.
Internal Process: The Docking Manager retrieves the dock from the database, navigates to it, and performs the docking maneuver. During this process, the Docking Manager relocalizes the robot to ensure precise alignment with the learned dock pose.

Alternatively, you can use rviz to dock easily as shown in the following video:

Next steps¶

If you want to know more about the docking architecture and how to configure it, check the 🔋 Docking documentation.

If you want to know more about how to use advanced docking functionalities such as the /go_and_dock and the /learn_dock actions, you can refer to the tutorial How to use advanced docking functionalities.