November 2016 DocID029859 Rev 1 1/18

www.st.com

UM2123 User manual

Getting started with osxMotionAW activity recognition for wrist library for X-CUBE-MEMS1 expansion for STM32Cube

Introduction osxMotionAW is an add-on software package for X-CUBE-MEMS1. The software runs on the STM32 and includes drivers that recognize ST inertial sensors LSM6DS0, LSM6DS3 or LSM6DSL.

It provides real-time information on user activities: stationary, walking, fast walking, jogging and biking.

The algorithm exclusively manages the data acquired from the accelerometer at a low 16 Hz sampling frequency to reduce host platform power consumption.

The software comes with sample implementations of drivers exploiting STM32Cube software technology, running on an X-NUCLEO-IKS01A2 or X-NUCLEO-IKS01A1 (with optional STEVAL-MKI160V1 board) expansion board, on top of a NUCLEO-F401RE or NUCLEO-L476RG development board.

Contents UM2123

2/18 DocID029859 Rev 1

Contents

1 osxMotionAW library add-on to X-CUBE-MEMS1 software expansion for STM32Cube ...................................................................... 5

1.1 osxMotionAW overview ..................................................................... 5

1.2 osxMotionAW architecture ................................................................ 5

1.3 osxMotionAW folder structure ........................................................... 6

1.4 osxMotionAW APIs ........................................................................... 7

1.4.1 osxMotionAW library ........................................................................... 7

1.5 Sample application ............................................................................ 8

1.5.1 Stand-alone working mode ................................................................. 9

1.5.2 PC GUI driven mode ........................................................................ 10

1.5.3 Unicleo-GUI utility ............................................................................. 11

1.5.4 Data storage ..................................................................................... 13

2 Acronyms and abbreviations ....................................................... 15

3 References ..................................................................................... 16

4 Revision history ............................................................................ 17

UM2123 List of tables

DocID029859 Rev 1 3/18

List of tables

Table 1: LED LD2 activity codes ............................................................................................................... 10 Table 3: Acronyms .................................................................................................................................... 15 Table 4: Document revision history .......................................................................................................... 17

List of figures UM2123

4/18 DocID029859 Rev 1

List of figures

Figure 1: osxMotionAW plus X-CUBE-MEMS1 software architecture ....................................................... 6 Figure 2: osxMotionAW package folder structure ....................................................................................... 7 Figure 3: Example x, y, z axes values ........................................................................................................ 8 Figure 4: NUCLEO-F401RE board details.................................................................................................. 9 Figure 5: State machine ............................................................................................................................ 10 Figure 6: Unicleo main window ................................................................................................................. 11 Figure 7: User Messages tab .................................................................................................................... 11 Figure 8: Activity recognition for Wrist window ......................................................................................... 12 Figure 9: Datalog window ......................................................................................................................... 13

UM2123 osxMotionAW library add-on to X-CUBE-MEMS1 software expansion for STM32Cube

DocID029859 Rev 1 5/18

1 osxMotionAW library add-on to X-CUBE-MEMS1 software expansion for STM32Cube

1.1 osxMotionAW overview

The osxMotionAW library is a complete middleware solution aimed at building applications strictly for 3D accelerometer sensors and specifically designed for wrist devices.

The software runs on the STM32 microcontroller and includes drivers to recognize the available inertial sensors (currently LSM6DS0, LSM6DS3 or LSM6DSL).

Starting from data acquired from the accelerometer only, it provides real-time information on the following activities performed by the user:

stationary

walking

fast walking

jogging

biking

It is built on the STM32Cube software platform to facilitate portability across different STM32 microcontrollers.

The key package features include:

Real-time activity recognition for wrist algorithm (under OpenSoftwareX license) based on accelerometer data only.

Complete middleware to build applications on top of X-CUBE-MEMS1.

Libraries for ARM Cortex-M3 and ARM Cortex-M4 MCU cores.

Easy portability across different MCU families, thanks to STM32Cube.

Sample application to transmit real-time sensor data and recognized activities to a PC.

Sample implementations for X-NUCLEO-IKS01A2 and X-NUCLEO-IKS01A1 (with optional STEVAL-MKI160V1 board) expansion boards, mounted on a NUCLEO-F401RE or NUCLEO-L476RG development board.

