🔌 Docking Server#

The Docking Server is a Nav2 framework designed for a wide variety of robots and docking scenarios. It handles docking and undocking maneuvers, ensuring that robots connect to dock stations safely and efficiently.

Attention

Please refer to the Nav2 Docking Server for more details on the underlying docking framework.

PAL Robotics extends the Docking Server from Nav2 with the pal_nav2_docking::ChargingDock plugin, introducing:

📡 Dynamic Dock Detection: Uses the dock_detector_server to detect and localize dock stations dynamically.
🔄 Flexible Docking Configurations: Customizable parameters such as staging pose offsets or detection methods for adapting to diverse environments.
🎯 Precise Docking and Servoing: Enables robots to approach and servo to any target detected, even non-charging targets.
🔋 Charging State Monitoring: Tracks the robot’s docking and charging status using the /power_status or a configurable distance threshold.

Note

The Docking Server handles docking and undocking maneuvers. For advanced docking workflows, consider using the Docking Manager.

Usage#

Attention

For detailed documentation on the Nav2 Docking Server API, including action definitions and usage examples, please visit the official Nav2 Docking Server API reference.

The Docking Server’s API and its usage follows the same structure and guideline as the Nav2 Docking Server, using standard actions such as /dock_robot and /undock_robot, for performing docking and undocking respectively.

Warning

When sending a /dock_robot goal, ensure to set the navigate_to_staging_pose field to true to make sure the robot navigates to the staging pose before docking. Otherwise, the docking maneuver may fail.

Please, refer to the following examples for executing docking:

ros2 action send_goal /dock_robot opennav_docking_msgs/action/DockRobot "use_dock_id: false
dock_id: 'DOCK_ID'
dock_pose:
  header:
    stamp:
      sec: 0
      nanosec: 0
    frame_id: ''
  pose:
    position:
      x: 0.0
      y: 0.0
      z: 0.0
    orientation:
      x: 0.0
      y: 0.0
      z: 0.0
      w: 1.0
dock_type: 'pal_charging_dock'
max_staging_time: 1000.0
navigate_to_staging_pose: true"

Attention

Remember to replace the <DOCK_ID> placeholder for your specific value in case you have set use_dock_id to true. Otherwise, set the dock_pose field with the desired docking pose.

And undocking:

ros2 action send_goal /undock_robot opennav_docking_msgs/action/UndockRobot "dock_type: ''
max_undocking_time: 30.0"

Configuration#

The Docking Server configuration can be adjusted to suit specific needs. PAL Robotics provides preloaded, tested configurations for various robots and dock stations. To view available configurations:

ls /opt/pal/$PAL_DISTRO/share/pal_navigation_cfg_params/params/opennav_docking/

These configurations are defined in YAML files containing the parameters listed below:

Parameter	Description	Default
`use_docked_status`	Use the /power_status to determine if the robot is docked.	`true`
`target_detector.detector`	Name of the detection plugin to use.	`"laser_target_detector"`
`target_detector.action_name`	Name of the action server for target detection.	`"detect_dock"`
`target_detector.target_id`	ID of the target to detect.	`0`
`base_frame_id`	Frame ID of the robot’s base link.	`"base_footprint"`
`world_frame_id`	Frame ID of the global reference frame (e.g., map).	`"map"`
`charging_connector_frame_id`	Frame ID of the charging connector.	`"base_dock_link"`
`docking_threshold`	Distance threshold (in meters) for determining docking status when `use_docked_status` is `false`.	`0.05`
`staging_x_offset`	X-axis offset (in meters) for the staging pose.	`-1.0`
`staging_yaw_offset`	Yaw offset (in radians) for the staging pose.	`0.0`
`external_detection_timeout`	Timeout (in seconds) for target detection.	`1.0`
`external_detection_translation_x`	X-axis offset for detected target pose.	`0.0`
`external_detection_translation_y`	Y-axis offset for detected target pose.	`0.0`
`external_detection_rotation`	Quaternion for rotation adjustments in target detection.	`[0.0, 0.0, 0.0, 1.0]`

Note

To use the Docking Server for non-charging targets, set use_docked_status to false and configure docking_threshold appropriately.

Customizing Configurations#

You can create new configurations for your docking server to suit specific requirements. Follow these steps:

Create a new directory in the .pal folder:

mkdir -p ~/.pal/pal_navigation_cfg_params/params/opennav_docking

Create a new configuration file:

touch ~/.pal/pal_navigation_cfg_params/params/opennav_docking/my_docking_server_config.yaml

Add your parameters to the new configuration file. Specify the supported robots and include your docking server parameters:

pal_navigation_cfg:
   ros__parameters:
      supported_robots:
      - some_pal_robot  # e.g., tiago, omni_base, tiago_pro, etc.

docking_server:
   # Your docking server parameters

Update the navigation pipeline to use your custom configuration:

Edit the <robot>_nav.yaml file in the <robot>_2dnav package:

sudo vi /opt/pal/$PAL_DISTRO/share/<robot>_2dnav/params/<robot>_nav.yaml

Change the params field to point to your custom configuration file:

nodes:
   docking_server:
      app: docking_server
      params: [my_docking_server_config]

Restart the navigation pipeline to apply the changes:
```
pal module restart navigation
```

🔌 Docking Server#

Usage#

Configuration#

Customizing Configurations#

See also#