# 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 -f ``` 2. Commit any changes to the `backbone-message-format/project/<project_name>/swagger.json` ## Run Tests We have found slightly different behaviour between the OpenAPI validators in python and javascript. By running tests in both languages we should protect against messages that pass validation in one client but fail in another. Run both tests below: 1. Test 1 - Use python validators ``` python3 -m unittest discover ``` 2. Test 2 - Use javascript validators ``` # Compile schema and run javascript validation tests in docker bash test-js.sh ``` ## Quick Links 1. [Generated Swagger Docs (recommended to look at this)](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/blob/dev/project/soar/swagger.json) 2. [Schema Fields Definitions](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/dev/formats) 3. [JSON Schema Examples](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/tree/dev/examples) 4. Ongoing Project: [SoAR README.md](https://git.noc.ac.uk/communications-backbone-system/backbone-message-format/-/blob/dev/project/soar/SOAR_README.md) ## Installing You can install the message formats as a package with pip ```requirements.txt 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 ```python import backbone_formats ``` ### Importing the compiled schema ```python import importlib.resources import soar_schema import json with importlib.resources.open_text(soar_schema, "swagger.json") as file: schema = json.load(file) ```