diff --git a/README.md b/README.md index 6df0aaa..1f9bca1 100644 --- 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 new file mode 100644 index 0000000..b86bd50 Binary files /dev/null and b/docs/images/image.png differ diff --git a/docs/mission_module.md b/docs/mission_module.md new file mode 100644 index 0000000..d94cd00 --- /dev/null +++ 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 new file mode 100644 index 0000000..757e0fa --- /dev/null +++ b/docs/uml/command.puml @@ -0,0 +1,69 @@ +@startuml command_activity_diagram + +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 \ No newline at end of file diff --git a/docs/uml/exported_diagrams/command_activity_diagram.png b/docs/uml/exported_diagrams/command_activity_diagram.png new file mode 100644 index 0000000..b8a3c0c Binary files /dev/null and b/docs/uml/exported_diagrams/command_activity_diagram.png differ diff --git a/resource/external_server_example_config.json b/resource/external_server_example_config.json new file mode 100644 index 0000000..89b31ed --- /dev/null +++ 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" +} \ No newline at end of file