ST UM3019 User manual

Introduction
The FP-ATR-ASTRA1 is an STM32Cube function pack that implements a complete asset tracking application,
which supports long-range connectivity and short-range connectivity. This application reads the data from the
environmental and motion sensors, retrieves the geo-position from GNSS and sends them to the cloud using
Bluetooth® Low Energy and LoRaWAN connectivity.
The FP-ATR-ASTRA1 package supports low-power profiles and the related transitions to ensure long battery
autonomy. Moreover, it provides key features such as secure element management, the possibility to add custom
algorithms, debugging interfaces, and expansion capability.
The firmware is available as a standard source code .zip file.
Getting started with the STM32Cube function pack for IoT tracker node with
Bluetooth® Low Energy, LoRa, NFC connectivity, GNSS and sensors
UM3019
User manual
UM3019 - Rev 1 - April 2022
For further information contact your local STMicroelectronics sales office.
www.st.com

1FP-ATR-ASTRA1 software expansion for STM32Cube
1.1 Overview
The FP-ATR-ASTRA1 software package expands STM32Cube functionality.
The key features of the package are:
• Complete asset tracking firmware application to manage long-range connectivity (LoRaWAN) and short-
range connectivity (Bluetooth® Low Energy and NFC)
• Environmental and motion sensors management to monitor asset status
• Outdoor localization and geo-fencing based on a GNSS NMEA string available on Teseo-LIV3F
• Secure element personalization and certificate retrieving
• Power/battery management with low-power operating modes
• Flexible state machine to support different use cases
• Predefined customizable use cases:
– Fleet management
– Livestock monitoring
– Goods monitoring
– Logistics
– Custom
• Implementation available for the STEVAL-ASTRA1B
• Fully integrated in an end-to-end, proof-of-concept ecosystem, which includes:
– the DSH-ASSETRACKING web cloud dashboard
– the STAssetTracking mobile app available on Google Play and App Store
1.2 Architecture
FP-ATR-ASTRA1 is developed to support all the STEVAL-ASTRA1B functionalities.
The FP-ATR-ASTRA1, compliant with the STM32Cube architecture, is structured into a set of layers of increasing
abstraction.
The hardware abstraction layer (HAL) interfaces with the hardware. It provides the low-level drivers and the
hardware interface methods to interact with the upper layers (application, libraries, and stacks). It also provides
the APIs for the communication peripherals (I²C, SPI, UART, etc.) for initialization and configuration, data transfer,
and communication errors.
The package provides a board support package (BSP), which deals with the board-specific peripherals and
functions (LED, user button, etc.). The BSP structure follows the hardware structure, including a component
management layer as well as the specific layers of the board used. The modules included in the BSP are selected
according to the used hardware configuration.
The horizontal interaction among the layer components is handled directly by calling the feature APIs. The vertical
interaction with the low-level drivers is managed through specific callbacks and static macros implemented in the
library system call interface.
On top, the application layer contains functions and procedures that characterize the application and can be
changed by the end user.
UM3019
FP-ATR-ASTRA1 software expansion for STM32Cube
UM3019 - Rev 1 page 2/43

Figure 1. FP-ATR-ASTRA1 software architecture
FP-ATR-ASTRA1
abstraction
GNSS NMEA
Hardware
Dashboard
Parson
ST ASSET TRACKING
CLOUD DASHBOARD
Application
And
Middleware
Utilities
STM32Cube hardware abstraction layer (HAL)
ST WPAN
STEVAL-ASTRA1B
and
Mobile App ST ASSET TRACKING
APP
Sequencer
USB
BLE manager and
SDK v2
LOW POWER
Hardware
MANAGER
ST SAFE
1.3 Folder structure
The software package includes the following folders:
•Documentation: contains a compiled HTML file generated from the source code, which details the software
components and APIs.
•Drivers: contains the HAL drivers and the board-specific drivers for each supported board or hardware
platform, including the on-board components and the CMSIS vendor-independent hardware abstraction
layer for the Arm Cortex®-M processor series.
•Middleware: contains libraries and protocols for the USB communication, STM32-WPAN, GNSS NMEA,
Parson library, Bluetooth® Low Energy manager, STSAFE, sequencer, and low-power manager.
•Projects: contains sample application used to implement asset tracking examples.
This application is provided for the STEVAL-ASTRA1B evaluation kit with three development environments
(IAR Embedded Workbench for Arm, MDK-ARM, and STM32CubeIDE).
Figure 2. FP-ATR-ASTRA1 folder structure
1.4 APIs
Detailed technical information with full user API function and parameter description is in a compiled HTML file in
the “Documentation” folder.
UM3019
Folder structure
UM3019 - Rev 1 page 3/43

