STMicroelectronics MotionFX User Manual

UM2220

User manual

Getting started with MotionFX sensor fusion library in X-CUBE-MEMS1 expansion for STM32Cube

Introduction

The MotionFX is a middleware library component of the X-CUBE-MEMS1 software and runs on STM32. It provides real-time motion-sensor data fusion. It also performs gyroscope bias and magnetometer hard iron 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 architectures.

It is built on top of STM32Cube software technology to ease portability across different STM32 microcontrollers.

The software comes with 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.

UM2220 - Rev 8 - April 2021	www.st.com
For further information contact your local STMicroelectronics sales office.

UM2220

Acronyms and abbreviations

1Acronyms 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

UM2220 - Rev 8	page 2/25

UM2220

MotionFX middleware library in X-CUBE-MEMS1 software expansion for STM32Cube

2MotionFX middleware library in X-CUBE-MEMS1 software expansion for STM32Cube

2.1MotionFX overview

The MotionFX library expands the functionality of the X-CUBE-MEMS1 software.

The library acquires data from the accelerometer, gyroscope (6-axis fusion) and magnetometer (9-axis fusion) and provides real-time motion-sensor data fusion.

The MotionFX filtering and predictive software uses advanced algorithms to intelligently integrate outputs from multiple MEMS sensors, regardless of environmental conditions, for an optimum performance.

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.

The complexity of the library dedicated to the Cortex-M0+ core is reduced due to the performance limitation of Cortex-M0+ architecture. This library uses different APIs and has less features in comparison with the version for Cortex-M3, Cortex-M4 and Cortex-M7 (for further details, see the following chapters).

A sample implementation is available on X-NUCLEO-IKS01A2 and X-NUCLEO-IKS01A3 expansion board, mounted on a NUCLEO-F401RE, NUCLEO-L476RG, NUCLEO-L152RE or NUCLEO-L073RZ development board.

2.2MotionFX library

Technical information fully describing the functions and parameters of the MotionFX APIs can be found in the MotionFX_Package.chm compiled HTML file located in the Documentation folder.

2.2.1MotionFX library description

The MotionFX sensor fusion library manages data acquired from accelerometer, gyroscope and magnetometer sensor; it features:

•real-time 9-axis motion-sensor data fusion (accelerometer, gyroscope, magnetometer)

•real-time 6-axis motion-sensor data fusion (accelerometer, gyroscope)

•computation of rotation, quaternions, gravity and linear acceleration data

•gyroscope bias calibration

•magnetometer hard iron calibration

•recommended sensor data sampling frequency of 100 Hz

•resources requirements:

–Cortex-M0+: 15.9 kB of code and 2.1 kB of data memory

–Cortex-M3: 49.3 kB of code and 1.1 kB of data memory

–Cortex-M4: 44.1 kB of code and 1.1 kB of data memory

–Cortex-M7: 42.6 kB of code and 1.1 kB of data memory

•available for ARM Cortex-M0+, Cortex-M3, Cortex-M4 and Cortex-M7 architecture

2.2.2MotionFX 6-axis and 9-axis sensor fusion modes

The MotionFX library implements a sensor fusion algorithm for the estimation of 3D orientation in space. It uses a digital filter based on the Kalman theory to fuse data from several sensors and compensate for limitations of single sensors. For instance, gyroscope data can drift and this impacts the orientation estimation; this issue can be fixed by using the magnetometer to provide absolute orientation information.

Similarly, the magnetometer does not have a very high bandwidth and suffers from magnetic disturbance, but these weaknesses can be compensated with a gyroscope.

9-axis sensor fusion uses data from the accelerometer, gyroscope and magnetometer and provides absolute orientation in 3D space including heading (i.e., the magnetic North direction).

6-axis sensor fusion uses the accelerometer and gyroscope data only. It has lower computational requirements, but does not provide information about the device absolute orientation.

6-axis sensor fusion is fit for fast movements (e.g., for gaming) and when absolute orientation is not necessary.

UM2220 - Rev 8	page 3/25

