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.
The schemas are using OpenApi 3.0 (due to the payload
sub-schemas that vary according to the message_type
).
Message Types
Each message below will be wrapped in a payload
field and will have a header
with message metadata information:
-
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).
Topics
Messages are routed using either a publish/subscribe or broadcast mechanism.
For published messages, the message is published for a given a topic.
Clients create a subscription (stored in their config) to a topic pattern which may include wildcards.
It's important to note that the client config documents the subscription. To change a client subscription it must be updated with the backbone.
Published messages are delivered to all clients where the message topic matches the client's subscription topic pattern.
Broadcast messages are delivered to all clients regardless of their subscription.
Field
The topic should be set in the message.header.destination
for published messages.
The destination
field should be set to broadcast
for any messages sent using broadcast.
Because the destination
field is a topic it defines what the message relates to - not
who the intended recipient is.
This means that the clients are not typically represented in the topics. A client publishes a message about a platform and subscribers interested in that project, platform or message type will receive that message.
Structure
<prefix>.<operator>.<platform_type>.<platform_identifier>.<to_platform|from_platform>.<message_type>
e.g
soar.noc.autosub.ah1.from_platform.platform_status
soar.planet-ocean.ecosub.eco1.to_platform.mission_plan
soar.hydrosurv.reav.reav1.to_platform.mission_plan
Terms
-
prefix
- an agreed hard-coded/config setting prefix shared by all adapters and client subscriptions eg soar -
operator
- human readable organisation name for the platform operator one of [noc|planet-ocean|hydrosurv] -
platform_type
- one of [autosub|ecosub|reav?] -
platform_identifier
- human readable identifier for the platform eg ah1, eco1, reav1 -
to_platform|from_platform
- eg ..to_platform.mission_plan, ..from_platform.platform_status missions are sentto_platform
to be executed and status updates are receivedfrom_platform
containing information about its position and health status -
message_type
- one of[acknowledgement|mission_plan|observation|planning_configuration|platform_status...]
Subscriptions
Subscriptions may contain multiword wildcards (#) or single word wildcards (*) eg
-
soar.#
- everything -
soar.planet-ocean.#
- anything relating to the planet-ocean operator -
soar.*.*.*.from_platform.*
- all messages inbound from platforms (autonomy engine) -
soar.*.*.*.to_platform.*
- all messages outbound to platforms (hermes) -
soar.*.slocum.#
- all messages relating to a slocum platform type
Run Docs
Run the command below and go to http://127.0.0.1:5000
python3 generate_schema_config.py
Run Tests
Run the command below
python3 -m unittest tests/test_schemas.py
Quick Links
- Generated Swagger Docs (recommended to look at this)
- Schema Fields Definitions
- JSON Schema Examples
- Ongoing Project: SoAR README.md
Installing
You can install the message formats as a package with pip
backbone-message-format @ git+https://git.noc.ac.uk/communications-backbone-system/backbone-message-format.git@v0.1.0#egg=backbone-message-format
Importing the formats
import backbone_formats
Importing the compiled schema
import importlib.resources
import soar_schema
import json
with importlib.resources.open_text(soar_schema, "swagger.json") as file:
schema = json.load(file)