Allow "null" values for optional JSON properties

The VDA5050 specification does not describe how to handle "null" values for optional properties in messages. Generally, depending on the implementation, a value of "null" for an optional property could indicate that the property has been omitted / explicitly not set. Allowing "null" values for optional properties makes the vehicle drivers more robust and work with vehicles that that use "null" values instead of omitting the property entirely from JSON messages. While here, fix the follwoing: * Fix some of the fields that are optional according to the VDA5050 specification and correctly treat them as such in the driver implementations. * Remove some fields (from messages) that have been removed with VDA5050 2.0. Co-authored-by: Martin Grzenia <martin.grzenia@iml.fraunhofer.de> Co-authored-by: Sebastian Bonna <sebastian.bonna@iml.fraunhofer.de> Merged-by: Martin Grzenia <martin.grzenia@iml.fraunhofer.de>
openTCS · May 27, 2024 · c253df3 · c253df3
1 parent 02ba420
commit c253df3
Show file tree

Hide file tree

Showing 65 changed files with 2,079 additions and 363 deletions.
diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc
@@ -24,8 +24,10 @@ toc::[]
 
 * New features and enhancements:
 ** In case the property `vda5050:vehicleLengthLoaded` or `vda5050:vehicleLengthUnloaded` is not set, the vehicle length configured in the plant model is used as the default value for the respective property.
+** Allow `null` for optional properties in JSON messages.
 * Fixes:
 ** Dont send cancel order actions when the vehicles changes its operating mode and is actively rejecting an order.
+** Some of the fields that are optional according to the VDA5050 specification are now also correctly treated as such in the driver implementations.
 * Changes affecting developers:
 ** Update JUnit to 5.10.1.
 ** Update ApprovalTests to 22.3.3.

diff --git a/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v1_1/message/state/ActionState.java b/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v1_1/message/state/ActionState.java
@@ -27,7 +27,7 @@ public class ActionState
    */
   private String actionId;
   /**
-   * Type of the action.
+   * [Optional] Type of the action.
    * <p>
    * Only for informational or visualization purposes.
    */
@@ -50,10 +50,8 @@ public class ActionState
   @JsonCreator
   public ActionState(
       @Nonnull @JsonProperty(required = true, value = "actionId") String actionId,
-      @Nonnull @JsonProperty(required = true, value = "actionType") String actionType,
       @Nonnull @JsonProperty(required = true, value = "actionStatus") ActionStatus actionStatus) {
     this.actionId = requireNonNull(actionId, "actionId");
-    this.actionType = requireNonNull(actionType, "actionType");
     this.actionStatus = requireNonNull(actionStatus, "actionStatus");
   }
 
@@ -97,8 +95,8 @@ public String getActionType() {
     return actionType;
   }
 
-  public ActionState setActionType(@Nonnull String actionType) {
-    this.actionType = requireNonNull(actionType, "actionType");
+  public ActionState setActionType(String actionType) {
+    this.actionType = actionType;
     return this;
   }
 

diff --git a/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v1_1/simulation/VehicleSimulator.java b/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v1_1/simulation/VehicleSimulator.java
@@ -225,8 +225,8 @@ private void newInstantAction(Action action) {
     ActionTuple tuple = new ActionTuple();
     tuple.action = action;
     tuple.state = new ActionState(action.getActionId(),
-                                  action.getActionType(),
-                                  ActionStatus.WAITING);
+                                  ActionStatus.WAITING)
+        .setActionType(action.getActionType());
     actionMap.put(action.getActionId(), tuple);
 
     switch (tuple.action.getActionType()) {
@@ -315,8 +315,9 @@ private void acceptNewOrder(Order order) {
       vehicleState.getNodeStates().add(state);
       node.getActions().forEach(action -> {
         vehicleState.getActionStates().add(new ActionState(action.getActionId(),
-                                                           action.getActionType(),
-                                                           ActionStatus.WAITING));
+                                                           ActionStatus.WAITING)
+            .setActionType(action.getActionType())
+        );
       });
     });
     vehicleState.getEdgeStates().clear();
@@ -329,8 +330,9 @@ private void acceptNewOrder(Order order) {
                                                      edge.isReleased()));
       edge.getActions().forEach(action -> {
         vehicleState.getActionStates().add(new ActionState(action.getActionId(),
-                                                           action.getActionType(),
-                                                           ActionStatus.WAITING));
+                                                           ActionStatus.WAITING)
+            .setActionType(action.getActionType())
+        );
       });
     });
     sendState();
