on - edited on by
Laurids_PETERSE
Summary
In this knowledge article, I will show you how you can easily implement accurate in-sensor inclination monitoring applications with an IMU featuring an embedded intelligent sensor processing unit (ISPU). This intelligent sensor, ISM330IS, can implement accelerometer calibration and run sensor fusion algorithm for continuous and accurate inclination monitoring on a power budget of a few microwatts.
Prerequisites
Software
The following software components are used:
- X-CUBE-ISPU, expansion software package for STM32Cube;
- AlgoBuilder, an application for the graphical design of algorithms;
- Unicleo-GUI, graphical user interface for X-CUBE-MEMS1, motion MEMS, and environmental sensor software expansion for STM32Cube;
- STM32CubeIDE, an integrated development environment for STM32.
Hardware
The following hardware components are used:
[1] STEVAL-MKI230KA, which is the DIL24 adapter board for ISM330IS, the industrial IMU MEMS sensor with ISPU;
[2] The industrial motion MEMS sensor expansion board X-NUCLEO-IKS02A1;
[3] NUCLEO-F401RE, STM32 Nucleo development board.
Hands-On
How to customize two examples inside the X-CUBE-ISPU package is shown inside this article. These two examples implement an accelerometer calibration and sensor fusion algorithm, which you can use to build inclination monitoring applications. Unicleo-GUI is used to visualize the results.
Download and open the ISPU folder inside the X-CUBE-ISPU package.
There is a readme file inside the folder: here you can find all the instructions to setup the ISPU toolchain. Either for the command-line usage or for an eclipse-based IDE, which you need to install the plugins. For this demo, STM32CubeIDE is chosen, inside which the ISPU plugins have been already configured. Going back to X-CUBE-ISPU package, inside the folder ism330is_lsm6dso16is, you can find examples and a template folder: acc_calibration and sensor_fusion_6x (in which the gyroscope calibration is already performed) examples are considered for this demo. Accelerometer calibration is firstly considered, then integrated inside the sensor fusion example.
Open the accelerometer calibration example: it contains a readme file, an output folder with prebuilt files and an ISPU folder containing all the development files. Copy this folder in your working folder and rename it, for example as inclinometer. Now, open STM32CubeIDE and import the newly created inclinometer folder, in particular select its Eclipse subfolder.
At this point we can rename the project in STM32CubeIDE: ispu_acc_calibration is renamed as ispu_inclinometer.
The first step is to get the needed libraries. If you go back to the folder inclinometer, inside the lib subfolder we only have the accelerometer calibration library: here the sensor fusion is also needed.
Do the following: If you go back to the x-cube-ispu folder, in particular you click on its sensor_fusion_6x subfolder. Then go to the ISPU subfolder and finally to the lib subfolder. Copy the libMotionFX.a and motion_fx.h files to the lib subfolder of the inclinometer folder.
If you go back to STM32CubeIDE, right-click on the name of the ispu_inclinometer project inside the project explorer window: click on properties. Then click on settings inside the section C/C++ build and finally on libraries under the section GNU STRED Cross C Linker in settings inside the section C/C++ build. Now, click on the add button in the libraries section on the right-hand side of the properties window and call it MotionFX. To finalize this step, click on apply and close.
You can now modify the code. First of all, open the main.c file inside STM32CubeIDE. Then import the sensor fusion example (sensor_fusion_6x) in the project by selecting its Eclipse folder inside the x-cube-ispu folder. Open its main.c file.
Open the two main.c file (the one of ispu_inclinometer project and the one of ispu_sensor_fusion_6x project inside the project explorer section), side by side.
Start integrating by copying from the ispu_sensor_fusion_6x project to the ispu_inclinometer project the following lines of code:
Line 22
#include "motion_fx.h"Line 25
#define GYR_SENS 0.070f /*sensitivity value for the gyroscope data*/Line 33
static void *mfx_6x; /*pointer to the motion_fx instance*/Inside the initialization function void __attribute__ ((signal)) algo_00_init(void), which is used to initialize the two libraries (acc_calibration and ispu_sensor_fusion_6x) of the final project, the dtime for the device is computed based on the device register. In particular, the actual delta time (dtime) is the time between two consecutive samples of the sensor and it is computed with the data rate configured at 104 Hz, as described inside AN5850. In this example, the algorithm is run at 52 Hz, so this is the reason why the dtime is scaled by a 2 factor along as a 1000 factor because of [ms]: dtime *= 2000.0f; You can modify it to dtime *= 2.0f; to get it in [s].
In the ispu_inclinometer project at line 48, modify the code in the following way:
knobs.Sample_ms = (uint32_t)(dtime*1000.0f);
To scale the dtime accordingly to [ms] again, while for the Motion_FX, we directly use [s].
Then copy from ispu_sensor_fusion_6x project to ispu_inclinometer project the following lines of code:
Lines 40-44, which initializes the Motion_FX library correctly:
if (mfx_6x != NULL) {
MotionFX_deinitialize(mfx_6x);
}
mfx_6x = MotionFX_initialize(MFX_6X);
MotionFX_enable_gbias(mfx_6x, MFX_ENGINE_ENABLE);Lines 49-51:
MFX_input_t in;
MFX_output_t out;
(void)memset(&out, 0, sizeof(out));In the ispu_inclinometer project at line 48, the dtime for the accelerometer calibration is scaled in [ms]:
float ts = (float)n * dtime;After that, copy from ispu_sensor_fusion_6x project to ispu_inclinometer project the following lines of code:
Lines 53-59
in.acc[0] = (float)cast_sint16_t(ISPU_ARAW_X) * ACC_SENS;
iacn.c[1] = (float)cast_sint16_t(ISPU_ARAW_Y) * ACC_SENS;
in.acc[2] = (float)cast_sint16_t(ISPU_ARAW_Z) * ACC_SENS;
in.gyro[0] = (float)cast_sint16_t(ISPU_GRAW_X) * GYR_SENS;
in.gyro[1] = (float)cast_sint16_t(ISPU_GRAW_Y) * GYR_SENS;
in.gyro[2] = (float)cast_sint16_t(ISPU_GRAW_Z) * GYR_SENS;
MotionFX_update(mfx_6x, &out, &in, dtime);In this case, the calibrated accelerometer values are considered instead of the accelerometer raw data. In this way sensor fusion uses calibrated data and the gyroscope will be calibrated internally. To do so, substitute lines 83-89 inside ispu_inclinometer project according to the following lines of code:
in.acc[0] = (data_in.Acc[0] - data_out.AccBias[0]) * data_out.SF_Matrix[0][0];
in.acc[1] = (data_in.Acc[1] - data_out.AccBias[1]) * data_out.SF_Matrix[1][1];
in.acc[2] = (data_in.Acc[2] - data_out.AccBias[2]) * data_out.SF_Matrix[2][2];
in.gyro[0] = (float)cast_sint16_t(ISPU_GRAW_X) * GYR_SENS;
in.gyro[1] = (float)cast_sint16_t(ISPU_GRAW_Y) * GYR_SENS;
in.gyro[2] = (float)cast_sint16_t(ISPU_GRAW_Z) * GYR_SENS;
MotionFX_update(mfx_6x, &out, &in, dtime); Finally, substitute lines 91-100 inside ispu_inclinometer project according to the following lines of code to have the sensor fusion output: these are the quaternion values, which represent the orientation of the device in the space. Moreover, the calibration quality is considered.
cast_float(ISPU_DOUT_00) = out.quaternion[0];
cast_float(ISPU_DOUT_02) = out.quaternion[1];
cast_float(ISPU_DOUT_04) = out.quaternion[2];
cast_float(ISPU_DOUT_06) = out.quaternion[3];
cast_uint8_t(ISPU_DOUT_08) = (uint8_t)data_out.CalQuality; One last step to be performed is to modify the conf.txt file present inside the inclinometer folder.
This file contains the sensor configuration and the ISPU configuration. Add the gyroscope configuration as follows:
- output data rate = 52 Hz
- output full scale = 2000 dps
- operating mode = high performance.
The content of conf.txt becomes:
acc_odr 52
acc_fs 8
acc_mode high_performance
gyr_odr 52
gyr_fs 2000
gyr_mode high_performance
ispu_irq_rate 52
ispu_int1 enable
ispu_sleep_int2 enable
ispu_latch disable
algo 0 enable
algo_int1 0 enable
Now, build your project. The output is an .ucf file containing the final configuration.
If we go to the inclinometer folder, inside the eclipse release folder there is the generated .ucf file, called ispu.ucf. The .ucf file contains all the right operations to perform on the device interface to load the sensor configuration in the ISPU program.
If you want to test this new demo and visualize the results, you can use AlgoBuilder and Unicleo-GUI. You need the JSON file, which describes the output of our algorithm.
You can copy the sensor_fusion_6x.json from the output folder of the ispu_sensor_fusion_6x example in the same folder of the ispu.ucf file of the inclinometer project folder and rename it with the same name of the ispu.ucf file that is ispu.json so that the tools can automatically find it.
If you open the ispu.json file, it describes the quaternion values. In this case, the calibration quality is also considered according to main.c of the inclinometer project, so the content of the ispu.json file is updated in the following way:
{
"output":
[
{
"name": "Quat x",
"type": "float"
},
{
"name": "Quat y",
"type": "float"
},
{
"name": "Quat z",
"type": "float"
},
{
"name": "Quat w",
"type": "float"
},
{
"name": "Acc accuracy",
"type": "uint8_t"
}
]
}After saving the updated ispu.json file, open AlgoBuilder tool: click on file, then new design. The firmware settings pop-up window appears:
- Browse to choose the location where the firmware project is generated by AlgoBuilder: for example, in a new folder called workspace_algobuilder/inclinometer_fw.
- Choose NUCLEO-F401RE + X-NUCLEO-IKS02A1 + ISM330IS as the target.
Save this design file for AlgoBuilder by naming it inclinometer.xml in the folder called workspace_algobuilder.
First of all, in the Properties section of the AlgoBuilder, set up all the configurations in the same way as before:
- Data Rate Control: Accelerometer
- Data Rate 52 Hz
- Accelerometer Full Scale 8 g
- Gyroscope Full Scale 2000 dps
Then add the ISPU block by looking for ISPU inside the filter bar (in the left hand corner of AlgoBuilder). Connect it to the sensor hub inside the main design section of AlgoBuilder. In the properties window, click on Load ISPU UCF file and open the ispu.ucf file of our inclinometer project.
To visualize the fusion block, look for Fusion inside the filter bar. The fusion block takes in input four float values. So, look for mux block inside the filter bar and add it between ISPU and fusion block. The mux block can be configured for four values, by setting: Number of inputs = 4 inside the properties section. Its inputs are the four quaternion values coming from the ISPU block. If you want to visualize the status of the calibration, look for graph inside the filter bar, add the block in the graphical view and configure it with
- Number of Curves = 1
- Graph Name = Acc cal
- Waveform 1 Name = Status
- Auto-scale ON
inside the properties section. Then connect this block to receive the input from the ISPU block.
Then you can build the project by clicking the dedicated button in the top bar: this automatically generates a firmware based on the created flow, shown by the graphical view in the main design window (see the picture below), and is built using the STM32CubeIDE.
When the building process is concluded, you can program the NUCLEO-F401RE by clicking the dedicated button in the top bar. When the board is flashed, click on the run Unicleo-GUI application button in the top bar.
When Unicleo-GUI opens, on the left you can see both the Acc cal and sensor fusion tabs.
Click on start. If you click on the Acc cal tab, the value now is zero because it is not calibrated. Move the device for a few seconds along all the six faces as described in the picture below to connect all the point needed to complete the accelerometer calibration:
After this calibration, the accuracy of Acc cal is higher.
Click on the sensor fusion tab: if you put the device flat on the table, the model (represented here by a teapot) is flat. If the device is tilted along the axes, the teapot is moving accordingly, and everything is extracted with accuracy.
Conclusion
This article shows how it is possible to easily implement accurate in-sensor inclination-monitoring applications with an IMU featuring an embedded intelligent sensor processing unit (ISPU). This intelligent sensor, ISM330IS, can implement accelerometer calibration and run sensor fusion algorithm for continuous and accurate inclination monitoring on a power budget of a few microwatts.
You can find a dedicated webinar on the topic at the following link, which also includes this demo: Webinar: In-sensor monitoring with intelligent MEMS sensors.
You may also be interested in reading the following knowledge article: How to implement in-sensor vibration monitoring with ISM330IS, with embedded ISPU