UM2220

MotionFX library

2.2.3MotionFX library operation

The MotionFX library integrates 6- and 9-axis sensor fusion algorithms in one library; they can even run simultaneously to provide both rotation vector (9X) and game rotation vector (6X).

Cortex-M3, Cortex-M4 and Cortex-M7

The library implements the following critical internal functions associated with sensor fusion computation:

1.the MotionFX_propagate is a prediction function used to estimate the orientation in 3D space; gyroscope data is given more weight in this phase.

2.the MotionFX_update is the corrective function which adjusts the predicted value when necessary; accelerometer and magnetometer data are given more weight in this phase.

The MotionFX_update function can be called whenever the MotionFX_propagate is invoked, or less often in systems that have less computation power.

The MotionFX_update function takes approximately three times more MCU computation time than the

MotionFX_propagate function.

Cortex-M0+

The sensor fusion computation is concentrated in only one function MotionFX_CM0P_update.

2.2.4MotionFX library parameters

Cortex-M3, Cortex-M4 and Cortex-M7

The library is "parametrized" using an MFX_knobs_t structure. The parameters for the structure are:

•ATime, MTime, FrTime represent the weighting stability of sensors for prediction (trust factor), from 0 to 1. Default values are recommended.

–ATime: lowering the value will increase the accelerometer weight and sensitivity towards external acceleration. If the application experiences low acceleration (<1g) most of time, it is recommended to increase the value.

–MTime, FrTime: for 9X solution, the lower value will increase the weight of magnetometer reading. If the application experiences low magnetic interference (<50 μT) most of time, it is recommended to increase the value.

•LMode represents the gyroscope bias learning mode; the library automatically tracks and calibrates gyro zero-rate bias drift.

This possible parameter values are:

–LMode = 0 – learning off; use this mode if the gyro is already calibrated

–LMode = 1 – static learning; learning is performed only when the system is not moving

–LMode = 2 – dynamic learning; learning is also performed when the system is moving

•gbias_acc/gyro/mag_th_sc represents the thresholds below which the gbias algorithm automatically starts. These values should be established through testing (they are different for different part numbers). The values in the example project are usually correct. The value can be determined by enabling start_automatic_gbias_calculation, placing the device stationary for 10 seconds and reading the value of knobs.

–modx represents the decimation of MotionFX_update call frequency

–output_type represents the sensor fusion library output orientation: 0 = NED, 1 = ENU

–start_automatic_gbias_calculation: this flag allows computing gbias_acc/gyr/ mag_sens_th_sc for an application, by placing the device stationary for 10 seconds and setting this flag to 1 by calling MotionFX_setKnobs API. After 10 seconds or more, call MotionFX_getKnobs API to get the value of these thresholds.

–acc/gyro/mag_orientation is the acc/gyro/mag 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).

As shown in the figure below, the X-NUCLEO-IKS01A2 accelerometer sensor has an NWU orientation (x - East, y - North, z - Up), so the string is: “nwu”.

UM2220 - Rev 8	page 4/25

UM2220

MotionFX library

Figure 1. Example of sensor orientations

Cortex-M0+

Only the sensor orientation must be set using MotionFX_CM0P_setOrientation function. The parameters of this function are orientation strings which are composed in the same manner as for Cortex-M3, Cortex-M4 and Cortex-M7 (see above).

The MotionFX_propagate and the MotionFX_update (MotionFX_CM0P_update) functions receive input from sensors in the MFX_input _t (MFX_CM0P_input_t) structure:

•mag represents magnetometer data after calibration in μT/50

•acc represents accelerometer data in g

•gyro represents gyroscope data in dps

The MotionFX_propagate and the MotionFX_update (MotionFX_CM0P_update) functions provide the sensor fusion output in the MFX_output_t (MFX_CM0P_output_t) structure:

•rotation represents the system orientation in three-angle format: yaw, pitch and roll

MotionFX library uses the following convention yaw range: 0-360 degrees, pitch range ±180 degrees and roll range ±90 degrees

