---
# System prepended metadata

title: Communication Framework - Software Design Description
tags: [Documentation]

---

Communication Framework - Software Design Description
===

## Table of Contents

[TOC]

# 1. Introduction
## 1.1. Purpose

The document describes the communication framework from the software aspect, including design goals and considerations. The document provides a high-level overview of the system architecture of the framework and operational scenarios. 

## 1.2. Scope

The high-level system design is decomposed into low-level detailed design specifications for 
1. operation scenarios
2. system components and communication protocols
    - software implementation
    - failure hanlings
3. the **component** referes to the unit involved in the communication framework, but **NOT** the device _using_ the communication framework. For example, the UAV itsefl is NOT a component described in this document, but the **communication unit** of UAV is.

## 1.3 Glossary
- GS: Ground Station
- ST: Survey Tool
- _(TBA)_

## 1.4. Design Considerations
### 1.4.1. Goals
1. Simplify the system including HW, SW and UX
    - Comm. Hub, GS, UAV, BS, ST
2. Simplify SW engineering process
3. Lower the cost
    - Reusable components/design
    - Lower cost operational options (e.g. cloud operation w/o 840M and BS)
    - General GS app, no dedicated mobile device
4. Increase flexibility for future expansion (international, domestic markets)
5. Re-usable components/design
6. Various communcation modes: cloud, offline, mixed, local, switched
7. Ability to raise up communication antennae and capability to use cellular connection so that operational range can be expanded
8. Easy and reliable installation of antennae, cables, and power is a must

### 1.4.2. Design Constraints
_(TBA)_
### 1.4.3. Dependencies
_(TBA)_

# 2. General Overview
## 2.1. Components
The Communication Framework includes 8 communication unit in following devices:
1. UAV(s)
2. DGPS provider - Cloud DGPS
3. DGPS provider - Base Station (BS)
4. GS (Android app)
5. BS
6. Survey Tool (Android/iOS app)
7. Backend
8. GS Comm. Hub

Only a subset of above components will be used simultaneously based on different use-cases, including following operational scenarios
- Survey Fields
    - _TBA_
- BS Setup
    - _TBA_
- UAV Operation
    - Cloud Mode
      - UAV(s)
      - GS
      - Backend
      - Cloud DGPS
    - Offline Mode
      - _TBA_
    - _Other modes... (TBA)_

## 2.2. Components and Data in the System
- UAV
  - Receive (from GS today)
    - DGPS messages (RT, 500B/s+)
    - Guidance commands (RT)
    - Mission
    - SW updates (file transfers)
  - Send (to GS today)
    - Warning (RT)
    - States (~RT)
    - Trajectory (<RT)
    - images (<RT, ?)
    - Data download (files)
    - Image file downloads (files)
  - Both
    - Handshakes and Ack.

- Survey Tool
  - Receive
    - DGPS messages (RT, from Backend or BS-offline)
    - Map (from Backend)
    - Fields (from Backend)
  - Send
    - Acquisition msg. (if web based)
    - Fields (to Backend)

- Ground Station (GS)
  - Receive
    - DGPS messages (RT, from Backend or BS-offline)
    - Fields (from Backend)
    - Map (from Backend)
    - Warning (RT, from UAV)
    - Flight path & UAV status (~RT, from UAV)
    - SW updates (from Backend)
    - Data download (from UAV)
    - Image file downloads (from UAV)
  - Send
    - DGPS messages (RT, to UAV)
    - Mission (to UAV, to Backend)
    - Guidance commands (RT, to UAV)
    - Flight path & UAV status (~RT, to Backend)
    - SW updates (to UAV)
    - Data download (to Backend)
    - Image file downloads (to Backend)

- BS (Base Station)
  - Send
    - DGPS messages, BS status (RT, to Backend or GS-offline)
    - Web based account handling (to Backend)
    - Web based data requested (to web based DGPS)
  - Receive
    - DGPS messages (RT, from web based DGPS)

# 3. Communication Interfaces of Components
Each component uses different communication interfaces under different operation modes.

- UAV
  - detect the existence/status of all comm. intefaces including
    | Interface \ Mode | Cloud        | Offline      | 
    | - | - | - |
    | 1. Cellular      | All Data     | ---          |
    | 2. 840M (UART)   | ---          | All Data     |
    | 3. WiFi (STA)    | Files, OTA   | Files, OTA   |
    | 4. BT            | Setup        | Setup        | 
    | 5. CAN           | talk to Host | talk to Host | 
- ST
  - detect the existence/status of all comm. intefaces including
    | Interface \ Mode | Cloud         | Offline      | 
    | - | - | - |
    | 1. GPS' (UART)   | GPS           | GPS          |
    | 2. 840M (UART)   | ---           | Diff         |
    | 3. WiFi          | STA => Mobile | AP <= Mobile |
    | 4. BT            | Setup         | Setup        | 
- GS Comm. Hub
  - detect the existence/status of all comm. intefaces including
    | Interface \ Mode | Offline  | 
    | - | - | - |
    | 1. 840M (UART)   | All Data |
    | 2. WiFi (AP)     | All Data |
    | 3. BT            | Setup    | 
- BS 
  - detect the existence/status of all comm. intefaces including
    | Interface \ Mode | Offline  | 
    | - | - | - |
    | 1. 840M (UART)   | All Data |
    | 2. WiFi (Mode?)  | All Data |
    | 3. BT            | Setup    | 
  - for offline mode, should it serve as GS Comm. Hub? **(TBD)** 
- **TBD: Is tethering necessary?**
# 4. Lifecycles of Each Component
- UAV
    - Setup
      1. Read the config file
      2. Check all required interface
          - WiFi, BT, CAN
          - Cellular (cloud mode)
          - 840M (offline mode) 
      3. **Check the host CPU**
      4. Go to Loop if no error; Go to Error if something wrong
    - Loop
      - Process messages
        - Commands
      - Forward messages
        - Diff, Commands, Mission, Warning, States, Traj 
      - Log (all?) messages
      - Monitor all interfaces and UAV state
        - If something wrong,
          - if UAV is in mission, stay in Loop
          - if UAV is not in mission, go to Error
    - Error
      - Possible failures
        - Remote (Backend/GS Comm. Hub) no response
        - Interface break
      - Wait until error fixed
        - Keep monitoring interfaces
        - Allow manually switch to Setup
```graphviz
digraph cloudmode {		
splines=spline
overlap=false

node [fontname="arial"]
P [label="Power On", group=main]
S [label="SETUP", group=main]
L [label="LOOP", group=main]
E [label="ERROR"]

{rank=same; S, E}

edge [fontname="arial"]
P->S [label=""]
S->L [headlabel="no error during setup", labeldistance=8, labelangle=70]
S->E [label="setup failed", constraint=false]
L->E:e [headlabel="interface failed / \n remote no response", labeldistance=10, labelangle=10, constraint=false]
E->S [label="reset by user", constraint=false]
E:s->L [label="error no longer exists"]
}
```
- ST
    - Setup
      1. Read the config file
      2. Check all required interface
          - UART (GPS)
          - BT
          - WiFi (cloud mode: STA; offline mode: AP) 
          - 840M (offline mode)
      3. **Check the GPS' module status**
      4. Go to Loop if no error; Go to Error if something wrong
    - Loop
      - Process messages
        - Commands
      - Forward messages
        - GPS, Diff, Commands 
      - Log (all?) messages
      - Monitor all interfaces and **GPS module** status
        - If something wrong, go to Error
    - Error
      - Possible failures
        - Remote (Mobile Device/GS Comm. Hub) no response
        - Interface break
      - Wait until error fixed
        - Keep monitoring interfaces
        - Allow manually switch to Setup
