STMicroelectronics X-CUBE-MEMS1 User Manual
UM2277
User manual
Getting started with MotionTL tilt measurement library in X-CUBE-MEMS1
expansion for STM32Cube
Introduction
The MotionTL middleware library is part of the X-CUBE-MEMS1 software and runs on STM32. It provides real-time information
about the tilt angles of the user device, i.e. cell phone. The library is also able to perform accelerometer 6-position calibration.
This library is intended to work with ST MEMS only.
The algorithm is provided in static library format and is designed to be used on STM32 microcontrollers based on the ARM
Cortex®-M0+, ARM® Cortex®-M3, ARM® Cortex®-M4 or ARM® Cortex®-M7 architecture.
It is built on top of STM32Cube software technology to ease portability across different STM32 microcontrollers.
The software comes with a sample implementation running on an X-NUCLEO-IKS01A2, X-NUCLEO-IKS01A3 or X-NUCLEO-
IKS02A1 expansion board on a NUCLEO-F401RE, NUCLEO-L476RG, NUCLEO-L152RE or NUCLEO-L073RZ development
board.
®
UM2277 - Rev 8 - April 2021
For further information contact your local STMicroelectronics sales office.
www.st.com
1 Acronyms and abbreviations
Table 1. List of acronyms
Acronym Description
API Application programming interface
BSP Board support package
GUI Graphical user interface
HAL Hardware abstraction layer
IDE Integrated development environment
UM2277
Acronyms and abbreviations
UM2277 - Rev 8
page 2/20
UM2277
MotionTL middleware library in X-CUBE-MEMS1 software expansion for STM32Cube
2 MotionTL middleware library in X-CUBE-MEMS1 software expansion
for STM32Cube
2.1 MotionTL overview
The MotionTL library expands the functionality of the X-CUBE-MEMS1 software.
The library acquires data from the accelerometer and provides real-time tilt information with multi-mode support
for 3-axis accelerometer. This library is suitable for static inclinometer where system acceleration is negligible,
such as in industrial applications, leveling, satellite antennas, solar panels, and automotive.
The library is also able to perform accelerometer 6-position calibration.
The library is designed for ST MEMS only. Functionality and performance when using other MEMS sensors are
not analyzed and can be significantly different from what described in the document.
A sample implementation is available for X-NUCLEO-IKS01A2, X-NUCLEO-IKS01A3 and X-NUCLEO-IKS02A1
expansion boards, mounted on a NUCLEO-F401RE, NUCLEO-L476RG, NUCLEO-L152RE or NUCLEO-L073RZ
development board.
2.2 MotionTL library
Technical information fully describing the functions and parameters of the MotionTL APIs can be found in the
MotionTL_Package.chm compiled HTML file located in the Documentation folder.
2.2.1 MotionTL library description
The MotionTL pedometer library manages the data acquired from the accelerometer; it features:
• calculation of pitch, roll and gravity inclination angles (Pitch-Roll-Gravity-Inclination mode)
• calculation of theta, psi and phi tilt angles (Theta-Psi-Phi mode)
• accelerometer 6-position calibration
• measurement based on the accelerometer data only
• configure knobs to mitigate vibration noise
• output: tilt angles, validity flag, expected error
• recommended sensor data sampling frequency of 100 Hz and support for all Full Scale ranges
• resources requirements:
– Cortex-M0+: 4.1 kB of code and 0.2 kB of data memory
– Cortex-M3: 3.6 kB of code and 0.2 kB of data memory
– Cortex-M4: 3.3 kB of code and 0.2 kB of data memory
– Cortex-M7: 3.3 kB of code and 0.2 kB of data memory
•
available for ARM® Cortex®-M0+, ARM® Cortex®-M3 and ARM® Cortex®-M4 and ARM® Cortex®-M7
architectures
2.2.2 MotionTL APIs
The MotionTL library APIs are:
• void MotionTL_Initialize(MTL_mcu_type_t mcu_type, const char *acc_orientation)
– performs MotionTL library initialization and setup of the internal mechanism
– the CRC module in STM32 microcontroller (in RCC peripheral clock enable register) has to be enabled
before using the library
• mcu_type is the type of MCU:
– MFX_CM0P_MCU_STM32 is a standard STM32 MCU
– MFX_CM0P_MCU_BLUE_NRG1 is BlueNRG-1
– MFX_CM0P_MCU_BLUE_NRG2 is BlueNRG-2
– MFX_CM0P_MCU_BLUE_NRG_LP is BlueNRG-LP
• *acc_orientation is the reference system of the accelerometer raw data
UM2277 - Rev 8
page 3/20
Note: This function must be called before using the tilt library.
• void MotionTL_SetKnobs(MTL_knobs_t *knobs)
– sets the knobs
– the parameters for the structure type MTL_knobs_t are:
◦ fullscale is the full scale of accelerometer (in g). It is recommended to set full scale >1g for
the sensor. A lower full scale can be selected if the tilt variation is limited and higher resolution is
required for the application.
◦ k is the filtering coefficient. The range of k is [0.1 to ODR]. The lower value of k increases the
filtering and removes the noise. For systems with high vibration, it is recommended to reduce the
value of k.
◦ orn[3] is the accelerometer data orientation string of three characters indicating the direction
of each positive orientation of the reference frame used for the accelerometer data output, in the
sequence x, y, z. Valid values are: n (north) or s (south), w (west) or e (east), u (up) or d (down)
(see Figure 1). The orn is defined to bring the sensor into the X-NUCLEO-IKS01A3 frame.
◦ mode is the operational mode where:
• MODE_PITCH_ROLL_GRAVITY_INCLINATION enables angle representation in Euler
angles (Roll, Pitch and Phi) form
• MODE_THETA_PSI_PHI enables angle computation of theta, psi and phi angle which
measure the angle individually on each axis
Note: The API can be called after MotionTL_Initialize() but before MotionTL_Update()
UM2277
MotionTL library
• void MotionTL_GetKnobs(MTL_knobs_t *knobs)
– gets the knobs setting
– for the parameters for the structure type MTL_knobs_t refer to the MotionTL_SetKnobs() function
• void MotionTL_Update(MTL_input_t *data_in, uint64_t timestamp_ms, MTL_output_t
*data_out)
– executes the tilt algorithm
– *data_in parameter is a pointer to a structure with input data
– timestamp_ms is the time stamp in milliseconds
– *data_out parameter is a pointer to a structure with output data
– the parameters for the structure type MTL_input_t are:
◦ acc_x is the accelerometer sensor value in X axis in g
◦ acc_y is the accelerometer sensor value in Y axis in g
◦ acc_z is the accelerometer sensor value in Z axis in g
– the parameters for the structure type MTL_output_t are:
◦ theta_3x in Theta-Psi-Phi mode – the angle between X axis and the horizontal plane. The
range of angle is [-90, 90] degrees.
◦ psi_3x in Theta-Psi-Phi mode – the angle between Y axis and the horizontal plane. The range of
angle is [-90, 90] degrees.
◦ phi_3xin both modes – the angle between X-Y planes and the horizontal plane. The range of
angle is [0, 90] degrees.
◦ roll_3x in Pitch-Roll-Gravity-Inclination – the roll angle. The range of angle is [-180, 180]
degrees.
◦ pitch_3x in Pitch-Roll mode – the pitch angle. The range of angle is [-90, 90] degrees.
◦ err_deg in both modes – the predicted angle error. The range of error in angle is [0, 90]
degrees. The output can be used to accept/reject the tilt angle.
◦ valid in both modes, this flag is used to show if output is valid or not. If accelerometer reading is
showing high vibration or saturation at full scale, library will output ‘0’ in the valid field.
Note: In Pitch-Roll-Gravity-Inclination mode, the psi_3x value represents gravity_inclination_3x value.
UM2277 - Rev 8
page 4/20
UM2277
MotionTL library
• uint8_t MotionTL_GetLibVersion(char *version)
– retrieves the library version
– *version is a pointer to an array of 35 characters
– returns the number of characters in the version string
• void MotionTL_CalibratePosition(float cal_data[][3], uint32_t num_records,
MTL_cal_position_t cal_position)
– calibrates accelerometer in a specific position
– calData parameter is a 2D array with accelerometer data for calibration (3 axes per record)
– nRecords parameter is the number of records
– calPosition parameter is an enumeration of the desired position
– the values for the enumeration type MTL_CalPosition_t are:
◦ X_UP
◦ X_DOWN
◦ Y_UP
◦ Y_DOWN
◦ Z_UP
◦ Z_DOWN
• MTL_CalResult_tMotionTL_GetCalValues(MTL_AccCal_t *accCal)
• – gets the calculated calibration values from the library to be used in the application
– the return value is an enumeration of the calibration result
– the values for the enumeration type MTL_CalResult_t are:
◦ CAL_PASS: Calibration passed
◦ CAL_NONE: Calibration not finished or not performed at all
◦ CAL_FAIL: Calibration failed
– accCal parameter is a pointer to a structure with calibration parameters
– the parameters for the structure type MTL_AccCal_t are:
◦ offset parameter is an array with calculated offset for all 3 axes
◦ gain parameter is an array with calculated gain for all 3 axes
• MTL_CalResult_t MotionTL_SetCalValues(MTL_AccCal_t *accCal)
– validates and sets the calibration values passed in the parameter
– the return value is an enumeration of the calibration result
– for the values for the enumeration type MTL_CalResult_t, see MotionTL_GetCalValues()
function
• void MotionTL_SetOrientation_Acc(const char *acc_orientation)
– this function is used to set the accelerometer data orientation
– configuration is usually performed immediately after the MotionTL_Initialize () function call
– *acc_orientation parameter is a pointer to a string of three characters indicating the direction of
each of the positive orientations of the reference frame used for accelerometer data output, in the
sequence x, y, z. Valid values are: n (north) or s (south), w (west) or e (east), u (up) or d (down).
As shown in the figure below, the X-NUCLEO-IKS01A2 accelerometer sensor has an NWU (x-North,
y-West, z-Up), so the string is: “nwu”.
UM2277 - Rev 8
page 5/20
Figure 1. Example of sensor orientations
UM2277
MotionTL library
2.2.3 Orientation
The MotionTL library works with ENU orientation system, which means device X axis going to East, Y axis going
to North, Z axis going Up.
Any sensor orientation is internally transformed into device ENU orientation system. For this reason the sensor
orientation must be defined using MotionTL_SetOrientation_Acc() function. All the outputs (angels) are
then calculated relative to the ENU orientation system.
Figure 2. Device ENU orientation system
UM2277 - Rev 8
The MotionTL library has different types of outputs angles as detailed in the following tables.
page 6/20
Loading...