Create initial message schemas

Closes #7 (closed)

docs/__init__.py

+from . import api
+import os
+
+
+__all__ = [
+    os.path.splitext(os.path.basename(x))[0]
+    for x in os.listdir(os.path.dirname(__file__))
+    if x.endswith(".py") and x != "__init__.py"
+]

docs/generate_swagger.py

+"""
+Generate swagger to view models/schemas.
+Command:
+1/ python3 generate_swagger.py
+2/ Go to http://127.0.0.1:5000/soardocs
+WARNING: API Endpoints are NOT functional. Purely for easy-reading.
+"""
+from flask import Flask, request
+from flasgger import Swagger, LazyString
+from flask_restx import Api, fields, Resource
+
+app = Flask(__name__)
+
+api = Api(app)
+swagger_template = dict(
+    info={
+        "title": LazyString(lambda: "SoAR Backbone Message Formats"),
+        "version": LazyString(lambda: "0.1"),
+        "description": LazyString(
+            lambda: "Backbone Message Format component for the Squad of Autonomous Robots (SoAR) message definitions."
+        ),
+    },
+    host=LazyString(lambda: request.host),
+)
+message_header_schema = api.model(
+    "MessageHeader",
+    {
+        "timestamp": fields.DateTime(
+            required=True,
+            description="Timestamp of message",
+            example="2022-11-16T00:00:00Z",
+        ),
+        "source": fields.String(
+            required=True,
+            description="Where is this message from",
+            example="autonomy_engine",
+        ),
+        "destination": fields.String(
+            required=True,
+            description="What is the destination of this message",
+            example="ah-1",
+        ),
+        "encoded": fields.Boolean(
+            required=True,
+            description="Indicate that message raw (encoded) or decoded. "
+            + "Options: encoded=True, decoded=False",
+            example=False,
+        ),
+        "type": fields.String(
+            required=True,
+            description="Type of message",
+            example="platform_status",
+        ),
+        # "payload":# TODO: schema applicable changes according to "type"
+    },
+)
+
+platform_schema = api.model(
+    "Platform",
+    {
+        "platform_ID": fields.Integer(
+            required=True,
+            description="unique identifier for platform",
+            example="ah-1",
+        ),
+        "serial": fields.Integer(
+            required=True,
+            description="platform serial number",
+            example="ah-1",
+        ),
+        "model": fields.Integer(
+            required=True,
+            description="platform serial number",
+            example="ah-1",
+        ),
+        "active": fields.Boolean(
+            required=False,
+            description="platform in mission",
+            example=True,
+        ),
+    },
+)
+
+squad_metadata_schema = api.model(
+    "SquadMetadata",
+    {
+        "squad_ID": fields.Integer(
+            required=True,
+            description="platform serial number",
+            example="ah-1",
+        ),
+        "no_of_platforms": fields.Integer(
+            required=True,
+            description="number of platform serial number",
+            example="ah-1",
+        ),
+        "platforms": fields.List(
+            fields.Nested(platform_schema),
+            required=True,
+            description="Metadata pf each platform",
+        ),
+        "squad_mission_type": fields.String(
+            required=True,
+            description="Survey or Detail",
+            example="survey",
+        ),
+        "squad_state": fields.Boolean(
+            required=True,
+            description="True if given Squad is executing mission type "
+            + "according to the Autonomy Engine plan",
+            example=False,
+        ),
+    },
+)
+
+constraints_schema = api.model(
+    "Constraints",
+    # TODO: Should this be per platform instead of squad?
+    {
+        "min_altitude": fields.Float(
+            required=True,
+            description="Minimum altitude set for squad.",
+            example=15.2,
+        ),
+        "min_velocity": fields.Float(
+            required=True,
+            description="Minimum velocity set for squad.",
+            example=0.1,
+        ),
+        "max_velocity": fields.Float(
+            required=True,
+            description="Maximum altitude set for squad.",
+            example=0.9,
+        ),
+    },
+)
+
+environment_config_schema = api.model(  # TODO: Discuss how regions are defined
+    "EnvironmentConfig",
+    {
+        "region_of_interest": fields.String(),
+        "exclusion_zone": fields.String(),
+    },
+)
+# Main Autonomy Configuration Schema
+autonomy_configuration_schema = api.model(
+    "Configuration",
+    {
+        "message": fields.Nested(
+            message_header_schema,
+            required=True,
+            description="Message header",
+        ),
+        "ID": fields.Integer(
+            required=True,
+            description="Unique identifier tagged to version of this"
+            + " configuration plan",
+            example=3,
+        ),
+        "time": fields.String(
+            required=True,
+            description="",
+            example="",
+        ),
+        "squads": fields.Nested(
+            squad_metadata_schema,
+            required=False,
+            description="Details of each squad",
+        ),
+        "environment": fields.Nested(
+            environment_config_schema,
+            required=False,
+            description="Region of interest and exclusion zone",
+        ),
+    },
+)
+
+gps_schema = api.model(
+    "GPS",
+    {
+        "gps_source": fields.Float(  # TODO: TBD with partners
+            required=False,
+            description="Source of gps position. E.g. Beacon",
+            example="internal",
+        ),
+        "latitude_type": fields.String(
+            required=False,
+            description="",
+            example="",
+        ),
+        "longitude_type": fields.String(
+            required=False,
+            description="",
+            example="",
+        ),
+        "latitude": fields.Float(
+            required=False,
+            description="Latitude in <insert units>",
+            example="",
+        ),
+        "longitude": fields.Float(
+            required=False,
+            description="Longitude in <insert units>",
+            example="",
+        ),
+        "depth": fields.Float(
+            required=False,
+            description="",
+            example="",
+        ),
+        "gps_fix_seconds_ago": fields.Float(
+            required=False,
+            description="",
+            example="",
+        ),
+    },
+)
+observation_schema = api.model(
+    "Observation",
+    {
+        "message": fields.Nested(
+            message_header_schema,
+            required=True,
+            description="Message header",
+        ),
+        "platform": fields.Nested(platform_schema),
+        "time": fields.String(
+            required=True,
+            description="Timestamp of message",
+            example="2022-11-16T00:00:00Z",
+        ),
+        "discuss_other_fields": fields.String(
+            required=False,
+            description="",  # we can track the version of the AE plan?
+            example="",
+        ),
+    }
+)
+platform_status_message_schema = api.model(
+    "PlatformStatusMessage",
+    {
+        "message": fields.Nested(
+            message_header_schema,
+            required=True,
+            description="Message header",
+        ),
+        "platform": fields.Nested(platform_schema),
+        "time": fields.String(
+            required=True,
+            description="Timestamp of message",
+            example="2022-11-16T00:00:00Z",
+        ),
+        "version": fields.Integer(
+            required=False,
+            description="",  # we can track the version of the AE plan?
+            example="",
+        ),
+        "platform_state": fields.String(
+            # TODO: Define dictionary with potential STATES of each platform
+            required=True,
+            description="Current state executed by platform. E.g. "
+            + "STOP, IDLE, ABORT.",
+            example="IDLE",
+        ),
+        "mission_track_number": fields.Integer(
+            required=False,
+            description=(
+                "Track number - stage in mission (e.g. "
+                + "4 --> Waypoint 3 to Waypoint 4)"
+            ),
+            example=4,
+        ),
+        "range_to_go": fields.Float(
+            required=False,
+            description="Estimated distance to reach next waypoint",
+            example=124.3,
+        ),
+        "c2_health_status": fields.String(
+            required=False,
+            description="Health status extracted by respective platform's C2 "
+            + "if any diagnosis available checks on sensors",
+            example="Warning",
+        ),
+        "gps_data": fields.Nested(gps_schema),
+        "battery_voltage": fields.Float(
+            required=True,
+            description="Volts",
+            example=23.0,
+        ),
+        "battery_current": fields.Float(
+            required=False,
+            description="Amps",
+            example=1.2,
+        ),
+        "battery_current_per_hour": fields.Float(
+            required=False,
+            description="Amp-Hours",
+            example=1.2,
+        ),
+        "battery_wattage": fields.Float(
+            required=False,
+            description="Watts",
+            example=23.0,
+        ),
+        "battery_wattage_per_hour": fields.Float(
+            required=False,
+            description="Watt-Hours",
+            example=23.0,
+        ),
+    },
+)
+
+swagger_config = {
+    "headers": [],
+    "specs": [
+        {
+            "endpoint": "swagger",
+            "route": "/swagger.json",
+            "rule_filter": lambda rule: True,
+            "model_filter": lambda tag: True,
+        }
+    ],
+    "static_url_path": "/flasgger_static",
+    "swagger_ui": True,
+    "specs_route": "/soardocs/",
+    "swagger": "2.0",
+    "basePath": "/soar",
+    "info": {
+        "title": "soar",
+        "version": "0.1",
+        "description": "SoAR message schemas",
+    },
+    "produces": ["application/json"],
+    "consumes": ["application/json"],
+}
+
+swagger = Swagger(app, template=swagger_template, config=swagger_config)
+
+ns1 = api.namespace("message", description="Message Header Format")
+@ns1.route("/header")
+class MessageHeader(Resource):
+    @ns1.response(200, "Success", message_header_schema)
+    def get(self):
+        pass
+
+
+ns2 = api.namespace("platform_status", description="Platform Status Message Format")
+@ns2.route("")
+class PlatformStatus(Resource):
+    @ns2.response(200, "Success", platform_status_message_schema)
+    def get(self):
+        pass
+
+
+ns3 = api.namespace(
+    "autonomy_configuration", description="Autonomy Configuration Format"
+)
+
+@ns3.route("")
+class AutonomyConfiguration(Resource):
+    @ns3.response(200, "Success", autonomy_configuration_schema)
+    def get(self):
+        pass
+
+
+# @api.route('/mission-plan/<str:platform_type')
+# @api.doc(params={"platform_type": "The type of platform of the mission plan to target."})
+ns4 = api.namespace("mission_plan", description="Mission Plan Format Per Platform")
+
+@ns4.route("/ecosub")
+class MissionPlanEcosub(Resource):
+    @ns4.response(200, "Success", {})
+    def get(self):
+        pass
+@ns4.route("/reav")
+class MissionPlanReav(Resource):
+    @ns4.response(200, "Success", {})
+    def get(self):
+        pass
+@ns4.route("/autosubhover")
+class MissionPlanAutosubHover(Resource):
+    @ns4.response(200, "Success", {})
+    def get(self):
+        pass
+
+ns5 = api.namespace("observation", description="Observation Format --> Per Platform or generic?")
+@ns5.route("")
+class Observation(Resource):
+    @ns5.response(200, "Success", observation_schema)
+    def get(self):
+        pass
+
+if __name__ == "__main__":
+    app.run()