The osxMotionAW is an add-on software package for X-CUBE-MEMS1, provided in the form of node-locked library whose license activation codes must be requested to ST and included in the project (thus becoming part of the build process) prior to attempting its usage. The resulting firmware binary image will therefore be node-locked.

For details on system setup and installation as well as details on hardware components, please refer to 2.

1.2 osxMotionAW architecture

The following software layers are used by the application to access and use the sensor expansion board:

STM32Cube HAL layer: the HAL driver layer provides a generic, multi-instance, simple set of APIs (application programming interfaces) to interact with the upper layers (application, libraries and stacks). It is composed of generic and extension APIs. It is directly built around a generic architecture and allows the layers that are built upon, such as middleware layers, to implement their functionalities avoiding dependencies on the specific hardware configuration for a given microcontroller unit

osxMotionAW library add-on to X-CUBE-MEMS1 software expansion for STM32Cube

UM2123

6/18 DocID029859 Rev 1

(MCU). This structure improves library code reusability and guarantees easy portability to other devices.

Board support package (BSP) layer: the software package needs to support all the available peripherals on the STM32 Nucleo board apart from the MCU. This software is included in the board support package (BSP). This is a limited set of APIs which provides a programming interface for certain board specific peripherals; e.g., the LED, user button, etc. This interface also helps in identifying the specific board version. If the sensor expansion board is used, it provides the programming interface for various inertial and environmental sensors. It provides support for initializing and reading sensor data.

The diagram below outlines the software architecture of the package:

Figure 1: osxMotionAW plus X-CUBE-MEMS1 software architecture

1.3 osxMotionAW folder structure

The image below outlines the package file system architecture:

Utilities

CMSIS

Applications

Sample Application

Drivers

Hardware Abstraction Layer API Board Support Packages

Middleware

Development boards

STM32 Nucleo Board

X-NUCLEO-IKS01A1

Expansion board

STEVAL-MKI160V1

Evaluation board (optional)

HW Components

STM32LSM303AGR

LPS25HB

LSM6DS0

LSM6DS3 LSM6DSL

LIS3MDL

X-NUCLEO-IKS01A2

Expansion board

HTS221

LPS22HB

STEVAL-MET001V1

Evaluation board (optional)

osxMotionAW

UM2123 osxMotionAW library add-on to X-CUBE-MEMS1 software expansion for STM32Cube

DocID029859 Rev 1 7/18

Figure 2: osxMotionAW package folder structure

The following folders are included in the package:

Documentation: contains a compiled HTML file detailing the software components and APIs.

Middlewares: contains the osxMotionAW static library binary code, library header file, documentation, license information plus header file for node-locked license validation.

Projects: contains a sample application to access sensor and activity data for the NUCLEO-F401RE and NUCLEO-L476RG platforms under the IAR Embedded Workbench for ARM, µVision (MDK-ARM) toolchain and System Workbench for STM32 integrated development environments.

1.4 osxMotionAW APIs

Detailed technical information fully describing the functions and parameters of the osxMotionAW APIs can be found in the osxMotionAW_Package.chm compiled HTML file located in the Documentation folder of the software package.

The osxMotionAW is provided as a node-locked library which allows derivative firmware images to run on a specific STM32 Nucleo device only. Licensing activation codes must be requested from ST and included in the project (and become part of the build process) prior to attempting its usage. The resulting firmware binary image will therefore be node-locked.

For complete information about the open.MEMS license agreement, please refer to the license file located in the Middlewares/ST/STM32_OSX_MotionPM_Library folder.

1.4.1 osxMotionAW library

The osxMotionAW is a real time activity recognition software solution specifically designed for wrist supports. The algorithm only manages the data acquired from the accelerometer, at the low sampling frequency of 16 Hz to reduce host platform power consumption.

The exposed APIs of the osxMotionAW library are listed below:

uint8_t osx_MotionAW_GetLibVersion(char *version);

retrieves the revision of the included core engine;

uint8_t osx_MotionAW_Initialize(void);

performs osxMotionAW initialization and setup of the internal mechanism used for node-locking (See 2). The output for correct or incorrect initialization is 1 or 0 respectively (e.g., 0 is returned for license errors);

void osx_MotionAW_SetOrientation_Acc (const char

*acc_orientation);

this function is used to set the accelerometer data orientation; library configuration is usually performed immediately after the

