document docking detector toggling options (#773)

* Document docking detector toggling options

Signed-off-by: bkoensgen <b.koensgen@gmail.com>

* Update configuration/packages/configuring-docking-server.rst

Signed-off-by: Steve Macenski <stevenmacenski@gmail.com>

* Update configuration/packages/configuring-docking-server.rst

Signed-off-by: Steve Macenski <stevenmacenski@gmail.com>

---------

Signed-off-by: bkoensgen <b.koensgen@gmail.com>
Signed-off-by: Steve Macenski <stevenmacenski@gmail.com>
Co-authored-by: Steve Macenski <stevenmacenski@gmail.com>

Author: bkoensgen

configuration/packages/configuring-docking-server.rst

@@ -479,6 +479,40 @@ Simple Charging Dock is a provided charging dock plugin that can handle many doc
   Description
     Whether to use external detection topic for dock or use the databases' pose.
 
+:<dock_name>.detector_service_name:
+
+  ============== ==============
+  Type           Default
+  -------------- --------------
+  string         ""
+  ============== ==============
+
+  Description
+    Optional ``std_srvs/Trigger`` service invoked when detection starts or stops via ``startDetectionProcess`` / ``stopDetectionProcess`` if detection method accepts a service call to start and stop.
+
+:<dock_name>.detector_service_timeout:
+
+  ============== ==================
+  Type           Default
+  -------------- ------------------
+  double         5.0
+  ============== ==================
+
+  Description
+    Timeout (s) to wait for ``detector_service_name`` to become available and respond.
+
+:<dock_name>.subscribe_toggle:
+
+  ============== ==============
+  Type           Default
+  -------------- --------------
+  bool           false
+  ============== ==============
+
+  Description
+    When true, subscribe to ``detected_dock_pose`` only while detection is active; otherwise keep the subscription persistent.
+
+
 :<dock_name>.external_detection_timeout:
 
   ============== ==============
@@ -675,6 +709,9 @@ Example
           docking_threshold: 0.05
           staging_x_offset: -0.7
           use_external_detection_pose: true
+          detector_service_name: '/detector/toggle'
+          detector_service_timeout: 5.0
+          subscribe_toggle: true
           use_battery_status: false # true
           use_stall_detection: false
           rotate_to_dock: false

migration/Kilted.rst

@@ -202,6 +202,16 @@ Removed Parameter action_server_result_timeout
 Removed the parameter ``action_server_result_timeout`` from all action servers after resolution within ``rcl`` and ``rclcpp`` to address early goal removal.
 This is not longer required to be set.
 
+Dock Plugin Detector Control
+----------------------------
+
+`PR #5218 <https://github.com/ros-navigation/navigation2/pull/5218>`_ adds on-demand detector control to ``opennav_docking``.
+``ChargingDock`` and ``NonChargingDock`` now provide pure virtual ``startDetectionProcess`` / ``stopDetectionProcess`` functions that the docking server invokes around the perception loop.
+
+- Custom dock plugins must implement the new hooks (return ``true`` if nothing extra is required).
+- ``Simple(Non)ChargingDock`` gained ``detector_service_name``, ``detector_service_timeout``, and ``subscribe_toggle`` parameters so a detector service can be triggered only while detections are needed.
+- See :ref:`configuring_docking_server` for the updated parameter reference and YAML example.
+
 Added Corner Smoothing functionality to route_server
 ----------------------------------------------------