formats/__init__.py

+from flask_restx import fields
+from . import api
+import os
+
+
+__all__ = [
+    os.path.splitext(os.path.basename(x))[0]
+    for x in os.listdir(os.path.dirname(__file__))
+    if x.endswith(".py") and x != "__init__.py"
+]
+
+message_types = [
+    "platform_status",
+    "mission_plan_ecosub",
+    "mission_plan_reav",
+    "mission_plan_autosub",
+]  # TODO: Add full range of message types once scoped out
+
+message_header_schema = api.model(
+    "MessageHeader",
+    {
+        "timestamp": fields.DateTime(
+            required=True,
+            description="Timestamp of message",
+            example="2022-11-16T00:00:00Z",
+        ),
+        "source": fields.String(
+            required=True,
+            description="Where is this message from",
+            example="autonomy_engine",
+        ),
+        "destination": fields.String(
+            required=True,
+            description="What is the destination of this message",
+            example="ah-1",
+        ),
+        "encoded": fields.Boolean(
+            required=True,
+            description="Indicate that message raw (encoded) or decoded. "
+            + "Options: encoded=True, decoded=False",
+            example=False,
+        ),
+        "type": fields.String(
+            required=True,
+            description="Type of message",
+            example="platform_status",
+        ),
+        # "payload":# TODO: schema applicable changes according to "type"
+    },
+)
+
+platform_schema = api.model(
+    "PlatformSchema",
+    {
+        "platform_ID": fields.Integer(
+            required=True,
+            description="unique identifier for platform",
+            example="ah-1",
+        ),
+        "serial": fields.Integer(
+            required=True,
+            description="platform serial number",
+            example="ah-1",
+        ),
+        "model": fields.Integer(
+            required=True,
+            description="platform serial number",
+            example="ah-1",
+        ),
+        "active": fields.Boolean(
+            required=False,
+            description="platform in mission",
+            example=True,
+        ),
+    },
+)
+# TODO: Add generic positions schema
+# TODO: Define units for all schemas

