Skip to content

GitLab

Commit defa0678 authored by Alvaro Lorenzo's avatar Alvaro Lorenzo
Browse files

Merge branch '1-add-guidelines-to-use-workspace' into 'master' 

Add contributing guidelines and readme

Closes #1

See merge request !3
parents 4471dd61 31c3970e
Hide whitespace changes
Inline Side-by-side
Showing with 128 additions and 2 deletions
CONTRIBUTING.md 0 → 100644
View file @ defa0678
# Contributing to Backbone Message Formats
_Last updated: 01 Dec 2022_
<br/>
Guidelines for our 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 |
| -------- | ---------------------------------------------------------- | ----------------------------------------------------------------------- |
| Project | `SoAR` | Associated project |
| Partner | `Planet Ocean`, `Hydro-Surv`, `NOC`, `RHU` | Associated partner |
| Asset | `ah1`, `ecosub`, `reav`, `autonomy engine` | 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/>
## 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)
### Project-Specific: SoAR Project
* **[Reference SoAR Message Format 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)**
* To view schema docs via Swagger UI, run the command below and go to `http://127.0.0.1:5000`
```
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).
<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`.
\ No newline at end of file
README.md
View file @ defa0678
# 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.
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 |
-----------------------------------
## 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