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()))

formats/mission_plan.py

             "items": action_schema,
         },
     },
-    "required": ["message_type", "plan_ID", "platform_ID", "plan"],
+    "required": ["message_type", "autonomy_engine_plan_ID", "platform_ID", "plan"],
 }

formats/planning_configuration.py

             "example": 10,
         },
         "additional_data": {
-            "type": "null",
             "description": "Any addition fields/data to be added here",
             "example": {},
         },
             "description": "Maximum altitude set for squad.",
             "example": 0.9,
         },
-        "additional_data": {
-            "type": "null",
+        "additional_specs": {
             "description": "Any addition fields/data to be added here",
             "example": {"swath_width": 10.0, "scan_type": "DVL"},
         },
         "platforms",
         "squad_mission_type",
         "squad_state",
-        "exclusion_zones",
     ],
 }
 
     },
     "required": [
         "message_type",
-        "config_ID",
+        "planning_config_ID",
         "squads",
         "exclusion_zones",
     ],

formats/platform_status.py

             "example": True,
         },
         "additional_data": {
-            "type": "null",
             "description": "Any addition fields/data to be added here",
             "example": {"payload": [1.2, 434]},
         },
     },
-    "required": [],
 }
 
 platform_status_message_schema = {
             "type": "string",
             "enum": ["acoustics", "iridium", "wifi", "starlink"],
             "description": "Mode in which status message was transmitted"
-            + " when on the surface (i.e. iridium/wifi) or underwater"
-            + " (i.e. acoustics)",
+            + " when on the surface (e.g. iridium/wifi) or underwater"
+            + " (e.g. acoustics)",
             "example": "wifi",
         },
         "platform_timestamp": {
             "type": "string",
             "format": "date-time",
-            "decription": "Timestamp for onboard platform status message",
+            "description": "Timestamp for onboard platform status message",
             "example": "2022-12-21T00:00:00Z",
         },
-        "active": {
-            "type": "boolean",
-            "description": "When a platform is in deployment (executing a"
-            + " mission plan) this should be True",
-            "example": True,
-        },
         "platform_state": {
-            # TODO: Define enum with potential STATES of each platform
-            "type": "string",
+            "type": "string", # TODO: Define enum with potential STATES of each platform
             "description": "Current state executed by platform. E.g. "
             + "STOP, IDLE, ABORT.",
             "example": "ABORT",

generate_schema_config.py

                 "discriminator": {
                     "propertyName": "message_type",
                     "mapping":{
-                        "MissionPlan": "#/components/schemas/mission_plan",
-                        "Observation": "#/components/schemas/observation",
-                        "PlanningConfiguration": "#/components/schemas/planning_configuration",
-                        "PlatformStatus": "#/components/schemas/platform_status",
-                        "Acknowledgement": "#/components/schemas/acknowledgement",
+                        "mission_plan": "#/components/schemas/mission_plan",
+                        "observation": "#/components/schemas/observation",
+                        "planning_configuration": "#/components/schemas/planning_configuration",
+                        "platform_status": "#/components/schemas/platform_status",
+                        "acknowledgement": "#/components/schemas/acknowledgement",
                     },
                 },
                 "oneOf":[

[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