Skip to content

GitLab

Merged
Created by Trishna Saeharaseelan@trishnaOwner

Create initial message schemas

11 unresolved threads
Compare
and
30 files
+ 1709
- 1019
Show latest version
do‎cs‎
__ini‎t__.py‎ +0 -9
generate_‎swagger.py‎ +0 -368
exam‎ples‎
autonom‎y_engine‎
configura‎tion.jsonc‎ +0 -71
mission_‎plan.json‎ +0 -0
autos‎ub_c2‎
sample_autosub.alr-3.‎v1.mission_script.sbd‎ +0 -0
sample_decoded_‎ah1_status.json‎ +0 -199
ecos‎ub_c2‎
mission_‎plan.json‎ +54 -0
observat‎ion.json‎ +24 -0
platform_status-fro‎m_usbl_example.json‎ +17 -0
platform_s‎tatus.json‎ +39 -0
g‎ui‎
emergency‎_stop.json‎ +0 -0
planning_conf‎iguration.json‎ +157 -0
hydrosur‎v_adapter‎
acknowledg‎ement.json‎ +12 -0
mission_‎plan.json‎ +26 -0
platform_s‎tatus.json‎ +25 -0
for‎mats‎
__ini‎t__.py‎ +109 -0
acknowled‎gement.py‎ +47 -0
message_w‎rapper.py‎ +59 -0
mission‎_plan.py‎ +153 -0
observa‎tion.py‎ +100 -0
planning_con‎figuration.py‎ +267 -0
platform_‎status.py‎ +327 -0
pro‎ject‎
SOAR_RE‎ADME.md‎ +51 -0
CONTRIB‎UTING.md‎ +73 -0
READ‎ME.md‎ +23 -77
__ini‎t__.py‎ +6 -70
autonomy_con‎figuration.py‎ +0 -101
generate_‎swagger.py‎ +136 -0
platform_‎status.py‎ +0 -124
requirem‎ents.txt‎ +4 -0
docs/__init__.py deleted
+ 0
- 9
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 deleted
+ 0
- 368
"""
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="",
),
},
)
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", message_header_schema)
def get(self):
pass
@ns4.route("/reav")
class MissionPlanReav(Resource):
@ns4.response(200, "Success", message_header_schema)
def get(self):
pass
@ns4.route("/autosubhover")
class MissionPlanAutosubHover(Resource):
@ns4.response(200, "Success", message_header_schema)
def get(self):
pass
if __name__ == "__main__":
app.run()
examples/autonomy_engine/configuration.jsonc deleted
+ 0
- 71
//****************************************************************
// File: config.json (THIS FILE WILL BE IN JSON FORMAT, NOT JSONC)
// Description: This file is configured by the respective
// platform's C2 if a platform is no longer active or change
// a configured value.
//
// Notes: All comments in this document will be stripped out
// during SOAR operations.
// (TODO: RHU to identify values that can and cannot be
// configured).
//----------------------------------------------------------------
// CHANGELOG
// -------------------
// 11-11-2022 Trishna S. Added comments, header, and data types
// for each field.
// 10-11-2022 Izzat K. Converted contents to json schema.
// 06-10-2022 Trishna S. New initialisation file.
//****************************************************************
{
"mission_config": {
"execute_stage": {
"survey": true, // bool
"detail": false // bool
}
},
"survey_team": {
"no_of_platforms": 3, // int
"platforms": [
{
"id": 1, // int
"platform": "ecosub", // str
"platform_serial": "eco101", // str
"active": true // bool
},
{
"id": 2,
"platform": "ecosub", // str
"platform_serial": "eco-102", // str
"active": true // bool
},
{
"id": 3, // int
"platform": "ecosub", // str
"platform_serial": "ecosub3", // str
"active": true // bool
}
],
"min_altitude": 0.0, // float
"min_velocity": 0.0, // float
"max_velocity": 0.0 // float
},
"detail_team": {
"execute_stage": true, // bool
"no_of_platforms": 1, // int
"platforms": [
{
"id": 1, // int
"platform": "autosub-hover", // str
"platform_serial": "ah1", // str
"active": true // bool
}
],
"min_altitude": 0.0, // float
"min_velocity": 0.0, // float
"max_velocity": 0.0 // float
},
"environment": {
"region_of_interest": 0.0, // float
"exclusion_zone": 0.0 // float
}
}
\ No newline at end of file
examples/autonomy_engine/mission_plan.json deleted
+ 0
- 0
examples/autosub_c2/sample_autosub.alr-3.v1.mission_script.sbd deleted
+ 0
- 0

sample_autosub.alr-3.v1.mission_script.sbd

Download
examples/autosub_c2/sample_decoded_ah1_status.json deleted
+ 0
- 199
{
"reason": "ready",
"gps_source": "internal",
"gps_lat": 60.16048651129611,
"gps_lon": -1.156730960091541,
"gps_fix_seconds_ago": 1665580800,
"alr_data": {
"format_version": "ocsv3",
"message_type": "H",
"message_source": 3,
"transmit_timestamp": 1665580753.564244,
"content_mask": 18410715202459939000,
"depth": -1.304158329963684,
"water_conductivity": 0,
"water_temperature": 0,
"max_depth": 0,
"altitude": 1000,
"min_altitude": 0,
"vehicle_heading": -58.08430862426758,
"water_speed": -0.000008320044798892923,
"time_since_last_gps": 1665580800,
"time_on_surface": 7814.99365234375,
"w_hours": 28.418603897094727,
"battery_current": 0.4806833267211914,
"battery_max_current": 65.45500183105469,
"battery_voltage": 25.113433837890625,
"battery_min_voltage": 23.034000396728516,
"leak_sensor_output": 9,
"ground_fault_sensor_out": 752,
"propeller_rpm": 0,
"rs485_fault_flags": {},
"rs232_fault_flags": {},
"helm_state": {
"8": "idle"
},
"max_abort_link_state": 358,
"health_events": {},
"helm_events": {
"14": "waiting"
},
"log_storage_space": 98649407488,
"sbd_parser_error": {},
"alr_warning": 0,
"compass_align_value": -1.8788431882858276,
"battery_energy_used": 0,
"dead_nodes": {},
"position": {
"latitude": 60.16048651129611,
"longitude": -1.156730960091541
},
"pth_1": {
"pressure_temp": 2.0399177074432373,
"pressure": 593,
"temp": 17.80158233642578,
"rel_humidity": 7
},
"pth_2": {
"pressure_temp": 1.9932914972305298,
"pressure": 574,
"temp": 14.916650772094727,
"rel_humidity": 16
},
"rs232_mute_counts": {
"port00": 0,
"port01": 0,
"port02": 0,
"port03": 0,
"port04": 0,
"port05": 0,
"port06": 0,
"port07": 0,
"port08": 0,
"port09": 0,
"port10": 0,
"port11": 0,
"port12": 0,
"port13": 0,
"port14": 0,
"port15": 0
},
"rs485_mute_counts": {
"port00": 0,
"port01": 0,
"port02": 0,
"port03": 0,
"port04": 0,
"port05": 0,
"port06": 0,
"port07": 0,
"port08": 0,
"port09": 0,
"port10": 0,
"port11": 0,
"port12": 0,
"port13": 0,
"port14": 0,
"port15": 0
},
"helm_state_bitmask": 8388608,
"helm_state_bitstring": "00000000100000000000000000000000",
"helm_events_bitmask": 562949953421312,
"helm_events_bitstring": "0000000000000010000000000000000000000000000000000000000000000000",
"health_events_bitmask": 0,
"health_events_bitstring": "0000000000000000000000000000000000000000000000000000000000000000",
"sbd_parser_error_bitmask": 128,
"sbd_parser_error_bitstring": "10000000",
"dead_nodes_bitmask": 0,
"dead_nodes_bitstring": "0000000000000000000000000000000000000000000000000000000000000000",
"rs232_fault_flags_bitmask": 0,
"rs232_fault_flags_bitstring": "0000000000000000",
"rs485_fault_flags_bitmask": 0,
"rs485_fault_flags_bitstring": "0000000000000000",
"rudder_status": {
"errors": [
"current_info_not_received"
],
"error_bitmask": 16,
"error_bitstring": "00010000",
"angle": 0
},
"sternplane_status": {
"errors": [
"current_info_not_received"
],
"error_bitmask": 16,
"error_bitstring": "00010000",
"angle": 0
},
"auv_roll": -0.8640746474266052,
"auv_pitch": 0.2900053858757019,
"biocam_status": {
"biocam_current_mode": 9,
"biocam_cam_0_image_count": 0,
"biocam_cam_1_image_count": 0,
"biocam_cpu_temperature": 273,
"biocam_cam_0_temperature": 273,
"biocam_cam_1_temperature": 273,
"biocam_available_disk_space": 0
},
"serial_states": {
"port01": {
"3": "on"
},
"port02": {
"3": "on"
},
"port03": {
"0": "off"
},
"port04": {
"0": "off"
},
"port05": {
"0": "off"
},
"port06": {
"0": "off"
},
"port07": {
"0": "off"
},
"port08": {
"0": "off"
},
"port09": {
"0": "off"
},
"port10": {
"3": "on"
},
"port11": {
"3": "on"
},
"port12": {
"0": "off"
},
"port13": {
"3": "on"
},
"port14": {
"0": "off"
},
"port15": {
"0": "off"
},
"port16": {
"0": "off"
}
},
"computed": {}
},
"serial_number": "alr-3",
"time": 1665580753.564244,
"version": "ocsv3",
"_kind": "comms",
"autosub_message_format": {
"git_commit_hash": "ba3e33a9e786772d9642390711cf48b0a08755ea"
}
}
\ No newline at end of file
examples/ecosub_c2/mission_plan.json
+ 54
- 0
{
"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
+ 24
- 0
{
"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,
"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
+ 17
- 0
{
"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
+ 39
- 0
{
"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": "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/gui/emergency_stop.json deleted
+ 0
- 0
examples/gui/planning_configuration.json
+ 157
- 0
{
"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": "platform_status",
"planning_config_ID": 3,
"exclusion_zones": [
{
"geometry_coordinates": [
[
[
-4.187143188645706,
50.37072283932642
],
[
-4.202697005964865,
50.368816892405874
],
[
-4.203156724702808,
50.365640144076906
],
[
-4.19449868846155,
50.362267670845654
]
]
]
}
],
"squads": [
{
"squad_ID": 1,
"no_of_platforms": 1,
"squad_mission_type": "tracking",
"squad_state": false,
"platforms": [
{
"model": "reav",
"platform_ID": 23,
"serial": "reav-60",
"emergency": {
"additional_data": {},
"latitude_waypoint": -7.432,
"longitude_waypoint": 50.365,
"safe_command": "go_home",
"target_depth": 10
},
"max_velocity": 0.9,
"min_altitude": 15.2,
"min_velocity": 0.1,
"additional_data": {}
}
],
"region_of_interest": {
"geometry_coordinates": [
[
[
-4.187143188645706,
50.37072283932642
],
[
-4.202697005964865,
50.368816892405874
],
[
-4.203156724702808,
50.365640144076906
],
[
-4.19449868846155,
50.362267670845654
]
]
]
}
},
{
"squad_ID": 2,
"no_of_platforms": 3,
"squad_mission_type": "survey",
"squad_state": true,
"platforms": [
{
"platform_ID": 23,
"serial": "ecosub-2",
"model": "ecosub",
"emergency": {
"additional_data": {},
"latitude_waypoint": -7.432,
"longitude_waypoint": 50.365,
"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": {
"additional_data": {},
"latitude_waypoint": -0.432,
"longitude_waypoint": 20.365,
"safe_command": "go_home",
"target_depth": 0.0
},
"max_velocity": 0.9,
"min_altitude": 15.2,
"min_velocity": 0.1,
"additional_data": {
"scan_type": "DVL",
"swath_width": 10
}
}
],
"region_of_interest": {}
},
{
"squad_ID": 3,
"no_of_platforms": 1,
"squad_mission_type": "inspection",
"squad_state": false,
"platforms": [
{
"platform_ID": 23,
"serial": "ah-1",
"model": "autosub",
"emergency": {
"additional_data": {},
"latitude_waypoint": 20.432,
"longitude_waypoint": 50.365,
"safe_command": "safety_abort",
"target_depth": 0.0
},
"max_velocity": 0.9,
"min_altitude": 15.2,
"min_velocity": 0.1,
"additional_data": {
"scan_type": "MBES"
}
}
],
"region_of_interest": {}
}
]
}
\ No newline at end of file
examples/hydrosurv_adapter/acknowledgement.json
+ 12
- 0
{
"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,
"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
+ 26
- 0
{
"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
+ 25
- 0
{
"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/__init__.py
+ 109
- 0
# 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"
]
# TODO: Define units for all schemas
# message_types = [
# "platform_status",
# "mission_plan_ecosub",
# "mission_plan_reav",
# "mission_plan_autosub",
# ] # TODO: Add full range of message types once scoped out
# 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="{}",
# ),
# },
# )
# 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),
# },
# )
formats/acknowledgement.py
+ 47
- 0
"""
schemas: Acknowledgement status sent by the surface platform to report
receipt of message.
"""
acknowledgement_schema = {
"allOf": [{"$ref": "#/components/schemas/Message"}],
"type": "object",
"properties": {
"acknowledged_message_ID": {
"type": "string",
"description": "Identifier of message received and executed with "
+ "success for mission plans sent by the Autonomy Engine.",
"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",
"example": "executed by platform",
},
},
"required": ["acknowledged_message_ID", "status"],
}
# 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",
# ),
# },
# )
formats/message_wrapper.py
+ 59
- 0
"""
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.
"""
message_wrapper_schema = {
"type": "object",
"discriminator": {
"propertyName": "message_type",
},
"properties": {
"message_ID": {
"type": "string",
"description": "An identifier for the type of message received.",
"example": "b427003c-0000-11aa-a1eb-bvcdfghjgfdd",
},
"timestamp": {
"type": "date-time",
"description": "Timestamp of message",
"example": "2022-11-16T00:00:00Z",
},
"message_type": {
"type": "Type of message",
"description": "Type of message",
"example": "platform_status",
},
"version": {
"type": "string",
"description": "Version of comms bacbone message format protocol",
"example": 2.0,
},
"source": {
"type": "string",
"description": "The sender; Where is this message from",
"example": "autonomy_engine",
},
"destination": {
"type": "string",
"description": "Publisher topic; What is the destination"
+ " of this message",
"example": "ah1",
},
"encoded": {
"type": "boolean",
"description": "Indicate that message raw (encoded) or decoded. "
+ "Options: encoded=True, decoded=False",
"example": False,
},
"delivery_type": {
"type": "string",
"description": "To publish or broadcast this message.",
"enum": ["broadcast", "publish"],
"example": "publish",
"default": "publish",
},
},
"required": ["message_type"],
}
formats/mission_plan.py
+ 153
- 0
"""
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.
"""
# from . import api, full_message_schema
# from flask_restx import fields
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": {
"type": "number",
"description": "Next waypoint, x-coordinate",
"example": -4.187143188645706,
},
"longitude_waypoint": {
"type": "number",
"description": "Next waypoint, y-coordinate",
"example": 50.37072283932642,
},
"altitude": {
"type": "number",
"description": "Altitude of next action",
"example": 15.0,
},
"depth": {
"type": "number",
"description": "Depth of next action",
"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": [
"latitude_waypoint",
"longitude_waypoint",
],
}
mission_plan_schema = {
"allOf": [{"$ref": "#/components/schemas/Message"}],
"type": "object",
"properties": {
"autonomy_engine_plan_ID": {"type": "integer"},
"platform_serial": {"type": "string"},
"plan": {
"type": "array",
"items": action_schema,
},
},
"required": ["plan_ID", "platform_serial", "plan"],
}
# 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="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.",
# ),
# },
# )
formats/observation.py
+ 100
- 0
"""
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_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.",
},
"region_surveyed": {
"description": "Region surveyed by given platform. DEFINE FORMAT."
+ " GEOJSON",
"example": "",
},
"additional_data": {
"description": "Placeholder field for any additional data",
"example": {"sensor_payload": False},
},
},
"required": ["platform_serial"],
}
# 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},
# ),
# },
# )
formats/planning_configuration.py
+ 267
- 0
"""
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, full_message_schema, platform_schema
# from flask_restx import fields
emergency_schema = {
"type": "object",
"properties": {
"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": "X-coordinate of safe place for respective platform",
"example": -7.432,
},
"longitude_waypoint": {
"type": "number",
"description": "Y-coordinate of safe place for respective platform",
"example": 50.365,
},
"target_depth": {
"type": "number",
"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": ["latitude_waypoint", "longitude_waypoint", "target_depth"],
}
platform_schema = {
"type": "object",
"properties": {
"platform_ID": {
"type": "integer",
"description": "Identifier for platform",
"example": 23,
},
"serial": {
"type": "string",
"description": "platform serial number",
"example": "reav-60",
},
"model": {
"type": "string",
"example": "reav",
},
"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", "emergency", "min_altitude", "min_velocity", "max_velocity"],
}
region_schema = {
"type": "object",
"properties": {
"geometry_coordinates": {
"type": "array", # TODO: Check if config defn is right.
"example": [
[
[-4.187143188645706, 50.37072283932642],
[-4.202697005964865, 50.368816892405874],
[-4.203156724702808, 50.365640144076906],
[-4.19449868846155, 50.362267670845654],
]
],
},
},
"description": "Using GEOJSON, exact 4-point region (rectangle shaped)",
"required": ["geometry_coordinates"],
}
squad_metadata_schema = {
"type": "object",
"properties": {
"squad_ID": {
"type": "integer",
"description": "Identifier of given squad",
"example": 23,
},
"no_of_platforms": {
"type": "integer",
"description": "Number of platforms",
"example": 3,
},
"platforms": {
"type": "array",
"items": platform_schema,
"description": "Squad consists of these platforms",
},
"squad_mission_type": {
"type": "string",
"enum": ["tracking", "survey", "inspection"],
"description": "Mission of given squad: `tracking`, `survey`"
+ ", `inspection`",
"example": "survey",
},
"squad_state": {
"type": "string",
"description": "In execution, Waiting.. <define further>",
"example": False,
},
"region_of_interest": region_schema,
},
"required": [
"squad_ID",
"no_of_platforms",
"platforms",
"squad_mission_type",
"squad_state",
"exclusion_zones",
],
}
planning_configuration_schema = {
"allOf": [{"$ref": "#/components/schemas/Message"}],
"type": "object",
"properties": {
"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",
"exclusion_zones",
],
}
# 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",
# ),
# },
# )
formats/platform_status.py
+ 327
- 0
"""
schema: platform-specific decoded status message
"""
sensor_schema = {
"type": "object",
"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_on": {
"type": "boolean",
"description": "Sensor switched on (True) or off (False)",
"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 = {
"allOf": [{"$ref": "#/components/schemas/Message"}],
"type": "object",
"properties": {
"platform_ID": {
"type": "integer",
"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",
"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 dictionary with potential STATES of each platform
"type": "string",
"description": "Current state executed by platform. E.g. "
+ "STOP, IDLE, ABORT.",
"example": "ABORT",
},
"autonomy_engine_plan_ID": {
"type": "integer",
"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. "
+ "4 --> Waypoint 3 to Waypoint 4)",
"example": 4,
},
"mission_action_ID": {
"type": "integer",
"description": "TODO: add description",
"example": 1,
},
"range_to_go": {
"type": "number",
"description": "Estimated distance to reach next waypoint",
"example": 124.3,
},
"speed_over_ground": {
"type": "number",
"description": "TODO: add description",
"example": 124.3,
},
"water_current_velocity": {
"type": "number",
"description": "TODO: add description",
"example": 124.3,
},
"thrust_applied": {
"type": "number",
"description": "TODO: Needs further consideration",
"example": 124.3,
},
"health_status": {
"type": "string",
"description": "Health status extracted by respective platform "
+ "if any diagnosis is available to check sensors",
"example": "Warning",
},
"localisation_error": {
"type": "number",
"description": "Localisation error at last USBL update.",
"example": 0.000129,
},
"usbl_fix_seconds_ago": {
"type": "number",
"description": "USBL Fix received x second ago.",
"example": 10.0,
},
"battery_remaining_capacity": {
"type": "number",
"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",
"latitude",
"longitude",
],
}
# 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"
# },
# )
# 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",
# ),
# },
# )
# 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
# },
# )
# # TBD: Do we append beacon positions with platform positions?
project/SOAR_README.md
+ 51
- 0
# SoAR Project
Squad of Adaptive Robots Project
-----------------------------------
## Message Data Flow Summary
| Partner | Message Type | Source | Destination | Via Comms Backbone? | Contains Serialized Vehicle-Specific File? | Comment |
| --------------------- | ------------------------ | --------------------- | ------------------------------------------ | ------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------- |
| Hydrosurv (reav) | platform status-compiled | Reav-60 | Hydrosurv Adapter | No | Yes | N/A |
| Hydrosurv (reav) | platform status | Hydrosurv Adapter | Autonomy Engine | Yes | No | N/A |
| Hydrosurv (reav) | mission plan | Autonomy Engine | Hydrosurv Adapter | Yes | No | N/A |
| Hydrosurv (reav) | mission plan-compiled | Hydrosurv Adapter | Reav-60 | No | Yes | N/A |
| Hydrosurv (reav) | acknowledgement | Hydrosurv Adapter | Comms Backbone (Audit) | Yes | No | When hydrosurv adapter has (a) Received, (b) Sent Plan to Reav, and (c) Executed by Reav |
| RHU (autonomy engine) | platform status | C2’s Hydrosurv/Ecosub | Autonomy Engine | Yes | No | N/A |
| RHU (autonomy engine) | mission plan | Autonomy Engine | C2’s Hydrosurv/Ecosub | Yes | No | N/A |
| RHU (autonomy engine) | planning configuration | GUI | Autonomy Engine | Yes | No | N/A |
| RHU (autonomy engine) | observation | Ecosub C2 | Autonomy Engine | Yes | No | N/A |
| RHU (autonomy engine) | survey progress | Ecosub/AH1 C2 | Autonomy Engine | TBD | TBD | N/A |
| RHU (autonomy engine) | scanline | TBD | TBD | TBD | TBD | N/A |
| RHU (autonomy engine) | emergency | GUI | TBD – all | TBD | TBD | TBD – all platforms pre-compiled ABORT via Black box |
| Planet Ocean (ecosub) | platform status-compiled | Ecosub | Black Box TBC | No | Yes | Via Hermes + Router |
| Planet Ocean (ecosub) | platform status-compiled | Black Box TBC | Ecosub C2 | Yes | Yes | N/A |
| Planet Ocean (ecosub) | platform status | Ecosub C2 | Autonomy Engine | Yes | No | N/A |
| Planet Ocean (ecosub) | mission plan | Autonomy Engine | Ecosub C2 | Yes | No | N/A |
| Planet Ocean (ecosub) | mission plan | Ecosub C2 | Black Box TBC | Yes | Yes | N/A |
| Planet Ocean (ecosub) | mission plan-compiled | Black Box TBC | Ecosub | No | Yes | Via Hermes + Router |
| Planet Ocean (ecosub) | observation-compiled | Ecosub | Black Box TBC | No | Yes | Via Hermes + Router |
| Planet Ocean (ecosub) | observation-compiled | Black Box TBC | Ecosub C2 | Yes | Yes | N/A |
| Planet Ocean (ecosub) | observation | Ecosub C2 | Autonomy Engine | Yes | No | N/A |
| Planet Ocean (ecosub) | survey progress | TBD | TBD | TBD | TBD | N/A |
| Planet Ocean (ecosub) | survey progress | TBD | TBD | TBD | TBD | N/A |
| Planet Ocean (ecosub) | scanline | TBD | TBD | TBD | TBD | N/A |
| Planet Ocean (ecosub) | scanline | TBD | TBD | TBD | TBD | N/A |
| Planet Ocean (ecosub) | emergency | GUI | TBD – Ecosub (ABORT command via Black Box) | TBD | TBD | TBD – all platforms pre-compiled ABORT via Black box |
| NOC (AH1) | platform status-compiled | AH1 | Black Box TBC | No | Yes | Via Hermes + Router |
| NOC (AH1) | platform status-compiled | Black Box TBC | NOC C2 | Yes | Yes | N/A |
| NOC (AH1) | platform status | NOC C2 | Autonomy Engine | Yes | No | N/A |
| NOC (AH1) | scan point | Autonomy Engine | NOC C2 | Yes | No | N/A |
| NOC (AH1) | scan point-compiled | NOC C2 | Black Box TBC | Yes | Yes | Would this technically be a mission plan-compiled? |
| NOC (AH1) | scan point | Black Box TBC | Ecosub | No | Yes | Via Hermes + Router |
| NOC (AH1) | survey progress | TBD | TBD | TBD | TBD | TBD |
| NOC (AH1) | survey progress | TBD | TBD | TBD | TBD | TBD |
| 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/`
CONTRIBUTING.md
+ 73
- 0
# Contributing to Backbone Message Formats
_Last updated: 01 Dec 2022_
<br/>
Guidelines for our project partners to collaborate in this workspace specifically for message formats that interact with each partner's software components and the Communications Backbone.
<br/><br/>
## Where To Find A Brief on Message Formats
Please refer to the [**README.md**](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/blob/master/README.md) file that summarises the `message types` and `message flows`.
> _Info: [Quick Links](#quick-links) might be helpful too!_
<br/>
## Commenting
A great way to collaborate and refine the message formats is by commenting on the schema definitions/examples (within the code itself) or on an `issue` card.
### **Commenting on Code**
Go to [`Merge Requests`](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/merge_requests), add your comment and click `Add comment now`. Be sure to **tag partners** who should response. **Use `@`** followed by the **partner's username** or **tag a partner's** organisation by **adding a label**.
P.S. The initial working branch is [`create-initial-message-formats`](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/merge_requests/2/diffs).
**But _HOW_ Do I Add A Comment?**
> A. To **comment directly on the** [**`master` branch**](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/master) directly, hover over the left column that shows the line numbers, and click on the **paperclip icon**. This copies the specific line of code. You can then proceed to pasting this link into a new issue as per [Raising New Ideas or Questions](#raising-new-ideas-or-questions).
> B. To **comment on a Merge Request**, hover over the left column that shows the line numbers, and click on the _paperclip_ or _comment bubble_ icon. This copies the line of code. You can then proceed to pasting this link into a new issue as per [Raising New Ideas or Questions](#raising-new-ideas-or-questions).
<br/>
### **Commenting on Issue Cards**
Go to the [issue](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/issues), scroll to the bottom of the page and add your comment. Once done, click on `Comment`.
<br/><br/>
## Raising New Ideas or Questions
If you have an idea or a question for our collaborators, it's simple! [`Create a new issue`](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/issues/new?issue), assign a person to respond/take action under `Assignee`, and add a partner under `Labels` .
<br/><br/>
## Labels Summary
To add/edit labels, go to [manage labels](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/labels).
| Category | Labels Available | Description |
| -------- | ---------------------------------------------------------- | ----------------------------------------------------------------------- |
| Project | `SoAR` | Associated project |
| Partner | `Planet Ocean`, `Hydro-Surv`, `NOC`, `RHU` | Associated partner |
| Asset | `ah1`, `ecosub`, `reav`, `autonomy engine` | Associated platform |
| Status | `In Sprint Backlog`, `In Progress`, `In Review`, `BLOCKED` | Status of resolving issue |
| Weight | `0`, `1`, `2`, `3`, `5`, `8` | Complexity of issue (0 - quick task and 8 - full 2 weeks worth of work) |
| - | `bug`, `feature` | Type of issue i.e. new feature, bug |
<br/>
## Quick Links
1. [Schema Fields Definitions](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/7-message-formats-initial/formats)
2. [JSON Schema Examples](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/7-message-formats-initial/examples)
### Project-Specific: SoAR Project
* **[Reference SoAR Message Format Slides](https://planetocean15.sharepoint.com/sites/IUKSoAR/Shared%20Documents/Forms/AllItems.aspx?id=%2Fsites%2FIUKSoAR%2FShared%20Documents%2FTechnical%2FTechnical%20meetings%2FDiscussions%E2%80%94%20Backbone%20Message%20Formats%2Epdf&viewid=1d649f5f%2Dd30e%2D482f%2Dbd77%2D9316a0023bf9&parent=%2Fsites%2FIUKSoAR%2FShared%20Documents%2FTechnical%2FTechnical%20meetings)**
* To view schema docs via Swagger UI, run the command below and go to `http://127.0.0.1:5000`
```
python3 docs/generate_swagger.py
```
*Disclaimer: These are *not* endpoints. Purely for schema representation purposes.
> TEMPORARY: Pregenerated Swagger docs can be [viewed here](https://planetocean15.sharepoint.com/sites/IUKSoAR/Shared%20Documents/Forms/AllItems.aspx?id=%2Fsites%2FIUKSoAR%2FShared%20Documents%2FTechnical%2FTechnical%20meetings%2Finitial%2Dswagger%2Ddocs%2Ddraft%2Epdf&viewid=1d649f5f%2Dd30e%2D482f%2Dbd77%2D9316a0023bf9&parent=%2Fsites%2FIUKSoAR%2FShared%20Documents%2FTechnical%2FTechnical%20meetings).
<br/>
## Getting Started
> Notes for this section is in PROGRESS
1. Clone this gitlab repository:
```
git clone https://git.noc.ac.uk/communications-backbone-system/backbone-message-format.git
```
2. Install the dependencies from `requirements.txt`.
\ No newline at end of file
README.md
+ 23
- 77
# 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
### 1/ Autonomy Engine
#### Transmit
* mission plan _(sent per platform)_
* TBD:
* Will emergency commands be sent via the autonomy engine (from the GUI) or directly to the C2s?
#### Receive
* configuration file
* emergency stop all
* decoded ecosub status message
* decoded reav status message
* decoded autosub-hover status message
* decoded ecosub survey data _(from squad 1 platforms)_
----------------------------------
### 2/ Ecosub C2
#### Transmit
* compiled ecosub mission plan
* decoded ecosub status message
* configuration file
* decoded ecosub survey data
#### Receive
* mission plan
* encoded ecosub status message
* encoded ecosub survey data
----------------------------------
### 3/ Autosub C2
#### Transmit
* compiled autosub-hover mission plan
* decoded autosub-hover status message
* configuration file
#### Receive
* mission plan
* encoded autosub-hover status message
----------------------------------
### 4/ Reav C2
#### Transmit
* decoded reav-60 status message?
#### Receive
* mission plan
* encoded reav-60 status message?
----------------------------------
### 5/ Hermes Box/Hydrosurv Smart Router?
#### Transmit
* encoded ecosub status message
* encoded (or is this already decoded?) reav status message
* encoded autosub status message
* encoded ecosub survey data
* TBD:
* are there acknowledgment messages from platforms?
* how are we receiving beacon messages per platform?
#### Receive
* compiled ecosub mission plan
* compiled reav mission plan
* compiled autosub mission plan
* compiled ecosub emergency command
* compiled reav emergency command
* compiled autosub emergency command
# Overview
This project repository is a collaborative workspace. It 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.
# Message Types
Each message below will be wrapped in a `message_wrapper`:
* `mission_plan`: these would be two message types, i. encoded (platform-specific serialized message) and ii. parsed, human-readable message.
* `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)
2. [JSON Schema Examples](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/7-message-formats-initial/examples)
3. Ongoing Project: [SoAR README.md](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/7-message-formats-initial/project/SOAR_README.md)
\ No newline at end of file
__init__.py
+ 6
- 70
from flask_restx import Api, fields
# from flask_marshmallow import Marshmallow
from flask_restx import Api
from flask import Flask
import os
# 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",
"formats",
]
app = Flask(__name__)
api = Api(app)
message_types = [
"platform_status"
] # TODO: Add full range of message types once scoped out
message_header_schema = api.model(
"MessageHeader",
{
"timestamp": fields.String( # TODO: Update to Datetime UTC format
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",
),
},
)
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
autonomy_configuration.py deleted
+ 0
- 101
"""
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",
),
},
)
generate_swagger.py
+ 136
- 0
from flask import Flask
from flasgger import Swagger
# from . import properties
from formats.message_wrapper import message_wrapper_schema
from formats.mission_plan import mission_plan_schema
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__)
swagger_config = {
"headers": [],
"openapi": "3.0.2",
"swagger_ui": True,
"specs_route": "/",
"info": {
"title": "Backbone Message Formats",
"version": "0.1",
"description": "SoAR message schemas (i.e. formats)",
},
"specs": [
{
"endpoint": "swagger",
"route": "/swagger.json",
"rule_filter": lambda rule: True,
"model_filter": lambda tag: True,
}
],
"components": {
"schemas": {
"Message": message_wrapper_schema,
"MissionPlan": mission_plan_schema,
"Observation": observation_schema,
"PlanningConfiguration": planning_configuration_schema,
"PlatformStatus": platform_status_message_schema,
"Acknowledgement": acknowledgement_schema,
},
},
"paths": {
"/all_messages": {
"get": {
"description": "Returns all messages from the system.",
"responses": {
"200": {
"description": "A list of messages.",
"content": {
"application/json": {
"schema": {
"oneOf": [
{
"$ref": "#/components/"
+ "schemas/Acknowledgement"
},
{
"$ref": "#/components/"
+ "schemas/PlatformStatus"
},
{
"$ref": "#/components/"
+ "schemas/MissionPlan"
},
{
"$ref": "#/components/"
+ "schemas/Observation"
},
{
"$ref": "#/components/"
+ "schemas/PlanningConfiguration"
},
{
"$ref": "#/components/"
+ "schemas/PlatformStatus"
},
],
"discriminator": {
"propertyName": "message_type",
},
}
}
},
}
},
}
},
},
"produces": ["application/json"],
"consumes": ["application/json"],
}
message_types = [
# "Message",
"Acknowledgement",
"MissionPlan",
"Observation",
"PlanningConfiguration",
"PlatformStatus",
]
for item in message_types:
swagger_config["paths"]["/" + str(item.lower())] = {
"get": {
"description": "Returns message for " + item,
"responses": {
"200": {
"description": item + " message.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas"
+ "/" + item,
},
],
"discriminator": {
"propertyName": "message_type",
},
}
}
},
}
},
}
}
swag = Swagger(app, config=swagger_config, merge=True)
# app.add_url_rule(
# '/coordinates',
# view_func=Coordinates.as_view('coordinates'),
# methods=['GET']
# )
if __name__ == "__main__":
app.run(debug=True)
platform_status.py deleted
+ 0
- 124
"""
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?
requirements.txt
+ 4
- 0
Flask
flask-restx
flasgger
flask-marshmallow
\ No newline at end of file