2Sample application description
A standard asset tracking routine acquires information about location, sensor and system status. Then, the
routine sends the information acquired through the available communication interfaces with the minimum power
consumption.
Different use cases require the customization of these routines in terms of:
• acquisition frequency
• sending interval
• algorithms to run in order to add specific features
• localization technologies
• communication interfaces
The FP-ATR-ASTRA1 offers the following preconfigured (and customizable) use cases:
1. fleet management
2. livestock monitoring
3. goods monitoring
4. logistics
5. custom
The characteristics of these use cases are listed in the table below.
Table 1. Use cases
Uses cases LoRa sending
interval
Bluetooth® Low Energy
sending interval
Indoor only
(GNSS disabled) Algorithm(1) Data logging(2)
Fleet management 40 s 100 ms N No Yes
Livestock monitoring 60 s 500 ms N Motion No
Goods monitoring 3600 s 200 ms Y Geofence Yes
Logistics 20 s 1000 ms N No Yes
Custom 30 s 400 ms N No Yes
1. Only an empty callback is available. It has to be filled by the user. See the manageAlgorithms( ) function in the source
code.
2. The “LOG” flag is available in the source code. The data logging is going to be available in the coming releases. See
AstraEngineParams_t typedef in the source code.
2.1 Firmware library structure
The FP-ATR-ASTRA1 firmware flexibility allows changing the operation mode easily. The state machine can
change states and transitions according to the selected use case.
The firmware library structure is modular to meet these requirements. The figure below shows how the data flow
from the input to the output.
UM3019
Sample application description
UM3019 - Rev 1 page 4/43

Figure 3. Data flow diagram
The data acquired from the sensors, GNSS, and ADC through the driver interface, are stored in the RAM and/or
EEPROM (the storage in the EEPROM is not implemented yet, but it is going to be available in the coming
releases). Then, they are processed and sent. The processing output can be sent as well. The same path is used
for the configuration channels, shown in the figure below, to manage the settings at runtime.
Figure 4. Configuration block diagram
2.2 State machine
The application flow evolves by using a state machine that triggers a status change depending on events and
triggers.
A simple state machine has been implemented featuring two states: full-run state and low-power state. These
states are not related to the MCU power state, but to the whole system condition. A minimum and a maximum
performance and, consequently, power consumption characterize these states. In the full-run state, everything is
on and all the data are sent to the dashboard. In the low-power state, all the components, except the MCU, are
configured in low-power mode.
The side button event triggers the transition between the two states. Another input can be a MEMS event output
or the result of an algorithm.
This is just an example of how a state machine can be implemented, changing the behavior of our device. Several
intermediate states can also be implemented, balancing the system responsiveness and the battery life.
UM3019
State machine
UM3019 - Rev 1 page 5/43

Figure 5. State machine-functional diagram
The figure below shows the detailed flow diagram of the process, referring to the code implementation.
Figure 6. State machine flow
UM3019
State machine
UM3019 - Rev 1 page 6/43

The states are:
•Start
•Run
•LP (low-power)
•End
Figure 7. State description
The following callbacks describe each state:
•StartXXXFn is the function that turns the module on in the start state;
•RunXXXFn is the function that executes the module in the run state (all the modules are running);
•LpXXXFn is the function that executes the module in the low-power state (GNSS, memory, and sensors are
turned off, while the other modules are in low power).
The events are:
•BP: button pressed event;
•SD: shutdown event;
•ER: error event;
•EP: automatic transition to next step;
•RN: go to full-run command
•LP: go to low-power command.
See the SM_APP.c file for further details.
2.3 HMI using LEDs and buttons
The STEVAL-ASTRA1B is provided with an RBG user LED and two user buttons:
• power/side button
• frontal button
UM3019
HMI using LEDs and buttons
UM3019 - Rev 1 page 7/43

Figure 8. STEVAL-ASTRA1B LEDs and buttons placement
The FP-ATR-ASTRA1B implements simple HMI functionalities using:
• the RGB LED, which turns:
– blue, if the configuration is ongoing
– red, if the sending is ongoing
– green:
◦ with slow blinking, if the Bluetooth® Low Energy is not connected
◦ with fast blinking, if the Bluetooth® Low Energy is connected
– yellow, if the Bluetooth® Low Energy is connected and sending
• the frontal button:
– short press: triggers asynchronous LoRa end data
– long press: system shutdown
• the side button:
– short press: changes the low-power status to run (or vice versa)
– long press: system reboot
UM3019
HMI using LEDs and buttons
UM3019 - Rev 1 page 8/43

3FP-ATR-ASTRA1 source code: relevant files
Despite the file tree complexity, only few files are involved in the application configuration of the use cases:
•App_astra.c
•Astra_confmng.c/.h
•Astra_sysmng.c/.h
•Astra_datamng.c/.h
•SM_APP.c/.h
Figure 9. Application files
3.1 App_astra.c
The app_astra.c file is the main file, that is, the entry point. It calls the initialization functions inside
MX_Astra_Init(). Specific defines allow disabling some blocks (for example, USE_XXXXXX).
The MX_Astra_Init() function is used for the system initialization:
•AstraSysInit();// → platform data initialization
•memory_init();
•sensor_init();
•gnss_init();
•stm32wl_init();
•stsafe_init();
UM3019
FP-ATR-ASTRA1 source code: relevant files
UM3019 - Rev 1 page 9/43

Figure 10. MX_Astra_Init() function
The MX_Astra_Process() function is used for the main loop:
•ASTRA_TASK_ID → the main sequencer task calls the process function related to each module:
–ManageMemory();
–ReadSensors();
–ReadGnss();
–stm32wl_process();
–stsafe_process();
UM3019
App_astra.c
UM3019 - Rev 1 page 10/43