osxMotionAW library add-on to X-CUBE-MEMS1 software expansion for STM32Cube

UM2123

8/18 DocID029859 Rev 1

osx_MotionAW_Initialize function call.

The required input 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-IKS01A1 accelerometer sensor has an ENU orientation (x - East, y - North, z - Up), so the string is: “enu”, while the accelerometer sensor in STEVAL-MKI160V1 is NWU (x-North, y-West, z-Up): “nwu”.

Figure 3: Example x, y, z axes values

osx_MAW_output_t osx_MotionAW_Update (osx_MAW_input_t *data_in);

The required input is a pointer to a structure containing the three-axis accelerometer data expressed in g-force units; the output is provided in the osx_MAW_output_t structure, whose fields are the total number of steps and the cadence.

void osx_MotionAW_ResetLib(void);

Resets the algorithm.

1.5 Sample application

The osxMotionAW middleware can be easily manipulated to build user applications.

A sample application is provided in the Projects folder; it is designed to run on either:

UM2123 osxMotionAW library add-on to X-CUBE-MEMS1 software expansion for STM32Cube

DocID029859 Rev 1 9/18

a NUCLEO-F401RE or a NUCLEO-L476RG board connected to an X-NUCLEO-IKS01A1 board (based on LSM6DS0) with optional STEVAL-MKI160V1 board (based on LSM6DS3) connected

a NUCLEO-F401RE or a NUCLEO-L476RG board connected to an X-NUCLEO-IKS01A2 (based on LSM6DSL).

The application performs real-time recognition of activities like being stationary, walking, fast walking, jogging and bike riding.

1.5.1 Stand-alone working mode

In stand-alone working mode, the user can power the board by means of an external battery pack to make the user experience more comfortable, portable and free of any PC connections, ensuring that jumper JP1 in Figure 4: "NUCLEO-F401RE board details" is fitted.

Figure 4: NUCLEO-F401RE board details

The above figure shows details of the NUCLEO-F401RE board, which has a similar layout to the NUCLEO-L476RG board. Once the board is powered, LED LD3 (PWR) turns on and the tricolour LED LD1 (COM) begins blinking slowly due to the missing USB enumeration (see 4).

When user button B1 is first pressed and LED LD2 (USER) is OFF, the system starts acquiring data from the accelerometer sensor and detects the performed activity; during this acquisition mode, rapid LED LD2 blinking indicates that the algorithm is running.

osxMotionAW library add-on to X-CUBE-MEMS1 software expansion for STM32Cube

UM2123

10/18 DocID029859 Rev 1

Pressing button B1 a second time stops the algorithm (and the relative data storage session) and the LED LD2 displays the activity code according to a sequence of flashes described in Table 1: "LED LD2 activity codes".

By pressing the button B1 a third time, the system goes in standby mode; i.e., the algorithm is not running and LED LD2 is off.

Pressing the button again initiates the algorithm and data storage once more (see Figure 5: "State machine").

If LED LD2 is ON after powering the board, this indicates that the flash memory is full or almost full (see Section 1.5.4: "Data storage") or the library has an incorrect embedded license number.

In order to retrieve acquired data stored in Flash, the STM32 Nucleo board has to be connected to a specific PC GUI (see Section 1.5.3: "Unicleo-GUI utility", Section 1.5.4: "Data storage").

Table 1: LED LD2 activity codes

Activity LED LD2 blinking sequence (5 s interval)

Stationary 1

Walking 2

Fast walking 3

Running 4

Biking 5

Figure 5: State machine

1.5.2 PC GUI driven mode

In this working mode the STM32 Nucleo board is powered from the PC via a USB connection, and controlled by a specific PC GUI. It allows the user to display the activity detected, accelerometer data, time stamp and any other sensor data, in real-time using the Unicleo-GUI utility.

Once the board is powered, launch Unicleo_Qt.exe and drive the sample application as described in Section 1.5.3: "Unicleo-GUI utility".

In this working mode the data are not stored in MCU Flash memory.

UM2123 osxMotionAW library add-on to X-CUBE-MEMS1 software expansion for STM32Cube

DocID029859 Rev 1 11/18

1.5.3 Unicleo-GUI utility

The osxMotionAW software package for STM32Cube uses the Windows Unicleo-GUI utility, which can be downloaded from www.st.com (see 5 for instructions).