```graphviz
digraph cloudmode {		
splines=spline
overlap=false

node [fontname="arial"]
P [label="Power On", group=main]
S [label="SETUP", group=main]
L [label="LOOP", group=main]
E [label="ERROR"]

{rank=same; S, E}

edge [fontname="arial"]
P->S [label=""]
S->L [headlabel="no error during setup", labeldistance=8, labelangle=70]
S->E [label="setup failed", constraint=false]
L->E:e [headlabel="interface failed / \n remote no response", labeldistance=10, labelangle=10, constraint=false]
E->S [label="reset by user", constraint=false]
E:s->L [label="error no longer exists"]
}
```
- GS Comm. Hub
    - Setup
      1. Read the config file
      2. Check all required interface
          - 840M
          - WiFi (AP)
          - BT
      3. Go to Loop if no error; Go to Error if something wrong
    - Loop
      - Process messages
        - Commands
      - Forward messages
        - Diff, Commands, Mission, Warning, States, Traj 
      - Log (all?) messages
      - Monitor all interfaces
        - If something wrong, go to Error
    - Error
      - Possible failures
        - Remote (Mobile Device/GS Comm. Hub) no response
        - Interface break
      - Wait until error fixed
        - Keep monitoring interfaces
        - Allow manually switch to Setup
```graphviz
digraph cloudmode {		
splines=spline
overlap=false

node [fontname="arial"]
P [label="Power On", group=main]
S [label="SETUP", group=main]
L [label="LOOP", group=main]
E [label="ERROR"]

{rank=same; S, E}

edge [fontname="arial"]
P->S [label=""]
S->L [headlabel="no error during setup", labeldistance=8, labelangle=70]
S->E [label="setup failed", constraint=false]
L->E:e [headlabel="interface failed / \n remote no response", labeldistance=10, labelangle=10, constraint=false]
E->S [label="reset by user", constraint=false]
E:s->L [label="error no longer exists"]
}
```
- BS
    - Setup
      1. Read the config file
      2. Check all required interface
      3. Go to Loop if no error; Go to Error if something wrong
    - Loop
      - Process messages
        - Commands
      - Forward messages
        - Diff, Commands 
      - Log (all?) messages
      - Monitor all interfaces and **GPS module** status
        - If something wrong, go to Error
    - Error
      - Possible failures
        - Remote (Mobile Device/GS Comm. Hub) no response
        - Interface break
      - Wait until error fixed
        - Keep monitoring interfaces
        - Allow manually switch to Setup
```graphviz
digraph cloudmode {		
splines=spline
overlap=false

node [fontname="arial"]
P [label="Power On", group=main]
S [label="SETUP", group=main]
L [label="LOOP", group=main]
E [label="ERROR"]

{rank=same; S, E}

edge [fontname="arial"]
P->S [label=""]
S->L [headlabel="no error during setup", labeldistance=8, labelangle=70]
S->E [label="setup failed", constraint=false]
L->E:e [headlabel="interface failed / \n remote no response", labeldistance=10, labelangle=10, constraint=false]
E->S [label="reset by user", constraint=false]
E:s->L [label="error no longer exists"]
}
```

All components are considered as a node in the communication framework, therefore all of them adopt the same lifecycle in a high-level viewpoint.


# 4. Communication Over MQTT
## 4.1. Overview
- A Pub/Sub mechanism is applied on top of MQTT
- UAVs and GS are MQTT clients; Backend (cloud mode)/GCH (offline mode) is the MQTT Broker.
- Topics
  - Backend: /BE/<BE ID>/<Message Type>
  - BS: /BS/<BS ID>/<Message Type>
  - GS: /GS/<User ID>/<Message Type>
  - UAV: /UAV/<Device ID>/<Message Type>
  - GS Comm. Hub: /GCH/<Message Type>

## 4.2. Synchronization Mechanism
- The QoS of MQTT will take care the synchronization

# 5. Operational Scenarios
## 5.1. UAV Operation
UAV operations includ following different modes:
1. cloud
2. offline
3. mixed
4. local (**?**)
5. switch
### 5.1.1. Cloud Mode
#### 5.1.1.1. Overview
UAV operate in **cloud mode** includes following components:
- UAV
- GS
- Backend
- Cloud-DGPS

```graphviz
digraph cloudmode {		
splines=spline
splines=true
overlap=false

node [fontname="arial"]
U [label="UAV", shape=rect]
B [label="Backend", style=dashed]
G [label="GS", shape=rect]
D [label="Cloud DGPS", style=dotted]

edge [fontname="arial"]
B->U [label="   control/mission message to UAV", constraint=false]
U->B [headlabel="UAV status message to GS    ", labeldistance=9, labelangle=70]
B->G [headlabel="UAV status message to GS    ", labeldistance=10, labelangle=50]
B->G [label="  user/task data to GS   ", labeldistance=6, labelangle=310, constraint=true]
G->B [headlabel="control/mission message to UAV", labeldistance=13, labelangle=10, constraint=true]
D->U [label="  DGPS message"]

}
```

