ST MotionTL Bedienungsanleitung

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.

Getting started with MotionTL tilt measurement library in X-CUBE-MEMS1

expansion for STM32Cube

UM2277

User manual

UM2277 - Rev 8 - April 2021

For further information contact your local STMicroelectronics sales office.

www.st.com

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

UM2277

Acronyms and abbreviations

UM2277 - Rev 8 page 2/20

2MotionTL 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

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

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()

•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

MotionTL library

UM2277 - Rev 8 page 4/20

•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

MotionTL library

UM2277 - Rev 8 page 5/20

Figure 1. Example of sensor orientations

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

The MotionTL library has different types of outputs angles as detailed in the following tables.

UM2277

MotionTL library

UM2277 - Rev 8 page 6/20

Table 2. Pitch, Roll and Gravity Inclination output angles

Value Pitch Roll Gravity Inclination

Formula arctan2 (-Y/Z) arcsin (X) arccos (Z)

Range -180°, +180° -90°, +90° 0, 180°

Description Angle between Y axis and horizontal

plane.

Angle between X axis and horizontal

plane.

Angle between gravity vector

and Z axis.

Sign Top edge of the device going towards

ground generates positive pitch.

Left edge of the device going towards

ground generates positive roll. Always positive.

Table 3. Theta, Psi and Phi output angles

Value Theta Psi Phi

Formula arctan (X/sqrt(Y2+Z2)) arctan (Y/sqrt(X2+Z2)) arctan (sqrt(X2+Y2)/Z)

Range -90°, +90° -90°, +90° -90°, +90°

Description Angle between X axis and

horizontal plane.

Angle between Y axis and

horizontal plane.

Angle between Z axis and gravity

vector.

Sign

Left edge of the device going

towards ground generates positive

theta angle.

Bottom edge of the device going

towards ground generates positive

Psi angle.

Positive if Z axis facing up, Negative

if Z axis facing down.

Note: Calculation using tangent functions produces constant tilt sensitivity over measurement range.

UM2277

MotionTL library

UM2277 - Rev 8 page 7/20

2.2.4 API flow chart

Figure 3. MotionTL API logic sequence (main program)

Wait Expiring Timer

Data Read Interrupt

Update

Read Accelerometer Data

Start

Initialize

Get Angles

GetLibVersion

Figure 4. MotionTL API logic sequence (calibration)

Calculate calib. values in

the desired position

Collect calibration data

Store calibration values

If calibration

command received

UM2277

MotionTL library

UM2277 - Rev 8 page 8/20

2.2.5 Demo code

The following demonstration code reads data from the accelerometer sensor and gets the tilt angles.

[…]

#define VERSION_STR_LENG 35

[…]

/*** Initialization ***/

char lib_version[VERSION_STR_LENG];

char acc_orientation[3];

acc_orientation[0] = 'n';

acc_orientation[1] = 'w';

acc_orientation[2] = 'u';

/* Tilt API initialization function */

/* Note: Use MCU type according to target HW – in this example we use standard STM32 MCU */

MotionTL_Initialize(MTL_MCU_STM32, acc_orientation);

/* OPTIONAL */

/* Get library version */

lib_version_len = MotionTL_GetLibVersion(lib_version);

[…]

/*** Using tilt algorithm ***/

Timer_OR_DataRate_Interrupt_Handler()

{

MTL_input_t data_in;

MTL_output_t data_out;

uint64_t timestamp_ms;

/* Set the angle computation mode */

MTL_knobs_t knobs;

MotionTL_GetKnobs(&knobs);

knobs.mode = MODE_THETA_PSI_PHI;

MotionTL_SetKnobs(&knobs);

/* Get acceleration X/Y/Z in g */

MEMS_Read_AccValue(&data_in.acc_x, &data_in.acc_y, &data_in.acc_z);

/* Get timestamp in ms */

timestamp_ms = get_time_ms();

/* Run tilt sensing algorithm */

MotionTL_Update(&data_in, timestamp_ms, &data_out);

}

2.2.6 Algorithm performance

Table 4. Cortex -M4 and Cortex-M3: elapsed time (µs) algorithm

Cortex-M4 STM32F401RE at 84 MHz Cortex-M3 STM32L152RE at 32 MHz

STM32CubeIDE

1.2.0

IAR EWARM

8.32.3 Keil µVision 5.27 STM32CubeIDE

1.2.0

IAR EWARM

8.32.3 Keil µVision 5.27

Min Avg Max Min Avg Max Min Avg Max Min Avg Max Min Avg Max Min Avg Max

80 159 163 104 104 162 104 300 303 514 571 584 373 375 575 375 967 974

UM2277

MotionTL library

UM2277 - Rev 8 page 9/20

Table 5. Cortex -M0+ and Cortex-M7: elapsed time (µs) algorithm

Cortex-M0+ STM32L073RZ at 32 MHz Cortex-M7 STM32F767ZI at 96 MHz

STM32CubeIDE

1.2.0

IAR EWARM

