[Firmware][SDK][Doc] Major refactor and protocol update

.gitignore

@@ -1,8 +1,9 @@
 
 firmware/build/
 
-sdk/bin/
-sdk/build/
+sdk/master_board_sdk/bin/
+sdk/master_board_sdk/build/
+sdk/master_board_sdk/graphs/
 
 firmware/sdkconfig\.old
 

README.md

@@ -24,13 +24,15 @@ Documentation
 -------------
 Here are some helpful links to the documentation :
 
-[How to flash the Master Board (install esp-idf and flash the firmware)]( firmware/README.md )
+[How to flash the Master Board (install esp-idf and flash the firmware)](firmware/README.md)
 
 [SDK : How to prepare your interface and run the example](sdk/master_board_sdk/README.md ) 
 
-[Description of the communication between the Master Board and the computer]( documentation/masterboard_communication.md )
+[Master Board State Machine Description](documentation/masterboard_state_machine.md)
 
-[Description of the BLMC µDriver SPI interface]( documentation/BLMC_%C2%B5Driver_SPI_interface.md )
+[Description of the communication between the Master Board and the computer](documentation/masterboard_communication.md)
+
+[Description of the BLMC µDriver SPI interface](documentation/BLMC_%C2%B5Driver_SPI_interface.md)
 
 [Wiring the MasterBoard](documentation/masterboard_wiring.md)
 

documentation/BLMC_µDriver_SPI_interface.md

@@ -60,7 +60,7 @@ ES | EM1 | EM2 | EPRE | EI1OC | EI2OC | - | - | Timeout | Timeout | Timeout | Ti
 |---|---|---|
 ES<15> (Enable System) | 0: Disable the system, motor can not be controlled<br>1: Enable the system| When the system is disabled, no current is sent to the motor. This can be useful to trigger a safety stop. |
 EM1 <14> (Enable Motor 1) | 0: Disable Motor 1<br>1: Enable Motor 1 | Enabling Motor will trigger the calibration procedure, aligning the rotor to a known magnetic field orientation. Minimal load should be applied while calibrating the motor. |
-EM2 <13> (Enable Motor 1) | 0: Disable Motor 2<br>1: Enable Motor 2 | Enabling Motor will trigger the calibration procedure, aligning the rotor to a known magnetic field orientation. Minimal load should be applied while calibrating the motor. |
+EM2 <13> (Enable Motor 2) | 0: Disable Motor 2<br>1: Enable Motor 2 | Enabling Motor will trigger the calibration procedure, aligning the rotor to a known magnetic field orientation. Minimal load should be applied while calibrating the motor. |
 EPRE <12> (Enable Position Rollover Error for both motors) | 0: Disable the Rollover Error<br>1: Enable the Rollover Error | Rollover can happen if position is coded with a maximum range from -128 to 128 (approximately, see Data representation below). Enable the Rollover error will generate an error reported in the Status Field and will disable the system. |
 EI1OC <11> (Enable Index 1 Offset Compensation) | 0: Disable Index Offset Compensation <br>1: Enable Index Offset Compensation | Incremental encoders often include an index line that can help to deduce the absolute position of the rotor shaft modulo one turn.<br>If EIxOC is set to one, and if IDXxD has been reported in the Status word, Position will be offset to be zero at the first index detected.<br>/!\ WARNING: Setting this bit will cause the position to jump. User need to take extra care if closed loop controller uses the position as feedback. | 
 EI2OC <10> (Enable Index 2 Offset Compensation) | 0: Disable Index Offset Compensation <br>1: Enable Index Offset Compensation | Incremental encoders often include an index line that can help to deduce the absolute position of the rotor shaft modulo one turn.<br>If EIxOC is set to one, and if IDXxD has been reported in the Status word, Position will be offset to be zero at the first index detected.<br>/!\ WARNING: Setting this bit will cause the position to jump. User need to take extra care if closed loop controller uses the position as feedback. | 

documentation/masterboard_communication.md

@@ -36,17 +36,36 @@ The interface on the PC needs to support monitor mode and injection. ASUS PCE-AC
 
 Data packet
 -----------
+
+### Current protocol version: **3**
+
 Both WiFi and Ethernet use the same data packet format.
 
