Add example of module documentation into ./doc folder

Author: jiri.strouhal

docs/module_documentation_template.md

@@ -1,45 +1,54 @@
 # 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.
+<!-- 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. -->
 
-Example:
-
-The Test module is provides communication between car test devices and the testing application. For more details on the usage of the module, see the [README](<path-to-readme>).
--->
+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.
 
 # Identification and supported devices
 
-<!-- Provide a list of supported devices and their identification.
-
-Example:
+<!-- Provide a list of supported devices and their identification. -->
 
-The module number/ID: `0`
+The module number/ID: `1000`.
 
 ## Devices
 
-| **Device Name** | **Device Type** | **Device Roles** | Comment                                          |
-| --------------- | --------------- | ---------------- | ------------------------------------------------ |
-| Test Button 1   | 0               | test-button-1    | Button verifying that the commands can be sent to a device of this module |
-| Test Button 2   | 0               | test-button-2    | Button verifying that the commands can be sent to a device of this module |
-| Test Camera     | 1               | test-camera      | Camera verifying quality and rate of data transfer from car |
--->
+| **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.
+# Messages
 
-Example of a status description:
+<!-- 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
 
-The status message contains information about test components with their state (`ON` or `OFF`).
+Each device (button) expects a status message containing a single key `pressed` with a boolean value indicating whether the button is pressed.
 
 ### Example
 
 ``` json
-{"state": "ON"}
+{
+    "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
 
@@ -50,3 +59,11 @@ The status message contains information about test components with their 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.
+These devices is a virtual button which sends its current state and expects state of it's 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 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.
+
 ### 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`):
+
 ```yaml
 - button1_name:
     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.
+> Manual mode of actual button pressing on keyboard can be specified by `--manual` argument.