•quaternion represents the system orientation in four-number format; this format gives the same information as rotation but it has advantages for computation and is therefore usually used by other algorithms (based on the sensor fusion)

•gravity represents the static acceleration (i.e., Earth gravity) vector extracted from the acceleration data

•linear_acceleration represents the dynamic acceleration (i.e., movement) vector extracted from the acceleration data

UM2220 - Rev 8	page 5/25

UM2220

MotionFX library

•heading represents the heading of the device in degrees. Heading 0 degree represents the magnetic North direction for 9-axis sensor fusion, while, for 6-axis sensor fusion, it represents heading of device at the algorithm start.

•headingErr represents the heading error of the device in degrees

2.2.5MotionFX library output data rate

It is important to set up the sensor fusion library output data rate properly; 100 Hz is recommended. The output data rate for:

•the gyroscope and the accelerometer should be equal to or greater than 100 Hz;

•the magnetometer can be lower - 20/40 Hz is typically good for a magnetic field sensor.

Cortex-M3, Cortex-M4 and Cortex-M7

It is possible to scale the library system requirements in terms of MCU/MPU load. As the MotionFX_update function requires approximately three times more computation power than the MotionFX_propagate function, it can be called at a lower frequency than the library output data rate if the system resources are limited (e.g., in embedded systems).

Use the modx parameter in MFX_knobs_t structure to decrease the frequency of MotionFX_update function calls. For example, setting modx to 2 calls the MotionFX_update function once every two

MotionFX_propagate function calls. The recommended settings are:

•modx = 1, for tablets or other systems with MCU/MPU and for STM32F4;

•modx = 2, for STM32F1.

2.2.6Sensor calibration in the MotionFX library

Gyroscope and accelerometer calibration

Accelerometer calibration is not necessary for sensor fusion except for applications demanding very high orientation precision; it involves aligning the system in several positions according to the gravity direction.

Gyroscope calibration is handled automatically by the MotionFX library by continuously compensating the zerorate offset effect.

Magnetometer calibration

The MotionFX library contains routines for magnetometer hard iron calibration.

The magnetometer is affected by the hard-iron and soft-iron phenomena described below.

Hard-iron distortion

Hard-iron distortion is normally generated by ferromagnetic material with permanent magnetic fields that are part of the object (e.g., a tablet) in use. These materials can be permanent magnets or magnetized iron or steel. They are time invariant and deform the local geomagnetic field with different offsets in different directions.

As each board can be magnetized differently, the hard iron effect is specific to the individual board.

If you move the board around a space approximating (as much as possible) a 3D sphere in an ideal environment (no hard-iron/soft-iron distortion) and plot the collected magnetic sensor raw data, the result is a perfect sphere with no offset.

The hard-iron distortion effect offsets the sphere along the x, y and z axes; in the x-y plane, the hard-iron distortion is identified by an offset of the origin of the ideal circle from (0, 0), scatter plots for XY and XZ axes are sufficient to determine if there is an offset.

Soft-iron distortion

Soft-iron distortion is generated by magnetically soft materials or current carrying PCB traces. While hard-iron distortion is constant regardless of the orientation, the soft-iron distortion changes with the orientation of the object in the Earth’s field (soft magnetic materials change their magnetization direction).

The local geomagnetic field is deformed with different gain on different directions. The effect of the soft-iron to distort the ideal full round sphere into a tilted ellipsoid; in the x-y plane, the soft-iron distortion is identified by a tilted ellipse with the origin at (0,0) for the XY axis (XZ).

UM2220 - Rev 8	page 6/25

UM2220

MotionFX library

The soft iron effect is the same across all boards of the same design, which is why a good PCB design which takes magnetometer placement (high current traces/other component clearance) into account can generally avoid any soft iron effects (valid for X-NUCLEO-IKS01A2 expansion board).

Calibration procedure

The MotionFX library magnetometer calibration library compensates for hard-iron distortions.

The magnetometer calibration can be performed at a slower frequency than the sensor fusion output data rate (e.g., 25 Hz).