-There are two types of packets. Packets coming from the computer are called **Command** packets, and packets coming from the master board are called **Sensor** packets.
+There are four types of packets. Packets coming from the computer containing command data are called **Command** packets, and packets coming from the master board containing sensor data are called **Sensor** packets. On top of these two, an initialization packet called **Init** packet is used to put the master board in its control mode and bond it to an interface running on the computer. The master board will respond to an initialization packet with an acknowledgement packet called **Ack** packet. 
+
+All packets contain a number called **Session ID** identifyng the link between the master board and a specific instance of the interface. This is used to prevent multiple programs from controlling the robot at once. The **Init** packet is used to set it up.  
+**Session Id** of **0** is reserved for when the masterboard boots up and should not be used otherwise.
+
+### Init packet (4 Bytes)
+Protocol version | Session ID |
+--- | ---
+2 bytes | 2 bytes
+
+The **Protocol version** field is used to ensure both the interface and the masterboard firmware use the same protocol. The master board checks it when receiving an **Init** packet.
+
+### Ack packet (3 Bytes)
+Session ID | SPI connected
+--- | --- 
+2 bytes | 1 byte
 
-Both packets encapsulate 6 BLMC µDriver SPI interface packets,  without the **Index** and **CRC** fields. Additional, sensor packets also include IMU measurement and AHRS estimation.
+The **SPI connected** field contains an 8 bit integer, each bit of which tells whether or not the corresponding SPI slave is connected (Least significant bit: SPI0, most significant bit: SPI7).
 
+Both **Command** and **Sensor** packets encapsulate 6 BLMC µDriver SPI interface packets,  without the **Index** and **CRC** fields. Additional, sensor packets also include IMU measurement and AHRS estimation.
 
-### Sensor packet (196 Bytes)
-µDriver0 | µDriver1 | µDriver2 | µDriver3 | µDriver4 | µDriver5 | IMU | Sensor Index | Last Command Index
---- | --- | --- | --- | --- | --- | --- | --- | ---
-28 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 18 Bytes | 2 Bytes | 2 Bytes
+### Sensor packet (200 Bytes)
+Session ID | µDriver0 | µDriver1 | µDriver2 | µDriver3 | µDriver4 | µDriver5 | IMU | Sensor Index | Packet Loss | Last Command Index
+--- | --- | --- | --- | --- | --- | --- | --- | --- | --- | ---
+2 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 24 Bytes | 2 Bytes | 2 Bytes | 2 Bytes
 
 **µDriverX** corresponds to a BLMC µDriver SPI interface sensor packet without the CRC and index fields.
 
@@ -66,13 +85,14 @@ AHRS R-P-Y | 16bits | rad | -4 | 3,9998779297 | 2^(-13)
 
 **Sensor Index** is a packet index to track packet loss.
 
-**Last Command Index** is the index of the last received command index, and can be used to track packet loss.
+**Packet Loss** is the number of command packets lost since the initialization, computed by the master board using **Command Packet**'s **Command Index**.
 
+**Last Command Index** is the index of the last **Command Packet** received, used to compute the latency of the communication
 
-### Command packet (170 Bytes)
-µDriver0 | µDriver1 | µDriver2 | µDriver3 | µDriver4 | µDriver5 | Command Index
---- | --- | --- | --- | --- | --- | --- 
-28 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 2 Bytes
+### Command packet (172 Bytes)
+Session ID | µDriver0 | µDriver1 | µDriver2 | µDriver3 | µDriver4 | µDriver5 | Command Index
+--- | --- | --- | --- | --- | --- | --- | --- 
+2 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 28 Bytes | 2 Bytes
 
 **µDriverX** corresponds to a BLMC µDriver SPI interface command packet without the CRC and index fields.
 

documentation/masterboard_state_machine.md