- **Note 1: All data transmit via cloud (i.e. cellular interface)**
- (X) _Note 2: Backend serves as a communication bridge between GS and UAV(s)_ **_(TBD: alternative? e.g. p2p)_**
- **Note 2: Backend forward the messages between UAV to GS and keep a copy**
- **Note 3: Backup connection interface between GS and UAV: Cellular signal is not always reliable. Therefore, an alternative connection interface (GS WiFi hotspot? / GS WiFi Direct? / BT?) should be ready to establish for emergency/debugging/manul-control. _(TBD)_**


#### 5.1.1.4. Connection Setup
1. The Backend is supposed to be ready for accepting connection from UAV and GS.
2. Either UAV or GS can connect to Backend after power-on/started.
    - If UAV connects first, GS will receive the info of UAV after login
    - If GS connects first, it will be notified after UAV connected.
3. After a handshake between UAV and GS, setup is considered finished successfully.

##### 5.1.1.4.1. Connection Setup Sequence
---

###### 5.1.1.4.1.1. UAV connect to Backend first
```mermaid
sequenceDiagram

participant GS
participant Backend
participant UAV

Note over UAV: UAV power-on
UAV->>Backend: /UAV/[uav_id]/State
UAV->>Backend: subscribe: /UAV/[uav_id]/Command
UAV->>Backend: subscribe: /UAV/[uav_id]/Mission
Note over Backend: UAV online

Note over GS: User login to GS app
GS->>Backend: /GS/[user_id]/Login
GS->>Backend: subscribe: /GS/[user_id]/*
Note over Backend: User online
Backend->>GS: /GS/[user_id]/Profile
Note over GS: "display: login status"
Backend->>GS: /GS/[user_id]/UAV
Note over GS: "display: UAV(s) info"

Note over GS, Backend: Path planning, Job management ...

Note over GS: User: "connect to UAV"
GS->>Backend: subscribe: /UAV/[uav_id]/State
GS->>Backend: /UAV/[uav_id]/Command: State
Backend->>UAV: /UAV/[uav_id]/Command: State
UAV->>Backend: /UAV/[uav_id]/State
Backend->>GS: /UAV/[uav_id]/State
Note over GS: "display UAV status"
Note over GS, UAV: communication setup finished
```

- Jill@20200224: UAV send status to GS logically should not be part of communication setup

---
###### 5.1.1.2.1.2. GS connect to Backend first

```mermaid
sequenceDiagram

participant GS
participant Backend
participant UAV

Note over GS: User login to GS app
GS->>Backend: /GS/[user_id]/Login
GS->>Backend: subscribe: /GS/[user_id]/*
Note over Backend: User online
Backend->>GS: /GS/[user_id]/Profile
Note over GS: "display: login status"

Note over UAV: UAV power-on
UAV->>Backend: /UAV/[uav_id]/State
UAV->>Backend: subscribe: /UAV/[uav_id]/Command
UAV->>Backend: subscribe: /UAV/[uav_id]/Mission
Note over Backend: UAV online

Backend->>GS: /GS/[user_id]/UAV
Note over GS: "display: UAV(s) info"

Note over GS, Backend: Path planning, Job management ...

Note over GS: User: "connect to UAV"
GS->>Backend: subscribe: /UAV/[uav_id]/State
GS->>Backend: /UAV/[uav_id]/Command: State
Backend->>UAV: /UAV/[uav_id]/Command: State
UAV->>Backend: /UAV/[uav_id]/State
Backend->>GS: /UAV/[uav_id]/State
Note over GS: "display UAV status"
Note over GS, UAV: communication setup finished
```
---

##### 5.1.1.2.2. Setup Flow of Each Components
###### 5.1.1.2.2.1 Setup flow of GS and UAV
```graphviz
digraph {

rankdir=TB
// splines=ortho
splines=spline
splines=true
overlap=false

label="Communication Setup Flow of GS and UAV"
fontname="arial"

node [fontname="arial"]
start [label="User login to GS\n / UAV power-on"]
conn_backend [label="Connect To Backend"]
if_conn_ok [shape="diamond", label="connect ok?"]
if_conn_timeout [shape="diamond", label="timeout?"]
ask_for_help [shape="box", label="Show Help Message"]
report_success [shape="box", label="GS-Backend Connection Ready"]

edge[fontname="arial"]
start -> conn_backend
conn_backend -> if_conn_ok
if_conn_ok:s -> report_success:n [label="  yes"]
if_conn_ok:s -> if_conn_timeout:e [label="no"]
if_conn_timeout:s -> ask_for_help:n [label="  yes"]
if_conn_timeout:w -> if_conn_ok:w [label="no, re-connect"]
ask_for_help:w -> conn_backend:w [headlabel="re-connect by user", labelangle=0, labeldistance=12]

start[group=main]
conn_backend[group=main]
if_conn_ok[group=main]
report_success[group=main]
if_conn_timeout [group=left]
ask_for_help [group=left]

{rank=min; start}
{rank=same; if_conn_ok}
{rank=same; if_conn_timeout}
{rank=max; report_success, ask_for_help}
}

```
---
###### 5.1.1.2.2.2 Setup Flow of Backend
```graphviz
digraph {
//splines=ortho
splines=spline
splines=true
overlap=false
rankdir=TB

label="communication setup flow of Backend"
fontname="arial"

node[fontname="arial"] // universal attr of nodes
start [label="Waiting for incoming connection"]
check_conn_type [shape=diamond, label="connection type?"]
if_user_exist [shape=diamond, label="user exist?"]
if_uav_exist [shape=diamond, label="uav exist?"]
reg_user [label="register user"]
reg_uav [label="register UAV"]
notify_uav_list [label="send UAV list to GS"]

edge [fontname="arial"]
start -> check_conn_type [label="  incoming connection"]
check_conn_type:e -> reg_uav:e [headlabel="   UAV connection", labeldistance=8, labelangle=100]
check_conn_type:w -> reg_user:w [label="  GS connection"]
reg_uav -> if_user_exist
reg_user -> if_uav_exist
if_user_exist:s -> notify_uav_list:e [label="yes"]
if_uav_exist:s -> notify_uav_list:w [label="yes"]
if_user_exist:e -> start:e [label="  no"]
if_uav_exist:w -> start:w [label="  no"]
notify_uav_list:s -> start:n [label="", constraint=false]

start [group=center]
check_conn_type [group=center]
notify_uav_list [group=center]

reg_uav [group=right_1]
if_user_exist [group=right_1]

reg_user [group=left_1]
if_uav_exist [group=left_1]

{rank=min; start}
{rank=same; reg_uav}

}

```
---
#### 5.1.1.3. Operation
##### 5.1.1.3.1. Operation Sequence
```mermaid
sequenceDiagram

participant GS
participant Backend
participant UAV
participant Cloud DGPS

Note over GS, UAV: communication setup finished
Note over GS, Backend: Path planning, Job management ...

Note over GS: User: select DGPS service
GS->>Backend: /UAV/[uav_id]/Command: Conn. DGPS
Backend->>UAV: /UAV/[uav_id]/Command: Conn. DGPS
UAV->>Cloud DGPS: login
Note left of Cloud DGPS: (keep sending DGPS message to UAV)
Cloud DGPS->>UAV: login ok


UAV->>Backend: /UAV/[uav_id]/State
Backend->>GS: /UAV/[uav_id]/State
Note over GS: display "UAV connect to DGPS"

loop Main Operation Flow
    Note over GS, Backend: Path planning, Job management ...

    Note over GS: User: upload mission to UAV
    GS->>Backend: /UAV/[uav_id]/Mission
    Backend->>UAV: /UAV/[uav_id]/Mission
    
    Note over UAV: checking status and mission...

    UAV->>Backend: /UAV/[uav_id]/State (ready to execute)
    Backend->>GS: /UAV/[uav_id]/State (ready to execute)
    Note over GS: display "UAV is ready to operate"

    Note over GS: User: execute
    GS->>Backend: /UAV/[uav_id]/Command (execute)
    Backend->>UAV: /UAV/[uav_id]/Command (execute)

    Note over UAV: execute mission
    Cloud DGPS-->>UAV: DGPS message (every ?ms)

activate UAV
        loop UAV auto mode
            UAV->>Backend: /UAV/[uav_id]/State
            Backend->>GS: /UAV/[uav_id]/State
            Note over GS: "display UAV status"
        end %% (UAV auto mode)

        Note over GS, UAV: User interrupt execution (begin)
        loop UAV manual mode    
            Note over GS: User ask UAV to do something
            GS->>Backend: /UAV/[uav_id]/Command
            Backend->>UAV: /UAV/[uav_id]/Command
            Note over UAV: Process Command
            UAV->>Backend: /UAV/[uav_id]/State
            Backend->>GS: /UAV/[uav_id]/State
            Note over GS: Display the response from UAV
        end %% (UAV manual mode)    
        Note over GS, UAV: User interrupt execution (end)

        loop UAV auto mode
            UAV->>Backend: /UAV/[uav_id]/State
            Backend->>GS: /UAV/[uav_id]/State
            Note over GS: "display UAV status"
        end %% (UAV auto mode)

        Note over UAV: finish mission
    deactivate UAV

    UAV->>Backend: /UAV/[uav_id]/State (mission finished)
    Backend->>GS: /UAV/[uav_id]/State (mission finished)

    Note over GS: "display: mission accomplished"
end %% Main Operation Flow

Note over GS, Backend: Path planning, Job management ...
```

#### 5.1.1.4. Finish
```mermaid
sequenceDiagram

participant GS
participant Backend
participant UAV
participant Cloud DGPS

Note over GS, Backend: [User<-->GS<-->Backend] Path planning, Job management ...

Note over GS: User: disconnect UAV
GS->>Backend: /UAV/[uav_id]/Command (logout DGPS)
Backend->>UAV: /UAV/[uav_id]/Command (logout DGPS)

UAV->>Cloud DGPS: logout
Note left of Cloud DGPS: (stop sending DGPS message to UAV)
Cloud DGPS->>UAV: logout ok
UAV->>Backend: /UAV/[uav_id]/State (logout DGPS)
Backend->>GS: /UAV/[uav_id]/State (logout DGPS)

Note over GS: display "UAV logout DGPS"

GS->>Backend: /UAV/[uav_id]/Command (logout Backend)
Backend->>UAV: /UAV/[uav_id]/Command (logout Backend)

Note over Backend: UAV offline

Backend->>GS: UAV disconnected ok (alternative? power-off?) 
Note over GS: display "UAV disconnected"

Note over GS, UAV: communication closed
```
#### 5.1.1.5. Failure/Exception Handling _(TBD)_
1. Poor network quality
2. UAV comm. interface died
3. GS died
4. Backend died
5. User shutdown UAV after finished work
6. Multiple users want to control an UAV simutaneously (**?**)
7. _?(TBA)_

### 5.1.2. Offline Mode
#### 5.1.2.1. Overview
UAV operate in **offline mode** includes following components:
- UAV
- GS
- GS Comm. Hub
- BS

As no 4G signal available, a 840M network is set for communication.
- A MQTT Boker is running in GCH, playing the same role as Backend in cloud mode
- Proxy Pattern: A stub as well as a MQTT client is running in GCH to receive 840M messages and convert them into MQTT topics, then publish
- GS connect to GCH via WiFi. Therefore GS itself could be a MQTT client pulishing topics the same way as cloud mode

```graphviz
digraph cloudmode {		
splines=spline
splines=true
overlap=false

node [fontname="arial"]
U [label="UAV", shape=rect]
C [label="GS Comm.Hub", shape=rect]
G [label="GS", shape=rect]
B [label="BS", shape=rect]

edge [fontname="arial"]
C->U [label="   control/mission message to UAV/\n DGPS message", constraint=false]
U->C [headlabel="UAV status message to GS    ", labeldistance=9, labelangle=70]
C->G [headlabel="UAV status message to GS    ", labeldistance=9, labelangle=80]
G->C [headlabel="control/mission message to UAV", labeldistance=11, labelangle=75, constraint=true]
B->C [label="  DGPS message"]
}
```

