Merge pull request #16 from bringauto/BAIP-250/documentation

Detailed documentation for the module
bringauto · Aug 2, 2024 · 6f97f0f · 6f97f0f
2 parents c29dc7e + 552de50
commit 6f97f0f
Show file tree

Hide file tree

Showing 6 changed files with 278 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -1,12 +1,45 @@
-# Mission module
+# Introduction
 
-Module for missions. This module connects Fleet Management and autonomy.
+The Mission Module is a core module of the BringAuto in-house [Fleet Protocol](https://github.com/bringauto/fleet-protocol) for communication between a car and a cloud.
 
-### Config
+It provides communication between
 
-Some configuration is required when running this module. Example config:
+1. Autonomy device - the driving component of the car.
+2. Cloud - a component providing an interface giving the end user to control the car's mission.
 
+For a detailed description of the inner workings, see the [Mission Module documentation](./docs/mission_module.md).
+
+## Identification and supported devices
+
+Module number/ID: `1`.
+
+### Device list
+
+| **Device Name** | **Device Type** | **Device Roles** | Comment                                          |
+| --------------- | --------------- | ---------------- | ------------------------------------------------ |
+| autonomy        | 0               | driving          | The device drives the car according the mission. |
+
+## Dependencies
+
+- [CMakeLib](https://github.com/cmakelib/cmakelib)
+
+If BRINGAUTO_SYSTEM_DEP=ON is set, the dependencies described by [cmake/Dependencies.cmake](cmake/Dependencies.cmake) need to be installed as part of the system.
+
+## Build
+
+```bash
+mkdir _build && cd _build
+cmake -DCMAKE_BUILD_TYPE=Release [-DBRINGAUTO_INSTALL=ON] [-DBRINGAUTO_PACKAGE=ON] [-DBRINGAUTO_SYSTEM_DEP=ON] ..
+make
+make install # in case of INSTALL feature on
+cpack # in case of PACKAGE feature on
 ```
+
+## Configuration
+
+External Server Module Configuration is required as:
+
+```json
 "config": {
     "api_url": "http://localhost:8080",
     "api_key": "StaticAccessKeyToBeUsedByDevelopersOnEtna",
@@ -19,19 +52,7 @@ Some configuration is required when running this module. Example config:
 }
 ```
 
-- api_url : URL of fleet http api ([project repository](https://gitlab.bringauto.com/bring-auto/fleet-protocol-v2/http-api/fleet-v2-http-api))
-- api_key : generated in fleet http api (script/new_admin.py)
-- company_name, car_name : used to identify car in fleet http api
-- max_requests_threshold_count, max_requests_threshold_period_ms, delay_after_threshold_reached_ms, retry_requests_delay_ms : explained in [http client README](./lib/fleet-v2-http-client/README.md)
-
-### Dependencies
-
-- [CMakeLib](https://github.com/cmakelib/cmakelib)
-
-### Build
-
-```
-mkdir _build && cd _build
-cmake -DCMAKE_BUILD_TYPE=Release [-DBRINGAUTO_INSTALL=ON] [-DBRINGAUTO_PACKAGE=ON] ..
-make
-```
+- `api_url`: URL of the Fleet Protocol HTTP API ([project repository](https://github.com/bringauto/fleet-protocol-http-api))
+- `api_key`: generated in Fleet Protocol HTTP API (script/new_admin.py)
+- `company_name`, `car_name`: used to identify the car in Fleet Protocol HTTP API
+- `max_requests_threshold_count`, `max_requests_threshold_period_ms`, `delay_after_threshold_reached_ms`, `retry_requests_delay_ms`: explained in [HTTP client README](./lib/fleet-v2-http-client/README.md)
diff --git a/docs/images/image.png b/docs/images/image.png
diff --git a/docs/mission_module.md b/docs/mission_module.md
@@ -0,0 +1,158 @@
+# Introduction to the Mission Module details
+
+Here, additional info on the Mission Module is provided. For the purpose and usage see the [README](../README.md).
+
+# Behavior of supported devices
+
+## Autonomy Device
+
+After connection, the autonomy device is in a state `Idle`. The internal state of Autonomy is driven by
+
+- the received command (e.g., the command stops names and the action value),
+- the sensors for car orientation (e.g., some obstacle prevents the car from driving).
+
+![autonomy state diagram](images/image.png "Car state diagram")
+
+The Autonomy keeps in memory the NAME of the next stop (the `nextStop` in the activity diagram below), it should drive to (it can be empty). This stop is used when calling for a change in the internal components of the Autonomy device driving the car. The actions taken by the autonomy after receiving the command are shown below. Note the `route` in the command is informative and does not affect the actions.
+
+![activity diagram of autonomy receiving command](uml/exported_diagrams/command_activity_diagram.png "Activity diagram of the autonomy receiving command")
+
+The Autonomy device sends the car status to the Mission Module. The status contains a field `State` with the value corresponding to the state of the device (`DRIVE`, `IN_STOP`, `IDLE`, `OBSTACLE`, `ERROR`).
+
+# Messages
+
+## Structure
+
+Below, the data passed in the messages used in the External Protocol are described. The data structure can also be found in the [.proto](../lib/protobuf-mission-module/) file.
+
+## Status payload data
+
+Always contains
+
+- state (State enum value: `IDLE`, `DRIVE`, `IN_STOP`, `OBSTACLE`, `ERROR`)
+
+If the state is `DRIVE` or `IN_STOP`, it must contain
+
+- next stop (`Station`)
+
+Optionally, the status contains
+
+- telemetry (`Telemetry`)
+
+Example:
+
+```json
+{
+  "state": "DRIVE",
+  "telemetry": {
+    "position": {
+      "latitude": 45.8137528,
+      "longitude": 15.9870608,
+      "altitude": 120.7
+    },
+    "speed": 7.2,
+    "fuel": 0.62
+  },
+  "nextStop": {
+    "name": "Train Station",
+    "position": {
+      "latitude": 45.815011,
+      "longitude": 15.981919,
+      "altitude": 125.3
+    }
+  }
+}
+```
+
+## Status Error payload data
+
+Always contains
+
+- finished stops (list of Station)
+
+Example:
+
+```json
+{
+  "finishedStops": [
+    {
+      "name": "Train Station",
+      "position": {
+        "latitude": 45.8144669,
+        "longitude": 15.9965289,
+        "altitude": 115.1
+      }
+    },
+    {
+      "name": "Bus Station",
+      "position": {
+        "latitude": 45.8139306,
+        "longitude": 15.9913147,
+        "altitude": 118.4
+      }
+    }
+  ]
+}
+```
+
+## Command payload data
+
+Always contains
+
+- action (Action enum value)
+- stop (Station)
+- stations (list of Station)
+- route (string)
+
+Example of command payload when the car received the mission:
+
+```json
+{
+  "action": "START",
+  "stations": [
+    {
+      "name": "Fish Market",
+      "position": {
+        "latitude": 45.815011,
+        "longitude": 15.981919,
+        "altitude": 125.3
+      }
+    },
+    {
+      "name": "Bus Station",
+      "position": {
+        "latitude": 45.8120758,
+        "longitude": 15.9837108,
+        "altitude": 120.7
+      }
+    },
+    {
+      "name": "Train Station",
+      "position": {
+        "latitude": 45.8144669,
+        "longitude": 15.9965289,
+        "altitude": 115.1
+      }
+    }
+  ],
+  "route": "FishMarketRoundTrip"
+}
+```
+
+Example of command payload when there is no mission defined for the car:
+
+```json
+{
+  "action": "NO_ACTION",
+  "stations": [],
+  "route": ""
+}
+```
+
+## Validation
+
+The validation of each of the messages is done against the message structure described above (and in the [.proto](../lib/protobuf-mission-module/) file). The functions for validation:
+
+- `parseAutonomyStatus` for status,
+- `parseAutonomyError` for status error,
+- `parseAutonomyCommand` for command.
diff --git a/docs/uml/command.puml b/docs/uml/command.puml
@@ -0,0 +1,69 @@
+@startuml command_activity_diagram
+<style>
+    activityDiagram {
+        BackgroundColor #88bcff
+        FontSize 12
+    }
+    start {BackgroundColor black}
+    stop {BackgroundColor black}
+    document {
+        BackgroundColor white
+    }
+    note {
+        BackgroundColor #ffee55
+    }
+</style>
+start
+
+note right
+    Device accepts
+    command with action
+    and list of stops.
+end note
+
+note left
+    Autonomy stores the `nextStop` -
+    - name of the next stop
+    it drives to, or empty string if
+    it is not driving.
+end note
+
+switch (Action value)
+case (\n   STOP)
+    #LightGray:Set nextStop to "";
+    note left
+        This branch is
+        always used to
+        stop the car.
+    end note
+    #LightGray:Autonomy cancels driving;
+    #Pink:send status with IDLE state;
+case (\n  NO_ACTION)
+    #LightGray::Set nextStop to "";
+    note right
+        The stops as a
+        consequence of
+        not having another
+        stop to drive to.
+    end note
+    #LightGray:Autonomy cancels driving;
+    #Pink:send status with IDLE state;
+case (\n   START)
+    if (Is list of stops empty?) then (No)
+        if (Is nextStop equal to name of stops[0]?) then (No)
+            #LightGray::Set nextStop to first
+            stop in the stop list;
+            #LightGray:Autonomy cancels driving;
+            #LightGray:Start driving to nextStop;
+            #Pink:send status with DRIVE state;
+        else (Yes)
+        endif
+    else (Yes)
+        #LightGray:Set nextStop to "";
+        #LightGray:Autonomy cancels driving;
+        #Pink:send status with IDLE state;
+    endif
+endswitch
+stop
+
+@enduml
diff --git a/docs/uml/exported_diagrams/command_activity_diagram.png b/docs/uml/exported_diagrams/command_activity_diagram.png
diff --git a/resource/external_server_example_config.json b/resource/external_server_example_config.json
@@ -0,0 +1,10 @@
+{
+    "api_url": "http://localhost:8080",
+    "api_key": "StaticAccessKeyToBeUsedByDevelopersOnEtna",
+    "company_name": "bringauto",
+    "car_name": "virtual_vehicle",
+    "max_requests_threshold_count": "10",
+    "max_requests_threshold_period_ms": "5000",
+    "delay_after_threshold_reached_ms": "5000",
+    "retry_requests_delay_ms": "200"
+}