docs(bms-monitor): add LTC6811 documentation

docs/.pages

@@ -0,0 +1,5 @@
+title: MicroLibs
+nav:
+    - index.md
+    - bms-monitor
+    - error-utils

docs/bms-monitor/bms-monitor.md

@@ -0,0 +1,17 @@
+# BMS Monitor
+
+The **Battery Management System Monitor** is a board designed with the purpose of monitoring battery pack cell voltages and temperatures as well as discharge the cells to achieve passive or active balancing through the needed configuration.
+
+The board is made up of two stacks, each having a single [LTC6811](https://www.analog.com/media/en/technical-documentation/data-sheets/LTC6811-1-6811-2.pdf). \
+Each stack can be used individually or can be connected in a [daisy-chain](https://en.wikipedia.org/wiki/Daisy_chain_(electrical_engineering)) configuration using the isoSPI protocol.
+
+![bms-monitor](images/bms-monitor/bms-monitor.png)
+
+Commands can be sent from a microcontroller to the daisy chain via SPI protocol as described in the datasheet, and each command depends.
+
+The library is divided in three sections:
+1. The [LTC6811 API](ltc6811/ltc6811.md)
+2. [Voltage reading](volt) utilities
+3. [Temperature reading](temp) utilities
+
+Each section depends on a single [configuration file](monitor-config/monitor-config.md) which is mainly used to define constants, types and structures used for the possible LTCs configurations.

docs/bms-monitor/ltc6811/ltc6811.md

@@ -0,0 +1,117 @@
+# LTC6811
+
+The **LTC6811** is a multicell battery stack monitor that measures up to 12 series connected battery cells, as described in the [datasheet](https://www.analog.com/media/en/technical-documentation/data-sheets/ltc6811-1-6811-2.pdf).
+
+The LTC6811 has two possible configurations, for our purposes we use the *LT6811-1* configuration which supports a daisy chain configuration. \
+In this configuration there are:
+- 13 *C* pins which are used to measure the cell voltages
+- 12 *S* pins used for the discharge of the cells
+- 5 GPIO that are used to get the cells temperatures via a multiplexer
+- The *DTEN* pin which enables the **discharge timer**
+- Other pins dedicated for the SPI peripheral or voltage references
+
+> Refer to the datasheet for more details.
+
+![ltc6811-1](images/bms-monitor/ltc6811.png)
+
+The chip has two internal timers:
+1. The **watchdog timer** which is always enabled and elapse after $t_{SLEEP} = 2s$ (it resets after every valid command)
+2. The **discharge timer** which is used to keep the discharge switches turned ON for a programmable period of time
+
+---
+
+Each operation performed by the LTC6811 is controlled by two separate [state machines](https://en.wikipedia.org/wiki/Finite-state_machine), \
+one for the the isoSPI peripheral and the other for the core functions.
+
+### IsoSPI state machine
+
+The isoSPI state machine has three possible states:
+1. Idle
+2. Ready
+3. Active
+
+![spi-fsm](images/bms-monitor/ltc-spi-fsm.png)
+
+The standby state is a **low power state** where the isoSPI ports are powered down, \
+when a *Wake-up signal* is received the FSM goes to the ready state where the LTC6811 is ready for communication. \
+In the ready state after a time of $t_{IDLE} = 5.5ms$ the FSM goes back to the idle state, \
+if any data is transmitted or received before $t_{IDLE}$ is elapsed the isoSPI goes to the active state and it remains until the end of the communication.
+
+### Core state machine
+
+The core state machine of the LTC6811 has five states:
+1. Sleep
+2. Standby
+3. Measure
+4. Refup
+5. Extended balancing
+
+![core-fsm](images/bms-monitor/ltc-core-fsm.png)
+
+The sleep state is a **low power state** where the voltage references and the ADCs are powered down, \
+if a *Wake-up signal* is received the FSM goes to the standby state. \
+In the standby state the voltage references and ADCs are still off but the *watchdog timer* and/or the *discharge timer* are running. \
+When a valid command is received the FSM enters either the refup or measure state, \
+otherwise, if no valid commands are received for $t_{SLEEP}$, it enters the sleep state or the extended balancing state if the discharge timer is enabled. \
+The refup state is a special state where the LTC6811 can initiate the conversions more quickly than from the standby state. \
+The measure state is used only for ADC conversion or diagnostic commands. \
+The extended balancing state is used only when the watchdog timer has expired but the discharge timer is still running.
+
+
+### Reset behaviours
+
+During each operation there are some cases where the LTC6811 resets some registers. \
+Each power cycle resets **all** registers and state machines.
+
+**Cell discharge** gets disabled after a power cycle, a thermal shutdown or a watchdog or discharge timeout. \
+The **configuration register** resets if the watchdog or discharge timer expires; \
+if the watchdog timeout happens while the discharge timer is running only the first four bytes of the configuration register reset, \
+and if the discharge timer expire while the watchdog timer as not elapsed yet only the last two byte of the configuration register reset.
+
+For more details refer to the datasheet in the *Reset behaviours* section.
+
+
+### Commands
+
+> IMPORTANT: The default value (which is ignored by the LTC6811) is 0xFF
+
+The LTC6811-1 configuration used for daisy chain setups support **broadcast commands only** because they have no addressing. \
+All devices in the chain receive the command bytes *simultaneously*. \
+
+###### Broadcast command format
+| NAME | RD/WR | BIT 7 | BIT 6 | BIT 5 | BIT 4 | BIT 3 | BIT 2 | BIT 1 | BIT 0 |
+| ---- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- | ----- |
+| CMD0 |   WR  |   0   |   0   |   0   |   0   |   0   | CC[10]| CC[9] | CC[8] |
+| CMD1 |   WR  | CC[7] | CC[6] | CC[5] | CC[4] | CC[3] | CC[2] | CC[1] | CC[0] |
+
+Where `CC[i]` is the command i-th byte.
+
+A **single command** needs to be sent in order to start the corresponding operation in all devices of the chain, \
+then the stacked devices effectively turn into a *cascaded shift register*, in which data is shifted through each device to the next higher (on write) or the next lower (on read). \
+When a command is sent the Chip Select (CS) pin is pulled low for the entire duration of the communication, then it is pulled again high at the end.
+
+There are three types of commands for the LTC6811:
+1. Poll command
+2. Write command
+3. Read command
+
+###### Poll command format
+| NUMBER OF BITS |    16   |      16     |   8  |
+| -------------- | ------- | ----------- | ---- |
+| CONTENT        | command | command PEC | 0xFF |
+
+###### Write command format
+| NUMBER OF BITS |    16   |      16     |          48         |        16       |       |          48          |        16        |
+| -------------- | ------- | ----------- | ------------------- | --------------- | ----- | -------------------- | ---------------- |
+| CONTENT        | command | command PEC | last device payload | last device PEC |  ...  | first device payload | first device PEC |
+
+###### Read command format
+| NUMBER OF BITS |    16   |      16     |          48          |        16        |       |         48          |        16       |
+| -------------- | ------- | ----------- | -------------------- | ---------------- | ----- | ------------------- | --------------- |
+| CONTENT        | command | command PEC | first device payload | first device PEC |  ...  | last device payload | last device PEC |
+
+The **Packer Error Code** (PEC) is a 16 bit checksum used by the LTC6811 to verify the correctness of the received data, \
+for more information refer to the datasheet *operation* section in the Packet Error Code paragraph.
+
+The **Wake-up signal** is a single byte with the default value, sent once for each LTC in the daisy chain. \
+For each command, if $t_{IDLE}$ time is elapsed a wake-up signal is sent before the actual command, to enable each device of the daisy chain for communication.

docs/bms-monitor/monitor-config/monitor-config.md

@@ -0,0 +1,14 @@
+# BMS monitor configuration
+
+The configuration file of the BMS monitor is pretty simple, it contains a single macro and three types.
+
+The `LTC_COUNT` macro defines the number of LTC6811 in the daisy chain but can be 1 if used individually. \
+The redefined types are:
+- `raw_voltage_t` used for **raw voltage** measures
+- `voltage_t` used for **converted voltage** measures in *mV*
+- `temperature_t` used for **converted temperature** measures in *°C*
+
+There is no raw temperature value because it is measured as a voltage that have to be converted 
+
+> ATTENTION: If you use the BMS monitor library remember to redefine this macro using the appropriate flag of the compiler \
+> (e.g. `gcc -D LTC_COUNT=1 ...`, `gcc -imacros "path/to/redefinition/file" ...`)

docs/docs.yml

@@ -0,0 +1,3 @@
+name: Micro Libs
+author: Matteo Bonora - Federico Carbone - Alex Sartori - Simone Ruffini - Antonio Gelain - Riccardo Benevelli
+car: fenice-evo

docs/index.md

@@ -0,0 +1,5 @@
+# Micro Libs
+
+The [micro-libs](https://github.com/eagletrt/micro-libs) repository is a collection of libraries targeted for **microcontrollers**
+
+The majority of the libraries depends on the HAL library used specifically with the ST microcontrollers