This application note guides the user through all the steps required to build specific LoRa® applications based on
STM32WL Series microcontrollers.
LoRa® is a type of wireless telecommunication network designed to allow long-range communications at a very‑low bitrate
and to enable long-life battery-operated sensors. LoRaWAN® defines the communication and security protocol that ensures the
interoperability with the LoRa® network.
The firmware in the STM32CubeWL MCU Package is compliant with the LoRa Alliance® specification protocol named
LoRaWAN® and has the following main features:
•Application integration ready
•
Easy add-on of the low-power LoRa® solution
•Extremely low CPU load
•No latency requirements
•Small STM32 memory footprint
•Low-power timing services
The firmware of the STM32CubeWL MCU Package is based on the STM32Cube HAL drivers.
This document provides customer application examples on the STM32WL Nucleo-64 boards NUCLEO_WL55JC
(order codes NUCLEO‑WL55JC1 for high‑frequency band and NUCLEO-WL55JC2 for low-frequency band).
To fully benefit from the information in this application note and to create an application, the user must be familiar with the
STM32 microcontrollers, the LoRa® technology, and understand system services such as low-power management and task
sequencing.
AN5406 - Rev 4 - February 2021
For further information contact your local STMicroelectronics sales office.
www.st.com
1Overview
The STM32CubeWL runs on STM32WL Series microcontrollers based on the Arm® Cortex®-M processor.
Note:Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.
1.1Acronyms
Table 1. Acronyms
AcronymDefinition
ABPActivation by personalization
ADRAdaptive data rate
BSPBoard support package
HALHardware abstraction layer
LoRaLong range radio technology
LoRaWANLoRa wide-area network
LPWANLow-power wide-area network
MACMedia access control
MCPSMAC common part sublayer
MIBMAC information base
MLMEMAC sublayer management entity
MSCMessage sequence chart
<target>STM32WL Nucleo-64 boards (NUCLEO-WL55JC)
AN5406
Overview
1.2Reference documents
[1]User manual STM32 LoRa Expansion Package for STM32Cube (UM2073)
[2]STM32WLEx reference manual (RM0461)
[3]Application note LoRaWAN AT commands for STM32CubeWL (AN5481)
[4]Application note Building wireless applications with STM32WB Series microcontrollers (AN5289)
[5]IEEE Std 802.15.4TM - 2011. Low-Rate Wireless Personal Area Networks (LR-WPANs)
1.3LoRa standard
Refer to document [1] for more details on LoRa and LoRaWAN recommendations.
AN5406 - Rev 4
page 2/63
2STM32CubeWL architecture
2.1STM32CubeWL overview
The firmware of the STM32CubeWL MCU Package includes the following resources (see Figure 1):
•Board support package: STM32WLxx_Nucleo drivers
•STM32WLxx_HAL_Driver
•Middleware:
–LoRaWAN containing:
◦LoRaWAN layer
◦LoRa utilities
◦LoRa software crypto engine
◦LoRa state machine
–SubGHz_Phy layer middleware containing the radio and radio_driver interfaces
•LoRaWAN applications:
–AT_Slave
–End_Node
•SubGHz_Phy application:
–PingPong
In addition, this application provides efficient system integration with the following:
•a sequencer to execute the tasks in background and enter low-power mode when there is no activity
•a timer server to provide virtual timers running on RTC (in Stop and Standby modes) to the application
For more details refer to Section 7 Utilities description.
AN5406
STM32CubeWL architecture
AN5406 - Rev 4
page 3/63
Figure 1. Project file structure
BSP drivers for STM32WL Nucleo-64 board
STM32WL HAL drivers
Middleware LoRa crypto engine
Middleware LoRa state machine
Middleware LoRa MAC layer
Middleware LoRa utilities
Middleware SubGHz_Phy
AN5406
STM32CubeWL overview
LoRaWAN AT_Slave application
LoRaWAN End_Node application
SubGhz_Phy PingPong application
AN5406 - Rev 4
page 4/63
2.2Static LoRa architecture
The figure below describes the main design of the firmware for the LoRa application.
AN5406
Static LoRa architecture
Figure 2. Static LoRa architecture
LoRa application
(AT_Slave, End_Node or PingPong)
LoRaWAN middleware
LmHandler.h
LmHandler LoRaMAC LoRaMAC crypto
radio.h
SubGHz_Phy middleware
radio.c
radio_driver.c
Utilities
Timer server
Sequencer
Debug trace
Low-power
mode
Board support package (BSP)
Hardware abstraction layer APIs (HAL)
NVICSubGHzRCCGPIORTC
Sub-GHz radio system peripheral
The HAL uses STM32Cube APIs to drive the MCU hardware required by the application. Only specific hardware
is included in the LoRa middleware as it is mandatory to run a LoRa application.
The RTC provides a centralized time unit that continues to run even in low-power mode (Stop 2 mode). The RTC
alarm is used to wake up the system at specific timings managed by the timer server.
The radio driver uses the SubGHz HAL to control the radio (see the above figure). The radio driver also provides
a set of APIs to be used by higher-level software.
The radio driver is split in the following parts:
•radio.c: contains all functions that are radio dependent only.
•radio_driver.c: contains low-level radio drivers.
AN5406 - Rev 4
The MAC controls the SubGHz_Phy using the 802.15.4 model. The MAC interfaces with the SubGHz_Phy driver
and uses the timer server to add or remove timed tasks.
Since the state machine that controls the LoRa Class A, is sensitive, an intermediate level of software is inserted
(lora.c) between the MAC and the application (refer to LoRaMAC driver in the above figure). With a limited set
of APIs, the user is free to implement the Class A state machine at application level. For more details, refer to
Section 6 .
The application, built around an infinite loop, manages the low-power, runs the interrupt handlers (alarm or GPIO)
and calls the LoRa Class A if any task must be done.
page 5/63
2.3Dynamic view
The MSC (message sequence chart) shown in the figure below depicts a Class A device transmitting an
application data and receiving application data from the server.
Figure 3. Class A Tx and Rx processing MSC
CPUSub-GHz
LoRaApp
LmHandler
LmHandlerSend
statusstatusstatus
OnMacProcessNotify
_LmHandler
Packages
Process
OnTxdataMcpsConfirm
LoRaMacMcps
Request
LoRaMacProcess
LoRaMAC
OnRadioTxDone
RadioTimer
RadioSend
setRxwindow1
TimerIsr
RadioRx
AN5406
Dynamic view
radio
peripheral
Tx
RadioIsr
OnMacProcessNotify
_LmHandler
Packages
Process
OnRxdata
OnRadioRxDone
LoRaMacProcess
McpsIndication
RadioIsr
Once the radio has completed the application data transmission, an asynchronous RadioIRQ wakes up the
system. The RadioIsr here calls txDone in the handler mode.
All RadioIsr and MAC timer call a LoRaMacProcessNotify callback to request the application layer to update
the LoRaMAC state and to do further processing when needed.
For instance, at the end of the reception, rxDone is called in the ISR (handler), but all the Rx packet processing
including decryption must not be processed in the ISR. This case is an example of call sequence. If no data is
received into the Rx1 window, then another Rx2 window is launched..
Rx
AN5406 - Rev 4
page 6/63
3SubGHz HAL driver
This section focuses on the SubGHz HAL (other HAL functions such as timers or GPIO are not detailed).
The SubGHz HAL is directly on top of the sub-GHz radio peripheral (see Figure 2. Static LoRa architecture).
The SubGHz HAL driver is based on a simple one-shot command-oriented architecture (no complete processes).
Therefore, no LL driver is defined.
This SubGHz HAL driver is composed the following main parts:
•Handle, initialization and configuration data structures
•Initialization APIs
•Configuration and control APIs
•MSP and events callbacks
•Bus I/O operation based on the SUBGHZ_SPI (Intrinsic services)
As the HAL APIs are mainly based on the bus services to send commands in one-shot operations, no functional
state machine is used except the RESET/READY HAL states.
3.1SubGHz resources
The following HAL SubGHz APIs are called at the initialization of the radio:
•Declare a SUBGHZ_HandleTypeDef handle structure.
•Initialize the sub-GHz radio peripheral by calling the HAL_SUBGHZ_Init(&hUserSubghz) API.
•Initialize the SubGHz low-level resources by implementing the HAL_SUBGHZ_MspInit() API:
–PWR configuration: Enable wakeup signal of the sub-GHz radio peripheral.
–NVIC configuration:
◦Enable the NVIC radio IRQ interrupts.
◦Configure the sub-GHz radio interrupt priority.
The following HAL radio interrupt is called in the stm32wlxx_it.c file:
•HAL_SUBGHZ_IRQHandler in the SUBGHZ_Radio_IRQHandler.
AN5406
SubGHz HAL driver
3.2SubGHz data transfers
The Set command operation is performed in polling mode with the HAL_SUBGHZ_ExecSetCmd(); API.
The Get Status operation is performed using polling mode with the HAL_SUBGHZ_ExecGetCmd(); API.
The read/write register accesses are performed in polling mode with following APIs:
•HAL_SUBGHZ_WriteRegister();
•HAL_SUBGHZ_ReadRegister();
•HAL_SUBGHZ_WriteRegisters();
•HAL_SUBGHZ_ReadRegisters();
•HAL_SUBGHZ_WriteBuffer();
•HAL_SUBGHZ_ReadBuffer();
AN5406 - Rev 4
page 7/63
BSP STM32WL Nucleo-64 boards
4BSP STM32WL Nucleo-64 boards
This BSP driver provides a set of functions to manage:
•an application dependent part, implementing external control of on-board components: RF switches, TCXO,
RF losses and LEDs/sensors available on the STM32WL Nucleo-64 board (NUCLEO-WL55JC)
•a fixed part implementing the internal radio accesses (reset, busy and the NVIC radio IRQs)
Note:In the current implementation, due to STM32CubeMX limitation, the firmware does not use BSP files but
radio_board_if.c/.h for radio related items, and board_resources.c/.h for LED and push buttons. The
choice between the two implementations is done into Core/Inc/platform.h by selecting USE_BSP_DRIVER
or MX_BOARD_PSEUDODRIVER.
4.1Frequency band
Two types of Nucleo board are available on the STM32WL Series:
•NUCLEO-WL55JC1: high-frequency band, tuned for frequency between 865 MHz and 930 MHz
•NUCLEO-WL55JC2: low-frequency band, tuned for frequency between 470 MHz and 520 MHz
Obviously, If the user tries to run a firmware compiled at 868 MHz on a low-frequency band board, very poor RF
performances are expected.
The firmware does not check the band of the board on which it runs.
AN5406
4.2RF switch
The STM32WL Nucleo-64 board embeds an RF 3-port switch (SP3T) to address, with the same board, the
following modes:
The RF states versus the switch configuration are given in the table below.
RF state
High-power transmissionLowHighHigh
Low-power transmissionHighHighHigh
ReceptionHighLowHigh
Table 2. BSP radio switch
FunctionDescription
Initializes the RF switch.
Configures the radio switch.
De-initializes the RF switch.
Returns the board configuration:
high power, low power or both.
Table 3. RF states versus switch configuration
FE_CTRL1FE_CTRL2FE_CTRL3
AN5406 - Rev 4
page 8/63
4.3RF wakeup time
The sub-GHz radio wakeup time is recovered with the following API.
uint32_t BSP_RADIO_GetWakeUpTime(void)
The user must start the TCXO by setting the command RADIO_SET_TCXOMODE with a timeout depending of the
application.
The timeout value can be updated in stm32wlxx_nucleo_conf.h. Default template value is defined below.
#define RF_WAKEUP_TIME 10U
4.4TCXO
Various oscillator types can be mounted on the user application. On the STM32WL Nucleo-64 boards, a TCXO
(temperature compensated crystal oscillator) is used to achieve a better frequency accuracy.
AN5406
RF wakeup time
Table 4. BSP radio wakeup time
FunctionDescription
Returns RF_WAKEUP_TIME value.
uint32_t BSP_RADIO_IsTCXO (void)
The user can change this value in stm32wlxx_nucleo_conf.h:
#define IS_TCXO_SUPPORTED 1U
4.5Power regulation
Depending on the user application, a LDO or an SMPS (also named DCDC) is used for power regulation.
An SMPS is used on the STM32WL Nucleo-64 boards.
uint32_t BSP_RADIO_IsDCDC (void)
The user can change this value in stm32wlxx_nucleo_conf.h:
#define IS_DCDC_SUPPORTED 1U
The SMPS on the board can be disabled by setting IS_DCDC_SUPPORTED to 0.
Table 5. BSP radio TCXO
FunctionDescription
Returns IS_TCXO_SUPPORTED value.
Table 6. BSP radio SMPS
FunctionDescription
Returns IS_DCDC_SUPPORTED value.
AN5406 - Rev 4
page 9/63
4.6STM32WL Nucleo-64 board schematic
The figure below details the STM32WL Nucleo-64 board, MB1389 reference board schematic, highlighting some
useful signals:
•control switches on PC4, PC5 and PC3
•TCXO control voltage PIN on PB0
•debug lines on PB12, PB13 and PB14
•system clock on PA8
•SCK on PA5
•MISO on PA6
•MOSI on PA7
Figure 4. NUCLEO-WL55JC schematic
Data transaction:
SKC, MOSI, MISO
AN5406
STM32WL Nucleo-64 board schematic
Control switchs
1 and 2
Debug line 2 and 3
Debug line 1
System clock
TCXO control
voltage
Control
switch 3
AN5406 - Rev 4
page 10/63
5SubGHz_Phy layer middleware description
The radio abstraction layer is composed of two layers:
•high-level layer (radio.c)
It provides a high-level radio interface to the stack middleware. It also maintains radio states, processes
interrupts and manages timeouts. It records callbacks and calls them when radio events occur.
•low-level radio drivers
It is an abstraction layer to the RF interface. This layer knows about the register name and structure, as well
as detailed sequence. It is not aware about hardware interface.
The SubGHz_Phy layer middleware contains the radio abstraction layer that interfaces directly on top of the
hardware interface provided by BSP (refer Section 4 BSP STM32WL Nucleo-64 boards).
The SubGHz_Phy middleware directory is divided in two parts
•radio.c: contains a set of all radio generic callbacks, calling radio_driver functions. This set of APIs is
meant to be generic and identical for all radios.
•radio_driver.c: low-level radio drivers
AN5406
SubGHz_Phy layer middleware description
AN5406 - Rev 4
page 11/63
5.1Middleware radio driver structure
A radio generic structure, struct Radio_s Radio {};, is defined to register all the callbacks, with the fields detailed in
the table below.
Table 7. Radio_s structure callbacks
CallbackDescription
RadioInit
RadioGetStatus
RadioSetModem
RadioSetChannel
RadioIsChannelFree
RadioRandom
RadioSetRxConfig
RadioSetTxConfig
RadioCheckRfFrequenc
RadioTimeOnAir
RadioSend
RadioSleep
RadioStandby
RadioRx
RadioStartCad
RadioSetTxContinuousWave
RadioRssi
RadioWrite
RadioRead
RadioSetMaxPayloadLength
RadioSetPublicNetwork
RadioGetWakeUpTime
RadioIrqProcess
RadioRxBoosted
RadioSetRxDutyCycle
RadioTxPrbs
RadioTxCw
Initializes the radio.
Returns the current radio status.
Configures the radio with the given modem.
Sets the channel frequency.
Checks if the channel is free for the given time.
Generates a 32-bit random value based on the RSSI readings.
Sets the reception parameters.
Sets the transmission parameters.
Checks if the given RF frequency is supported by the hardware.
Computes the packet time on air in ms, for the given payload.
Sends the buffer of size. Prepares the packet to be sent and sets the radio in
transmission.
Sets the radio in Sleep mode.
Sets the radio in Standby mode.
Sets the radio in reception mode for the given time.
Starts a CAD (channel activity detection).
Sets the radio in continuous wave transmission mode.
Reads the current RSSI value.
Writes the radio register at the specified address.
Reads the radio register at the specified address.
Sets the maximum payload length.
Sets the network to public or private. Updates the sync byte.
Gets the time required for the board plus radio to exit Sleep mode.
Processes radio IRQ.
Sets the radio in reception mode with max LNA gain for the given time.
Sets the Rx duty-cycle management parameters.
Sets the transmitter in continuous PRBS mode.
Sets the transmitter in continuous unmodulated carrier mode.
AN5406
Middleware radio driver structure
AN5406 - Rev 4
page 12/63
5.2Radio IRQ interrupts
The possible sub-GHz radio interrupt sources are detailed in the table below.
BitSourceDescriptionPacket typeOperation
txDone
0
rxDone
1
PreambleDetected
2
SyncDetected
3
HeaderValid
4
HeaderErr
5
Err
6
CrcErr
CadDone
CadDetected
8
Timeout
9
Radio IRQ interrupts
Table 8. Radio IRQ bit mapping and definition
Packet transmission finished
Packet reception finished
Preamble detected
Synchronization word validGFSK
Header valid
Header error
Preamble, sync word, address, CRC or
length error
CRC error
Channel activity detection finished
Channel activity detected
Rx or TX timeoutLoRa and GFSKRx and Tx
LoRa and GFSK
LoRa
GFSK
LoRa7
AN5406
Tx
Rx
CAD
For more details, refer to the product reference manual.
AN5406 - Rev 4
page 13/63
6LoRaWAN middleware description
The LoRa stack middleware is split into the following modules:
•LoRaMAC layer module (in Middlewares\Third_Party\LoRaWAN\Mac)
•LoRa utilities module (in Middlewares\Third_Party\LoRaWAN\Utilities)
•LoRa crypto module (in Middlewares\Third_Party\LoRaWAN\Crypto)
•LoRa LmHandler module (in Middlewares\Third_Party\LoRaWAN\LmHandler)
6.1LoRaWAN middleware features
•Compliant with the specification for the LoRa Alliance protocol, named LoRaWAN
•On-board LoRaWAN Class A, Class B and Class C protocol stack
•EU 868MHz ISM band ETSI compliant
•EU 433MHz ISM band ETSI compliant
•US 915MHz ISM band FCC compliant
•KR 920Mhz ISM band defined by Korean government
•RU 864Mhz ISM band defined by Russian regulation
•CN 779Mhz and CN470Mhz ISM bands defined by Chinese government
•AS 923Mhz ISM band defined by Asian governments
•AU 915Mhz ISM bands defined by Australian government
•IN 865Mhz ISM bands defined by Indian government
•End-device activation either through OTAA or through activation-by-personalization (ABP)
•Adaptive data rate support
•LoRaWAN test application for certification tests included
•Low-power optimized
AN5406
LoRaWAN middleware description
6.2LoRaWAN middleware initialization
The initialization of the LoRaMAC layer is done through the LoRaMacInitialization API, that initializes both
the preamble run time of the LoRaMAC layer and the callback primitives of the MCPS and MLME services (see
the table below).
Table 9. LoRaWAN middleware initialization
FunctionDescription
LoRaMacStatus_t LoRaMacInitialization
(LoRAMacPrimitives_t *primitives,
LoRaMacCallback_t *callback,
LoRaMacRegion_t region)
6.3Middleware MAC layer APIs
The provided APIs follow the definition of “primitive” defined in IEEE802.15.4-2011 (see document [5]).
The interfacing with the LoRaMAC is made through the request-confirm and the indication-response architecture.
The application layer can perform a request that the LoRaMAC layer confirms with a confirm primitive.
Conversely, the LoRaMAC layer notifies an application layer with the indication primitive in case of any event.
The application layer may respond to an indication with the response primitive. Therefore, all the confirm or
indication are implemented using callbacks.
Initializes the LoRaMAc layer module
(see Section 6.4 Middleware MAC layer callbacks)
AN5406 - Rev 4
page 14/63
Middleware MAC layer APIs
The LoRaMAC layer provides the following services:
•MCPS services
In general, the LoRaMAC layer uses the MCPS services for data transmissions and data receptions.
Generates a join request or requests for a link check.
AN5406
•MIB services
The MIB stores important runtime information (such as MIB_NETWORK_ACTIVATION or MIB_NET_ID) and
holds the configuration of the LoRaMAC layer (for example the MIB_ADR, MIB_APP_KEY).
Notifies the application that a received packet is available.
Table 14. MLME primitive
Manages the LoRaWAN network.
6.5
•MIB
No available functions.
Middleware MAC layer timers
•Delay Rx window
Refer to document [1], section 'End-device classes' for more details.
Table 15. Delay Rx window
FunctionDescription
void OnRxWindow1TimerEvent (void)
void OnRxWindow2TimerEvent (void)
•Delay for Tx frame transmission
Table 16. Delay for Tx frame transmission
FunctionDescription
void OnTxDelayedTimerEvent (void)
Sets the RxDelay1
(ReceiveDelayX - RADIO_WAKEUP_TIME).
Sets the RxDelay2.
Sets the timer for Tx frame transmission.
AN5406 - Rev 4
page 16/63
•Delay for Rx frame
Table 17. Delay for Rx frame
FunctionDescription
void OnAckTimeoutTimerEvent (void)
Sets timeout for received frame acknowledgment.
6.6Middleware LmHandler application function
The interface to the MAC is done through the MAC interface LoRaMac.h file, in one of the following modes:
•Standard mode
An interface file (LoRaMAC driver, see Figure 2 ) is provided to let the user start without worrying about the
LoRa state machine. This file is located in
Middlewares\Third_Party\LoRaWAN\LmHandler\LmHandler.c and implements:
–a set of APIs to access to the LoRaMAC services
–the LoRa certification test cases that are not visible to the application layer
•Advanced mode
The user accesses directly the MAC layer by including the MAC in the user file.
AN5406
Middleware LmHandler application function
AN5406 - Rev 4
page 17/63
6.6.1Operation model
The operation model proposed for the LoRa End_Node is based on ‘event-driven’ paradigms including ‘timedriven’ (see the figure below). The behavior of the LoRa system is triggered either by a timer event or by a radio
event plus a guard transition.
AN5406
Middleware LmHandler application function
Figure 5. Operation model
AN5406 - Rev 4
The next sections detail the End_Node and AT_Slave APIs used to access the LoRaMAC services. The
corresponding interface files are located in: