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
• survey: this would be demanded track, platform actual path, and survey line
• 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 sent to_platform to be executed and status updates are received from_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 & Save Schema When Updating Message Formats

1. Run the command below and go to http://127.0.0.1:5000

python3 generate_schema_config.py

2. Copy the schema generated http://127.0.0.1:5000/soar_protocol.json into the backbone-message-format/project/<project_name>/swagger.json

3. In the json copied, remove the key "definitions" from the schema and save this.

Run Tests

Run both tests below:

1. Test 1

python3 -m unittest tests/test_schemas.py

2. Test 2

cd tests-js/docker; docker compose up --build

Quick Links

1. Generated Swagger Docs (recommended to look at this)
2. Schema Fields Definitions
3. JSON Schema Examples
4. 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)