# 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 to a topic pattern which may include wildcards. 

Messages with a topic matching a client's subscription pattern are delivered to that client.

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 desintation field should be set to `broadcast` for any messages sent using broadcast. 

### 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

The `header.destination` field contains the topic that messages will be published to.

This is not the intended recipient of those messages.

The autonomy engine/frontend/c2s are not represented in the topic.

The topic describes what the message relates to.

The client `subscription` will define which clients receive a message.

* `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
* `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
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)