8.32.3 Keil µVision 5.27 STM32CubeIDE

1.2.0

IAR EWARM

8.32.3 Keil µVision 5.27

Min Avg Max Min Avg Max Min Avg Max Min Avg Max Min Avg Max Min Avg Max

233 1719 1744 856 860 1727 858 2607 2619 27 28 28 17 18 18 29 30 31

2.3 Sample application

The MotionTL middleware can be easily manipulated to build user applications; a sample application is provided

in the Application folder.

It is designed to run on a NUCLEO-F401RE, NUCLEO-L476RG, NUCLEO-L152RE or NUCLEO-L073RZ

development board connected to an X-NUCLEO-IKS01A2, X-NUCLEO-IKS01A3 or X-NUCLEO-IKS02A1

expansion board.

The tilt sensing algorithm only uses data from the accelerometer. It detects and provides real-time information

about the tilt angles of the user device. The library is also able to perform accelerometer 6-position calibration if

required. The data can be displayed through a GUI.

A USB cable connection is required to monitor real-time data. This allows the user to display in real-time

calculated tilt angles, accelerometer data, time stamp and eventually other sensor data using the Unicleo-GUI.

After pressing the Tilt Calibrate button in the Unicleo-GUI, the user is asked to hold the device still in each of the

six positions while the calibration data is collected. Then the calibration parameters (offset and gain for all 3 axes)

are calculated and sent to the Unicleo-GUI.

2.4 Unicleo-GUI application

The sample application uses the Windows Unicleo-GUI utility, which can be downloaded from www.st.com.

Step 1. Ensure that the necessary drivers are installed and the STM32 Nucleo board with appropriate

expansion board is connected to the PC.

Step 2. Launch the Unicleo-GUI application to open the main application window.

If an STM32 Nucleo board with supported firmware is connected to the PC, it is automatically detected

and the appropriate COM port is opened.

Figure 5. Unicleo main window

UM2277

Sample application

UM2277 - Rev 8 page 10/20

Inhaltsverzeichnis

Andere ST Computerhardware Handbücher

ST UM3019 Bedienungsanleitung

ST X-NUCLEO-53L5A1 Bedienungsanleitung

ST STEVAL-SCR002V1 Bedienungsanleitung

ST UM2168 Bedienungsanleitung

ST STEVAL-ISQ008V1 Bedienungsanleitung

ST UPSD3212A Bedienungsanleitung

ST STM32C0 Series Bedienungsanleitung

ST X-NUCLEO-53L5A1 Bedienungsanleitung

ST TDA911 Series Montage- und Bedienungsanleitung

ST STM32MP157D-DK1 Bedienungsanleitung

ST X-NUCLEO-OUT10A1 Bedienungsanleitung

ST X-NUCLEO-SNK1M1 Bedienungsanleitung

ST AEK-LCD-DT028V1 Bedienungsanleitung

ST STM32F405 Series Bedienungsanleitung

ST STEVAL-ISF001V1 Bedienungsanleitung

ST ST10R272L Bedienungsanleitung

ST STR9 Bedienungsanleitung

ST STM32 ODE Bedienungsanleitung

ST X-NUCLEO-OUT17A1 Bedienungsanleitung

ST STEVAL-IPFC02V1 Bedienungsanleitung

ST STM32 Nucleo Bedienungsanleitung

ST ST7LITEUS2 Bedienungsanleitung

ST X-NUCLEO-OUT09A1 Bedienungsanleitung

ST X-NUCLEO-IHM09M1 Bedienungsanleitung

Beliebte Computerhardware Handbücher anderer Marken

EMC2

EMC2 VNX Series Betriebsanleitung

Panasonic

Panasonic DV0PM20105 Bedienungsanleitung

Mitsubishi Electric

Mitsubishi Electric Q81BD-J61BT11 Bedienungsanleitung

Gigabyte

Gigabyte B660M DS3H AX DDR4 Bedienungsanleitung

Raidon

Raidon iT2300 Bedienungsanleitung

National Instruments

National Instruments PXI-8186 Bedienungsanleitung

Hauppauge

Hauppauge WinTV-HVR-2250 Bedienungsanleitung

Kontron

Kontron CP6002 Bedienungsanleitung

Manhattan

Manhattan 702843 Bedienungsanleitung

Aphex

Aphex 230 Bedienungsanleitung

Intel

Intel NUC 12 Pro Bedienungsanleitung

Galaxy

Galaxy GHDX2-2430S-24F4D Bedienungsanleitung

Intel

Intel AXXRMFBU4 Bedienungsanleitung

Kontron

Kontron DIMM-PC/MD Bedienungsanleitung

STEINWAY LYNGDORF

STEINWAY LYNGDORF SP-1 Bedienungsanleitung

Advantech

Advantech ASMB-935 Series Bedienungsanleitung

Jupiter

Jupiter RAM PACK Bedienungsanleitung

Measurement Computing

Measurement Computing CIO-EXP-RTD16 Bedienungsanleitung