formats/autonomy_configuration.py

+"""
+    schemas: configuration sent to Autonomy Engine (i.e. during an emergency,
+    if a platform needs to be removed from the mission planning)
+"""
+from . import api, message_header_schema, platform_schema
+from flask_restx import fields
+
+
+squad_metadata_schema = api.model(
+    "SquadMetadataSchema",
+    {
+        "squad_ID": fields.Integer(
+            required=True,
+            description="platform serial number",
+            example="ah-1",
+        ),
+        "no_of_platforms": fields.Integer(
+            required=True,
+            description="number of platform serial number",
+            example="ah-1",
+        ),
+        "platforms": fields.List(
+            fields.Nested(platform_schema),
+            required=True,
+            description="Metadata pf each platform",
+        ),
+        "squad_mission_type": fields.String(
+            required=True,
+            description="Survey or Detail",
+            example="survey",
+        ),
+        "squad_state": fields.Boolean(
+            required=True,
+            description="True if given Squad is executing mission type "
+            + "according to the Autonomy Engine plan",
+            example=False,
+        ),
+    },
+)
+
+constraints_schema = api.model(
+    "ConstraintsSchema",
+    # TODO: Should this be per platform instead of squad?
+    {
+        "min_altitude": fields.Float(
+            required=True,
+            description="Minimum altitude set for squad.",
+            example=15.2,
+        ),
+        "min_velocity": fields.Float(
+            required=True,
+            description="Minimum velocity set for squad.",
+            example=0.1,
+        ),
+        "max_velocity": fields.Float(
+            required=True,
+            description="Maximum altitude set for squad.",
+            example=0.9,
+        ),
+    },
+)
+
+environment_config_schema = api.model(  # TODO: Discuss how regions are defined
+    "EnvironmentConfig",
+    {
+        "region_of_interest": fields.String(),
+        "exclusion_zone": fields.String(),
+    },
+)
+# Main Autonomy Configuration Schema
+autonomy_configuration_schema = api.model(
+    "SquadConfigurationSchema",
+    {
+        "message": fields.Nested(
+            message_header_schema,
+            required=True,
+            description="Message header",
+        ),
+        "ID": fields.Integer(
+            required=True,
+            description="Unique identifier tagged to version of this"
+            + " configuration plan",
+            example=3,
+        ),
+        "time": fields.String(
+            required=True,
+            description="",
+            example="",
+        ),
+        "squads": fields.Nested(
+            squad_metadata_schema,
+            required=False,
+            description="Details of each squad",
+        ),
+        "environment": fields.Nested(
+            environment_config_schema,
+            required=False,
+            description="Region of interest and exclusion zone",
+        ),
+    },
+)