@@ -360,8 +362,9 @@ private void acceptOrderUpdate(Order order) {
       vehicleState.getNodeStates().add(state);
       node.getActions().forEach(action -> {
         vehicleState.getActionStates().add(new ActionState(action.getActionId(),
-                                                           action.getActionType(),
-                                                           ActionStatus.WAITING));
+                                                           ActionStatus.WAITING)
+            .setActionType(action.getActionType())
+        );
       });
     });
     order.getEdges().forEach(edge -> {
@@ -373,8 +376,9 @@ private void acceptOrderUpdate(Order order) {
                                                      edge.isReleased()));
       edge.getActions().forEach(action -> {
         vehicleState.getActionStates().add(new ActionState(action.getActionId(),
-                                                           action.getActionType(),
-                                                           ActionStatus.WAITING));
+                                                           ActionStatus.WAITING)
+            .setActionType(action.getActionType())
+        );
       });
     });
     sendState();

diff --git a/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v2_0/StateMappings.java b/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v2_0/StateMappings.java
@@ -138,6 +138,10 @@ public static String toInfoPropertyValue(@Nonnull State state, @Nonnull InfoLeve
     requireNonNull(state, "state");
     requireNonNull(infoLevel, "infoLevel");
 
+    if (state.getInformation() == null) {
+      return "";
+    }
+
     return String.join(
         ", ",
         state.getInformation().stream()

diff --git a/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v2_0/message/common/ControlPoint.java b/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v2_0/message/common/ControlPoint.java
@@ -31,37 +31,26 @@ public class ControlPoint
    */
   private Double y;
   /**
-   * The weight with which this control point pulls on the curve. Range: [0 ... infinity]
+   * [Optional] The weight with which this control point pulls on the curve. Range: [0 ... infinity]
    * <p>
    * When not defined, the default will be 1.0.
    */
   private Double weight;
-  /**
-   * [Optional] Orientation of the AGV on this position of the curve. Range: [-PI ... PI]
-   * <p>
-   * The orientation is in world coordinates. When not defined the orientation of the AGV will be
-   * tangential to the curve.
-   */
-  private Double orientation;
 
   @JsonCreator
   public ControlPoint(
       @Nonnull @JsonProperty(required = true, value = "x") Double x,
-      @Nonnull @JsonProperty(required = true, value = "y") Double y,
-      @Nonnull @JsonProperty(required = true, value = "weight") Double weight) {
+      @Nonnull @JsonProperty(required = true, value = "y") Double y) {
     this.x = requireNonNull(x, "x");
     this.y = requireNonNull(y, "y");
-    this.weight
-        = checkInRange(requireNonNull(weight, "weight"), 0.0, Double.MAX_VALUE, "weight");
   }
 
   public Double getWeight() {
     return weight;
   }
 
-  public ControlPoint setWeight(@Nonnull Double weight) {
-    this.weight
-        = checkInRange(requireNonNull(weight, "weight"), 0.0, Double.MAX_VALUE, "weight");
+  public ControlPoint setWeight(Double weight) {
+    this.weight = weight == null ? null : checkInRange(weight, 0.0, Double.MAX_VALUE, "weight");
     return this;
   }
 
@@ -83,24 +72,11 @@ public ControlPoint setY(@Nonnull Double y) {
     return this;
   }
 
-  public Double getOrientation() {
-    return orientation;
-  }
-
-  public ControlPoint setOrientation(Double orientation) {
-    if (orientation != null) {
-      checkInRange(orientation, -Math.PI, Math.PI, "orientation");
-    }
-    this.orientation = orientation;
-    return this;
-  }
-
   @Override
   public String toString() {
     return "ControlPoint{" + "x=" + x
         + ", y=" + y
         + ", weight=" + weight
-        + ", orientation=" + orientation
         + '}';
   }
 

diff --git a/...a/org/opentcs/commadapter/vehicle/vda5050/v2_0/message/instantactions/InstantActions.java b/...a/org/opentcs/commadapter/vehicle/vda5050/v2_0/message/instantactions/InstantActions.java
@@ -55,7 +55,7 @@ public InstantActions(
       @Nonnull @JsonProperty(required = true, value = "version") String version,
       @Nonnull @JsonProperty(required = true, value = "manufacturer") String manufacturer,
       @Nonnull @JsonProperty(required = true, value = "serialNumber") String serialNumber,
-      @Nonnull @JsonProperty(required = true, value = "instantActions") List<Action> actions) {
+      @Nonnull @JsonProperty(required = true, value = "actions") List<Action> actions) {
     super(headerId, timestamp, version, manufacturer, serialNumber);
     this.actions = requireNonNull(actions, "actions");
   }

diff --git a/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v2_0/message/state/ActionState.java b/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v2_0/message/state/ActionState.java
@@ -27,7 +27,7 @@ public class ActionState
    */
   private String actionId;
   /**
-   * Type of the action.
+   * [Optional] Type of the action.
    * <p>
    * Only for informational or visualization purposes.
    */
@@ -50,10 +50,8 @@ public class ActionState
   @JsonCreator
   public ActionState(
       @Nonnull @JsonProperty(required = true, value = "actionId") String actionId,
-      @Nonnull @JsonProperty(required = true, value = "actionType") String actionType,
       @Nonnull @JsonProperty(required = true, value = "actionStatus") ActionStatus actionStatus) {
     this.actionId = requireNonNull(actionId, "actionId");
-    this.actionType = requireNonNull(actionType, "actionType");
     this.actionStatus = requireNonNull(actionStatus, "actionStatus");
   }
 
@@ -97,8 +95,8 @@ public String getActionType() {
     return actionType;
   }
 
-  public ActionState setActionType(@Nonnull String actionType) {
-    this.actionType = requireNonNull(actionType, "actionType");
+  public ActionState setActionType(String actionType) {
+    this.actionType = actionType;
     return this;
   }
 

diff --git a/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v2_0/message/state/State.java b/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v2_0/message/state/State.java
@@ -146,7 +146,7 @@ public class State
    */
   private List<ErrorEntry> errors;
   /**
-   * List of {@link InfoEntry} objects.
+   * [Optional] List of {@link InfoEntry} objects.
    * <p>
    * This should only be used for visualization or debugging – it must not be used for logic in
    * master control. An empty list indicates that the AGV has no information.
@@ -407,7 +407,7 @@ public List<InfoEntry> getInformation() {
   }
 
   public State setInformation(List<InfoEntry> information) {
-    this.information = requireNonNull(information, "information");
+    this.information = information;
     return this;
   }
 

diff --git a/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v2_0/simulation/VehicleSimulator.java b/src/main/java/org/opentcs/commadapter/vehicle/vda5050/v2_0/simulation/VehicleSimulator.java
@@ -224,8 +224,8 @@ private void newInstantAction(Action action) {
     ActionTuple tuple = new ActionTuple();
     tuple.action = action;
     tuple.state = new ActionState(action.getActionId(),
-                                  action.getActionType(),
-                                  ActionStatus.WAITING);
+                                  ActionStatus.WAITING)
+        .setActionType(action.getActionType());
     actionMap.put(action.getActionId(), tuple);
 
     switch (tuple.action.getActionType()) {
@@ -314,8 +314,9 @@ private void acceptNewOrder(Order order) {
       vehicleState.getNodeStates().add(state);
       node.getActions().forEach(action -> {
         vehicleState.getActionStates().add(new ActionState(action.getActionId(),
-                                                           action.getActionType(),
-                                                           ActionStatus.WAITING));
+                                                           ActionStatus.WAITING)
+            .setActionType(action.getActionType())
+        );
       });
     });
     vehicleState.getEdgeStates().clear();
@@ -328,8 +329,9 @@ private void acceptNewOrder(Order order) {
                                                      edge.isReleased()));
       edge.getActions().forEach(action -> {
         vehicleState.getActionStates().add(new ActionState(action.getActionId(),
-                                                           action.getActionType(),
-                                                           ActionStatus.WAITING));
+                                                           ActionStatus.WAITING)
+            .setActionType(action.getActionType())
+        );
       });
     });
     sendState();
@@ -359,8 +361,9 @@ private void acceptOrderUpdate(Order order) {
       vehicleState.getNodeStates().add(state);
       node.getActions().forEach(action -> {
         vehicleState.getActionStates().add(new ActionState(action.getActionId(),
-                                                           action.getActionType(),
-                                                           ActionStatus.WAITING));
+                                                           ActionStatus.WAITING)
+            .setActionType(action.getActionType())
+        );
       });
     });
     order.getEdges().forEach(edge -> {
@@ -372,8 +375,9 @@ private void acceptOrderUpdate(Order order) {
                                                      edge.isReleased()));
       edge.getActions().forEach(action -> {
         vehicleState.getActionStates().add(new ActionState(action.getActionId(),
-                                                           action.getActionType(),
-                                                           ActionStatus.WAITING));
+                                                           ActionStatus.WAITING)
+            .setActionType(action.getActionType())
+        );
       });
     });
     sendState();

diff --git a/...resources/org/opentcs/commadapter/vehicle/vda5050/v1_1/schemas/instantActions.schema.json b/...resources/org/opentcs/commadapter/vehicle/vda5050/v1_1/schemas/instantActions.schema.json
@@ -52,7 +52,10 @@
                         "title": "actionId"
                     },
                     "actionDescription": {
-                        "type": "string",
+                        "type": [
+                          "string",
+                          "null"
+                        ],
                         "title": "Additional Information on the action"
                     },
                     "blockingType": {
@@ -65,7 +68,10 @@
                         ]
                     },
                     "actionParameters": {
-                        "type": "array",
+                        "type": [
+                          "array",
+                          "null"
+                        ],
                         "items": {
                             "title": "actionParameter",
                             "type": "object",