- **Note 1: All data transmit via GS Comm. Hub**
- **Note 2: The GS Comm. Hub serves as a communication mediator among GS, BS, and UAV(s)**

#### 5.1.2.4. Connection Setup
1. The 840M on GS Comm. Hub is master, while all others are slaves.
2. **(TBA) 840M master/slave pairing process?**
3. UAV, BS and GS connect to GS Comm. Hub after power-on/started; the order doesn't matter.
    - If UAV connects first, GS will receive the info of UAV after login
    - If GS connects first, it will be notified after UAV connected.

##### 5.1.2.4.1. Connection Setup Sequence
---

```mermaid
sequenceDiagram
participant G as GS
participant C as GCH
participant U as UAV1
participant U2 as UAV2
participant B as BS

Note over U: waiting for 840M pairing
Note over B: waiting for 840M pairing

C->>U: pair 840M (?)
U->>C: /UAV/[uav_1]/State
U->>C: subscribe: /UAV/[uav_1]/Command
U->>C: subscribe: /UAV/[uav_1]/Mission
U->>C: subscribe: /BS/*
C->>B: pair 840M (?)
B->>C: /BS/[bs_id]/State

Note over B: keep sending DGPS message

loop DGPS messages forwarding
B->>C: /BS/[bs_id]/DGPS
C->>U: /BS/[bs_id]/DGPS
end

Note over G: User login
G->>C: connect
G->>C: /GS/[user_id]/Login
G->>C: subscribe: /GS/[user_id]/*
C->>G: /GS/[user_id]/UAV
C->>G: /GS/[user_id]/BS
G->>C: subscribe: /UAV/[uav_1]/*
G->>C: subscribe: /BS/[bs_id]/*
C->>G: /UAV/uav_1]/State
C->>G: /BS/[bs_id]/State

Note over G, B: example: connect order doesn't matter

Note over U2: power-on
C->>U2: pair 840M (?)
U2->>C: /UAV/[uav_2]/State
U2->>C: subscribe: /UAV/[uav_2]/Command
U2->>C: subscribe: /UAV/[uav_2]/Mission
C->>G: /GS/[user_id]/UAV
G->>C: subscribe: /UAV/[uav_2]/*
C->>G: /UAV/uav_2]/State




```
---
##### 5.1.2.2.2. Setup Flow of Each Components
###### 5.1.2.2.2.1 Setup flow of GS
```graphviz
digraph offlinemode {		
splines=spline
splines=true
overlap=false

node [fontname="arial"]
U [label="User Login", group=center]
C [label="Conn. to GCH", group=center]
if_conn_succ [label="Conn. Success?", shape=diamond, group=center]
if_conn_timeout [label="Conn. Timeout?", shape=diamond, group=right]
restart_conn [label="User Restart Conn."]
S [label="Setup Successfully", shape=rect, group=center]
W [label="Stop Reconnecting", shape=rect, group=right]


edge [fontname="arial"]
U:s->C:n
C:s->if_conn_succ:n
if_conn_succ:e->if_conn_timeout:w [label="no"]
if_conn_succ:s->S:n [label="yes"]
if_conn_timeout:n->C:e [label="no"]
if_conn_timeout:s->W:n [label="yes"]
W:w->restart_conn:e
restart_conn:n->C:w
}
```

###### 5.1.1.2.2.1 Setup flow of UAV
```graphviz
digraph offlinemode {		
splines=spline
splines=true
overlap=false

node [fontname="arial"]
P [label="Power-On", group=center]
C [label="Conn. to GCH", group=center]
if_conn_succ [label="Conn. Success?", shape=diamond, group=center]
if_conn_timeout [label="Conn. Timeout?", shape=diamond, group=right]
restart_conn [label="User Restart Conn."]
S [label="Setup Successfully", shape=rect, group=center]
W [label="Stop Reconnecting", shape=rect, group=right]


edge [fontname="arial"]
P:s->C:n
C:s->if_conn_succ:n
if_conn_succ:e->if_conn_timeout:w [label="no"]
if_conn_succ:s->S:n [label="yes"]
if_conn_timeout:n->C:e [label="no"]
if_conn_timeout:s->W:n [label="yes"]
W:w->restart_conn:e
restart_conn:n->C:w
}
```