formats/observation.py

+"""
+    schema: platform-specific decoded status message (DRAFT)
+"""
+from . import message_header_schema, platform_schema, api
+from flask_restx import fields
+
+
+observation_schema = api.model(
+    "Observation",
+    {
+        "message": fields.Nested(
+            message_header_schema,
+            required=True,
+            description="Message header",
+        ),
+        "platform": fields.Nested(platform_schema),
+        "time": fields.String(
+            required=True,
+            description="Timestamp of message",
+            example="2022-11-16T00:00:00Z",
+        ),
+        "discuss_other_fields": fields.String(
+            required=False,
+            description="",  # we can track the version of the AE plan?
+            example="",
+        ),
+    }
+)
\ No newline at end of file

formats/platform_status.py

+"""
+    schema: platform-specific decoded status message (DRAFT)
+"""
+from . import message_header_schema, platform_schema, api
+from flask_restx import fields
+
+# TODO: Discuss nomenclature > platform or vehicle?
+
+gps_schema = api.model(
+    "GPS",
+    {
+        "gps_source": fields.Float(  # TODO: TBD with partners
+            required=False,
+            description="Source of gps position. E.g. Beacon",
+            example="internal",
+        ),
+        "latitude_type": fields.String(
+            required=False,
+            description="",
+            example="",
+        ),
+        "longitude_type": fields.String(
+            required=False,
+            description="",
+            example="",
+        ),
+        "latitude": fields.Float(
+            required=False,
+            description="Latitude in <insert units>",
+            example="",
+        ),
+        "longitude": fields.Float(
+            required=False,
+            description="Longitude in <insert units>",
+            example="",
+        ),
+        "depth": fields.Float(
+            required=False,
+            description="",
+            example="",
+        ),
+        "gps_fix_seconds_ago": fields.Float(
+            required=False,
+            description="",
+            example="",
+        ),
+    },
+)
+
+platform_status_message_schema = api.model(
+    "PlatformStatusMessage",
+    {
+        "message": fields.Nested(
+            message_header_schema,
+            required=True,
+            description="Message header",
+        ),
+        "platform": fields.Nested(platform_schema),
+        "time": fields.String(
+            required=True,
+            description="Timestamp of message",
+            example="2022-11-16T00:00:00Z",
+        ),
+        "version": fields.Integer(
+            required=False,
+            description="",  # we can track the version of the AE plan?
+            example="",
+        ),
+        "platform_state": fields.String(
+            # TODO: Define dictionary with potential STATES of each platform
+            required=True,
+            description="Current state executed by platform. E.g. "
+            + "STOP, IDLE, ABORT.",
+            example="IDLE",
+        ),
+        "mission_track_number": fields.Integer(
+            required=False,
+            description=(
+                "Track number - stage in mission (e.g. "
+                + "4 --> Waypoint 3 to Waypoint 4)"
+            ),
+            example=4,
+        ),
+        "range_to_go": fields.Float(
+            required=False,
+            description="Estimated distance to reach next waypoint",
+            example=124.3,
+        ),
+        "c2_health_status": fields.String(
+            required=False,
+            description="Health status extracted by respective platform's C2 "
+            + "if any diagnosis available checks on sensors",
+            example="Warning",
+        ),
+        "gps_data": fields.Nested(gps_schema),
+        "battery_voltage": fields.Float(
+            required=True,
+            description="Volts",
+            example=23.0,
+        ),
+        "battery_current": fields.Float(
+            required=False,
+            description="Amps",
+            example=1.2,
+        ),
+        "battery_current_per_hour": fields.Float(
+            required=False,
+            description="Amp-Hours",
+            example=1.2,
+        ),
+        "battery_wattage": fields.Float(
+            required=False,
+            description="Watts",
+            example=23.0,
+        ),
+        "battery_wattage_per_hour": fields.Float(
+            required=False,
+            description="Watt-Hours",
+            example=23.0,
+        ),
+    },
+)
+
+# TBD: Do we append beacon positions with platform positions?