1 Ensure that the necessary drivers are installed and the STM32 Nucleo board with appropriate expansion board is connected to the PC.

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 will automatically be detected and the appropriate COM port will be opened.

Figure 6: Unicleo main window

3 Start and stop data streaming by using the appropriate buttons on the vertical tool bar.

The data coming from the connected sensor can be viewed in the User Messages tab.

Figure 7: User Messages tab

osxMotionAW library add-on to X-CUBE-MEMS1 software expansion for STM32Cube

UM2123

12/18 DocID029859 Rev 1

4 Click on the Activity for Wrist icon in the vertical tool bar to open the dedicated window for wrist activity recognition.

Figure 8: Activity recognition for Wrist window

UM2123 osxMotionAW library add-on to X-CUBE-MEMS1 software expansion for STM32Cube

DocID029859 Rev 1 13/18

5 Click on the Datalog icon in the vertical tool bar to open the datalog configuration window.

Here, you can select which sensor and activity data to save in files. Saves can be started or stopped by clicking on the corresponding button.

Figure 9: Datalog window

1.5.4 Data storage

The sample application allows the user to detect activity performed and store it in MCU flash memory. Data is automatically saved every five minutes to avoid losing too much data in case of an unforeseen power fault. Data is also stored when the user stops acquisition by pressing button B1 to display data by LED.

When stored data is retrieved via the GUI, the MCU Flash sector dedicated to this purpose is cleared.

LED LD2 should be OFF at power-on, unless:

the Flash memory is full or almost full

the license number is incorrect

In the first case, the user can continue using the board for normal activity recognition and data storage (if enough space is available) as described in Section 1.5.1: "Stand-alone working mode" by pushing the user button (LED switches off in five seconds). Data continues to be stored until the reserved sector is full, at which time the algorithm keeps running, but data is no longer stored.

The Flash sector for data storage is 128 KB, allowing memorization of more than 16,000 data sets, or:

a minimum of 91 hours (activity changes and a new buffer is stored every 20 seconds)

a maximum of 1365 hours (activity never changes and data is automatically stored every 5 minutes).

If LED LD2 switches ON at reset, no more than 1400 Bytes are free; i.e., a recording time of between one hour if data is stored every 20 seconds to 15 hours if data is automatically saved every five minutes.

osxMotionAW library add-on to X-CUBE-MEMS1 software expansion for STM32Cube

UM2123

14/18 DocID029859 Rev 1

If a large amount of data needs to be stored and no PC is available for data download and Flash memory clean up, the MCU memory can be erased when LED LD2 is ON by holding the user push button down for at least five seconds. LED LD2 switches OFF and then starts blinking to indicate that acquisition mode has been activated and the data stored in the MCU has been erased.

If LED LD2 does not switch OFF after this operation, the license number is wrong and no action is allowed. See 2 for details on how to obtain a license.

UM2123 Acronyms and abbreviations

DocID029859 Rev 1 15/18

2 Acronyms and abbreviations Table 3: Acronyms

Acronym Description

API application programming interface

BSP board support package

ENU x-East, y-North, z-Up

GUI graphical user interface

HAL hardware abstraction layer

IDE integrated development environment

NED x-North, y-East, z-Down

SEU x-South, y-East, z-Up

References UM2123

16/18 DocID029859 Rev 1

3 References

1. UM1859: Getting started with the X-CUBE-MEMS1 motion MEMS and environmental sensor software expansion for STM32Cube

2. UM2012: osxMotionXX system setup 3. DB3052: Real-time activity recognition for wrist software expansion for STM32Cube 4. UM1724: STM32 Nucleo-64 boards 5. UM2128: Unicleo-GUI

UM2123 Revision history

DocID029859 Rev 1 17/18

4 Revision history Table 4: Document revision history

Date Revision Changes

11-Nov-2016 1 First release.

UM2123

18/18 DocID029859 Rev 1

IMPORTANT NOTICE – PLEASE READ CAREFULLY

STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.

Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of Purchasers’ products.

No license, express or implied, to any intellectual property right is granted by ST herein.

Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.

ST and the ST logo are trademarks of ST. All other product or service names are the property of their respective owners.

Information in this document supersedes and replaces information previously supplied in any prior versions of this document.

© 2016 STMicroelectronics – All rights reserved