🔌 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.

To provide the functionalities described above, two nodes are used:

docking_server: Implements a plugin-based framework designed for executing low-level docking and undocking maneuvers. Its implementation is publicly available in Nav2
dock_detector_server: Implements a Target Detector specialized in detecting PAL dock stations.

Parameters#

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

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]`

The Docking Server can also be used for non-charging targets, namely it can be used to align the robot with the respect to a specific dock target.

Note

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

In this case, the robot will NOT enter in contact with the dock station, but it will position itself at a specific distance from it (defined in the docking_threshold parameter) and will stop there. This is also the default mode when using the docking_server in simulation.

Tip

When setting the use_docked_status to false, the Dock station doesn’t need to be powered.

The following video shows an example of Dock alignment without contact. The robot detects the dock pattern, starts the approach, and stops at a specific distance (10cm) from the dock station.

Configuration#

In addition to the available PAL configurations for the docking_server node, you can create new configurations for your robot. To do so, you first need to create a new directory in the .pal folder of your robot.

mkdir -p ~/.pal/config

And then, within this folder, you can create a new docking_server configuration file.

touch ~/.pal/config/99_my_docking_server_config.yaml

Attention

The name of the file should start with a number to ensure that it is loaded last and overrides the default PAL configurations.

Within the newly created 99_my_docking_server_config.yaml file, you can insert your custom docking_server parameters. For the list of available parameters, their meaning and how they affect the docking_server, you can refer to the docking_server configuration guide. When creating a new Navigation configuration file, you need to specify the node name it refers to, in this case, docking_server.

/docking_server:
   ros__parameters:
      # Your docking_server parameters

Attention

If you want to change the parameters for the docking_server node used in the simulation, you need to use the docking_server_sim node name instead of docking_server.

Once created, to start using your custom docking_server configuration, you need to restart the docking module with the command:

pal module restart docking

Note

This change is is persistent and will be loaded every time you start the docking module. If you want to revert to the default PAL configuration, you can simply delete the custom configuration file you created in the ~/.pal/config folder.

🔌 Docking Server#

Parameters#

Configuration#

See also#