Create initial message schemas

Closes #7 (closed)

examples/ecosub_c2/platform_status-from_usbl_example.json

+{
+    "message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
+    "timestamp": "2022-11-16T00:00:00Z",
+    "version": 2,
+    "source": "hermes",
+    "destination": "autonomy_engine",
+    "delivery_type": "publish",
+    "encoded": false,
+    "message_type": "platform_status",
+    "platform_ID": 1,

examples/ecosub_c2/observation.json

+{
+    "message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
+    "timestamp": "2022-11-16T00:00:00Z",
+    "version": 2,
+    "source": "ecosub_c2",
+    "destination": "autonomy_engine",
+    "delivery_type": "publish",
+    "encoded": false,
+    "message_type": "observation",
+    "platform_ID": 3,

examples/gui/planning_configuration.json

+              "safe_command": "go_home",
+              "target_depth": 10.0
+            },
+            "max_velocity": 0.9,
+            "min_altitude": 15.2,
+            "min_velocity": 0.1,
+            "additional_data": {
+                "scan_type": "DVL",
+                "swath_width": 10
+            }
+          },
+          {
+            "platform_ID": 10,
+            "serial": "ecosub-5",
+            "model": "ecosub",
+            "emergency": {

formats/mission_plan.py

+            "example": 15.0,
+        },
+        "activate_payload": {
+            "type": "boolean",
+            "description": "To activate/deactivate sensor for Autosub "
+            + "Hover-1 --> `MBES` sensor and for EcoSUB --> `Sidescan`",
+            "example": True,
+        },
+        "send_environmental_data": {
+            "type": "boolean",
+            "description": "To trigger the platform to send list of"
+            + "  observations if any found",
+            "example": False,
+        },
+    },
+    "required": [

formats/mission_plan.py

+action_schema = {
+    "type": "object",
+    "properties": {
+        "action": {
+            "type": "string",
+            "description": "Autonomy Engine's action from `move`, `payload`,"
+            + " `dive`, `send_hits`, `scanline`, `scanpoint`.",
+            "example": "move",
+        },
+        "flight_style": {
+            "type": "string",
+            "description": "Platform-specific modes/flight styles to perform"
+            + " next action",
+            "example": "orbit",
+        },
+        "latitude_waypoint": {

formats/platform_status.py

+            "example": {"payload": [1.2, 434]},
+        },
+    },
+    "required": [],
+}
+
+platform_status_message_schema = {
+    "allOf": [{"$ref": "#/components/schemas/Message"}],
+    "type": "object",
+    "properties": {
+        "platform_ID": {
+            "type": "integer",
+            "description": "Identifier for platform",
+            "example": 1,
+        },
+        "status_source": {

formats/planning_configuration.py

+            "description": "Minimum altitude set for squad.",
+            "example": 15.2,
+        },
+        "min_velocity": {
+            "type": "number",
+            "format": "float",
+            "description": "Minimum velocity set for squad.",
+            "example": 0.1,
+        },
+        "max_velocity": {
+            "type": "number",
+            "format": "float",
+            "description": "Maximum altitude set for squad.",
+            "example": 0.9,
+        },
+        "additional_data": {

requirements.txt

+Flask
+flask-restx
+flasgger
+flask-marshmallow

tests/test.py

+"""
+schema, spec_url = read_from_filename("fixtures/swagger.json")
+errors_iterator = openapi_v3_spec_validator.iter_errors(schema)
+print(errors_iterator)
+print(openapi_v30_spec_validator.validate(schema))
+
+"""
+Test schema - Hydrosurv Messages
+"""
+message_types = ["acknowledgement", "mission_plan", "platform_status"]
+for item in message_types:
+    f = open("mock_data/hydrosurv_adapter/%s.json" % item)
+    mock_data = json.load(f)
+    header_data = mock_data["header"]
+    payload_data = mock_data["payload"]
+    print(validate(header_data, message_header, format_checker=FormatChecker()))

examples/all/acknowledgement.json

 {
-    "message_ID": "b427003c-7bc8-11ed-a1eb-0242ac120002",
+    "message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
     "timestamp": "2022-11-16T00:00:00Z",
-    "version": 1,
-    "source": "hydrosurv_adapter",
-    "destination": "autonomy_engine",
+    "version": 2,
+    "source": "autonomy_engine",
+    "destination": "ah1",
+    "delivery_type": "publish",
     "encoded": false,
-    "type": "acknowledgement",
-    "payload": {
-        "message_ID": "b427003c-7bc8-11ed-a1eb-0242ac999999",
-        "status": "executed"
-    }
+    "message_type": "platform_status",
+    "acknowledged_message_ID": "02125022255-7bc8-11ed-a1eb-0242ac999999",
+    "status": "executed by platform"
 }
\ No newline at end of file

examples/all/mission_plan.json

 {
-    "message_ID": "b427003c-7bc8-11ed-a1eb-0242ac120002",
+    "message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
     "timestamp": "2022-11-16T00:00:00Z",
     "version": 2,
     "source": "autonomy_engine",
-    "destination": "ah-1",
+    "destination": "hydrosurv_adapter",
+    "delivery_type": "publish",
     "encoded": false,
-    "type": "platform_status",
-    "payload": {
-        "plan_ID": 1,
-        "platform_serial": "reav-60",
-        "plan": [
-            {
-                "action": "move",
-                "flight_style": "orbit",
-                "latitude_waypoint": -4.187143188645706,
-                "longitude_waypoint": 50.37072283932642,
-                "altitude": 0,
-                "depth": 0,
-                "activate_payload": false,
-                "send_environmental_data": false
-            }
-        ]
-    }
-}
\ No newline at end of file
+    "message_type": "mission_plan",
+    "plan_ID": 1,
+    "plan": [
+        {
+          "action": "move",
+          "flight_style": "orbit",
+          "activate_payload": true,
+          "altitude": 15,
+          "depth": 15,
+          "latitude_waypoint": -4.187143188645706,
+          "longitude_waypoint": 50.37072283932642,
+          "send_environmental_data": false
+        }
+      ],  
+    "platform_serial": "reav-60"
+}

examples/all/platform_status.json

 {
-    "message_ID": "b427003c-7bc8-11ed-a1eb-0242ac120002",
-    "timestamp": "2022-11-16T00:00:00Z",
-    "version": 1,
-    "source": "hydrosurv_adapter",
-    "destination": "autonomy_engine",
-    "encoded": false,
-    "type": "platform_status",
-    "payload": {
-        "platform_ID": 1,
-        "active": true,
-        "platform_state": "ORBIT",
-        "autonomy_plan_ID": 1,
-        "mission_track_ID": 4,
-        "mission_action_ID": 1,
-        "range_to_go": 0.3,
-        "speed_over_ground": 0.3,
-        "water_current_velocity": 0.3,
-        "thrust_applied": 0.3,
-        "health_status": "Warning",
-        "gps_data": [
-            {
-                "gps_source": "internal",
-                "latitude_type": "",
-                "longitude_type": "",
-                "latitude": -7.432,
-                "longitude": 50.365,
-                "depth": 0.0,
-                "altitude": 0.0
-            }
-        ],
-        "localisation_error": null,
-        "usbl_fix_seconds_ago": null,
-        "battery_remaining_capacity": 80,
-        "sensor_config": {
-            "sensor_name": null,
-            "sensor_status": false,
-            "additional_data": null
-        }
-    }
-  }
\ No newline at end of file
+  "message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
+  "timestamp": "2022-11-16T00:00:00Z",
+  "version": 2,
+  "source": "hydrosurv_adapter",
+  "destination": "autonomy_engine",
+  "delivery_type": "publish",
+  "encoded": false,
+  "message_type": "platform_status",
+  "autonomy_engine_mission_plan_ID": 1,
+  "active": true,
+  "status_source": "onboard_platform",
+  "altitude": 20,
+  "battery_remaining_capacity": 80.2,
+  "depth": 50,
+  "health_status": "Warning",
+  "latitude": 178.2,
+  "localisation_error": 0.000129,
+  "longitude": -10.122,
+  "mission_action_ID": 1,
+  "mission_track_ID": 4,
+  "platform_ID": 1,
+  "platform_state": "ABORT",
+  "platform_timestamp": "2022-12-21T00:00:00Z",
+  "range_to_go": 124.3,
+  "sensor_config": {
+    "additional_data": {
+      "payload": [
+        1.2,
+        434
+      ]
+    },
+    "sensor_serial": "mbes-002a",
+    "sensor_status": true
+  },
+  "speed_over_ground": 124.3,
+  "thrust_applied": 124.3,
+  "usbl_fix_seconds_ago": 10,
+  "water_current_velocity": 124.3
+}
\ No newline at end of file

examples/ecosub_c2/mission_plan.json

 {
-    "message_ID": "b427003c-7bc8-11ed-a1eb-0242ac120002",
-    "timestamp": "2022-11-16T00:00:00Z",
-    "version": 2,
-    "source": "autonomy_engine",
-    "destination": "ecosub_c2",
-    "encoded": false,
-    "type": "mission_plan",
-    "payload": {
-        "plan_ID": 3,
-        "platform_serial": "ecosub-4",
-        "plan": [
-            {
-                "action": "move",
-                "flight_style": "dive",
-                "latitude_waypoint": -4.187143188645706,
-                "longitude_waypoint": 50.37072283932642,
-                "altitude": 20,
-                "depth": null,
-                "activate_payload": true,
-                "send_environmental_data": false
-            }
-        ]
+  "message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
+  "timestamp": "2022-11-16T00:00:00Z",
+  "version": 2,
+  "source": "autonomy_engine",
+  "destination": "ecosub_c2",
+  "delivery_type": "publish",
+  "encoded": false,
+  "message_type": "mission_plan",
+  "platform_serial": "reav-60",
+  "autonomy_engine_mission_plan_ID": 1,
+  "plan": [
+    {
+      "action": "move",
+      "flight_style": "go to waypoint",
+      "latitude_waypoint": -3.237143188645706,
+      "longitude_waypoint": 52.37072283932642,
+      "altitude": null,
+      "depth": 0.0,
+      "activate_payload": false,
+      "send_environmental_data": false
+    },
+    {
+      "action": "dive",
+      "flight_style": "dive to depth",
+      "latitude_waypoint": -3.237143188645706,
+      "longitude_waypoint": 52.37072283932642,
+      "altitude": 10,
+      "depth": null,
+      "activate_payload": false,
+      "send_environmental_data": false
+    },
+    {
+      "action": "scanline",
+      "flight_style": "go to waypoint",
+      "latitude_waypoint": -0.237143188645706,
+      "longitude_waypoint": 60.00000000000000,
+      "altitude": 10,
+      "depth": null,
+      "activate_payload": true,
+      "send_environmental_data": false
+    },
+    {
+      "action": "climb",
+      "flight_style": "go to surface",
+      "latitude_waypoint": -0.237143188645706,
+      "longitude_waypoint": 52.37072283932642,
+      "altitude": null,
+      "depth": 0,
+      "activate_payload": false,
+      "send_environmental_data": true
     }
+  ]
 }
\ No newline at end of file

examples/ecosub_c2/observation.json

 {
-    "message_ID": "b427003c-7bc8-11ed-a1eb-0242ac120002",
+    "message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
     "timestamp": "2022-11-16T00:00:00Z",
     "version": 2,
     "source": "ecosub_c2",
     "destination": "autonomy_engine",
+    "delivery_type": "publish",
     "encoded": false,
-    "type": "platform_status",
-    "payload": {
-        "platform_serial":"ecosub-3",
-        "points_of_interest": [],
-        "region_surveyed": [],
-        "quality_of_points": 0.98,
-        "additional_data": {
-            "sensor_x": false
+    "message_type": "observation",
+    "platform_ID": 3,
+    "points_of_interest": [
+        {
+            "latitude": 178.2,
+            "longitude": -10.122,
+            "quality_of_point": 0.98
+        },
+        {
+            "latitude": 50.1382,
+            "longitude": -11.122,
+            "quality_of_point": 0.50
         }
-    }
+    ],
+    "region_surveyed": ""
 }
\ No newline at end of file

examples/ecosub_c2/platform_status-from_usbl_example.json

+{
+    "message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
+    "timestamp": "2022-11-16T00:00:00Z",
+    "version": 2,
+    "source": "hermes",
+    "destination": "autonomy_engine",
+    "delivery_type": "publish",
+    "encoded": false,
+    "message_type": "platform_status",
+    "platform_ID": 1,
+    "platform_timestamp": "2022-12-21T00:00:00Z",
+    "status_source": "usbl",
+    "latitude": 178.2,
+    "longitude": -10.122,
+    "depth": 50,
+    "altitude": 20
+}

examples/ecosub_c2/platform_status.json

 {
-    "message_ID": "b427003c-7bc8-11ed-a1eb-0242ac120002",
+    "message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
     "timestamp": "2022-11-16T00:00:00Z",
-    "version": 1,
-    "source": "hermes_ecosub",
+    "version": 2,
+    "source": "ecosub_c2",
     "destination": "autonomy_engine",
+    "delivery_type": "publish",
     "encoded": false,
-    "type": "platform_status",
-    "payload": {
-        "platform_ID": 2,
-        "active": true,
-        "platform_state": "IDLE",
-        "autonomy_plan_ID": 1,
-        "mission_track_ID": 4,
-        "mission_action_ID": 1,
-        "range_to_go": 12.3,
-        "speed_over_ground": 10.3,
-        "water_current_velocity": 10.3,
-        "thrust_applied": 0.3,
-        "health_status": "Warning",
-        "gps_data": [
-            {
-                "gps_source": "internal",
-                "latitude_type": "",
-                "longitude_type": "",
-                "latitude": -7.432,
-                "longitude": 50.365,
-                "depth": 5.0,
-                "altitude": 20.0
-            }
-        ],
-        "localisation_error": null,
-        "usbl_fix_seconds_ago": null,
-        "battery_remaining_capacity": 80,
-        "sensor_config": {
-            "sensor_ID": 22,
-            "serial": "sidescan-2x",
-            "sensor_status": true,
-            "additional_data": {
-                "whiskers_on": true
-            }
-        }
-    }
-  }
\ No newline at end of file
+    "message_type": "platform_status",
+    "platform_ID": 1,
+    "platform_timestamp": "2022-12-21T00:00:00Z",
+    "status_source": "onboard_platform",
+    "autonomy_engine_plan_ID": 1,
+    "battery_remaining_capacity": 80.2,
+    "active": true,
+    "platform_state": "ABORT",
+    "mission_action_ID": 1,
+    "mission_track_ID": 4,
+    "latitude": 178.2,
+    "longitude": -10.122,
+    "depth": 50,
+    "altitude": 20,
+    "health_status": "Warning",
+    "localisation_error": null,
+    "usbl_fix_seconds_ago": null,
+    "range_to_go": 124.3,
+    "sensor_config": {
+        "sensor_ID": 22,
+        "serial": "sidescan-2x",    
+        "sensor_on": true,
+        "additional_data": {
+            "whiskers_on": true
+        }      
+    },
+    "current_pitch": -4,
+    "speed_over_ground": 4.3,
+    "thrust_applied": 124.3,
+    "water_current_velocity": 124.3
+}

examples/hydrosurv_adapter/acknowledgement.json

 {
-    "message_ID": "b427003c-7bc8-11ed-a1eb-0242ac120002",
+    "message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
     "timestamp": "2022-11-16T00:00:00Z",
     "version": 1,
     "source": "hydrosurv_adapter",
     "destination": "autonomy_engine",
+    "delivery_type": "publish",
     "encoded": false,
-    "type": "acknowledgement",
-    "payload": {
-        "message_ID": "b427003c-7bc8-11ed-a1eb-0242ac999999",
-        "status": "executed"
-    }
+    "message_type": "acknowledgement",
+    "acknowledged_message_ID": "11111111-7bc8-11ed-a1eb-0242ac999999",
+    "status": "Approved and sent to platform"
 }
\ No newline at end of file

examples/hydrosurv_adapter/mission_plan.json

 {
-    "message_ID": "b427003c-7bc8-11ed-a1eb-0242ac120002",
-    "timestamp": "2022-11-16T00:00:00Z",
-    "version": 2,
-    "source": "autonomy_engine",
-    "destination": "ah-1",
-    "encoded": false,
-    "type": "platform_status",
-    "payload": {
-        "plan_ID": 1,
-        "platform_serial": "reav-60",
-        "plan": [
-            {
-                "action": "move",
-                "flight_style": "orbit",
-                "latitude_waypoint": -4.187143188645706,
-                "longitude_waypoint": 50.37072283932642,
-                "altitude": 0,
-                "depth": 0,
-                "activate_payload": false,
-                "send_environmental_data": false
-            }
-        ]
-    }
+  "message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
+  "timestamp": "2022-11-16T00:00:00Z",
+  "version": 2,
+  "source": "autonomy_engine",
+  "destination": "hydrosurv_adapter",
+  "delivery_type": "publish",
+  "encoded": false,
+  "message_type": "mission_plan",
+  "platform_serial": "reav-60",
+  "autonomy_engine_plan_ID": 1,
+  "plan": [
+      {
+        "latitude_waypoint": -4.187143188645706,
+        "longitude_waypoint": 50.37072283932642
+      },
+      {
+        "latitude_waypoint": -3.187143188645706,
+        "longitude_waypoint": 51.37072283932642
+      },
+      {
+        "latitude_waypoint": -3.237143188645706,
+        "longitude_waypoint": 52.37072283932642
+      }
+    ]
 }
\ No newline at end of file

examples/hydrosurv_adapter/platform_status.json

 {
-    "message_ID": "b427003c-7bc8-11ed-a1eb-0242ac120002",
-    "timestamp": "2022-11-16T00:00:00Z",
-    "version": 1,
-    "source": "hydrosurv_adapter",
-    "destination": "autonomy_engine",
-    "encoded": false,
-    "type": "platform_status",
-    "payload": {
-        "platform_ID": 1,
-        "active": true,
-        "platform_state": "ORBIT",
-        "autonomy_plan_ID": 1,
-        "mission_track_ID": 4,
-        "mission_action_ID": 1,
-        "range_to_go": 0.3,
-        "speed_over_ground": 0.3,
-        "water_current_velocity": 0.3,
-        "thrust_applied": 0.3,
-        "health_status": "Warning",
-        "gps_data": [
-            {
-                "gps_source": "internal",
-                "latitude_type": "",
-                "longitude_type": "",
-                "latitude": -7.432,
-                "longitude": 50.365,
-                "depth": 0.0,
-                "altitude": 0.0
-            }
-        ],
-        "localisation_error": null,
-        "usbl_fix_seconds_ago": null,
-        "battery_remaining_capacity": 80,
-        "sensor_config": {
-            "sensor_name": null,
-            "sensor_status": false,
-            "additional_data": null
-        }
-    }
-  }
\ No newline at end of file
+  "message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
+  "timestamp": "2022-11-16T00:00:00Z",
+  "version": 2,
+  "source": "hydrosurv_adapter",
+  "destination": "autonomy_engine",
+  "delivery_type": "publish",
+  "encoded": false,
+  "message_type": "platform_status",
+  "autonomy_engine_plan_ID": 1,
+  "active": true,
+  "status_source": "onboard_platform",
+  "battery_remaining_capacity": 80.2,
+  "health_status": "Lost Connection",
+  "latitude": 178.2,
+  "longitude": -10.122,
+  "mission_action_ID": 1,
+  "mission_track_ID": 4,
+  "platform_ID": 1,
+  "platform_state": "ABORT",
+  "platform_timestamp": "2022-12-21T00:00:00Z",
+  "speed_over_ground": 4.5,
+  "range_to_go": null,
+  "thrust_applied": null
+}
\ No newline at end of file

formats/acknowledgement.py

     receipt of message.
 """
 acknowledgement_schema = {
+    "allOf": [{"$ref": "#/components/schemas/Message"}],
+    "type": "object",
     "properties": {
-        "message_ID": {
+        "acknowledged_message_ID": {
             "type": "string",
             "description": "Identifier of message received and executed with "
             + "success for mission plans sent by the Autonomy Engine.",
-            "example": "b427003c-7bc8-11ed-a1eb-0242ac999999",
+            "example": "02125022255-7bc8-11ed-a1eb-0242ac999999",
         },
         "status": {
             "type": "string",
-            "description": "Highest level of acknowledgement. I.e. `c2_received`:"
-            + " Received by C2, `c2_sent`: Sent from C2->Platform, `executed`:"
-            + " Executed by platform",
+            "description": "Highest level of acknowledgement. I.e."
+            + " `c2_received`: Received by C2, `c2_sent`: Sent from"
+            + "  C2->Platform, `executed`: Executed by platform",
             "example": "executed by platform",
         },
     },
-    "required": ["message_ID", "status"],
+    "required": ["acknowledged_message_ID", "status"],
 }
 
 # acknowledgement_schema = api.model(
 #         ),
 #         "status": fields.String(
 #             required=True,
-#             description="Highest level of acknowledgement. I.e. `c2_received`:"
-#             + " Received by C2, `c2_sent`: Sent from C2->Platform, `executed`:"
-#             + " Executed by platform",
+#             description="Highest level of acknowledgement. "
+#             + " I.e. `c2_received`: Received by C2, `c2_sent`:"
+#             + "  Sent from C2->Platform, `executed`: Executed by platform",
 #         ),
 #     },
 # )

formats/message_wrapper.py

 """
     schemas: Message Wrapper is used to wrap all message types that contain
-    details of where the message is coming from, which end client is its destination
-    and the type of message.
+    details of where the message is coming from, which end client is its
+    destination and the type of message.
 """
 
 message_wrapper_schema = {
     "properties": {
         "message_ID": {
             "type": "string",
-            "description": "An identifier for the type of " + "message received.",
-            "example": "PlatformStatus",
+            "description": "An identifier for the type of message received.",
+            "example": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
         },
         "timestamp": {
             "type": "date-time",
         },
         "version": {
             "type": "string",
-            "description": "Version of comms bacbone messaging format protocol",
+            "description": "Version of comms bacbone message format protocol",
             "example": 2.0,
         },
         "source": {
         },
         "destination": {
             "type": "string",
-            "description": "Publisher topic; What is the destination of this message",
+            "description": "Publisher topic; What is the destination"
+            + " of this message",
             "example": "ah1",
         },
         "encoded": {

formats/mission_plan.py

 """
-    schemas: Mission plan (un-complied) geenrated by the  Autonomy Engine
+    schemas: Mission plan (un-compiled) geenrated by the  Autonomy Engine
     sent to the respective platform's C2 to compile into a platform-specific
     mission plan.
 """
         },
         "send_environmental_data": {
             "type": "boolean",
-            "description": "To trigger the platform to send list of observations"
-            + " if any found",
+            "description": "To trigger the platform to send list of"
+            + "  observations if any found",
             "example": False,
         },
     },
     "required": [
-        "action",
         "latitude_waypoint",
         "longitude_waypoint",
     ],
     "allOf": [{"$ref": "#/components/schemas/Message"}],
     "type": "object",
     "properties": {
-        "plan_ID": {"type": "integer"},
+        "autonomy_engine_plan_ID": {"type": "integer"},
         "platform_serial": {"type": "string"},
         "plan": {
             "type": "array",
 #         ),
 #         "send_environmental_data": fields.Boolean(
 #             required=False,
-#             description="To trigger the platform to send list of observations"
-#             + " if any found",
+#             description="To trigger the platform to send list of"
+#             + " observations if any found",
 #             example=False,
 #         ),
 #     },
 #         "plan": fields.List(
 #             fields.Nested(action_schema),
 #             required=True,
-#             description="Sequence of actions/instructions generated by the "
-#             + " Autonomy Engine that should be compiled by the respective C2.",
+#             description="Sequence of actions/instructions generated by the"
+#             + " Autonomy Engine that should be compiled by the",
+#             + " respective C2.",
 #         ),
 #     },
 # )

formats/observation.py

 """
-    schema: platform-specific decoded status message (DRAFT)
+    schema: Observation Message sent by platforms when points of
+    interest are found.
 """
 # from . import full_message_schema, api
 # from flask_restx import fields
 
+hits_schema = {
+    "type": "object",
+    "properties": {
+        "latitude": {
+            "type": "number",
+            "description": "Identified x-coordinate of point of interest",
+            "example": 178.2,
+        },
+        "longitude": {
+            "type": "number",
+            "description": "Identified y-coordinate of point of interest",
+            "example": -10.122,
+        },
+        "quality_of_point": {
+            "type": "number",
+            "description": "Quality/strength of points from features of"
+            + " interest identified by platform. TODO: DEFINE FORMAT.",
+            "example": 0.98,
+        },
+    },
+    "required": [],
+}
+
 observation_schema = {
     "allOf": [{"$ref": "#/components/schemas/Message"}],
     "type": "object",
     "properties": {
-        "platform_serial": {
-            "description": "Serial of platform to sendign observations",
+        "platform_ID": {
+            "type": "integer",
+            "description": "ID of platform to sending observations",
             "example": "ecosub-3",
         },
         # "observation_type" ==> payloads tied to different types maybe?
         # properties of each observation?
         "points_of_interest": {
+            "type": "array",
+            "items": hits_schema,
             "description": "Points from features of interest identified by"
             + " platform if any found. DEFINE FORMAT.",
-            "example": "",
         },
         "region_surveyed": {
             "description": "Region surveyed by given platform. DEFINE FORMAT."
-            + " GEOJSON?",
+            + " GEOJSON",
             "example": "",
         },
-        "quality_of_points": {
-            "description": "Quality/strength of points from features of interest"
-            + " identified by platform. DEFINE FORMAT.",
-            "example": 0.98,
-        },
         "additional_data": {
             "description": "Placeholder field for any additional data",
             "example": {"sensor_payload": False},
 #         ),
 #         "quality_of_points": fields.Float(
 #             required=False,
-#             description="Quality/strength of points from features of interest"
-#             + " identified by platform. DEFINE FORMAT.",
+#             description="Quality/strength of points from features of"
+#             + " interest identified by platform. DEFINE FORMAT.",
 #             example=0.98,
 #         ),
 #         "additional_data": fields.Raw(

formats/planning_configuration.py

 # from . import api, full_message_schema, platform_schema
 # from flask_restx import fields
 
-
-constraints_schema = {
+emergency_schema = {
     "type": "object",
     "properties": {
-        "min_altitude": {
+        "safe_command": {
+            "type": "string",
+            "enum": ["go_home", "abort_now", "stop_mission"],
+            "description": "Command/Action that is native to respective partner's platform/C2",
+            "example": "go_home",
+        },
+        "latitude_waypoint": {
             "type": "number",
-            "description": "Minimum altitude set for squad.",
-            "example": 15.2,
+            "description": "X-coordinate of safe place for respective platform",
+            "example": -7.432,
         },
-        "min_velocity": {
+        "longitude_waypoint": {
             "type": "number",
-            "description": "Minimum velocity set for squad.",
-            "example": 0.1,
+            "description": "Y-coordinate of safe place for respective platform",
+            "example": 50.365,
         },
-        "max_velocity": {
+        "target_depth": {
             "type": "number",
-            "description": "Maximum altitude set for squad.",
-            "example": 0.9,
+            "description": "Z-coordinate of safe place for respective platform"
+            + " . If platform to NOT stay at depth, key in `0.0`",
+            "example": 10,
+        },
+        "additional_data": {
+            "type": "null",
+            "description": "Any addition fields/data to be added here",
+            "example": {},
         },
     },
-    "required": ["min_altitude", "min_velocity", "max_velocity"],
+    "required": ["latitude_waypoint", "longitude_waypoint", "target_depth"],
 }
 
+
 platform_schema = {
     "type": "object",
     "properties": {
             "type": "string",
             "example": "reav",
         },
-        "constraints": constraints_schema,
+        "emergency": emergency_schema,
+        "min_altitude": {
+            "type": "number",
+            "description": "Minimum altitude set for squad.",
+            "example": 15.2,
+        },
+        "min_velocity": {
+            "type": "number",
+            "description": "Minimum velocity set for squad.",
+            "example": 0.1,
+        },
+        "max_velocity": {
+            "type": "number",
+            "description": "Maximum altitude set for squad.",
+            "example": 0.9,
+        },
+        "additional_data": {
+            "type": "null",
+            "description": "Any addition fields/data to be added here",
+            "example": {"swath_width": 10.0, "scan_type": "DVL"},
+        },
     },
-    "required": ["platform_ID", "serial", "model", "constraints"],
+    "required": ["platform_ID", "serial", "model", "emergency", "min_altitude", "min_velocity", "max_velocity"],
 }
 
 region_schema = {
             "example": False,
         },
         "region_of_interest": region_schema,
-        "exclusion_zones": {
-            "type": "array",
-            "items": region_schema,
-            "description": "Exclusion zones per squad.",
-        },
     },
     "required": [
         "squad_ID",
     "allOf": [{"$ref": "#/components/schemas/Message"}],
     "type": "object",
     "properties": {
-        "config_ID": {
+        "planning_config_ID": {
             "type": "integer",
             "description": "Unique identifier tagged to version of this"
             + " configuration plan",
             "example": 3,
         },
+        "exclusion_zones": {
+            "type": "array",
+            "items": region_schema,
+            "description": "Exclusion zones for all platforms",
+        },
         "squads": {
             "type": "array",
             "items": squad_metadata_schema,
         },
     },
-    "required": ["config_ID", "squads"],
+    "required": [
+        "config_ID",
+        "squads",
+        "exclusion_zones",
+    ],
 }
 
 # region_schema = api.model(
 #     {
 #         "region": fields.Raw(
 #             required=True,
-#             description="Using GEOJSON, exact region of interest in rectangle"
-#             + " format polygon",
+#             description="Using GEOJSON, exact region of "
+#             + "interest in rectangle format polygon",
 #             example={
 #                 "type": "FeatureCollection",
 #                 "features": [

formats/platform_status.py

 """
     schema: platform-specific decoded status message
 """
-# from . import full_message_schema, api
-# from flask_restx import fields
-
-
-gps_schema = {
-    "type": "object",
-    "properties": {
-        "gps_source": {
-            "type": "string",
-            "description": "Source of gps position. E.g. USBL (external),"
-            + "platform itself (internal)",
-            "example": "internal",
-        },
-        "latitude_type": {
-            "type": "string",
-            "description": "TODO: Add description",
-        },
-        "longitude_type": {
-            "type": "string",
-            "description": "TODO: Add description",
-        },
-        "latitude": {
-            "type": "number",
-            "description": "Latitude in decimal degrees.",
-            "example": 178.2,
-        },
-        "longitude": {
-            "type": "number",
-            "description": "Longitude in decimal degrees.",
-            "example": -10.122,
-        },
-        "depth": {
-            "type": "number",
-            "description": "Target depth in metres",
-            "example": 50,
-            "default": 0,
-        },
-        "altitude": {
-            "type": "number",
-            "description": "Target altitude in metres",
-            "example": 20,
-        },
-    },
-    "required": [
-        "gps_source",
-        "latitude",
-        "longitude",
-    ],
-}
-
 sensor_schema = {
     "type": "object",
-    "description": "Scanning sensor on platform available to be controlled by  the Autonomy Engine",
+    "description": "Scanning sensor on platform available"
+    + " to be controlled by  the Autonomy Engine",
     "properties": {
         "sensor_serial": {
             "type": "string",
             "description": "serial number of sensor",
             "example": "mbes-002a",
         },
-        "sensor_status": {
+        "sensor_on": {
             "type": "boolean",
             "description": "Sensor switched on (True) or off (False)",
             "example": True,
             "description": "Identifier for platform",
             "example": 1,
         },
+        "status_source": {
+            "type": "string",
+            "enum": ["usbl", "onboard_platform"],
+            "description": "Indicate if this status message is from the"
+            + " platform or USBL",
+            "example": "usbl",
+        },
         "platform_timestamp": {
             "type": "date-time",
             "decription": "Timestamp for onboard platform status message",
             + "STOP, IDLE, ABORT.",
             "example": "ABORT",
         },
-        "autonomy_plan_ID": {
+        "autonomy_engine_plan_ID": {
             "type": "integer",
-            "description": "Last mission plan ID (according to Autonomy Engine's"
-            + " mission plan number) executed by platform",
+            "description": "Last mission plan ID (according to Autonomy"
+            + " Engine's mission plan number sent) executed by platform",
             "example": 1,
         },
+        "latitude": {
+            "type": "number",
+            "description": "Latitude in decimal degrees.",
+            "example": 178.2,
+        },
+        "longitude": {
+            "type": "number",
+            "description": "Longitude in decimal degrees.",
+            "example": -10.122,
+        },
+        "depth": {
+            "type": "number",
+            "description": "Target depth in metres",
+            "example": 50,
+            "default": 0,
+        },
+        "altitude": {
+            "type": "number",
+            "description": "Target altitude in metres",
+            "example": 20,
+        },
         "mission_track_ID": {
             "type": "integer",
             "description": "Track number - stage in mission (e.g. "
             + "if any diagnosis is available to check sensors",
             "example": "Warning",
         },
-        "gps_data": {
-            "type": "array",
-            "description": "position of platform",
-            "items": gps_schema,
-        },
         "localisation_error": {
             "type": "number",
             "description": "Localisation error at last USBL update.",
         },
         "battery_remaining_capacity": {
             "type": "number",
-            "description": "Battery remaining capacity % provided by respective",
+            "description": "Battery remaining % provided by respective C2",
             "example": 80.2,
         },
+        "current_pitch": {
+            "type": "number",
+            "description": "Current pitch of platform",
+            "example": -4.0,
+        },
         "sensor_config": sensor_schema,
     },
     "required": [
         "platform_ID",
+        "status_source",
         "platform_timestamp",
-        "gps_data",
-        "battery_remaining_capacity",
+        "latitude",
+        "longitude",
     ],
 }
 
 #         ),
 #         "autonomy_plan_ID": fields.Integer(
 #             required=False,
-#             description="Last mission plan ID (according to Autonomy Engine's"
+#             description="Last mission plan ID (
+#             + "according to Autonomy Engine's"
 #             + " mission plan number) executed by platform",
 #             example=1,
 #         ),

project/SOAR_README.md

 | NOC (AH1)             | emergency                | GUI                   | TBD – AH1 (ABORT command via Black Box)    | TBD                 | TBD                                        | TBD – all platforms pre-compiled ABORT via Black box                                     |
 | NOC (GUI)             | planning configuration   | GUI                   | Autonomy Engine                            | Yes                 | No                                         | N/A                                                                                      |
 | NOC (GUI)             | emergency                | GUI                   | TBD                                        | TBD                 | TBD                                        | TBD                                                                                      |
+
+## Run Docs
+1. Run the command below
+```
+python3 generate_swagger.py
+```
+2. Go to `http://127.0.0.1:5000/soardocs/`

README.md

 * `platform_status`: these would be two message types, i. encoded (platform-specific serialized message) and ii. parsed, human-readable message.
 * `observation`: this would be desired scientific data sent by the platform
 * `acknowledgement`: level of acknowledgment where an acknowledgement is sent when a message is i. received, ii. sent to the next destination (e.g. platform in the water).
+* `planning_configuration`: sent from the GUI to initialise the AI model (autonomy engine).
 
+# Run Docs
+1. Run the command below
+```
+python3 generate_swagger.py
+```
+2. Go to `http://127.0.0.1:5000`
 
 # Quick Links
 1. [Schema Fields Definitions](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/7-message-formats-initial/formats)

generate_swagger.py

 from formats.observation import observation_schema
 from formats.planning_configuration import planning_configuration_schema
 from formats.platform_status import platform_status_message_schema
+from formats.acknowledgement import acknowledgement_schema
 
 app = Flask(__name__)
 
     "headers": [],
     "openapi": "3.0.2",
     "swagger_ui": True,
-    "specs_route": "/soardocs/",
+    "specs_route": "/",
     "info": {
         "title": "Backbone Message Formats",
         "version": "0.1",
             "Observation": observation_schema,
             "PlanningConfiguration": planning_configuration_schema,
             "PlatformStatus": platform_status_message_schema,
+            "Acknowledgement": acknowledgement_schema,
         },
     },
     "paths": {
                                     "oneOf": [
                                         {
                                             "$ref": "#/components/"
-                                            + "schemas/Coordinate"
+                                            + "schemas/Acknowledgement"
                                         },
                                         {
                                             "$ref": "#/components/"
     "consumes": ["application/json"],
 }
 message_types = [
-    "Message",
+    # "Message",
     "Acknowledgement",
     "MissionPlan",
     "Observation",

[Trishna Saeharaseelan]

Note: Ignore all the files under examples/*. Main files are:

• README.md
• init.py
• autonomy_configuration.py
• platform_status.py

[izzat]

Another thing to consider is the sensor data for perception or scientific observation, and whether it should go under platform status or a separate status message/topic for on-board sensor payload. Another thing we discussed previously is if this could be made generic or if we should allow customised data/messages for some platforms.

For SoAR, this would be for the pings/targets/feature-of-interests detected by the AUVs.

[Trishna Saeharaseelan]

[Alvaro] Add message format version

[Trishna Saeharaseelan]

To add separate message schema for usbl_position_updates

latitude: <>
longitude: <>
depth: <>
timestamp: <>
comms_quality: <>
ref_platform_ID: <>

[Trishna Saeharaseelan]

@geosal to have a look for USBL positions update example.

[Trishna Saeharaseelan]

@geosal to have a look at observations example. Is anything missing?

[Trishna Saeharaseelan]

@geosal @danjon to check out initial sample based on our idea for emergency behaviour in the planning config

[Trishna Saeharaseelan]

Remove safe_command

[Trishna Saeharaseelan]

[DAN] Useful to add a heading value in the vehicle status updates

[James Kirk]

Should action also be required? I guess the sub can declare its position without that, but I'd think that might be an action in and of itself? declare_pos action or something?

[Trishna Saeharaseelan]

[TO DISCUSS] action is basically from the Autonomy engine's side (i.e. what is the "action" in autonomy engine lingo). Let's discuss?

[Trishna Saeharaseelan]

To be platform-agnostic; remove flightstyle field + make action mandatory

declare_pos > not needed

[James Kirk]

Few comments of little bits I think have been from copy + pasting Only other thing is there's a lot of TODOs, commented out stuff, and just things to come back to later. Are the comments needed in there? And are there issues or notes somewhere of what work is left to do amongst all the TODOs and that?

[Dan Jones]

Can we have a chat about the structure of the messages maybe after stand-up tomorrow? This (I think) is the opposite way round from the schema I've based the prototype on. In the prototype schema every message is an instance of Message and the anyOf defines which payload schema it contains. The idea is that the backbone only deals in messages and passes the message on to the protocol handler which cares about what a message contains.

The model here is there are a bunch of different top-level schemas which each contain the content of the "Message" schema. It may well be fine or even preferable but it doesn't match the thing I've currently got working so it's probably worth a conversation.

[Trishna Saeharaseelan]

[TO DISCUSS] Interesting. Let's discuss this (need to clarify). If we need to change it from this end instead of the core, we should make the changes sooner since the partners will be working with this schemas as a start

[Trishna Saeharaseelan]

• Trishna to follow the structure the adapter is using to read schemas
• Validate all examples

[Dan Jones]

Have you tried validating the examples against this schema? I had a go with npm swagger-model-validator which I've used for the javascript adapter in the prototype. So far I've only tried the ecosub platform status message but it's not successfully validating.

[Trishna Saeharaseelan]

So with openapi-spec-validator it was validated successfully. Let's chat. That being said, I will add a task to build some tests

[Dan Jones]

That's interesting. I'll see if there's a javascript equivalent and have a go at validating it with that.

[Dan Jones]

Oh wait a minute. openapi-spec-validator is validating that the swagger.json conforms to the open api standard. It's not parsing a messaging and validating that the message conforms to the schema definition. What I'm talking about is validating that the example platform_status.json messages validate against the PlatformStatus definition defined in the schema.

[Dan Jones]

I think the python version of what I'm talking about is here: https://github.com/p1c2u/openapi-schema-validator

[Dan Jones]

The swagger.json is also curiously different in structure to all out existing APIs. Normally the models are under definitions but here they're under components/schemas and definitions is there but empty.

[Dan Jones]

The other thing Ashley suggested was that rather than define our own schema for anything geographic we just point to the existing GeoJson feature schema: https://geojson.org/schema/Feature.json

We could explicitly require a Point or a BoundingBox or whatever or just point to the parent feature definition.

Point is not very specific - it just has a min of 2 coordinates so we could supply 3=z or even 4=depth+altitude if it were necessary.

[Dan Jones]

The advantage of using Feature would be that the operating area and exclusion zones could be a BoundingBox or they could be a Polygon or even a MultiPolygon. We might not want to allow that complexity for the MVP but it would be good to have it in future - especially given the ultimate goal of the funders.

[Trishna Saeharaseelan]

Actually geojson is being in the planning_configuration message for exclusion_zones and the optional region_of_interest. Would we want to generate a 4-point polygon for each point then?

[Dan Jones]

What I mean by using geojson is adding a ref to the published geojson schema.

"coordinates": {
  "$ref": "https://geojson.org/schema/Point.json"
},

What the planning configuration message is doing is creating a data structure that matches GeoJSON.

To do that we'd need a validator that supported resolving remote refs which it seems like the one I'm currently using doesn't.

[Dan Jones]

Would we want to generate a 4-point polygon for each point then

No - We use the GeoJSON feature that represents what we want to draw. So Point for a status update/area of interest, Polygon for an operating area / exclusion zone.

[Dan Jones]

This one does it: https://www.npmjs.com/package/json-schema-remote

[Trishna Saeharaseelan]

@allore what's the best terminology to distinguish between the type of status message (i.e. from USBL or from the platform itself) vs. source/rx mode of the message (i.e. from acoustics, iridium, or wifi)?

[Alvaro Lorenzo]

Tricky. Maybe we want a field called something like platform_source: {USBL, Slocum, Ecosub, ALR ...} and other called transmission_mean : {Wifi, acoustics, iridium, starlink ... }

[Trishna Saeharaseelan]

To add warm-up time field in the planning config (e.g. for ecosub warm-up of sidescan payload)

[Dan Jones]

Needs the validator packages adding in here or in a requirements-dev.txt

[Trishna Saeharaseelan]

DONE

[Dan Jones]

Why aren't you validating the whole mock_data as a whole against the MESSAGE schema?

Should the tests be pytest/unittest or something so we can tell if they pass/fail in the CI later?

[Trishna Saeharaseelan]

1. Didn't just validate the FULL mock messages against message_schema because it kept passing even when it should have errors. Decided to break it down in the meantime to ensure it gets validated & does prompt errors (as it should). Added TODO in epic issue card to clean this up for better validation

2. DONE