To run the calibration:

1.initialize magnetometer calibration library (MotionFX_MagCal_init or MotionFX_CM0P_MagCal_init)

2.call periodically calibration function (MotionFX_MagCal_run or MotionFX_CM0P_MagCal_run) until the calibration is successfully performed

3.check if calibration was successful (MotionFX_MagCal_getParams or

MotionFX_CM0P_MagCal_getParams); if the function returns mag_data_out.cal_quality = MFX_MAGCALGOOD or MFX_CM0P_CALQSTATUSBEST, the calibration was successfully performed

4.apply calibration results:

–− MAG_Calibrated.AXIS_X = MAG_Value.AXIS_X - MAG_Offset.AXIS_X

–− MAG_Calibrated.AXIS_Y = MAG_Value.AXIS_Y - MAG_Offset.AXIS_Y

–− MAG_Calibrated.AXIS_Z = MAG_Value.AXIS_Z - MAG_Offset.AXIS_Z

After calibration routine initialization, slowly rotate the device in a figure 8 pattern in space. While performing this movement, keep the device clear of other magnetic objects such as cell phones, computers and other steel objects.

Figure 2. STM32 Nucleo board rotation during calibration

To check that the calibration was performed correctly, check magnetometer data (after applying calibration results) using the scatter plot.

UM2220 - Rev 8	page 7/25

UM2220

MotionFX library

2.2.7MotionFX APIs

The MotionFX APIs are:

Cortex-M3, Cortex-M4 and Cortex-M7

•size_t MotionFX_GetStateSize(void)

–retrieves the size of the library to be allocated prior to run

–every instance of motionFX requires the allocation of this size

•void MotionFX_initialize(MFXState_t mfxstate_pt)

–performs MotionFX library initialization and setup of the internal mechanism

–mfxstate_pt is the pointer to the allocated memory for the instance of MotionFX

Note:	This function must be called before using the sensor fusion library and the CRC module in the STM32
	microcontroller (in RCC peripheral clock enable register) has to be enabled.
	•	uint8_t MotionFX_GetLibVersion(char *version)
		–	retrieves the version of the library
		–	*version is a pointer to an array of 35 characters
		–	returns the number of characters in the version string
	•	void MotionFX_setKnobs(MFXState_t mfxstate_pt, MFX_knobs_t *knobs)
		–	sets the internal knobs
		–	mfxstate_pt is a pointer to the allocated memory for the instance of MotionFX
	•	void MotionFX_getKnobs(MFXState_t mfxstate_pt, MFX_knobs_t *knobs)
		–	gets the current internal knobs
		–	mfxstate_pt is a pointer to the allocated memory for the instance of MotionFX
		–	*knobs parameter is a pointer to a structure with knobs
	•	MFX_engine_state_t MotionFX_getStatus_6X(MFXState_t mfxstate_pt)
		–	gets the 6 axes library status
		–	mfxstate_pt is a pointer to the allocated memory for the instance of MotionFX
		–	returns 1 if enabled, 0 if disabled
	•	MFX_engine_state_t MotionFX_getStatus_9X(MFXState_t mfxstate_pt)
		–	gets the 9 axes library status
		–	mfxstate_pt is a pointer to the allocated memory for the instance of MotionFX
		–	returns 1 if enabled, 0 if disabled
	•	void MotionFX_enable_6X(MFXState_t mfxstate_pt, MFX_engine_state_t enable)
		–	enables or disables the 6 axes function (ACC + GYRO)
		–	mfxstate_pt is a pointer to the allocated memory for the instance of MotionFX
		–	enable parameter is 1 to enable, 0 to disable
	•	void MotionFX_enable_9X(MFXState_t mfxstate_pt, MFX_engine_state_t enable)
		–	enables or disables the 9 axes function (ACC + GYRO + MAG)
		–	mfxstate_pt is a pointer to the allocated memory for the instance of MotionFX
		–	enable parameter is 1 to enable, 0 to disable

UM2220 - Rev 8	page 8/25