Skip to content

GitLab

Merged
Created by Trishna Saeharaseelan@trishnaOwner

Create initial message schemas

11 unresolved threads
Compare
and
20 files
+ 1229
- 1251
Show latest version
do‎cs‎
__ini‎t__.py‎ +0 -8
generate_‎swagger.py‎ +0 -631
exam‎ples‎
a‎ll‎
acknowledg‎ement.json‎ +8 -9
mission_‎plan.json‎ +19 -20
observat‎ion.json‎ +1 -1
platform_s‎tatus.json‎ +35 -35
hydrosur‎v_adapter‎
acknowledg‎ement.json‎ +8 -9
mission_‎plan.json‎ +19 -20
platform_s‎tatus.json‎ +35 -35
for‎mats‎
__ini‎t__.py‎ +95 -95
acknowled‎gement.py‎ +39 -22
message_w‎rapper.py‎ +58 -0
mission‎_plan.py‎ +140 -72
observa‎tion.py‎ +70 -38
planning_con‎figuration.py‎ +218 -90
platform_‎status.py‎ +333 -164
pro‎ject‎
SOAR_RE‎ADME.md‎ +7 -0
READ‎ME.md‎ +8 -1
__ini‎t__.py‎ +0 -1
generate_‎swagger.py‎ +136 -0
docs/__init__.py deleted
+ 0
- 8
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 deleted
+ 0
- 631
"""
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),
)
full_message_schema = api.model(
"FullMessageSchema",
{
"message_ID": fields.String(
required=True,
description="UUID assigned to this message",
example="b427003c-7bc8-11ed-a1eb-0242ac120002",
),
"timestamp": fields.DateTime(
required=True,
description="Timestamp of message",
example="2022-11-16T00:00:00Z",
),
"version": fields.Float(
required=True,
description="Version of comms bacbone messaging format protocol",
example=2.0,
),
"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": fields.Raw(
required=True,
description="Content of Message",
# example="{}",
),
},
)
sensor_schema = api.model(
"SensorSchema",
{
"sensor_ID": fields.Integer(
required=True,
description="unique identifier for platform",
example=2,
),
"serial": fields.String(
required=False,
description="serial number of sensor",
example="mbes-001",
),
"sensor_status": fields.Boolean(
required=False,
description="Sensor switched on (True) or off (False)",
example=True,
),
"additional_data": fields.Raw(
required=False,
description="Any addition fields/data to be added here",
),
},
)
constraints_schema = api.model(
"ConstraintsSchema",
{
"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,
),
},
)
platform_schema = api.model(
"PlatformSchema",
{
"platform_ID": fields.Integer(
required=True,
description="unique identifier for platform",
example=1,
),
"serial": fields.String(
required=True,
description="platform serial number",
example="reav-60",
),
"model": fields.String(
required=True,
description="platform serial number",
example="reav",
),
"constraints": fields.Nested(constraints_schema),
},
)
action_schema = api.model(
"AutonomyEngineAction",
{
"action": fields.String(
required=True,
description="Autonomy Engine's action from `move`, `payload`,"
+ " `dive`, `send_hits`, `scanline`, `scanpoint`.",
example="move",
),
"flight_style": fields.String(
required=False,
description="Platform-specific modes/flight styles to perform"
+ " next action",
example="orbit",
),
"latitude_waypoint": fields.Float(
required=True,
description="Next waypoint, x-coordinate",
example=-4.187143188645706,
),
"longitude_waypoint": fields.Float(
required=True,
description="Next waypoint, y-coordinate",
example=50.37072283932642,
),
"altitude": fields.Float(
required=False,
description="Altitude of next action",
example=15.0,
),
"depth": fields.Float(
required=False,
description="Depth of next action",
example=15.0,
),
"activate_payload": fields.Boolean(
required=False,
description="To activate/deactivate sensor for Autosub "
+ "Hover-1 --> `MBES` sensor and for EcoSUB --> `Sidescan`",
example=True,
),
"send_environmental_data": fields.Boolean(
required=False,
description="DO WE NEED THIS? To trigger the platform to send"
+ " list of observations if any found",
example=False,
),
},
)
mission_plan_schema = api.model(
"MissionPlan",
{
"message": fields.Nested(
full_message_schema,
required=True,
description="Message header",
),
"plan_ID": fields.Integer(
required=True,
description="Identifier of given mission sequence planned",
example=1,
),
"platform_serial": fields.String(
required=True,
description="Serial of target platform to send mission to",
example="reav-60",
),
"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.",
),
},
)
observation_schema = api.model(
"Observation",
{
"message": fields.Nested(
full_message_schema,
required=True,
description="Message header",
),
"platform_serial": fields.String(
required=True,
description="Serial of platform to sendign observations",
example="ecosub-3",
),
# "observation_type" ==> payloads tied to different types maybe?
# properties of each observation?
"points_of_interest": fields.Float(
required=False,
description="Points from features of interest identified by"
+ " platform if any found. DEFINE FORMAT.",
example="",
),
"region_surveyed": fields.Float(
required=False,
description="Region surveyed by given platform. DEFINE FORMAT."
+ " GEOJSON?",
example="",
),
"quality_of_points": fields.Float(
required=False,
description="Quality/strength of points from features of interest"
+ " identified by platform. DEFINE FORMAT.",
example=0.98,
),
"additional_data": fields.Raw(
required=False,
description="Placeholder field for any additional data",
example={"sensor_payload": False},
),
},
)
region_schema = api.model(
"RegionSchema",
{
"region": fields.Raw(
required=True,
description="Using GEOJSON, exact region of interest in rectangle"
+ " format polygon",
example={
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {},
"geometry": {
"coordinates": [
[
[-4.187143188645706, 50.37072283932642],
[-4.202697005964865, 50.368816892405874],
[-4.203156724702808, 50.365640144076906],
[-4.19449868846155, 50.362267670845654],
]
],
"type": "Polygon",
},
}
],
},
),
},
)
squad_metadata_schema = api.model(
"SquadMetadataSchema",
{
"squad_ID": fields.Integer(
required=True,
description="Identifier of given squad",
example=23,
),
"no_of_platforms": fields.Integer(
required=True,
description="Number of platforms",
example=3,
),
"platforms": fields.List(
fields.Nested(platform_schema),
required=True,
description="Squad consists of these platforms",
),
"squad_mission_type": fields.String(
required=True,
description="Mission of given squad: `tracking`, `survey`,"
+ " `inspection`",
example="survey",
),
"squad_state": fields.Boolean(
required=True,
description="In execution, Waiting.. <define further>",
example=False,
),
"region_of_interest": fields.List(
fields.Nested(region_schema),
required=False,
description="Region of interest and exclusion zones per squad.",
),
"exclusion_zones": fields.List(
fields.Nested(region_schema),
required=True,
description="Exclusion zones exclusion zones per squad.",
),
},
)
planning_configuration_schema = api.model(
"PlanningConfigurationSchema",
{
"message": fields.Nested(
full_message_schema,
required=True,
description="Message header",
),
"ID": fields.Integer(
required=True,
description="Unique identifier tagged to version of this"
+ " configuration plan",
example=3,
),
"squads": fields.Nested(
squad_metadata_schema,
required=False,
description="Details of each squad",
),
},
)
gps_schema = api.model(
"GPS",
{
"gps_source": fields.Float( # TODO: TBD with partners
required=False,
description="Source of gps position. E.g. USBL (external), "
+ "platform itself (internal)",
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 <DEFINE UNITS>",
example="",
),
"longitude": fields.Float(
required=False,
description="Longitude in <DEFINE UNITS>",
example="",
),
"depth": fields.Float(
required=False,
description="Depth in <DEFINE UNITS>",
example="",
),
"altitude": fields.Float(
required=False,
description="Altitude in <DEFINE UNITS>",
example="",
),
# "gps_fix_seconds_ago"
},
)
platform_status_message_schema = api.model(
"platformStatusMessage",
{
"message": fields.Nested(
full_message_schema,
required=True,
description="Message header",
),
"platform_ID": fields.Integer(
required=True,
description="unique identifier for platform",
example=1,
),
"active": fields.Boolean(
required=False,
description="When a platform is in deployment (executing a mission"
+ " plan) this should be True",
example=True,
),
"platform_state": fields.String(
# TODO: Define dictionary with potential STATES of each platform
required=False,
description="Current state executed by platform. E.g. "
+ "STOP, IDLE, ABORT.",
example="IDLE",
),
"autonomy_plan_ID": fields.Integer(
required=False,
description="Last mission plan ID (according to Autonomy Engine's "
+ "mission plan number) executed by platform",
example=1,
),
"mission_track_ID": fields.Integer(
required=False,
description=(
"Track number - stage in mission (e.g. "
+ "4 --> Waypoint 3 to Waypoint 4)"
),
example=4,
),
"mission_action_ID": fields.Integer(
required=False,
description="to add description",
example=1,
),
"range_to_go": fields.Float(
required=False,
description="Estimated distance to reach next waypoint",
example=124.3,
),
"speed_over_ground": fields.Float(
required=False,
description="",
example=124.3,
),
"water_current_velocity": fields.Float(
required=False,
description="",
example=124.3,
),
"thrust_applied": fields.Float(
required=False,
description="TODO: Needs further consideration",
example=124.3,
),
"health_status": fields.String(
required=False,
description="Health status extracted by respective platform "
+ "if any diagnosis available checks on sensors",
example="Warning",
),
"gps_data": fields.List(
fields.Nested(gps_schema), # TODO: TBD Do we want a list of gps
# readings to allow > 1 reading i.e. platform + usbl
required=True,
description="Metadata pf each platform",
),
"localisation_error": fields.Float(
required=False,
description="Localisation error at last USBL update.",
example="",
),
"usbl_fix_seconds_ago": fields.Float(
required=False,
description="",
example="",
),
"battery_remaining_capacity": fields.Float(
required=True,
description="Battery remaining capacity % provided by respective"
+ " platform/C2.",
example=80.0,
),
"sensor_config": fields.Nested(
sensor_schema
), # TODO: TBD Do we want a list of sensors to allow > 1 sensor
},
)
acknowledgement_schema = api.model(
"Acknowledgement",
{
"message": fields.Nested(
full_message_schema,
required=True,
description="Message header",
),
"message_ID": fields.Integer(
required=True,
description="Identifier of message received and executed with "
+ "success for mission plans sent by the Autonomy Engine.",
example=202,
),
"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",
),
},
)
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 Wrapper (Full Message Schema) Format"
)
@ns1.route("/wrapper")
class MessageWrapper(Resource):
@ns1.response(200, "Success", full_message_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(
"planning_configuration",
description="Planning Configuration Format. Do we want region of "
+ "interest to be per squad, per platform or in the main schema?",
)
@ns3.route("")
class PlanningConfiguration(Resource):
@ns3.response(200, "Success", planning_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("")
class MissionPlan(Resource):
@ns4.response(200, "Success", mission_plan_schema)
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
ns6 = api.namespace("acknowledgement", description="Acknowledgment Format")
@ns6.route("")
class Acknowledgment(Resource):
@ns6.response(200, "Success", acknowledgement_schema)
def get(self):
pass
if __name__ == "__main__":
app.run()
examples/all/acknowledgement.json
+ 8
- 9
{
"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
+ 19
- 20
{
"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/observation.json
+ 1
- 1
Show all unchanged lines Show 20 lines
"source": "ecosub_c2",
"destination": "autonomy_engine",
"encoded": false,
"type": "platform_status",
"type": "observation",
"payload": {
"platform_serial":"ecosub-3",
"points_of_interest": [],
Show 20 lines Show all unchanged lines
examples/all/platform_status.json
+ 35
- 35
{
"message_ID": "b427003c-7bc8-11ed-a1eb-0242ac120002",
"message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
"timestamp": "2022-11-16T00:00:00Z",
"version": 1,
"version": 2,
"source": "hydrosurv_adapter",
"destination": "autonomy_engine",
"delivery_type": "publish",
"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
"message_type": "platform_status",
"active": true,
"autonomy_plan_ID": 1,
"battery_remaining_capacity": 80.2,
"gps_data": [
{
"altitude": 20,
"depth": 50,
"gps_source": "internal",
"latitude": 178.2,
"latitude_type": "string",
"longitude": -10.122,
"longitude_type": "string"
}
}
}
\ No newline at end of file
],
"health_status": "Warning",
"localisation_error": null,
"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": {},
"sensor_serial": null,
"sensor_status": null
},
"speed_over_ground": 124.3,
"thrust_applied": 124.3,
"usbl_fix_seconds_ago": null,
"water_current_velocity": 124.3
}
examples/hydrosurv_adapter/acknowledgement.json
+ 8
- 9
{
"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/hydrosurv_adapter/mission_plan.json
+ 19
- 20
{
"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/hydrosurv_adapter/platform_status.json
+ 35
- 35
{
"message_ID": "b427003c-7bc8-11ed-a1eb-0242ac120002",
"message_ID": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
"timestamp": "2022-11-16T00:00:00Z",
"version": 1,
"version": 2,
"source": "hydrosurv_adapter",
"destination": "autonomy_engine",
"delivery_type": "publish",
"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
"message_type": "platform_status",
"active": true,
"autonomy_plan_ID": 1,
"battery_remaining_capacity": 80.2,
"gps_data": [
{
"altitude": 20,
"depth": 50,
"gps_source": "internal",
"latitude": 178.2,
"latitude_type": "string",
"longitude": -10.122,
"longitude_type": "string"
}
}
}
\ No newline at end of file
],
"health_status": "Warning",
"localisation_error": null,
"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": {},
"sensor_serial": null,
"sensor_status": null
},
"speed_over_ground": 124.3,
"thrust_applied": 124.3,
"usbl_fix_seconds_ago": null,
"water_current_velocity": 124.3
}
formats/__init__.py
+ 95
- 95
formats/acknowledgement.py
+ 39
- 22
formats/message_wrapper.py
+ 58
- 0
formats/mission_plan.py
+ 140
- 72
formats/observation.py
+ 70
- 38
formats/planning_configuration.py
+ 218
- 90
formats/platform_status.py
+ 333
- 164
project/SOAR_README.md
+ 7
- 0
README.md
+ 8
- 1
__init__.py
+ 0
- 1
generate_swagger.py
+ 136
- 0