###### 5.1.1.2.2.2 Setup Flow of GCH
```graphviz
digraph offlinemode {
P [label="Power-On"]
I [label="Init all interfaces"]
R [label="Ready for connections", shape=rect]
GS_conn [label="Conn. Req. from GS"]
if_gs_already [label="GS already connect?", shape=diamond]
accept_gs [label="Accept"]
reject_gs [label="Reject"]
UAV_conn [label="Conn. Req. from UAV"]


}
```

###### 5.1.1.2.2.2 Setup Flow of BS (TBA)
---
#### 5.1.1.3. Operation
##### 5.1.1.3.1. Operation Sequence
```mermaid
sequenceDiagram

participant G as GS
participant C as GCH
participant U as UAV
participant B as BS

Note over U, C: [User<-->GS<-->Backend] Path planning, Job management ...

U->>C: /UAV/[uav_id]/State
C->>G: /UAV/[uav_id]/State

loop Main Operation Flow
    Note over G: Path planning, Job management ...
    Note over G: User: upload mission to UAV
    G->>C: /UAV/[uav_id]/Mission
    C->>U: /UAV/[uav_id]/Mission
    
    Note over U: checking status and mission...
    U->>C: /UAV/[uav_id]/State (ready to execute)
    C->>G: /UAV/[uav_id]/State (ready to execute)
    Note over G: display: "UAV is ready to operate"

    Note over G: user: execute
    G->>C: /UAV/[uav_id]/Command (execute)
    C->>U: /UAV/[uav_id]/Command (execute)

    Note over U: execute mission
    B->>C: DGPS message (every ?ms)
    C->>U: DGPS message (every ?ms)

activate U
        loop UAV auto mode
            U->>C: /UAV/[uav_id]/State
            C->>G: /UAV/[uav_id]/State
        end %% (UAV auto mode)

        Note over G, U: User interrupt execution (begin)
        loop UAV manual mode    
            Note over G: User ask UAV to do something
            G->>C: /UAV/[uav_id]/Command
            C->>U: /UAV/[uav_id]/Command
            Note over U: Process Command
            U->>C: /UAV/[uav_id]/State
            C->>G: /UAV/[uav_id]/State
            Note over G: Display the response from UAV
        end %% (UAV manual mode)    
        Note over G, U: User interrupt execution (end)

        loop UAV auto mode
            U->>C: /UAV/[uav_id]/State
            C->>G: /UAV/[uav_id]/State
            Note over G: display UAV status
        end %% (UAV auto mode)

        Note over U: finish mission
    deactivate U

    U->>C: /UAV/[uav_id]/State (mission finished)
    C->>G: /UAV/[uav_id]/State (mission finished)

    Note over G: display: "mission accomplished"
end %% Main Operation Flow
```

#### 5.1.1.4. Finish
```mermaid
sequenceDiagram

participant User
participant GS
participant Backend
participant UAV
participant Cloud DGPS

Note over User, Backend: [User<-->GS<-->Backend] Path planning, Job management ...


User-->>GS: disconnect UAV
GS->>Backend: /UAV/[uav_id]/Command (logout DGPS)
Backend->>UAV: /UAV/[uav_id]/Command (logout DGPS)

UAV->>Cloud DGPS: logout
Note left of Cloud DGPS: (stop sending DGPS message to UAV)
Cloud DGPS->>UAV: logout ok
UAV->>Backend: /UAV/[uav_id]/State (logout DGPS)
Backend->>GS: /UAV/[uav_id]/State (logout DGPS)

GS-->>User: "UAV logout DGPS"


Note over Backend: UAV offline

Backend->>GS: UAV disconnected ok
GS-->>User: "UAV disconnected"

Note over User, UAV: communication closed
```
#### 5.1.1.5. Failure/Exception Handling _(TBD)_
1. Poor network quality
2. UAV comm. interface died
3. GS died
4. Backend died
5. User shutdown UAV after finished work
6. Multiple users want to control an UAV simutaneously (**?**)
7. _?(TBA)_

# 6. Detailed Design
_(TBA)_


# 7. Appendix

:::info
**A communication framework software requirement specification should be include here**
:::

###### tags: `Documentation`
