Skip to content

GitLab

Commit a6af2a95 authored by Trishna Saeharaseelan's avatar Trishna Saeharaseelan
Browse files

docs: add contributing guidelines and readme

parent 4471dd61
Hide whitespace changes
Inline Side-by-side
Showing with 200 additions and 2 deletions
CONTRIBUTING.md 0 → 100644
View file @ a6af2a95
# Contributing to Backbone Message Formats
_Last updated: 01 Dec 2022_
<br/>
Guidelines for our Squad of Adaptive Robots (SoAR) 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 |
| -------- | -------------------------------------------------- | ----------------------------------------------------------------------- |
| Partner | Planet Ocean, Hydrosurv, NOC, RHU | Associated partner |
| Vehicles | ah1 | Associated vehicle |
| 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/>
## 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`.
<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)
3. To view schema docs via Swagger UI, run the command below and go to `http://127.0.0.1:5000/soardocs`
```
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).
README.md
View file @ a6af2a95
# backbone-message-format
# 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 vehicle's data and statuses defined by each partner.
**[Reference 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)**
Message format(s) for the Communications Backbone System
\ No newline at end of file
# Message Types
* Each message below will be treated as the `payload` that are wrapped in a `full_message_format` that includes a `message_header`.
| Type | Summary of File | Serialized/Compiled in Vehicle-Specific Format? |
| --------------------------| ---------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `planning_configuration` | Autonomy Engine's Configuration file (if c2 needs to update its respective vehicle directly) | No |
| `mission_plan` | Mission plan generated by Autonomy Engine per vehicle | No |
| `encoded_mission_plan` | Encoded/serialized vehicle-specific mission plan | Yes |
| `encoded_vehicle_status` | Encoded/serialized vehicle-specific vehicle status | Yes |
| `vehicle_status` | Decoded/de-serialized generic vehicle status | No |
| `encoded_observation` | Encoded/serialized observation data from vehicle for Autonomy Engine | Yes |
| `observation` | Decoded/de-serialized observation data from vehicle for Autonomy Engine | No |
| `acknowledgement` | Decoded/de-serialized acknowledgement message from the Hydrosurv Adapater | No |
-----------------------------------
## Breakdown of Message Sources & Types
### 1/ Autonomy Engine
#### Transmit
* mission plan _(sent per vehicle??)_
* 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 observation data _(from squad 1 vehicles)_
----------------------------------
### 2/ Ecosub C2
#### Transmit
* compiled ecosub mission plan
* decoded ecosub status message
* autonomy configuration file
* decoded ecosub observation data
#### Receive
* mission plan
* encoded ecosub status message
* encoded ecosub observation data
----------------------------------
### 3/ Autosub C2
#### Transmit
* compiled autosub-hover mission plan
* decoded autosub-hover status message
* autonomy 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 observation data
* TBD:
* are there acknowledgment messages from vehicles?
* how are we receiving beacon messages per vehicle?
#### 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
------------------------------------
## Message Data Flow Summary
| Partner | Message Type | Source | Destination | Via Comms Backbone? | Contains Serialized Vehicle-Specific File? | Comment |
| --------------- | ---------------------- | ----------------- | ---------------------- | ------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------- |
| Autonomy Engine | vehicle status | C2’s | Autonomy Engine | Yes | No | |
| Autonomy Engine | Hydrosurv/Ecosub/Ah1 |
| Autonomy Engine | mission plan | Autonomy Engine | C2’s | Yes | No | |
| Autonomy Engine | Hydrosurv/Ecosub/Ah1 |
| Autonomy Engine | autonomy configuration | GUI | ALL | Yes | No | Common file sent to all partners – to store |
| Autonomy Engine | autonomy configuration | C2’s | Autonomy Engine | Yes | No | IF REQUIRED ONLY, UPDATE STORED FILE. |
| Autonomy Engine | Hydrosurv/Ecosub/Ah1 |
| Hydrosurv | vehicle status | Hydrosurv C2 | Autonomy Engine | Yes | No | |
| Hydrosurv | mission plan | Autonomy Engine | Hydrosurv C2 | Yes | No | |
| Hydrosurv | mission plan | Hydrosurv C2 | Reav-60 | No | Yes | |
| Hydrosurv | autonomy configuration | GUI | Hydrosurv C2 (ALL) | Yes | No | Common file sent to all partners – to store |
| Hydrosurv | autonomy configuration | Hydrosurv C2 | GUI | Yes | No | IF REQUIRED ONLY, UPDATE STORED FILE. |
| Hydrosurv | acknowledgment | Hydrosurv C2 | Comms Backbone (Audit) | Yes | No | When hydrosurv adapter has (a) Received, (b) Sent Plan to Reav, and (c) Executed by Reav |
| Planet Ocean | vehicle status | Ecosub | Hydrosurv Adapter | No | Yes | |
| Planet Ocean | vehicle status | Hydrosurv Adapter | Ecosub C2 | Yes | Yes | |
| Planet Ocean | vehicle status | Ecosub C2 | Autonomy Engine | Yes | No | |
| Planet Ocean | mission plan | Autonomy Engine | Ecosub C2 | Yes | No | |
| Planet Ocean | mission plan | Ecosub C2 | Hydrosurv Adapter | Yes | Yes | |
| Planet Ocean | mission plan | Hydrosurv Adapter | Ecosub | No | Yes | Via Hermes + Router |
| Planet Ocean | autonomy configuration | GUI | Ecosub C2 (ALL) | Yes | No | Common file sent to all partners – to store |
| Planet Ocean | autonomy configuration | Hydrosurv C2 | GUI | Yes | No | IF REQUIRED ONLY, UPDATE STORED FILE. |
| Planet Ocean | observation | Ecosub | Hydrosurv Adapter | No | Yes | Via Hermes + Router |
| Planet Ocean | observation | Hydrosurv Adapter | Ecosub C2 | Yes | Yes | |
| Planet Ocean | observation | Ecosub C2 | Autonomy Engine | Yes | No | |
| Planet Ocean | vehicle status | AH1 | Hydrosurv Adapter | No | Yes | Via Hermes + Router |
| NOC | vehicle status | Hydrosurv Adapter | NOC C2 | Yes | Yes | |
| NOC | vehicle status | NOC C2 | Autonomy Engine | Yes | No | |
| NOC | mission plan | Autonomy Engine | NOC C2 | Yes | No | |
| NOC | mission plan | NOC C2 | Hydrosurv Adapter | Yes | Yes | |
| NOC | mission plan | Hydrosurv Adapter | AH1 | No | Yes | Via Hermes + Router |
| NOC | autonomy configuration | GUI | NOC C2 (ALL) | Yes | No | Common file sent to all partners – to store |
| NOC | autonomy configuration | Hydrosurv C2 | GUI | Yes | No | IF REQUIRED ONLY, UPDATE STORED FILE. |
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment