STMicroelectronics X-CUBE-SFXS2LP1 User Manual

UM2497

User manual

Getting started with the X-CUBE-SFXS2LP1 software expansion for STM32Cube

Introduction

The X-CUBE-SFXS2LP1 expansion software package for STM32Cube runs on the STM32 and includes the drivers for S2-LP and the library for the Sigfox™ proprietary protocol.

This software together with the suggested combination of STM32 and S2-LP device can be used, for example, to develop applications for smart home/building and smart cities, agriculture, parking, lighting, etc.

The expansion is built on STM32Cube software technology to ease portability across dif

The software comes with a sample implementation of the drivers running on the X-NUCLEO-S2868A2 and X-NUCLEO-

S2915A1 expansion boards connected to a NUCLEO-L073RZ, NUCLEO-L152RE or NUCLEO-L476RG development board.

1 Acronyms and abbreviations

Table 1. List of acronyms

Acronym Description

BSP Board support package

CLI Command line interface

CMSIS

GUI Graphical user interface

HAL Hardware abstraction layer

ID Unique device ID

PAC Port authorization code

SPI Serial peripheral interface

Cortex® microcontroller software interface standard

UM2497

Acronyms and abbreviations

UM2497 - Rev 2

page 2/21

X-CUBE-SFXS2LP1 software expansion for STM32Cube

2 X-CUBE-SFXS2LP1 software expansion for STM32Cube

2.1 Overview

The X-CUBE-SFXS2LP1 software package key features are:

Complete software to build applications using Sigfox™ long range wireless area network running on the S2-

•

LP high performance ultra-low power RF transceiver

• S2-LP Sigfox™ library with a complete set of APIs to develop embedded applications

• Compatible with the STSW-S2LP-SFX-DK graphical user interface (GUI) to register end-device to Sigfox™ network and get ID (Unique Device ID)/PAC (Port Authorization code) /Key from the pool assigned to ST devices

• Sigfox proprietary protocol with Monarch feature

• GUI PC application available as interactive interface to transmit messages to the Sigfox™ network

• Sample implementation available on the X-NUCLEO-S2868A2 and X-NUCLEO-S2915A1 expansion boards connected to a NUCLEO-L073RZ, NUCLEO-L152RE or NUCLEO-L476RG development board

• ID/PAC/Key stored in internal MCU flash or external EEPROM

• Easy portability across different MCU families, thanks to STM32Cube

• Free, user-friendly license terms

UM2497

2.2 Architecture

The software is based on the STM32CubeHAL hardware abstraction layer for the STM32 microcontroller and extends STM32Cube by providing the middleware library for the Sigfox application using the S2-LP expansion board and ready-to-use samples to show this library usage.

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

• STM32Cube HAL layer: provides a generic, multi-instance set of simple 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 the middleware layer hardware configuration for a given Microcontroller Unit (MCU). This structure improves the library code reusability and guarantees easy portability across devices.

• Board support package (BSP) layer: supports the peripherals on the STM32 Nucleo board, except for the MCU. This limited set of APIs provides a programming interface for certain board specific peripherals (like the user button, the reset button, etc.) and helps in identifying the specific board version.

• Middleware: includes the Sigfox Libraries in lib(.a) form with a complete set of APIs to develop embedded applications.

, to implement their functionalities without dependencies on the specific

UM2497 - Rev 2

page 3/21

Figure 1. X-CUBE-SFXS2LP1 architecture

STM32Cube Hardware Abstraction Layer (HAL)

Push button demo

X-NUCLEO-S2868A2/X-NUCLEO-S2915A1 (Connect)

Hardware

Hardware Abstraction

Application

STM32 Nucleo expansion boards

STM32 Nucleo development board

CLI demo

Middleware

Sigfox library

UM2497

Folder structure

2.3 Folder structure

Figure 2. X-CUBE-SFXS2LP1 package folder structure

UM2497 - Rev 2

page 4/21

The software is packaged in the following main folders:

• Documentation: with a compiled HTML file generated from the source code that details the software

• Drivers: contains the HAL drivers, the board specific drivers for each supported board or hardware platform,

• Middlewares: contains the Sigfox library and Sigfox interface for STM32 as well as the libraries for ETSI,

• Projects: provides sample applications for the push button demo and CLI demo.

• Utilities: contains the files to interpret the commands sent via PC using the GUI or any terminal utility. It also

2.4 APIs

UM2497

APIs

components and APIs.

including the on-board components ones and the CMSIS layer which is a vendor-independent hardware abstraction layer for the ARM Cortex-M processor series.

ARIB,FCC and ALL specification.

In the push button demo, the Sigfox message is transmitted by simply pressing the user button on the STM32 Nucleo boards. The message is shown on the Sigfox web application.

In the CLI demo, CLI (command line interface) mode provides the connectivity with Sigfox GUI. The Sigfox message is transmitted by clicking “Tx” in the GUI. The projects are provided for the NUCLEO-L073RZ,

NUCLEO-L152RE

Workbench for ARM, RealView Microcontroller Development Kit (MDK-ARM) and System Workbench for STM32 (SW4STM32)).

contains the Sigfox GUI.

and NUCLEO-L476RG platforms with three development environments (IAR Embedded

Detailed function and parameter descriptions for the user-APIs are compiled in an HTML file in the software package Documentation folder

2.5 Sample application description

The Sigfox over S2-LP library features:

• complete set of the APIs to develop the embedded application

• graphical user interface (GUI) PC application to provide an interactive interface to transmit messages to the Sigfox network

• ready-to-use projects available for IAR, Keil and STM32CubeIDE

• easy portability across different MCU families, thanks to STM32Cube

The user application features:

• initialization of the Sigfox and S2-LP stack

• user functions required for the application

• application handling

2.5.1 RF_LIB library

The RF_LIB library configures and implements the S2-LP modulation scheme.

The library drives the S2-LP according to the Sigfox modulation protocol:

•

DBPSK for uplink (14 dBm at 100 bps for RCZ1/3, 22 dBm at 600 bps for RCZ2/4)

• 2GFSK, BT=1 for downlink

The channel frequency, data rate and other relevant parameters depend on the applicable radio control zone (RCZ).

UM2497 - Rev 2

page 5/21

UM2497

Sample application description

The library is compiled for devices equipped with certain ARM® Cortex® cores. Separate versions are supplied in the following folders:

Projects\Middlewares\ST\Sigfox_STM32_Library\Lib\Monarch:

•

– ST_MONARCH_LIB_CMx_GCC.a

– ST_MONARCH_LIB_CMx_IAR.a

– ST_MONARCH_LIB_CMx_Keil.a

• Projects\Middlewares\ST\Sigfox_STM32_Library\Lib\Retriever:

– ST_RETRIEVER_LIB_CMx_GCC.a

– ST_RETRIEVER_LIB_CMx_IAR.a

– ST_RETRIEVER_LIB_CMx_Keil.a

• Projects\Middlewares\Third_Party\Sigfox\Lib\RF_Library:

– ADDON_RF_PROTOCOL_MON_CMx_GCC.a

– ADDON_RF_PROTOCOL_MON_CMx_IAR.a

– ADDON_RF_PROTOCOL_MON_CMx_Keil.a

• Projects\Middlewares\Third_Party\Sigfox\Lib\Sigfox_Library:

– SFX_LIB_MON_CMx_GCC.a

– SFX_LIB_MON_CMx_IAR.a

– SFX_LIB_MON_CMx_Keil.a

User applications call generic APIs not linked to any specific hardware whereas the RF_LIB library calls low level APIs to provide the necessary hardware platform support.

2.5.2 MCU_API module

The framework can be easily ported to another board equipped with a microprocessor of the same type but with a dif

ferent pinout by simply re-implementing the MCU_API module.

Table 2. MCU_API module details

Name Argument Description

size: the number of bytes to be allocated

MCU_API_malloc

MCU_API_free pointer: pointer to the memory of free up Free memory allocated to the library.

MCU_API_get_voltage_temperature

MCU_API_delay delay_ms: number of ms to wait Blocking function for delay_ms milliseconds.

MCU_API_aes_128_cbc_encrypt

MCU_API_get_nv_mem

MCU_API_set_nv_mem

MCU_API_timer_start_carrier_sense

pointer: pointer to the new allocated block of memory

voltage_idle: pointer to the variable where voltage in idle should be stored

voltage_tx: pointer to the variable where voltage in TX should be stored temperature: pointer to the variable where temperature should be stored

encrypted_data: pointer to the destination buffer where the encrypted data must be stored

data_to_encrypt: pointer to the source buf where the data to encrypt are stored data_len: length of the data buffer to encrypt

read_data: pointer to the array where the NVM content should be stored.

data_to_write: pointer to the array containing the data to be stored in the NVM.

timer_duration_ms: the total duration of the timer in milliseconds. This function starts a timer without blocking the application.

fer

Allocates memory for library usage (memory usage = size in bytes) This function is called only once at the Sigfox library opening.

Gets voltage and temperature for out of band frames. The value must respect the units for backend compatibility

This function is in charge of encrypting the data transmitted by the Sigfox library.

This function is used to read data from the NVM used by the Sigfox library

This function is used to write data to the NVM used by the Sigfox library

This timer is used for the carrier sense (in RCZ3 only).

UM2497 - Rev 2

page 6/21

Sample application description

Name Argument Description

MCU_API_timer_start

MCU_API_timer_stop None

MCU_API_timer_stop_carrier_sense None

MCU_API_timer_wait_for_end None

MCU_API_report_test_result

MCU_API_get_version pointer to the array variable and size This function gets current version

MCU_API_get_device_id_and_payload_en cryption_flag

MCU_API_get_initial_pac

ST_MCU_API_SpiRaw

ST_MCU_API_GpioIRQ

ST_MCU_API_Shutdown sdn_flag: 1 - enter shutdown 0 - exit shutdown Sets the S2-LP on or off via GPIO

ST_MCU_API_LowPower

ST_MCU_API_WaitForInterrupt None

ST_MCU_API_SetSysClock None

ST_MCU_API_TimerCalibration None RTC calibration routine.

ST_MCU_API_SetEncryptionPayload

timer_duration_ms: the total duration of the timer in milliseconds

status: 1 - passed

0 - failed

rssi: RSSI of the received frame

pointer to the uint8_t array variable where the returned ID should be stored.

pointer to the uint8_t array variable where the returned P

number: number of elements of the total SPI transaction

value_ptr_in: pointer to the input buf memory where the SPI data to write are stored)

value_ptr_out: pointer to the output buffer (the μC memory where the data from SPI must be stored)

can_return_bef_tx: if this flag is 1, the function can be non-blocking, returning immediately.

pin: the GPIO pin of the S2-LP (integer from 0 to

new_state: enables or disables the EXTI

trigger_flag: 1: rising edge, 0: falling edge

low_power_flag: 1 - enter in low power mode 0 do not use low power

ePayload: 1 -Enable encryption 0 - Disable encryption

AC should be stored.

fer (μC

This function starts a timer without blocking the application. Y let the μC enter low power mode.

This function stops the timer started by the MCU_API_timer_start.

This function stops the timer started by the MCU_API_timer_start_carrier_sense

Blocking function to wait for interrupt indicating timer elapsed. This function is used only for the 20 seconds in downlink.

Reports the result of RX test for each valid message received/validated by the library

Gets the device ID

Gets the device initial PAC

Performs a raw SPI operation with the passed input buffer and stores the returned SPI bytes in the output buffer.

Enables or disables the external interrupt on the μC side. The interrupt must be set on the rising or falling edge of the input signal according to the trigger_flag. The pin number represents the S2-LP GPIO number

Instructs the firmware to use the low power when blocking procedures are called.

The μC waits for an interrupt function. This can be a null implementation or can activate μC low power mode.

Sets the system clock. This function is used after waking up from low power

Enables the encryption payload flag.

ou should use an RTC to

UM2497

UM2497 - Rev 2

This module has to call the callbacks listed below and implemented by the ST Sigfox library.

page 7/21

+ 14 hidden pages