@@ -0,0 +1,27 @@
+# Master Board State Machine
+
+The master board runs a state machine that handles the differents stages of communication and errors that can occur.
+
+State machine description and behaviour
+---
+[![master board state machine diagram](../images/master_board_state_machine.svg)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoic3RhdGVEaWFncmFtXG4gICAgc3RhdGUgXCJTRVRVUFwiIGFzIFNFVFVQOiBTZXR0aW5nIHVwIGFsbCBjb21wb25lbnRzXG4gICAgc3RhdGUgXCJXQUlUSU5HX0ZPUl9JTklUXCIgYXMgV0FJVElOR19GT1JfSU5JVDogV2FpdGluZyBmb3IgYW4gSW5pdCBwYWNrZXQgZnJvbSBQQ1xuICAgIHN0YXRlIFwiU1BJX0FVVE9ERVRFQ1RcIiBhcyBTUElfQVVUT0RFVEVDVDogRGV0ZWN0aW5nIGNvbm5lY3RlZCBTUEkgc2xhdmVzXG4gICAgc3RhdGUgXCJTRU5ESU5HX0lOSVRfQUNLXCIgYXMgU0VORElOR19JTklUX0FDSzogU2VuZGluZyBBY2tub3dsZWRnZW1lbnQgcGFja2V0IHRvIFBDXG4gICAgc3RhdGUgXCJBQ1RJVkVfQ09OVFJPTFwiIGFzIEFDVElWRV9DT05UUk9MOiBSb2JvdCBhY3RpdmVseSBjb250cm9sbGVkIGJ5IHRoZSBQQ1xuICAgIHN0YXRlIFwiV0lGSV9FVEhfTElOS19ET1dOXCIgYXMgV0lGSV9FVEhfTElOS19ET1dOOiBFdGhlcm5ldCBsaW5rIGlzIGRvd25cbiAgICBzdGF0ZSBcIldJRklfRVRIX0VSUk9SXCIgYXMgV0lGSV9FVEhfRVJST1I6IFRpbWVvdXQsIG5vIHBhY2tldCBmcm9tIFBDXG5cbiAgICBbKl0gLS0-IFNFVFVQXG4gICAgU0VUVVAgLS0-IFdBSVRJTkdfRk9SX0lOSVQ6IFNldHVwIGRvbmUgaW4gV2lGaVxuICAgIFxuICAgIFdJRklfRVRIX0xJTktfRE9XTiAtLT4gV0lGSV9FVEhfRVJST1I6IEV0aGVybmV0IExpbmsgVXBcblxuICAgIFdBSVRJTkdfRk9SX0lOSVQgLS0-IFNQSV9BVVRPREVURUNUOiBJbml0IHBhY2tldCByZWNlaXZlZFxuICAgIFxuICAgIFNQSV9BVVRPREVURUNUIC0tPiBTRU5ESU5HX0lOSVRfQUNLOiBOdW1iZXIgb2YgdGVzdCB0cmFuc2FjdGlvbnMgZXhjZWVkZWRcblxuICAgIFNFTkRJTkdfSU5JVF9BQ0sgLS0-IFdJRklfRVRIX0VSUk9SOiBUaW1lb3V0IGFja25vd2xlZGdlbWVudFxuICAgIFNFTkRJTkdfSU5JVF9BQ0sgLS0-IEFDVElWRV9DT05UUk9MOiBGaXJzdCBjb21tYW5kIHBhY2tldCByZWNlaXZlZFxuXG4gICAgQUNUSVZFX0NPTlRST0wgLS0-IFdJRklfRVRIX0VSUk9SOiBUaW1lb3V0IGNvbnRyb2xcblxuICAgIFdJRklfRVRIX0VSUk9SIC0tPiBTUElfQVVUT0RFVEVDVDogSW5pdCBwYWNrZXQgcmVjZWl2ZWRcbiIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In19)
+
+Diagram generated using [Mermaid](https://github.com/mermaid-js/mermaid) Live Editor, click on picture to edit.
+
+During **WAITING_FOR_INIT**, the master board waits for an init message from both ethernet and wifi, checking all channels. This enables an autoselection of the type of communication with the computer.
+
+Please note that **WIFI_ETH_LINK_DOWN** state is accessible from any state except WAITING_FOR_INIT via a callback on the ethernet link down event, but links have not been drawn for the sake of readability.
+
+State machine LED code
+---
+To each state is associated a LED behaviour.
+
+State | LED behaviour
+--- | ---
+SETUP | Steady White
+WAITING_FOR_INIT | Red Fade
+SPI_AUTODETECT | Magenta Fade
+SENDING_INIT_ACK | Blue Fade
+ACTIVE_CONTROL | Green Fade
+WIFI_ETH_LINK_DOWN | Yellow Blink
+WIFI_ETH_ETH_ERROR | Red Blink

firmware/README.md

@@ -4,9 +4,7 @@ Install esp-idf
 --------
 The master board is based on a ESP32 module programmed in C++ using the expressif idf SDK https://github.com/espressif/esp-idf
 
-To install the SDK simply follow the instruction form https://docs.espressif.com/projects/esp-idf/en/stable/get-started/.
-
-Please checkout the github issue about the esp-idf version: https://github.com/open-dynamic-robot-initiative/master-board/issues/3.
+To install the SDK (v4.0.1) simply follow the instruction form https://docs.espressif.com/projects/esp-idf/en/v4.0.1/get-started/index.html.
 
 Firmware of the ESP32 can be found here https://github.com/open-dynamic-robot-initiative/master-board.
 
@@ -30,17 +28,7 @@ On a freshly assembled board, we first need to burn a configuration fuse  becaus
 
 `python espefuse.py set_flash_voltage 3.3V`
 
-To flash the board, the esp environment variables must be sourced and a special branch must be checked out. Assuming the `esp-idf` installation is under `~/esp/esp-idf`:
-
-```
-cd ~/esp/esp-idf
-git checkout v4.0 # The export.sh is only available at newer versions.
-source export.sh
-git checkout 8d1a9c0 # Need to checkout this old version for now
-git submodule update --init --recursive
-```
-
-Then, from the `master-board/firmware` folder, you can run:
+To flash the board, from the `master-board/firmware` folder, you can run:
 
 * Flash the board: `make flash`
 * Change configurations: `make menuconfig`