Trigger reset of vehicle's last known position

When the vehicle's reported operating mode changes, optionally reset its
last known position.

Co-authored-by: Stefan Walter <stefan.walter@iml.fraunhofer.de>
Merged-by: Stefan Walter <stefan.walter@iml.fraunhofer.de>

CHANGELOG.adoc

@@ -16,7 +16,7 @@ toc::[]
 * New features and enhancements:
 ** Publish a user notification to the kernel when the vehicle rejects an order.
 ** Fall back to the last known position when other methods of determining the vehicle position fail.
-** When the vehicle's reported operating mode changes, optionally withdraw its transport order and/or update its integration level.
+** When the vehicle's reported operating mode changes, optionally withdraw its transport order and/or update its integration level and/or reset its last known position.
 ** Show the MQTT topic name prefix used for communicating with the vehicle in the driver's KCC control panel.
 * Fixes:
 ** Send order and instant action messages to the vehicle only as long as its reported operating mode is `AUTOMATIC` or `SEMIAUTOMATIC`.

doc/configuration.adoc

@@ -34,6 +34,11 @@ Set to a map of VDA5050 operating mode names to boolean values.
 Whenever the vehicle's reported operating mode changes to a value given in the map, the vehicle's transport order may be withdrawn; if it is withdrawn, this happens forcibly.
 Valid values for operating mode names are `TEACHIN`, `SERVICE`, `MANUAL`, `SEMIAUTOMATIC` and `AUTOMATIC`.
 Valid assignment values are `true` (do withdraw the transport order forcibly) and `false` (do not withdraw the transport order), with `false` being the default for every operating mode.
+`commadapter.vehicle.vda5050.onOpModeChangeDoResetPosition`::
+Set to a map of VDA5050 operating mode names to boolean values.
+Whenever the vehicle's reported operating mode changes to a value given in the map, the vehicle's last known position may be reset.
+Valid values for operating mode names are `TEACHIN`, `SERVICE`, `MANUAL`, `SEMIAUTOMATIC` and `AUTOMATIC`.
+Valid assignment values are 'true' (do reset the last known position) and 'false' (do not reset the last known position), with 'false' being the default for every operating mode.
 `commadapter.vehicle.vda5050.mqtt.brokerHost`::
 The IP address or host name of the MQTT broker to be used.
 `commadapter.vehicle.vda5050.mqtt.brokerPort`::
@@ -64,6 +69,7 @@ The following example configuration can be used as a template to be pasted into
 commadapter.vehicle.vda5050.enabledVersions = 1.1, 2.0
 commadapter.vehicle.vda5050.onOpModeChangeDoUpdateIntegrationLevel = AUTOMATIC=TO_BE_UTILIZED, SEMIAUTOMATIC=TO_BE_UTILIZED, SERVICE=TO_BE_RESPECTED, MANUAL=TO_BE_IGNORED, TEACHIN=TO_BE_IGNORED
 commadapter.vehicle.vda5050.onOpModeChangeDoWithdrawOrder = AUTOMATIC=false, SEMIAUTOMATIC=false, SERVICE=true, MANUAL=true, TEACHIN=true
+commadapter.vehicle.vda5050.onOpModeChangeDoResetPosition = AUTOMATIC=false, SEMIAUTOMATIC=false, SERVICE=true, MANUAL=true, TEACHIN=true
 commadapter.vehicle.vda5050.mqtt.brokerHost = broker.example.com
 commadapter.vehicle.vda5050.mqtt.brokerPort = 1883
 commadapter.vehicle.vda5050.mqtt.connectionEncrypted = false

src/main/java/org/opentcs/commadapter/vehicle/vda5050/CommAdapterConfiguration.java

@@ -33,16 +33,22 @@ public interface CommAdapterConfiguration {
 
   @ConfigurationEntry(
       type = "Map of operating modes to the integration level",
-      description = "See doc",
-      orderKey = "0_changeLevel")
+      description = "See driver documentation.",
+      orderKey = "1_1_changeLevel")
   Map<ConfigOperatingMode, ConfigIntegrationLevel> onOpModeChangeDoUpdateIntegrationLevel();
 
   @ConfigurationEntry(
       type = "Map of operating modes to a boolean",
-      description = "See doc",
-      orderKey = "0_changeLevel")
+      description = "See driver documentation.",
+      orderKey = "1_2_withdrawOrder")
   Map<ConfigOperatingMode, Boolean> onOpModeChangeDoWithdrawOrder();
 
+  @ConfigurationEntry(
+      type = "Map of operating modes to a boolean",
+      description = "See driver documentation.",
+      orderKey = "1_3_resetPosition")
+  Map<ConfigOperatingMode, Boolean> onOpModeChangeDoResetPosition();
+
   /**
    * Vehicle operating modes.
    */

src/main/java/org/opentcs/commadapter/vehicle/vda5050/v1_1/CommAdapterImpl.java

@@ -621,6 +621,14 @@ private void processVehicleOperatingMode(State state) {
       movementCommandManager.failCurrentCommand(this::onMovementCommandFailed);
     }
 
+    if (configuration.onOpModeChangeDoResetPosition()
+        .getOrDefault(mapToConfigOperatingMode(state.getOperatingMode()), Boolean.FALSE)) {
+      LOG.debug("{}: Resetting last known vehicle position due to op mode change to {}...",
+                getName(),
+                state.getOperatingMode());
+      getProcessModel().setVehiclePosition(null);
+    }
+
     configuration.onOpModeChangeDoUpdateIntegrationLevel()
         .getOrDefault(
             mapToConfigOperatingMode(state.getOperatingMode()),

src/main/java/org/opentcs/commadapter/vehicle/vda5050/v2_0/CommAdapterImpl.java

@@ -629,6 +629,14 @@ private void processVehicleOperatingMode(State state) {
       movementCommandManager.failCurrentCommand(this::onMovementCommandFailed);
     }
 
+    if (configuration.onOpModeChangeDoResetPosition()
+        .getOrDefault(mapToConfigOperatingMode(state.getOperatingMode()), Boolean.FALSE)) {
+      LOG.debug("{}: Resetting last known vehicle position due to op mode change to {}...",
+                getName(),
+                state.getOperatingMode());
+      getProcessModel().setVehiclePosition(null);
+    }
+
     configuration.onOpModeChangeDoUpdateIntegrationLevel()
         .getOrDefault(
             mapToConfigOperatingMode(state.getOperatingMode()),