README.md

 # Message Formats (DRAFT)
 Consists of all messages transferred into and out of the Communications Backbone. Message type schemas will be developed once reviewing each platform's data and statuses defined by each partner.
 
-## Types of Messages by Software Component
+## Message Types
+
+| Type                       | Summary of File                                                                                  | Human-Readable  |
+|--------------------------- | ------------------------------------------------------------------------------------------------ | ----------------|
+| `autonomy_configuration`   |  Autonomy Engine's Configuration file (sent by each C2 if there are any changes)                 | Yes             |
+| `autonomy_mission_plan`    |  Mission plan generated by Autonomy Engine per platform                                          | Yes             |
+| `mission_plan`             |  Encoded/serialized platform-specific mission plan  **(shared filepath)**                        | No              |
+| `platform_status`          |  Encoded/serialized platform-specific platform status **(shared filepath)**                      | No              |
+| `platform_status`          |  Decoded/de-serialized generic platform status                                                   | Yes             |
+| `observation`              |  Encoded/serialized observation data from platform for Autonomy Engine **(shared filepath)**     | No              |
+| `observation`              |  Decoded/de-serialized observation data from platform for Autonomy Engine                        | Yes             |
+
+
+## Breakdown of Message Sources & Types
 ### 1/ Autonomy Engine
 #### Transmit
 * mission plan _(sent per platform)_
 * decoded ecosub status message
 * decoded reav status message
 * decoded autosub-hover status message
-* decoded ecosub survey data _(from squad 1 platforms)_
+* decoded ecosub observation data _(from squad 1 platforms)_
 
 ----------------------------------
 
 * compiled ecosub mission plan
 * decoded ecosub status message
 * configuration file
-* decoded ecosub survey data
+* decoded ecosub observation data
 
 
 #### Receive
 * mission plan
 * encoded ecosub status message
-* encoded ecosub survey data
+* encoded ecosub observation data
 
 ----------------------------------
 
 * encoded ecosub status message
 * encoded (or is this already decoded?) reav status message
 * encoded autosub status message
-* encoded ecosub survey data
+* encoded ecosub observation data
 * TBD: 
     * are there acknowledgment messages from platforms?
     * how are we receiving beacon messages per platform?