Merge pull request #7 from bringauto/BAIP-239/module-documentation-template

Baip 239/module documentation template

Author: jiristrouhal

README.md

@@ -3,6 +3,8 @@ This is the implementation of Example module. Repo contains example_module libra
 This module serves as an example for module maintainers to implement their own modules outside reserved range of modules. It is not intended to be used in production.
 Module number of this module is 1000.
 
+For more details on the module, see [module documentation](./docs/module_documentation_template.md).
+
 # Requirements
 
 - fleet protocol library - [v2.0.0](https://github.com/bringauto/fleet-protocol/releases/tag/v2.0.0)

docs/example_module.md

@@ -0,0 +1,69 @@
+# Introduction
+
+<!-- Provide a single sentence or a short paragraph describing the module's purpose. When using the documentation inside repository, add link to the README and vice versa - link the README to this documentation. -->
+
+This module serves as an example for module maintainers to implement their own modules outside reserved range of modules and does not serve any role in the production environment. For usage of this module, see the [README](../README.md).
+
+# Identification and supported devices
+
+<!-- Provide a list of supported devices and their identification. -->
+
+The module number/ID: `1000`.
+
+## Devices
+
+| **Device Name** | **Device Type** | **Device Roles** | Comment                                     |
+| --------------- | --------------- | ---------------- | ------------------------------------------- |
+| button1         | 0               | test             | Button driving a state of a dedicated LED   |
+| button1         | 10              | test             | Button driving a state of a dedicated LED   |
+| button2         | 0               | test2            | Button driving a state of a dedicated LED   |
+
+
+# Messages
+
+<!-- Describe all types of messages handled by the module (including status, status error and command). For each type, describe the message contents, structure and example of the message. -->
+
+## Status
+
+Each device (button) expects a status message containing a single key `pressed` with a boolean value indicating whether the button is pressed.
+
+### Example
+
+``` json
+{
+    "pressed": true
+}
+```
+## Status Error
+
+Status errors are not defined for this module.
+
+## Command
+
+Each device (button) expects a command message containing a single key `lit_up` with a boolean value indicating whether the LED should be lit up.
+
+### Example
+
+``` json
+{
+    "lit_up": true
+}
+```
+
+# Details of supported devices
+
+<!-- In this section, list all supported devices. Describe their purpose on the car and their behavior relevant to the application accessing the devices through the module. This includes mainly
+
+- the device state machine,
+- how the status machine reflects the state machine's state,
+- how the state is affected by the received command.
+
+-->
+
+## Button
+
+Button is a simple button device which has one LED attached to it. As status, it sends JSON with key `"pressed"` indicating whether button is pressed. As command, it expects JSON with key `"lit_up"` indicating the desired state of internal LED.
+
+See the state transition diagram below:
+
+![Button state diagram](./uml/exported_diagrams/button_state_transition_diagram.png)

docs/uml/button_state.puml

@@ -0,0 +1,16 @@
+@startuml button_state_transition_diagram
+    skinparam style strictuml
+
+    !define state_color #77cdff
+
+    state Pressed state_color
+    state NotPressed state_color
+
+    hide empty description
+
+    Pressed ---> NotPressed: turn off
+    Pressed -up-> Pressed: lit up
+    NotPressed ---> Pressed: lit up
+    NotPressed -up-> NotPressed: turn off
+
+@enduml

docs/uml/exported_diagrams/button_state_transition_diagram.png

@@ -1,36 +1,46 @@
 # Internal client examples
 
-This repo contains implementation of example module device using internal client for fleet protocol v2.
-These devices is a virtual button which sends it's current state and expects state of it's LED as response.
+This repo contains an implementation of the Example Module using the Internal Client for Fleet Protocol v2.
+The devices supported by this module are virtual buttons which send their current state and expect state of their LED as response.
 
 #### Preparing environment
+
 Before running example devices, it is good practice to create a virtual environment:
-```
+
+```bash
 python -m venv .venv
 source .venv/bin/activate
 ```
+
 Install dependencies:
-```
+
+```bash
 pip install -r requirements.txt
 ```
 
 ## Button
-Button is a simple button device which has one LED attached to it. As status, it sends json with key `"pressed"` indicationg wheter button is pressed. As command, it expects json with key `"lit_up"` indicating the desired state of internal LED.
+
+Button is a simple button device with one LED attached to it. As status, it sends JSON with key `"pressed"` indicating whether button is pressed. As command, it expects JSON with key `"lit_up"` indicating the desired state of internal LED.
+
 ### Usage
-Fake buttons can be run with `run_buttons.py` script. It expects config in `yaml` format which specifies attributes for button or multiple buttons (see `buttons.yaml`):
+
+Fake buttons can be run with the `run_buttons.py` script. It expects config in `yaml` format which specifies attributes for a button or multiple buttons (see `buttons.yaml`):
+
 ```yaml
 - button1_name:
-    type: <int> specifying module specific device type (default is 0)
+    type: <int> specifying module-specific device type (default is 0)
     role: <str> device role
     priority: <int> device priority (default is 0)
 
-- button2_name:
-    ...
+- button2_name: ...
 ```
+
 To run use:
-```
+
+```bash
 python run_buttons.py --ip <server_ip> --port <server_port> --config <path_to_yaml>
 ```
-Multiple fake buttons will be created according to yaml config. They will try to connect to specified server, generate and send their statuses periodically and set their LED states according to commands.
 
-> Manual mode of actual button pressing on keyboard can be specified by `--manual` argument.
+Multiple fake buttons will be created according to yaml config. They will try to connect to the specified server, generate and send their statuses periodically, and set their LED states according to commands.
+
+> The manual mode of the actual button pressing on the keyboard can be specified by `--manual` argument.