The Machine Learning Core (MLC) is an hardware processing engine embedded in the sensor and capable to run Machine Learning algorithms based on Decision Trees classifiers. The MLC enables a reduction of the overall system power consumption because the host microcontroller can be put in sleep or stand-by, while the sensor process the data. The MLC can generate an interrupt and wake-up the host microcontroller when a specific event is detected and classified by the sensor.
In this knowledge article we will explain how to build your Machine Learning algorithm to detect precise angles using ST sensors LSM6DSOX or ISM330DHCX and the tool Unico-GUI
Authors contributing to the article:
Luca Seghizzi
Andrea Vitali, Michael Galizzi (AME Marketing and Application team)
Federico Rizzardini, Lorenzo Bracco (MEMS SW development team)
The accelerometer in LSM6DSOX enables the detection of the inclination angle: tilt (0-180 degrees range), pitch (±90 degrees range), or full rotation angle (±180 degrees range).
When the accelerometer is resting parallel to the horizontal plane and its Z-axis is pointing up, it reports AccX = 0 g, AccY = 0 g, AccZ = 1 g. The gravity acceleration is seen on the Z-axis. The sign is positive because the gravity is pulling down which causes the same effect as accelerating up.
Rotations around the Z-axis (also known as yaw, which causes the X and Y axes to move) do not change the accelerometer output. In the picture below, the yaw angle is set to 0, -20, -40, and -60 degrees going from left to right. The accelerometer output is always AccX = 0 g, AccY = 0 g, AccZ = 1 g.
When the accelerometer is tilted in any direction, the projection of the gravity vector along the Z-axis is reduced, while the projection along the X and Y axes is increased in the positive or negative direction. The AccZ measurement is mathematically linked to the tilt angle: AccZ = cos(tilt angle) x 1 g. The tilt angle is defined as the angle between the vertical and the Z-axis of the accelerometer; it is highlighted in yellow in the pictures below. The range is from 0 to 180 degrees.
In general, any accelerometer inclination can be obtained as a sequence of two rotations. Using the flight dynamic conventions, axes named according to standard DIN 9300, the first is a rotation around the Y-axis (also known as pitch, which causes the X and Z axes to move, range ±90 degrees), the second is a rotation around the X-axis (also known as roll, which causes the Y and Z to move, range ±180 degrees). Note that the Android platform has a different naming convention: the first is a rotation around the Y-axis, parallel to the left and right edge of the smartphone (this rotation is defined as roll, range ±90 degrees), the second is a rotation around the X-axis, parallel to the bottom and top edge (this rotation is defined as pitch, range ±180 degrees).
In the picture below the pitch angle is set to 0, +15, +30, +45 degrees going from left to right. Pitch is a rotation around the Y-axis therefore the AccY measurement does not change. The AccZ and AccX measurements are mathematically linked to the pitch angle: AccZ = cos(pitch angle) x 1 g and AccX = sin(pitch angle) x 1 g. The pitch angle is defined as the angle between the horizontal plane and the X-axis of the accelerometer; it is highlighted in green in the pictures below. The range is from -90 to +90 degrees. See also Design Tip DT0140 for more information on how to compute tilt angle.
It is also necessary to install a C compiler. This tutorial describes the procedure of compilation with the GCC compiler on Windows (using Cygwin). Please note that the Cygwin bin directory (typically "C:\cygwin64\bin") should be added to the Windows PATH environment variable. Successful GCC installation can be checked by writing the gcc -v command in the Windows Command prompt (it should display the GCC configuration and its version).
To further evaluate the output of this tutorial, it is worth mentioning the following software tools:
For more hardware details, visit:
We go through the following:
Mandatory parameters:
If the accelerometer is not installed in the horizontal plane, then the "vertical" axis does not correspond to AccZ. For example IIS2ICLX is a 2-axis accelerometer where only AccX and AccY are available. If it is installed with AccX pointing up and AccY in the horizontal plane to support dual mode and full rotation angle detection, then one must set vstr="AccX" and hstr="AccY".
The LSM6DSOX folders show the step-by-step procedure to create configurations for inclination angle detection and to integrate them onto the STWIN board and the SensorTile.box board.
Open the Windows Command Prompt (for example, press Win+R, type cmd and press the Enter key) and go to the folder where the DecisionTree_for_AngleDetection.c is located. For instance, if the file is located in
"C:\DecisionTree_for_AngleDetection_script", then you can use the following command:
cd C:\DecisionTree_for_AngleDetection_script
The correct location can be verified by writing the command dir or ls as shown in the picture below (the DecisionTree_for_AngleDetection.c must be listed):
Execute the following command to build the DecisionTree_for_AngleDetection.c:
If no parameter is used, the program opens in interactive mode and the user need to input the parameters to configure the Decision Tree. The fist parameter that needs to be selected is the mode of the angle detection.
For this example, we will select mode 2 that configures the Decision Tree to detect rotation constrained around the 3rd axis within a given range. The program will then ask for the following information:
In this tutorial inputs will be as shown in picture below:
After the input of the required parameters is finished, the program will generate two files in the program folder (dectree.txt and session.txt) and a list of useful information are also displayed out in the Command Prompt.
Confirm the message about limited functionality (only if the offline mode was selected) and open the MLC window:
Open the machine learning core tab by clicking the MLC button:
Go directly to the Configuration tab:
Select LSM6DSOX and choose the required parameters of the MLC and sensor. The chosen configuration of the sensor and MLC output data rate (ODR) for this tutorial is visible in the picture below:
Select one decision tree from the list and continue configuring the MLC. The Window Length should be configured to 1 sample to minimize the latency, the output is updated on each sample. In this example the ODR is set to 52Hz, therefore the output is updated 52 times a second, every 19.23 ms. A longer window can be used for a less frequent but more stable output because the mean feature is selected below:
In the next step, check the Mean feature for the accelerometer X axis (ACC_X) and Z axis (ACC_Z):
In the next section it is required to provide the Decision Tree Attributes names for each feature. The generated decision tree session file (session.txt) contains the names that need to be used:
Once the attribute name is copied, the Results labels must be copied as well from the decision tree session file as follows:
The next steps are to import the decision tree generated with the program (dectree.txt) and select the output name for the .ucf configuration file to be saved:
At this point, the .ucf file has been generated and the Unico-GUI can be closed.
Since the ODR of the accelerometer and the ODR of the machine learning core has been set up to 52 Hz in Unico-GUI, then in the [Sensor Hub] building block we need to set the Data Rate to 52 Hz as well. To change the configuration, click on the [Sensor Hub] building block and configure it as in picture below:
At this point we need to drag-and-drop all the building blocks that are needed to build the example project. From the left list, simply drag-and-drop all the block needed which are:
1x Sensor Hub -> Acceleration [g] 1x Sensor Hub -> FSM / MLC 1x Display -> Graph 1x Display -> Value 1x Other -> Int to Float 2x Constants -> Constant (Float) 1x Math Operators -> Multiply (*) 1x Math Operators -> Add (+) 1x Display -> Angle Level.
The blocks should be placed as in picture below:
Some display block must be configured properly before it can be connected to other blocks, because input/output types between connected blocks must match; please see following picture to configure them properly:
Import the .ucf file by selecting the FSM/MLC building block, as in picture below:
The multiplication and the sum blocks have been placed to implement the computation of the angle from the value of the machine learning core output register. The formula can be found in the session.txt in the section called angles and conversion formula, as shown below:
On the top menu, click on firmware -> Generate C Code. After C Code generation is completed, click on firmware -> Build firmware. If there is any error, the compilation should complete successfully as in picture below:
The SensorTile.box must be in DFU (Direct firmware Upgrade) mode before it can be programmed: disconnect the battery, press and hold the boot button, plug to USB to power the target microcontroller.
At this point, click Program Target in AlgoBuilder GUI as shown in the picture.
The AlgoBuilder should detect the SensorTile.box and program the binary generated. AlgoBuilder can be closed.
To see the detected Angle, click on the Angle level on the left panel. Move the board within +/-6 degrees respect to the horizon to see the variation detected in real time.
The dual+ mode can be selected to use the third axis (Y) when it is available and check that the rotation is indeed constrained (abs(Y) < threshold). The decision tree can be simplified by using the absolute value of the selected feature for AccY.
The optimization mode can provide shallower trees or decision thresholds, which are farther from the interval centers, giving more robustness against RMS noise. RMS noise can always be reduced by selecting longer windows to compute the mean feature and by enabling a digital lowpass filter.
When the RMS noise level is specified, the intervals that may be subject to misclassification caused by noise are highlighted by an asterisk in the console output of the C utility and highlighted with red color in the picture below:
This example covers the 3-axis accelerometer LSM6DSOX:
The whole example and more configurations with other sensors can also be find in ST GitHub repository at the link:
STMems_Machine_Learning_Core/tools/mlc_tilt_angle_tool at master STMicroelectronics/STMems_Machine_Learning_Core · GitHub
Before starting
How can an accelerometer be used to detect the angle inclination?
The accelerometer in LSM6DSOX enables the detection of the inclination angle: tilt (0-180 degrees range), pitch (±90 degrees range), or full rotation angle (±180 degrees range).
When the accelerometer is resting parallel to the horizontal plane and its Z-axis is pointing up, it reports AccX = 0 g, AccY = 0 g, AccZ = 1 g. The gravity acceleration is seen on the Z-axis. The sign is positive because the gravity is pulling down which causes the same effect as accelerating up.
Rotations around the Z-axis (also known as yaw, which causes the X and Y axes to move) do not change the accelerometer output. In the picture below, the yaw angle is set to 0, -20, -40, and -60 degrees going from left to right. The accelerometer output is always AccX = 0 g, AccY = 0 g, AccZ = 1 g.
In general, any accelerometer inclination can be obtained as a sequence of two rotations. Using the flight dynamic conventions, axes named according to standard DIN 9300, the first is a rotation around the Y-axis (also known as pitch, which causes the X and Z axes to move, range ±90 degrees), the second is a rotation around the X-axis (also known as roll, which causes the Y and Z to move, range ±180 degrees). Note that the Android platform has a different naming convention: the first is a rotation around the Y-axis, parallel to the left and right edge of the smartphone (this rotation is defined as roll, range ±90 degrees), the second is a rotation around the X-axis, parallel to the bottom and top edge (this rotation is defined as pitch, range ±180 degrees).
In the picture below the pitch angle is set to 0, +15, +30, +45 degrees going from left to right. Pitch is a rotation around the Y-axis therefore the AccY measurement does not change. The AccZ and AccX measurements are mathematically linked to the pitch angle: AccZ = cos(pitch angle) x 1 g and AccX = sin(pitch angle) x 1 g. The pitch angle is defined as the angle between the horizontal plane and the X-axis of the accelerometer; it is highlighted in green in the pictures below. The range is from -90 to +90 degrees. See also Design Tip DT0140 for more information on how to compute tilt angle.
In the picture below the roll angle is set to 0, +10, +20, +30 degrees going from left to right. Roll is a rotation around the X-axis therefore the AccX measurement does not change. AccY = sin(roll) cos(pitch) x 1 g and AccZ = cos(roll) cos(pitch) x 1 g. Note that the tilt angle will be affected by both roll and pitch: AccZ = cos(tilt) x 1 g = cos(roll) cos(pitch) x 1 g, the tilt angle is identical to roll angle only if pitch is 0 degrees (rotation constrained around X), or it is identical to pitch angle only if roll is 0 degrees (rotation constrained around Y).
One can compute the roll from the ratio of AccY and AccZ: AccY/AccZ = sin(roll)/cos(roll) = tan(roll), roll = arctan(AccY/AccZ) or roll = arctan2(AccY, AccZ).
See also Design Tip DT0058 for more information on how to compute roll and pitch angles.
See also Design Tip DT0058 for more information on how to compute roll and pitch angles.
Before starting, material you need
Software
The main and mandatory software tool that we will use in this knowledge article is Unico-GUI, a graphical user interface (available for Linux, MacOS, and Windows) that supports a wide range of sensors and allows building an MLC program (even without any board connected = offline mode) and generating a sensor configuration file (UCF file).It is also necessary to install a C compiler. This tutorial describes the procedure of compilation with the GCC compiler on Windows (using Cygwin). Please note that the Cygwin bin directory (typically "C:\cygwin64\bin") should be added to the Windows PATH environment variable. Successful GCC installation can be checked by writing the gcc -v command in the Windows Command prompt (it should display the GCC configuration and its version).
To further evaluate the output of this tutorial, it is worth mentioning the following software tools:
- Unico-GUI, a comprehensive software package, which can be used without any board to generate the configuration for all MEMS sensors (accelerometers, gyroscopes, magnetometers, and environmental sensors).
- AlgoBuilder, a PC application to design a custom processing flow and build the firmware for STM32 Nucleo boards coupled with the MEMS expansions boards, or for form-factor evaluation boards such as the SensorTile.box
- Unicleo-GUI, a PC application that connects to the STM32 Nucleo boards or SensorTile.box to display the data received in real-time
Hardware
The SensorTile.box multisensor kit is used in this tutorial and in particular the LSM6DSOX sensor. The same procedure shown here also applies to other ST sensors equipped with the machine learning core.For more hardware details, visit:
- ST resource page on MEMS sensor
- ST resource page on Explore machine learning core in MEMS sensors
- Application note AN5259 on the machine learning core embedded in the LSM6DSOX
How to build a decision tree
This knowledge article describes how to build and use the DecisionTree_for_AngleDetection.c program, which you find on Github to generate a decision tree for tilt sensing, how to create from the decision trees an UCF configuration file (.ucf) for the machine learning core (MLC) of the LSM6DSOX and finally how to evaluate the result.We go through the following:
- How to build the DecisionTree_for_AngleDetection.c program
- How to run the program to generate customized decision trees for inclination angle measurement
- How to use the Unico-GUI to generate a sensor configuration file (UCF file) from the previously generated decision tree file
- How to create a project with AlgoBuilder, importing the UCF file and program the SensorTile.box evaluation platform
- How to use the Unicleo-GUI and evaluate the MLC results
1. C Utility to design decision trees for inclination angle detection
The C utility has been designed to support all sensors equipped with the machine learning core and to offer maximum flexibility. Here below the list of parameters that can be passed on the command line (if no parameter is specified, the utility enters interactive mode and prompt the user).Mandatory parameters:
- m mode: 0 (horizontal axis mode, AccX is used to detect the pitch angle), 1 (vertical axis mode, AccZ is used to detect the tilt angle), 2 (dual axis mode, AccX, and AccZ are used to detect the full rotation angle), 3 (dual+ axis mode, like dual axis mode but also uses the third axis, AccY is checked to verify that it is close to 0 g).
- a1 first angle in degrees: for pitch a1 ≥ -90, for tilt a1 ≥ 0, for full circle rotation a1 ≥ -180 degrees.
- a2 last angle in degrees: for pitch a2 ≤ +90, for tilt a2 ≤ 180, for full circle rotation a2 ≤ +180 degrees (note: +180 is the same as -180 and it may be useful to set a2 < 180 when a1 = -180, or set a1 > -180 when a2 = +180, see example below).
- N number of intervals, leaves of the decision tree. The maximum number of intervals depends on the device. Example: N=16 for LSM6DSOX.
- opt optimization mode: 0 for shallow tree (best for horizontal or vertical mode), 1 for noise-safe tree (best for dual axis mode). The shallow tree mode prioritizes thresholds that split the interval sets as evenly as possible to minimize the overall depth of the tree; the noise-safe mode prioritizes thresholds that have the maximum distance to the interval center, so that it is less likely to cross a boundary and misclassify because of noise.
- g gravity vector value: the value corresponding to 1 g depends on the device. Example: 1.0 for LSM6DSOX.
- RMS noise value: this value is available from the sensor datasheet. If the noise density is specified, then compute RMS = Noise Density x sqrt(bandwidth), where bandwidth depends on the configured lowpass filter, when no lowpass filter is configured the bandwidth = output data rate / 2. If it is specified, the C utility can verify which interval is prone to misclassification: if the distance to the threshold is less than 3 x RMS level, then the risk is larger than 0.4% and the interval will be flagged with an asterisk in the console output.
- this threshold for third axis (Y) in dual+ mode: when mode m=3 the decision tree is extended with two additional decision nodes to verify that the third axis is close to 0: abs(Y) < th, that is Y > -th and Y < +th. If this condition holds, the rotation is constrained around the third axis and the detection of the rotation angle can be performed, otherwise the output code corresponding to invalid interval (-1) is emitted.
- hofs, hsns, hstr: offset, sensitivity, and string for the horizontal axis. Default to 0.0, 1.0, and AccX respectively.
- vofs, vsns, vstr: offset, sensitivity, and string for the vertical axis. Default to 0.0, 1.0, and AccZ respectively.
- tofs, tsns, tstr: offset, sensitivity, and string for the thirds axis. Default to 0.0, 1.0, and AccY respectively.
If the accelerometer is not installed in the horizontal plane, then the "vertical" axis does not correspond to AccZ. For example IIS2ICLX is a 2-axis accelerometer where only AccX and AccY are available. If it is installed with AccX pointing up and AccY in the horizontal plane to support dual mode and full rotation angle detection, then one must set vstr="AccX" and hstr="AccY".
The LSM6DSOX folders show the step-by-step procedure to create configurations for inclination angle detection and to integrate them onto the STWIN board and the SensorTile.box board.
1.2 How to build the C programmer
Download the DecisionTree_for_AngleDetection.c file to your PC. The program may be modified according to the user's needs in a text editor. However, in many cases or for a basic evaluation, the program can be used without modifications.Open the Windows Command Prompt (for example, press Win+R, type cmd and press the Enter key) and go to the folder where the DecisionTree_for_AngleDetection.c is located. For instance, if the file is located in
"C:\DecisionTree_for_AngleDetection_script", then you can use the following command:
cd C:\DecisionTree_for_AngleDetection_script
The correct location can be verified by writing the command dir or ls as shown in the picture below (the DecisionTree_for_AngleDetection.c must be listed):
Execute the following command to build the DecisionTree_for_AngleDetection.c:
gcc DecisionTree_for_AngleDetection.c -lm -o DecisionTree_for_AngleDetection
The command creates an executable file in the current folder (in this case "DecisionTree_for_AngleDetection.exe"). Under Windows the .exe extension is automatically appended to the executable name.
2. Generate decision trees with the built program
After building the program, it can be run with the following command: "DecisionTree_for_AngleDetection.exe"If no parameter is used, the program opens in interactive mode and the user need to input the parameters to configure the Decision Tree. The fist parameter that needs to be selected is the mode of the angle detection.
- first angle (in this tutorial set to -40 deg). It must be an integer in the range of -180 to 180 [deg].
- last angle (in this tutorial set to 100 deg). It must be an integer in the range of -180 to 180 [deg]. This angle must be greater than the first angle
- number of leaves (in this tutorial set to 16). It must be an integer in the range 2-255. The number of leaves is limited by the "Maximum number of results per decision tree" of the sensor. For the LSM6DSOX, the maximum number is 16:
- opt (in this tutorial set to 1). The value for determining the use of a shallow tree (0) or noise safe tree(1).
- g (in this tutorial set to 1). The value corresponding to 1g depends on the sensor model.
- RMS noise (in this tutorial set to 0.0018). It must be the value of the RMS noise reported on the datasheet for the selected full scale. For the LSM6DSOX, the acceleration RMS noise in normal/low-power mode is 1.8 mg (0.0018 g):
- The file dectree.txt contains the decision tree that can be imported in the Unico-GUI software.
- The file session.txt contains the decision tree and more information such as: -- Angles and conversion formula section: reports the angle resolution that the program has managed to get with the input parameters. It reports also a list of angles that the decision tree is able to detect. The conversion formula for output code is the formula that needs to be applied to the MLC output code to have the corresponded angle in degrees. -- Output codes/labels section: is the list of the output code that the MLC outputs. It is used to label the output in the Unico-GUI tool, during the generation of the .ucf configuration file. -- Other information section: report the maximum recursion level of the decision tree and the number of angles that are prone to RMS noise.
3. Generate the Unico Configuration file (UCF file)
Once the decision tree files are generated by the DecisionTree_for_AngleDetection.exe program, open the Unico-GUI software tool and select the "iNEMO Inertial Modules" from the list of Device Type and then select the "STEVAL-MKI197V1 (LSM6DSOX)" item from the list of Device Names. You do not need to have the board, but there you find the LSM6DSOX MEMS device. The "Communication with the motherboard [Enabled]" option box must be unchecked to enable the offline mode (no hardware is required). Then click on the "Select Device" button or double click "STEVAL-MKI197V1 (LSM6DSOX)".Confirm the message about limited functionality (only if the offline mode was selected) and open the MLC window:
Open the machine learning core tab by clicking the MLC button:
The next steps are to import the decision tree generated with the program (dectree.txt) and select the output name for the .ucf configuration file to be saved:
4. AlgoBuilder project
To test the .ucf file created with Unico-GUI in this tutorial, we create a project with AlgoBuilder. Open AlgoBuilder and click on File -> New Design. From the firmware Settings window select the firmware location, the Toolchain, and the Target platform as in picture below:Since the ODR of the accelerometer and the ODR of the machine learning core has been set up to 52 Hz in Unico-GUI, then in the [Sensor Hub] building block we need to set the Data Rate to 52 Hz as well. To change the configuration, click on the [Sensor Hub] building block and configure it as in picture below:
At this point we need to drag-and-drop all the building blocks that are needed to build the example project. From the left list, simply drag-and-drop all the block needed which are:
1x Sensor Hub -> Acceleration [g] 1x Sensor Hub -> FSM / MLC 1x Display -> Graph 1x Display -> Value 1x Other -> Int to Float 2x Constants -> Constant (Float) 1x Math Operators -> Multiply (*) 1x Math Operators -> Add (+) 1x Display -> Angle Level.
The blocks should be placed as in picture below:
5. Programming SensorTile.box
The SensorTile.box must be in DFU (Direct firmware Upgrade) mode before it can be programmed: disconnect the battery, press and hold the boot button, plug to USB to power the target microcontroller.
At this point, click Program Target in AlgoBuilder GUI as shown in the picture.
The AlgoBuilder should detect the SensorTile.box and program the binary generated. AlgoBuilder can be closed.
5. Testing the MLC angle detection
Open the Unicleo-GUI software. The software should automatically detect and connect to the SensorTile.box Press the Start button to start the streaming from the SensorTile.box.To see the detected Angle, click on the Angle level on the left panel. Move the board within +/-6 degrees respect to the horizon to see the variation detected in real time.
Decision tree examples–Dual Axis Mode
The dual axis mode supports the full rotation range, from -180 to +180 degrees. These two angles however represent the same orientation (the "upside-down" position). If one wants to detect on which side the upside-down position is, for example, -179.9 or +179.9 degrees, then the following decision tree is to be used. Otherwise, it is better to either remove -180 or remove +180, so that the output code does not oscillate between the two values when the device is in the upside position.The dual+ mode can be selected to use the third axis (Y) when it is available and check that the rotation is indeed constrained (abs(Y) < threshold). The decision tree can be simplified by using the absolute value of the selected feature for AccY.
The optimization mode can provide shallower trees or decision thresholds, which are farther from the interval centers, giving more robustness against RMS noise. RMS noise can always be reduced by selecting longer windows to compute the mean feature and by enabling a digital lowpass filter.
When the RMS noise level is specified, the intervals that may be subject to misclassification caused by noise are highlighted by an asterisk in the console output of the C utility and highlighted with red color in the picture below:
Conclusions
In this knowledge article we have shown how you can implement the inclination angle leveraging on machine learning core using LSM6DSOX sensor.The whole example and more configurations with other sensors can also be find in ST GitHub repository at the link:
STMems_Machine_Learning_Core/tools/mlc_tilt_angle_tool at master STMicroelectronics/STMems_Machine_Learning_Core · GitHub