Merge pull request #10 from jerabaul29/main

document the units

Author: cparata

README.md

@@ -37,6 +37,31 @@ The access to the sensor value is done as explained below:
     AccGyr.ACC_GetAxes(accelerometer);  
     AccGyr.GYRO_GetAxes(gyroscope);
 
+## Units
+
+All the MEMS drivers in stm32duino repositories have the same units when returning physical (scaled) values:
+
+    - mg for accelerometer (thousandth of g, 1g is 9.81 m/s^2)
+    - mdps for gyroscope (thousandth of degree/s)
+    - mgauss for magnetometer (thousandth of gauss)
+
+Readings can be obtained either as raw (unscaled) ```uint16_t``` values from the ```XXX_GetAxesRaw``` functions, or as physical (scaled) ```uint32_t``` values from the ```XXX_GetAxes``` functions, where ```XXX``` is either ```ACC``` or ```GYRO```. The factor to use for scaling from a raw to a physical value is obtained from the ```XXX_GetSensitivity``` functions.
+
+For example, to convert the raw acceleration reading to float m/s^2, the following can be done:
+
+```cpp
+int16_t acc_raw[3];
+float acc_ms2[3];
+float acc_sensitivity;
+
+AccGyr.ACC_GetAxesRaw(acc_raw);
+AccGyr.ACC_GetSensitivity(&acc_sensitivity);
+
+acc_ms2[0] = ((float)acc_raw[0] * acc_sensitivity) / 1000.0f * 9.81f;
+acc_ms2[1] = ((float)acc_raw[1] * acc_sensitivity) / 1000.0f * 9.81f;
+acc_ms2[2] = ((float)acc_raw[2] * acc_sensitivity) / 1000.0f * 9.81f;
+```
+
 ## Documentation 
 You can find the source files at  
 https://github.com/stm32duino/ISM330DHCX

src/ISM330DHCXSensor.h

@@ -50,6 +50,16 @@ typedef struct {
 
 /**
 * Abstract class of an ISM330DHCX.
+*
+* A few notes about the acceleration and angular rate outputs:
+* - these are returned as either int16_t for the raw (unscaled) value (XXX_GetAxesRaw functions)
+*   or int32_t for the physical (scaled) value (XXX_GetAxes functions)
+* - the physical (scaled) readings have the following units:
+*   - mg for accelerometer (thousandth of 1g, 1g is 9.81 m/s^2)
+*   - mdps for gyroscope (thousandth of degree/s)
+* - conversion from raw to physical value is done by multiplying the output of the XXX_GetAxesRaw functions
+*   by the output of the XXX_GetSensitivity functions.
+*
 */
 class ISM330DHCXSensor {
   public: