Add documentation for temperature sensor

Update the documentation with explanation of conversion from celsius to raw
Udpate summary window for temperature sensor

docs/temperature_sensors/index.md

@@ -0,0 +1,5 @@
+## Temperature Sensors
+We collect here information regarding the temperature sensors of the `ergoCub` motors.
+
+- [Reading Temperature Data](./software/reading_data.md)
+- [Temperature Sensor Data Flow](./software/dataflow.md)

docs/temperature_sensors/software/dataflow.md

@@ -0,0 +1,44 @@
+## Temperature Data Flow
+
+Generally speaking the data flow is quite simple. Summing up the whole flow, we have that:
+
+- configuration data, i.e. type of sensor and temperature warning and hardware limits, are parsed by the high level
+- if everything goes fine, the hardware temperature limit is converted to its raw value and the boolean defining the presence of a temperature sensor is set, then these data are sent down to the `EMS` baord via ETH
+- the `EMS` board parses the hardware temperature limit and send it via a spefic CAN message to the `FOC` baord.
+- the `FOC` baord parses the received CAN frame, configures the limits and activates the periodic reading of the temperature from the I2C
+- with a frequency of 207.48 Hz the routine that reads the temperature from the I2C continues to cycle
+    - if the value of the read temperature overcomes the hardware limit the specific error bit is risen and this status is sent up to the `EMS`, so that it can put the motor is fault
+- with a frequency of 1KHz the routine of the CAN frames transmission is called and with a frequency of 10Hz we send the CAN frame containing the raw temperature value up to the `EMS`
+- the CAN frame coming from the `FOC` board is parsed by the EMS and saved locally in the memory
+- each 2ms (in general, but this value can be personalized in the configuration files) the ETH callback, needed for getting the motor status basic info, is called
+- if the callback is called correctly the high level convert the raw value to Celsius depending on the type of sensor
+
+### Main Flow of Information
+
+- **Transmission of configuration data down to the low level firmware**
+
+Here's a short flow diagram showing how the configuration data related to the temperature sensors are parsed by the high level software and sent down to the low level firmware.
+Precisely, the info we are sending down are the hardware temperature limit (necessary for rising the overheating fault at its overcome) and a boolean value defining the presence or not of the temperature sensor.
+
+<p align="center">
+    <img  src="../img/temperatureParsingDiagram.drawio.png" width="700">
+</p>
+
+- **Transmission of raw temperature data up to the high level software**
+
+Here's a short flow diagram showing how the temperature value retrieved from the temperature sensor and evaluated by the TDB (Temperature Detection Board) is sent up to the high level software, so that it can be available for the end user. 
+As a matter of fact, the end user can prompt the updated temperature value in Celsius Degree to a yarp port exploiting specific Motion Control APIs inside a RF Module type application, which should be designed by the end user.
+A model application, which has been used for testing is available at [this link](https://github.com/MSECode/motionControlModule)
+
+<p align="center">
+    <img  src="../img/TemperatureDiagram.drawio.png" width="700">
+</p>
+
+- **Sequence Diagram**
+
+Here's a short sequence diagram showing at a high level how the different parts of the code interact among each others.
+
+<p align="center">
+    <img  src="../img/MotorTemperature-Feature.png" width="700">
+</p>
+

docs/temperature_sensors/software/reading_data.md

@@ -0,0 +1,75 @@
+## Reading Raw Temperature Data
+
+Each temperature sensor outputs an integer raw value whose range depends on the type of temperature sensor the motor is provided with.
+Currently we can configure and exploit two type of sensors: `PT100` and `PT1000`. Anyways, if you happen to take a look to the low level firmware code, you can notice that in some line the temperature is set to `-5000` by default. This has been done because, since the temperature values will always be greater than `-5000`, we have chosen this value as the Temperature initialization value. Moreover, if there is an error in the reading of the temperature on the I2C protocol line, we will set that value as an error value for the raw output.
+Regarding the typical raw value, we have that usuallu, for `PT100` sensor the temperatures generally ranges between `0` and `3500`, instead for the `PT1000` the temperatures ranges between `0` and `8000`. Anyhow, it should be noted that negative temperatures are accepted, even if it would be extremely rare to get them in normal working conditions. Finally, generally speaking we have that higher the temperature and higher the raw output value.
+
+## Reading Compensated Temperature Data
+
+At this point and supposed we are not interested in the technical aspects of the layers of code between the low machine and the high user level, one could ask how the user can see a temperature in Celsius Degree published on the yarp port and not in raw value and how it is possible to set the configuration values in Celius Degree and work at the lower firmware level with raw values.
+So here follows a brief description of the two data conversion that we are employing in the code. Both of them are based on the same principle of the voltage divider and the conversion factors depends directly on the type of temperature sensor we are using.
+
+### Data conversion from raw value to Celsius degree value
+
+For a technical point of view, when we are receiving the raw value from the low level we convert them to Celsius Degree following a predefined equation that depends on multiple factors as described here.
+The base of the equation is a simple voltage divider that constitutes the TDB (Temperature Detection Board), which is used to evaluate the value in `Ohm` that comes from the `PTXXX` and outputs a raw value.
+Thus, considering we are basing on a voltage divider, we are doing the following:
+
+```console
+
+Evaluate a first temporary value:
+    
+    double tmp = temperature * ((_resolution_pga) / (_pga_gain * _vcc * (_resolution_tdb + 1)));
+
+where:
+- _resolution_pga: resolution of the pga after the TDB, which is set to 2.048
+- _resolution_tdb: resolution of the tdb micro, which is set to 32767 since it works at 16bit and we are saving the value to a signed int
+- _vcc: incoming voltage in the voltage divider, which for us is set to 5V
+- _pga_gain: gain for the pga, which we have set to 2
+        
+The use the calculated temporary value for calulating the denominator of the final operation:
+    
+    double den = _ptc_gradient * (_r_2 - _r_2*tmp - _r_3*tmp);
+
+where:
+- _ptc_gradient: slope of the PTXXX line
+- _r_2: one of the two upper resistors in the voltage divider bridge, which for us is equal to 4700
+- _r_3: lower resistor of the bridge, which it should be set equal to the value, in Ohm, of the PTXXX at zero degree. Thererfore, if we are using the PT100 it should be equal to 100
+
+Finally, the last calulation that outputs the value of the got temperature in Celsius Degree is:
+
+    double res = (tmp * (_first_res_coeff) / den) + ((_second_res_coeff) / den);
+
+where:
+- _first_res_coeff  = _r_1*_r_2 + _r_1*_r_3 + _ptc_offset*_r_2 + _ptc_offset*_r_3
+- _second_res_coeff = _r_3*_r_1 - _r_2*_ptc_offset
+- _ptc_offset: is the offset of the PTXXX line, thus it is 1000 in the case of PT1000 and 100 in the other case.
+
+It should be noted that those offsets are used to have the PTXXX line passes through zero at 0 Celsius Degree.
+
+```
+
+### Data conversion from Celius degree value to raw value
+
+Similarly to what defined above, when we are parsing the temperature limits from the configuration files, before sending them down to the firmware level, we are converting them to the raw value as follows:
+
+```console
+
+    double tmp = (( (_ptc_offset + _ptc_gradient * temperature) / ((double)_r_1 + (_ptc_offset + _ptc_gradient * temperature))) - _half_bridge_resistor_coeff) * (double)_vcc;
+    double res = (_resolution_tdb + 1) * ((_pga_gain * tmp) / _resolution_pga);
+
+where:
+- temperature: temperature limit value passed in Celsius degree
+- _ptc_gradient: slope of the PTXXX line
+- _ptc_offset: offset of the PTXXX line, thus it is 1000 in the case of PT1000 and 100 in the other case.
+- _half_bridge_resistor_coeff = (double)_r_3 / (double)(_r_2 + _r_3) and it is the coefficient of half of the voltage divider
+- vcc: incoming voltage in the voltage divider, which for us is set to 5V
+- _resolution_pga: resolution of the pga after the TDB, which is set to 2.048
+- _resolution_tdb: resolution of the tdb micro, which is set to 32767 since it works at 16bit and we are saving the value to a signed int
+
+Thus, as one can observer, the output defined as tmp and calculated first is the basic formula of the full bridge voltage divider, where the factor given by the temperature multiplicated by the _ptc_gradient and summed with the _ptc_offset is seen as one of the four resistors of the full bridge.
+This value, then should be scaled with the resolution of the pga and its gain and then rescaled to the 16bit signed integer by multiplying it by (_resolution_tdb + 1).
+
+```
+
+Thus, that's all regarding the reading and conversion of the data.

mkdocs.yml

@@ -301,3 +301,7 @@ nav:
         - Reading Tactile Data: tactile_sensors/software/reading_data.md
         - Visualizing Tactile Data: tactile_sensors/software/visualizing_data.md
         - Tactile Data Flow: tactile_sensors/software/dataflow.md
+      - Temperature Sensors:
+        - Summary: temperature_sensors/index.md
+        - Reading Temperature Data: temperature_sensors/software/reading_data.md
+        - Temperature Data Flow: temperature_sensors/software/dataflow.md