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.
RELATED LINKS
Visit the STM32Cube ecosystem web page on www.st.com for further information
ferent STM32 microcontrollers.
UM2497 - Rev 2 - July 2020
For further information contact your local STMicroelectronics sales of
fice.
www.st.com
1Acronyms and abbreviations
Table 1. List of acronyms
AcronymDescription
BSPBoard support package
CLICommand line interface
CMSIS
GUIGraphical user interface
HALHardware abstraction layer
IDUnique device ID
PACPort authorization code
SPISerial peripheral interface
Cortex® microcontroller software interface standard
UM2497
Acronyms and abbreviations
UM2497 - Rev 2
page 2/21
X-CUBE-SFXS2LP1 software expansion for STM32Cube
2X-CUBE-SFXS2LP1 software expansion for STM32Cube
2.1Overview
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.2Architecture
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
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.4APIs
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.5Sample 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.1RF_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:
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.2MCU_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
NameArgumentDescription
size: the number of bytes to be allocated
MCU_API_malloc
MCU_API_freepointer: pointer to the memory of free upFree memory allocated to the library.
MCU_API_get_voltage_temperature
MCU_API_delaydelay_ms: number of ms to waitBlocking 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
NameArgumentDescription
MCU_API_timer_start
MCU_API_timer_stopNone
MCU_API_timer_stop_carrier_senseNone
MCU_API_timer_wait_for_endNone
MCU_API_report_test_result
MCU_API_get_versionpointer to the array variable and sizeThis function gets current version
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
Table 3. Callbacks exported by the RF_LIB module
NameArgumentsDescription
ST_RF_API_S2LP_IRQ_CBNone
ST_RF_API_Timer_CBNone
ST_RF_API_Timer_Channel_Clear_CBNone
The RF_LIB module configures the S2-LP to raise interrupts
and to notify them on a GPIO. This function must be called in
case of GPIO interrupt.
It must be called when the timer started by the
MCU_API_timer_start expires.
It must be called when the timer started by the
MCU_API_timer_start_Carrier_sense expires.
The applicative callback void Appli_Exti_CB(uint16_t GPIO_Pin) can be implemented to demand
application management of all the ETXI interrupts dif
ferent from the ST_RF_API_S2LP_IRQ_CB.
2.5.3Sigfox data retriever
The MCU_API_aes_128_cbc_encrypt function encrypts an input buf
While the CBC algorithm IV vector should be set to 0, the encryption key is provided by Sigfox and is associated
with each node.
This key must be stored and used in the MCU_API_aes_128_cbc_encrypt routine.
In the ST reference design, the key is stored in the board during the registration phase.
ST provides a compiled ID_KEY_RETRIEVERv_CMx_C.a library that exports the functions listed below.
UM2497
Sample application description
fer using AES128-CBC encryption.
Table 4. ID_KEY_RETRIEVER_CMx.a functions
NameArgumentsDescription
encrypted_data: pointer to the destination buffer
where the encrypted data must be stored
enc_utils_encrypt
enc_utils_retrieve_data
enc_utils_set_public_key
enc_utils_get_idpointer to the ID uint8_t arrayGets the ID stored in the EEPROM.
enc_utils_get_initial_pacpointer to the PAC uint8_t arrayGets the PAC stored into the EEPROM.
enc_utils_set_test_keyen: if 1 switch to test key; if 0 reset to default
enc_utils_set_test_iden: if 1 switch to test ID; if 0 reset to defaultSets the RSA test key: 0xFEDCBA98
enc_utils_set_credentials_dataSigfox settingsOverrides credentials and RCZ.
data_to_encrypt: pointer to the source buf
where the data to encrypt are stored
data_len: length of the data buffer to encrypt
id_ptr: pointer to the 32bits word variable where
the ID of the board must be stored.
pac_ptr: pointer to the 8bytes array where the
P
AC of the board must be stored.
rcz_ptr: pointer to the byte where the RCZ
number of this board must be stored.
en: if 1 switch to the public key, if 0 (default
config) use the one associated to the board.
fer
Perform the AES128-CBC encryption using the AES
KEY associated with the board.
Retrieve the ID, PAC and RCZ number of the board
and returns it to the caller. The ID should be used
when opening the library. The PAC is used to register
the node on the backend.
Set the public key for encryption (used for test
purposes).
Sets the RSA test key:
0x0123456789ABCDEF0123456789ABCDEF
UM2497 - Rev 2
page 8/21
UM2497
Sample application description
2.5.4Application level Sigfox API
Table 5. Sigfox API details
NameArgumentsDescription
SIGFOX_API_open
SIGFOX_API_send_frame
SIGFOX_API_closeNoneCloses the Sigfox library, resetting its state.
SIGFOX_API_set_std_config
SIGFOX_API_get_version
SIGFOX_API_get_infoinfo: array containing infoGets info
SIGFOX_API_send_outofbandoob_type: type of the OOB frame to send
SIGFOX_API_send_bit
SIGFOX_API_start_continuous_trans
mission
SIGFOX_API_stop_continuous_trans
mission
SIGFOX_API_send_test_frame
rcz: pointer to sfx_rc_t type representing the RCZ
number (1, 2, 3 or 4).
cust_data: pointer to the data to transmit
cust_data_size: size in bytes of the data to
transmit (max. 12)
cust_response: pointer to the buf
store the received payload (only if
initiate_downlink_flag=1)
tx_repetition: number of repetitions
initiate_downlink_flag: wait for a response after
transmitting
config_words_ptr: 3-config-word array to select
the FCC channels to use.
default_sigfox_channel: default channel to be
used among those selected by the config_words.
version_ptr: pointer to the array where to store the
lib version.
version_size_ptr: size of the written version array
type (MCU, RF
bit_value: bit value to send
cust_response: pointer to the buf
store the received payload (only if
initiate_downlink_flag=1)
tx_repetition: number of repetitions (only if
initiate_downlink_flag=1)
initiate_downlink_flag: wait for a response after
transmitting
frequency: frequency at which the signal has to be
generated
type: type of modulation to use in continuous
mode
NoneStops the current continuous transmission
frequency: frequency at which the wave is
generated
customer_data: data to transmit
customer_data_length: data length in bytes
initiate_downlink_flag: flag to initiate a downlink
response
, etc.)
fer where to
fer where to
This function opens the library initializing all state
machine parameters. It does not involve the radio
configuration.
Sends the frame.
Sets the standard configuration.
Returns the library version.
Sends an out-of-band frame, that is a test frame
used to monitor the node parameters (voltage,
temperature)
This function is used to send a single bit mainly
when the node seeks downlink data (not to
transmit).
Executes a continuous wave or modulation
depending on the parameter type
This function builds a Sigfox frame with the
customer payload and sends it at a specific
frequency
UM2497 - Rev 2
page 9/21
NameArgumentsDescription
frequency: frequency at which the wave is
generated
mode: mode ( AUTHENTICA
AUTHENTICATION_OFF)
buffer: depends on the authentication mode:
•if AUTHENTICATION_OFF : buffer is used
SIGFOX_API_receive_test_frame
SIGFOX_API_get_device_iddev_id: pointer where to write the device ID
SIGFOX_API_get_initial_pacinitial_pac: pointer to initial PACSets initial pac
SIGFOX_API_switch_public_key
SIGFOX_API_set_rc_sync_period
as input to check the bit stream of the
received frame
•if AUTHENTICATION_ON : buffer is used
as output to get the received payload
timeout: timeout for the reception of a valid
downlink frame
rssi: RSSI of the received frame
use_public_key: switch to public key if
SFX_TRUE, private key else
rc_sync_period: transmission period of the RC
Sync frame (in number of 'normal' frames)
TION_ON or
This function waits for a valid downlink frame
during timeout time and returns the data received
in customer_data.
This function copies the device ID to the pointer
given as parameter
Switches device to public or private key
Sets the period for transmission of RC Sync frame
UM2497
Sample application description
.
2.5.5ST_RF_API
The application calls a set of functions to instruct the RF_LIB to configure the radio properly. These functions are
exported by the ST_RF_API header (st_rf_api.h) and are implemented in the RF_LIB module.
UM2497 - Rev 2
page 10/21
Table 6. ST_RF_API functions
NameArgumentsDescription
ST_RF_API_set_xtal_freqAn integer with the XTAL value in Hz.
ST_RF_API_set_freq_offsetAn integer with the RF offset value in Hz.
ST_RF_API_set_tcxoA boolean value (0 or 1).
ST_RF_API_set_rssi_offsetAn integer with the RSSI offset value in dB.
ST_RF_API_get_rssi_offset
ST_RF_API_gpio_irq_pin
ST_RF_API_gpio_tx_rx_pin
ST_RF_API_gpio_rx_pin
ST_RF_API_gpio_tx_pin
ST_RF_API_reduce_output_pow
er
ST_RF_API_smpsSMPS voltage word
ST_RF_API_set_paA boolean value (0 or 1).
ST_RF_API_get_ramp_durationNone
ST_RF_API_Get_Transmission_
State
A pointer to the variable where the RSSI value
should be stored.
An integer representing the number of the GPIO to
be set as an interrupt source.
An integer representing the number of the GPIO to
be set as a TX or RX state indication. 0xFF to
configure no one of the S2-LP GPIO with this
function.
An integer representing the number of the GPIO to
be set as a RX state indication. 0xFF to configure
no one of the S2-LP GPIO with this function.
An integer representing the number of the GPIO to
be set as a TX state indication. 0xFF to configure no
one of the S2-LP GPIO with this function.
Power reduction in half dB
None
Sets the XTAL frequency of the S2-LP in Hertz
(default is 50 MHz).
Sets the RF frequency offset in Hertz (default is 0
Hz).
Instructs the library to configure the S2- LP for a
TCXO or for a XT
the S2-LP oscillator registers.
Sets an RSSI offset for the RSSI. Very useful if the
RF frontend has an LNA or to calibrate the RSSI
measurement
Gets the RSSI offset for the RSSI
Configures one of the S2-LP pin to be an IRQ pin.
Configures one of the S2-LP pin to be to be
configured as (RX or TX) signal
Configures one of the S2-LP pin to be configured as
RX signal
Configures one of the S2-LP pin to be configured as
TX signal.
Reduces the output power of the transmitted signal
by a factor (reduction*0.5 dB against the actual
value)
Instructs the library to configure the S2-LP with a
user defined smps frequency
Instructs the library to configure the S2- LP for a
external P
Returns the duration of the initial (or final) ramp in
ms
Returns information about the TX state of the MCU
API
A (Power Amplifier).
UM2497
Sample application description
AL. This is needed to configure
2.5.6Opening the Sigfox library
SIGFOX_API_open must be called to initialize the library before performing any other operation.
This API requires pointer to the Radio Configuration zone structure to be used.
Uplink frequencies are:
•
RCZ1 - 868.13 MHz
•RCZ2 - 902.2 MHz
•RCZ3 - 923.3 MHz
•RCZ4 - 920.8 MHz
Note:As frequency hopping is implemented, the transmission frequency is not fixed.
Downlink frequencies are:
•RCZ1 - 869.525 MHz
•RCZ2 - 905.2 MHz
•RCZ3 - 922.2 MHz
•RCZ4 - 922.3 MHz
UM2497 - Rev 2
page 11/21
2.5.7Sending the frames
SIGFOX_API_send_frame is the core Sigfox library function; this blocking function handles message exchange
between the node and the base-stations.
2.5.8Setting the standard configuration
This function has different purposes according to the RC mode used for the serial port opening.
FCC allows the transmitters to choose certain macro channels to implement a frequency hopping pattern allowed
by the standard.
The channel map is specified in the first argument of SIGFOX_API_set_std_config, which consists of an
array of three 32-bit configuration words.
2.5.9Running CLI demo commands via terminal
For the CLI demo, some commands can be run via any terminal utility.
The command list can be retrieved using the help command in the terminal window (for the complete command
list, refer to UM2169, Section 4.3.1, on www
Figure 3. SigFox CLI demo: running commands via terminal
.st.com).
UM2497
Sample application description
UM2497 - Rev 2
Once the board is programmed using the CLI mode demo, it can be connected to the GUI.
page 12/21
Figure 4. Running the CLI demo via GUI
UM2497
Sample application description
Figure 5. Sigfox message captured
UM2497 - Rev 2
page 13/21
3System setup guide
3.1Hardware description
3.1.1STM32 Nucleo
STM32 Nucleo development boards provide an af
prototypes with any STM32 microcontroller line.
The Arduino™ connectivity support and ST morpho connectors make it easy to expand the functionality of the
STM32 Nucleo open development platform with a wide range of specialized expansion boards to choose from.
The STM32 Nucleo board does not require separate probes as it integrates the ST-LINK/V2-1 debugger/
programmer.
The STM32 Nucleo board comes with the comprehensive STM32 software HAL library together with various
packaged software examples for different IDEs (IAR EWARM, Keil MDK-ARM, STM32CubeIDE, mbed and GCC/
LLVM).
All STM32 Nucleo users have free access to the mbed online resources (compiler, C/C++ SDK and developer
community) at www.mbed.org to easily build complete applications.
UM2497
System setup guide
fordable and flexible way for users to test solutions and build
Figure 6. STM32 Nucleo board
Information regarding the STM32 Nucleo board is available at www
.st.com/stm32nucleo
3.1.2X-NUCLEO-S2868A2 and X-NUCLEO-S2915A1 expansion boards
The X-NUCLEO-S2868A2 expansion board is based on the S2-LP radio and operates in the 868 MHz ISM
frequency band.
The X-NUCLEO-S2915A1 expansion board is based on the S2-LP radio and operates in the 915 MHz ISM
frequency band.
The expansion boards are compatible with ST morpho and Arduino UNO R3 connectors, and interface with the
STM32 Nucleo microcontroller via SPI connections and GPIO pins.
UM2497 - Rev 2
page 14/21
You can change some of the GPIOs by mounting or removing the resistors.
Figure 7. X-NUCLEO-S2868A2 expansion board
UM2497
Hardware setup
3.2Hardware setup
The following hardware components are needed:
1.
One STM32 Nucleo development platform (NUCLEO-L073RZ,NUCLEO-L152RE or NUCLEO-L476RG)
2.One S2-LP expansion board (order code: X-NUCLEO-S2868A2 or X-NUCLEO-S2915A1)
3.One USB type A to Mini-B USB cable to connect the STM32 Nucleo to the PC
Figure 8. X-NUCLEO-S2915A1 expansion board
3.2.1STM32 Nucleo and X-NUCLEO-S2868A2 expansion board setup
The STM32 Nucleo
UM2497 - Rev 2
board integrates the ST-LINK/V2-1 debugger/programmer.
page 15/21
UM2497
Software setup
The developer can download the ST-LINK/V2-1 USB driver by looking for the STSW
www.st.com.
The S2-LPX-NUCLEO-S2868A2 or X-NUCLEO-S2915A1 expansion board can interface the external STM32
microcontroller on the STM32 Nucleo using SPI.
It also can be easily connected to the STM32 Nucleo through the Arduino UNO R3 extension connector as shown
below.
Figure 9. X-NUCLEO-S2868A2 expansion board connected to the STM32 Nucleo board
-LINK009 software on
3.3Software setup
The following software components are needed for a suitable development environment for creating applications
for the STM32 Nucleo equipped with the S2-LPX-NUCLEO-S2868A2 or X-NUCLEO-S2915A1 expansion board:
•X-CUBE-SFXS2LP1 expansion for STM32Cube dedicated to Sigfox applications development.
•
One of the following development tool-chain and compilers:
–Keil RealView Microcontroller Development Kit (MDK-ARM-STR) + ST-LINK
Figure 9. X-NUCLEO-S2868A2 expansion board connected to the STM32 Nucleo board ...................... 16
UM2497 - Rev 2
page 20/21
UM2497
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’
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. For additional information about ST trademarks, please refer to www
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.
s terms and conditions of sale in place at the time of order acknowledgement.