Update motor temperature sensor

docs/temperature_sensors/general/overview.md

@@ -1,13 +1,7 @@
-## Temperature Sensors
+## Motor temperature Sensors
 
-The Temperature Sensors are simple sensors made of a specific type of resistor (PT100 or PT1000) and of a small board defined as Temperature Detection Board (TDB), which has the goal of decoding the value read by the resistor giving out a raw output code, which can be then translated to Celsius Degree so that it can be easily understood by the end-user.
-
-Regarding our hardware, these sensors are mounted on the `ergoCub` motors that are provided with a resistance thermometer (i.e. PT100 or PT1000).
-Therefore, if one desires to read the temperature at the motor and print it to a yarp port, the following should be done.
-First of all, the robot configuration files should be updated accordingly as described in the [configuration section](#how-to-update-the-configuration-files).
-Finally, since the temperature values in Celsius degrees are not currently printed out on the yarp `stateExt` port, one should develop a module application similar to [this one](https://github.com/MSECode/motionControlModule), in order to output the temperature values for a specific robot body part on a defined yarp port.
-
-In a nutshell, most of the `ergoCub` motors are provided with an internal resistance temperature detector, which is then connected to a TDB board. This one is then linked to a `FOC` board, which elaborates that data coming from the `I2C` and send them via `CAN` to an `EMS` board. Finally, this one streams the raw temperature values via `ETH` to `embObjMotionControl` that updates and stores all of these data, ready to be requested, through an external module, by the end-user, which has the job to output them to a specific yarp port.
+The Motor Temperature Sensors are simple sensors made of a specific type of resistor (PT100 or PT1000) and of a small board defined as Temperature Detection Board (TDB), which has the goal of decoding the value read by the resistor giving out a raw output code, which can be then translated to Celsius Degree so that it can be easily understood by the end-user.
+In a nutshell, most of the `ergoCub` motors are provided with an internal resistance temperature detector, which is then connected to a TDB board. This one is then linked to a `FOC` board, which elaborates that data coming from the `I2C` and send them via `CAN` to an `EMS` board. Finally, this one streams the raw temperature values via `ETH` to `embObjMotionControl` that updates and stores all of these data, ready to be requested by an user external module.
 
 
 ### How to update the configuration files
@@ -18,3 +12,11 @@ Regarding the robot configuration files, whose templates can be seen at [this li
 - under `hardware/mechanicals/body_part-ebX-jA_B-mec.xml` you need to add the parameter `TemperatureSensorType` in the `2FOC` group, and remove the soon deprecated `HasTempSensor` parameter in the same area.
 
 Thus, once that is done, and keeping in mind the points defined at the previous section, it should be possible to use correctly the feature of the temperature sensors.
+
+### How to read the motor temperature
+The user need to update the robot configuration files accordingly as described in the [configuration section](#how-to-update-the-configuration-files), after ensuring that the sensor has been mounted on the desired motors.
+The correct configuration ensures that the motor temperature is read and forwarded to yarprobotinterface, but currently this measure in not published on the yarp `stateExt` port. Therefore the user needs to develop a module application similar to [this one](https://github.com/MSECode/motionControlModule), in order to read the tempereature.
+
+In addition, the user modul can retrive the `warningTemperatureLimits` and check if the current teperature exceds that limit to put the motor in a less-current consumption state.
+Is it important to notice that the firware put the motor in fault when the teperature goes beyond the `hardwareTemperatureLimits`.
+More details on the temperature flow are availble in the section [data flow](../software/dataflow.md)

docs/temperature_sensors/index.md

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

docs/temperature_sensors/software/dataflow.md

@@ -1,13 +1,16 @@
-## Temperature Data Flow
+## Motor temperature Data Flow
 
 Generally speaking the data flow related to the whole pipeline of the sensing of the motor temperature is quite simple and here a brief summary is proposed, whose main scope is to make the reader aware of how the temperature data are retrieved from the motor resistance thermometer and printed out to a yarp port. 
 
 In a nutshell, as introduced in the [introductory section](../general/overview.md#temperature-sensors), most of the `ergoCub` motors are currently provided with a `PT100`, which is roughly a particular resistor able to correlate a value of temperature to a value of resistance in `Ohm`. This is then linked to a board called Temperature Detection Board (TDB), whose internal components are meaningless for our aim.
-Anyways, its function is to evaluate the `Ohm` value given by the `PT100` (or `PT1000` for different types of motors) and streams out with a `I2C` protocol the raw data. This are then read by the `2FOC` board with a frequency of around 200Hz, which also checks if there's any `overHeating` error depending on the values set by the end-user in the configuration files at the parameter `hardwareTemperatureLimits`. If everything is fine, the raw temperatures are sent over `CAN` to the `EMS` board, which stores them in the memory. Finally, with a default frequency of `2 ms`, those values are managed by the `embObjMotionControl` that converts the values from raw to Celsius, check if the set `warningTemperatureLimit` is going to be overcome and updates the data so that they can be printed anytime to a yarp port. 
+Anyways, its function is to evaluate the `Ohm` value given by the `PT100` (or `PT1000` for different types of motors) and streams out with a `I2C` protocol the raw data. This are then read by the `2FOC` board with a frequency of around 200Hz, which also checks if there's any `overHeating` error depending on the values set by the end-user in the configuration files at the parameter `hardwareTemperatureLimits`. The raw temperatures are sent over `CAN` to the `EMS` board, which stores them in the memory and sends to `embObjMotionControl` together all the other motor information. 
+
+On reception of the motor temperature, `embObjMotionControl` converts the values from raw to Celsius and checks if the set `warningTemperatureLimit` is overcome. In that case it print a warning on the yarprobotinterface log just to advise the user. Any other actions are taken.
+
 It is important to note that in the whole pipeline we are doing two different checks for the temperature:
 
-- first, when reading the raw temperature value the `2FOC` board checks that it is not higher than the `hardwareTemperatureLimits`, otherwise it triggers the `overHEating` error and sends the fault state to the robot
-- then, when the temperature is received and converted to Celsius degree by the `embObjMotionControl`, this one checks that the passed value is not beyond the `warningTemperatureLimit`, otherwise a counter is started, which computes how much time the read value stays over that threshold, triggering a warning message if and only if the set counter overcomes a set limit.
+1. when reading the raw temperature value the `2FOC` board checks that it is not higher than the `hardwareTemperatureLimits`, otherwise it triggers the `overHEating` error and sends the fault state to the robot
+2. when the temperature is received and converted to Celsius degree by the `embObjMotionControl`, this checks that the passed value is not beyond the `warningTemperatureLimit`, otherwise it prints a warning log until the temperature drops. 
 
 ### Main Flow of Information
 

docs/temperature_sensors/software/reading_data.md

@@ -5,7 +5,7 @@ Currently we can configure 2 types of sensors: `PT100` and `PT1000`.
 When regarding raw values, we have that usually, for the `PT100` 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, we have that higher the temperature and higher the raw output value.
 
-## Reading Compensated Temperature Data
+## Reading compensated motor temperature data
 
 Regarding the correlation between raw temperature data and Celsius degree values here follows a brief description.
 First of all, in order to reduce the effort of the end-user and at the same time remain compliant with the rest of the firmware, we have decided to work with values in Celsius degree on `embObjMotionControl` and, instead, use the raw value in the firmware part.
@@ -43,9 +43,10 @@ Finally, the last calculation that outputs the value of the got temperature in C
     double res = (tmp * (_first_res_coeff) / den) + ((_second_res_coeff) / den);
 
 where:
+- _ptc_offset: is the offset of the PTXXX line, thus it is 1000 in the case of PT1000 and 100 in the other case.
+- r1: the other of the two upper resistors in the voltage divider bridge, which for us is equal to 4700 [Ohm]
 - _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.
 

mkdocs.yml

@@ -301,8 +301,8 @@ 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:
+      - Motor Temperature Sensors:
         - Summary: temperature_sensors/index.md
         - Overview of Temperature Sensors: temperature_sensors/general/overview.md
-        - Temperature Data Flow: temperature_sensors/software/dataflow.md
-        - Reading Temperature Data: temperature_sensors/software/reading_data.md
+        - Motor Temperature Data Flow: temperature_sensors/software/dataflow.md
+        - Reading Motor Temperature Data: temperature_sensors/software/reading_data.md