ST Sigfox User manual
AN5480
Application note
How to build a Sigfox
™
application with STM32CubeWL
Introduction
This application note provides guideline to build specific Sigfox™ applications based on STM32WL Series microcontrollers. This
document groups together the most important information and lists the aspects to be addressed.
Sigfox™ is a type of wireless telecommunication network designed to allow long-range communication at very low bit rates, and
to enable the use of long-life battery-operated sensors. The Sigfox Stack™ library manages the channel access and security
protocol that ensures interoperability with the Sigfox™ network.
The application based on the NUCLEO_WL55JC, STM32WL Nucleo-64 boards (order code NUCLEO‑WL55JC1 for
high‑frequency band), and firmware in the STM32CubeWL MCU Package is Sigfox Verified™.
Sigfox™ application main features are:
• Application integration ready
•
RC1, RC2, RC3c, RC4, RC5, RC6 and RC7 Sigfox Verified
•
Sigfox™ Monarch (STMicroelectronics algorithm patented)
• Extremely low CPU load
• No latency requirements
• Small STM32 memory footprint
• Utilities services provided
The firmware of the STM32CubeWL MCU Package is based on the STM32Cube HAL drivers.
™
AN5480 - Rev 3 - January 2021
For further information contact your local STMicroelectronics sales office.
www.st.com
1 Overview
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.
Table 1. Acronyms
Acronym Definition
CS Carrier sense
DC Duty cycle
FH Frequency hopping
IoT Internet of things
LBT Listen before talk
PAC Porting authorization code
POI Point of interest
RC Region configuration
RSA Radio Sigfox analyzer
RSSI Receive signal strength indicator
Rx Reception
SDR Software-defined radio
Tx Transmission
AN5480
Overview
AN5480 - Rev 3
page 2/77
2 Sigfox standard
This section provides a general Sigfox overview, focusing, in particular, the Sigfox end-device.
Sigfox is a wireless telecommunication network operator designed to allow long range communication at a low
bit‑rate enabling long-life battery operated sensors. The firmware of the STM32CubeWL MCU Package includes
the Sigfox Stack library.
Sigfox limits the use of its network to 144 messages per day and per device. Each message can be from 1 bit up
to 12 bytes.
2.1 End-device hardware architecture
The end device is the STM32WL55JC microcontroller mounted on NUCLEO-WL55JC board.
This MCU, with integrated sub-GHZ radio operating in the150 - 960 MHz ISM band, belongs to the
STM32WL Series that include microcontrollers with different memory sizes, packages and peripherals.
2.2 Regional radio resource
The European, North American and Asian markets have different spectrum allocations and regulatory
requirements. Sigfox has split requirements in various RCs (region configurations) listed in the table below.
AN5480
Sigfox standard
Table 2. Region configurations
RC Countries
RC1 Europe, Oman, Lebanon, South Africa, Kenya
RC2 USA, Canada, Mexico
RC3c Japan
RC4 Brazil, Colombia, Peru, New–Zealand, Australia and Singapore
RC5 South Korea
RC6 India
RC7 Russia
AN5480 - Rev 3
page 3/77
AN5480
Rx/Tx radio time diagram
The table below provides an overview of the regulatory requirements for the region configurations.
Table 3. RF parameters for region configurations
RF parameter RC1 RC2 RC3c RC4 RC5 RC6 RC7
Frequency band downlink
(MHz)
Frequency band uplink (MHz) 868.130 902.2 923.2 920,8 923.3 865.2 868.8
Uplink modulation DBPSK
Downlink modulation GFSK
Uplink data‑rate 100 600 100 600 100 100 100
Down-link data‑rate 600
Max output power (dBm) 14 22 13 22 13 13 14
Medium access
CS center frequency (MHz)
CS threshold (dBm) -80 NA -65
869.525 905.2 922.2 922.3 922.3 866.3 869.1
Duty
cycle 1%
Frequency
hopping
Max on time
400 ms/20 s
NA
Carrier
sense
923.2 NA 923.3
Frequency
hopping
Max on time
400 ms/20 s
Carrier
sense
Duty cycle 1%
NACS bandwidth (kHz) 200 NA 200
2.3 Rx/Tx radio time diagram
The end device transmits data to the network in an asynchronous manner. This is due to the fact that
transmission data is only sent per device-report event. The figures below depict the timing sequences with and
without a downlink.
Tx1 Tx2 Tx3
Interframe Tx
Figure 2. Timing diagram for uplink with downlink
Tx1
StartTx
delay
Interframe TRx
Figure 1. Timing diagram for uplink only
Interframe Tx
End timeout
Tx2 Tx3 Rx window TxOOB
Interframe TRx
Rx delay
Rx timeout
Interframe Tx
OOB_ACK
delay
Note: The presence of a downlink only depends on device configuration.
The three transmissions Tx1, Tx2 and Tx3 contain the same payload information. These consecutive
transmissions only maximize the probability of a correct reception by the network. When the device observes
good link quality to the network, it may decide to send only Tx1 to save power consumption only if downlink frame
is requested. The API to select preferred scheme is described in Section 6.1.2 Send frames/bits.
AN5480 - Rev 3
page 4/77
AN5480
Listen before talk (LBT)
The timings shown in the previous figures are detailed in the table below for the various regional configurations.
Table 4. Timings
2.4
RC StartTx delay
RC1
RC2 10 s
RC3c
RC4 10 s 500 ms 20 s 25 s
RC5
RC6
RC7
0 s 500 ms 20 s 25 s
100 ms max
(start LBT)
100 ms max
(LBT)
0 s 500 ms 20 s 25 s
Interframe
Tx/TRx
500 ms + LBT 19 s 34 s
500 ms + LBT 19 s 34 s
Rx delay Rx timeout
OOB_ACK
delay
1.4 s
End timeout
NA
NA
The Tx periods depend on the number of bytes sent and on the RC zone:
• It takes 10 ms to send a bit in RC1 and RC3c.
• It takes 1.66 ms to send a bit in RC2 and RC4.
A message can be 26-byte long at the most (including sync word, header, and payload data). Therefore, for RC1,
a Tx period can be maximum 26 x 8 x 10 ms = 2.08 s.
Listen before talk (LBT)
In RC3c and RC5, LBT is mandatory before any transmission.
In RC3c, the device must listen and check if the channel is free. The channel is considered as free if the power
within a 200 kHz bandwidth stays below -80 dBm (CS threshold) for 5 ms.
When the channel is free, the device starts a transmission. The transmission is not started otherwise.
2.5 Monarch
Monarch is a Sigfox beacon placed at a point of interest (POI). The signal of the Sigfox beacon is emitted at a
frequency allowed by the region the POI belongs to. The beacon contains region configuration (RC) information
that a Monarch‑capable device can demodulate.
Upon reception of this information, the Monarch-capable device is able to switch automatically to the right RC and
send information to the network.
The Monarch feature allows a Sigfox IoT device to roam seamlessly across the world.
2.5.1 Monarch signal description
The Monarch signal is sent at POI every 5 minutes plus a random back-off period of 10 seconds. The frequency
of the beacon is region specific. The beacon lasts in total 400 ms. If a device clock is set, it is hence possible to
open a scan window only when the Monarch signal is present to reduce current consumption of the end device.
Time
(0:2:30)
Figure 3. Monarch beacon
Time
(0:7:30)
Beacon time boundBeacon
Time
(0:12:30)
Time
(0:17:30)
Time
(ss:mm:ss)
AN5480 - Rev 3
page 5/77
AN5480
Monarch
The signal is OOK modulated, meaning the signal is either ON or OFF. The modulation frequency is specified to
16384 Hz (half an RTC clock). The signal is ON for one sample and then OFF. It is ON with a periodicity of 11, 13
or 16 (16384 Hz) samples. Hence the following OOK frequency dF are possible:
• dF1 = 16384 / 16 = 1024 Hz
• dF2 = 16384 / 13 = 1260.3 Hz
• dF3 = 16384 / 11 = 1489.4 Hz
The 400 ms of the Monarch pattern is composed of two sub-patterns:
• The pattern1 lasts 362 ms at a specific dF.
• The pattern2 lasts 38 ms at another specific dF.
Table 5. Monarch signal characteristics versus RC
RC Monarch frequency (Hz) Pattern1 dF (Hz) Pattern2 dF (Hz)
RC1 869 505 000
1024 1260.3RC2 905 180 000
RC3
RC4 1260.3
RC5
RC6 866 250 000
RC7 869 160 000 1260.3
922 250 000
1024
1489.4
2.5.2 Monarch signal demodulation
When a device starts to scan a Monarch signal, the device sweeps during 5 mn onto all Monarch frequencies
listed in Table 5: this is called the sweep period.
Note: If the time is known, the sweep time may be reduced about 10 s + some clock drift.
During this period, the device tries to match with one of the pattern1. When a match is found, the device exits
the sweep period to enter a second period called the window period during for 400 ms. The device sets its RF
frequency where the pattern1 match occurred. The device then tries to match the pattern2 to confirm a Monarch
beacon is found.
AN5480 - Rev 3
page 6/77
3 SubGHz 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 1).
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.1 SubGHz 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.
AN5480
SubGHz HAL driver
3.2 SubGHz 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();
AN5480 - Rev 3
page 7/77
BSP STM32WL Nucleo-64 boards
4 BSP 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.1 Frequency 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.
AN5480
4.2 RF switch
The STM32WL Nucleo-64 board embeds an RF 3-port switch (SP3T) to address, with the same board, the
following modes:
• high-power transmission
• low-power transmission
• reception
int32_t BSP_RADIO_Init(void)
BSP_RADIO_ConfigRFSwitch(BSP_RADIO_Switch_TypeDef Config)
int32_t BSP_RADIO_DeInit (void)
int32_t BSP_RADIO_GetTxConfig(void)
The RF states versus the switch configuration are given in the table below.
RF state
High-power transmission Low High High
Low-power transmission High High High
Reception High Low High
Table 6. BSP radio switch
Function Description
Initializes the RF switch.
Configures the radio switch.
De-initializes the RF switch.
Returns the board configuration:
high power, low power or both.
Table 7. RF states versus switch configuration
FE_CTRL1 FE_CTRL2 FE_CTRL3
AN5480 - Rev 3
page 8/77
4.3 RF 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.4 TCXO
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.
AN5480
RF wakeup time
Table 8. BSP radio wakeup time
Function Description
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.5 Power 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 9. BSP radio TCXO
Function Description
Returns IS_TCXO_SUPPORTED value.
Table 10. BSP radio SMPS
Function Description
Returns IS_DCDC_SUPPORTED value.
AN5480 - Rev 3
page 9/77
4.6 STM32WL 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
AN5480
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
AN5480 - Rev 3
page 10/77
AN5480
Sigfox Stack description
5 Sigfox Stack description
The firmware of the STM32CubeWL MCU Package includes STM32WL resources such as:
• STM32WLxx Nucleo drivers
• STM32WLxx HAL drivers
• Sigfox middleware
• SubGHz physical layer middleware
• Sigfox application example
• Utilities
The Sigfox middleware for STM32 microcontrollers is split into several modules:
• Sigfox Core library layer module
• Sigfox crypto module
• Sigfox Monarch (ST algorithm patent)
The Sigfox Core library implements a Sigfox medium access controller that interfaces with the Cmac library
encrypting uplink payload and verifying downlink payload. The Cmac library interfaces with the Credentials library
holding the cryptographic functions. This medium access controller also interfaces with the ST Monarch library.
The Sigfox Core library interfaces also with i.e rf_api.c.and and mcu_api,cm porting files in the user
directory. It is not advised to modify these files.
The Sigfox Core, Sigfox test, cryptographic and Monarch library modules are provided in compiled object.
The libraries have been compiled with wchar32 and 'short enums'. These settings are used by default in IAR
Embedded workbench and STM32CubeIDE.
For μVision Keil, specific care must be taken. Tickbox 'Short enums/wchar' must be unchecked and 'fshort
-enums' must be added in 'Misc Controls' field.
Note: For dual-core applications, these settings must be applied to both cores to guaranty same enum formatting.
5.1
Sigfox certification
The system including the NUCLEO-WL55JC board and the STM32CubeWL firmware modem application has
been verified by Sigfox Test Lab and passed the Sigfox Verified certification.
Nevertheless, the end product based on a STM32WL Series MCU must pass again the Sigfox Verified and the
Sigfox Ready™ certification before the end-product commercialization.
AN5480 - Rev 3
page 11/77
5.2 Architecture
5.2.1 Static view
The figure below details the main design of the firmware for the Sigfox application.
radio.h
AN5480
Architecture
Figure 5. Static Sigfox architecture
Sigfox application
(AT_Slave or PushButton)
Sigfox middleware
rf_protocol_api.h
Sigfox test
library
rf_api
Utilities
NVM (E2P)
Timer server
Sequencer
Debug trace
Low-power
mode
Cmac
library
se_api
sigfox_api.h
Monarch
library
mn_api
Sigfox
library
SubGHz_Phy middleware
radio.c
radio_driver.c
mcu_api
Board support package (BSP)
Hardware abstraction layer APIs (HAL)
NVIC SubGHz RCC GPIO RTC
Sub-GHz radio system peripheral
The HAL uses STM32Cube APIs to drive the hardware required by the application.
The RTC provides a centralized time unit that continues to run even in the low-power Stop mode. The RTC alarm
is used to wake up the system at specific times managed by the timer server.
The Sigfox Core library embeds the medium access controller (MAC) as well as some security functions (see
Section 6.1 Sigfox Core library for more details).
The application is built around an infinite loop including a scheduler. The scheduler processes tasks and events.
When nothing remains to be done, the scheduler transitions to idle state and calls the low-power manager.
Typical application examples:
• AT layer to interface with external host (refer to Section 11.2 AT modem application)
• application reading and sending sensor data upon an action (refer to Section 11.3 PushButton application)
AN5480 - Rev 3
page 12/77
5.2.2 Dynamic view
The message sequence chart (MSC) in the figure below depicts the dynamic calls between APIs in Tx mode (for
one transmission).
AN5480
Architecture
Figure 6. Transmission MSC
Application
SIGFOX_API_
send_frame
Sigfox Core
library
rf_mode: SFX_RF_MODE_TX
RF_API_change_
frequency(frequency)
MANUF_API
RF_API_init
Radio.SetChannel
(frequency)
Get EEPROM power
Radio.SetTxConfig
(MODEM_SIGFOX_TX,
Power, datarate,
timeout)
Radio.Send
(stream, size)
CFG_SEQ_Evt_TxTimout
Callback SUBGHZ_Radio_IRQHandler
CFG_SEQ_Evt_TxTimout
RF_API_stop Radio.Sleep()
Radio Idle
Return
Interrupt
SEQ_WaitEvt
Tx ON
MCU stop
SEQ_SetEvt
When a downlink window is requested, an Rx sequence is started after Rxdelay is elapsed (see Figure 2. Timing
diagram for uplink with downlink).
When Rxdelay is elapsed, the sequence detailed in the figure below occurs.
Sigfox Core
library
rf_mode: SFX_RF_MODE_RX
RF_API_change_
frequency(frequency)
MCU_API_timer_start
RF_API_wait_frame
MCU_API_timer_stop
Figure 7. Reception MSC
MANUF_API
RF_API_init
RF_API_stop Radio.Sleep()
Radio.SetTxConfig
(MODEM_SIGFOX_RX)
RF_API_change_
frequency(frequency)
T 25 s
onTimerTImoutEvt
CFG_SEQ_Evt_TxTimout
Radio.RxBoosted(0)
CFG_SEQ_Evt_TxTimout
Callback SUBGHZ_Radio_IRQHandler
CFG_SEQ_Evt_TxTimout
T
Radio Idle
Return
Interrupt
SEQ_WaitEvt
Rx ON
MCU stop
SEQ_SetEvt
AN5480 - Rev 3
page 13/77
5.3 Required STM32 peripherals to drive the radio
Sub-GHz radio
The sub-GHz radio peripheral is accessed through the stm32wlxx_hal_subghz HAL.
The sub-GHz radio issues an interrupt through SUBGHZ_Radio_IRQHandler NVIC, to notify a TxDone or
RxDone event. More events are listed in the product reference manual.
RTC
The RTC (real-time clock) calendar is used as 32-bit counter running in all power modes from the 32 kHz
external oscillator. By default, the RTC is programed to provide 1024 ticks (sub-seconds) per second. The RTC is
programed once at hardware initialization when the MCU starts for the first time. The RTC output is limited to a
32-bit timer that corresponds to about a 48-day period.
Caution: When changing the tick duration, the user must keep it below 1 ms.
LPTIM
The LPTIM (low-power timer) is used for Monarch only. The LPTIM is set when a Monarch scan is requested,
uses the LSE clock and issues an interrupt at 16384 Hz.
AN5480
Required STM32 peripherals to drive the radio
AN5480 - Rev 3
page 14/77
6 Sigfox middleware programming guidelines
6.1 Sigfox Core library
Embedded applications using the Sigfox Core library call SIGFOX_APIs to manage communication.
Table 11. Application level Sigfox APIs
Function Description
sfx_error_t SIGFOX_API_get_device_id
(sfx_u8 *dev_id);
sfx_error_t SIGFOX_API_get_initial_pac
(sfx_u8 *initial_pac);
sfx_error_t SIGFOX_API_open
(sfx_rc_t *rc);
sfx_error_t SIGFOX_API_close(void);
sfx_error_t SIGFOX_API_send_frame
(sfx_u8 *customer_data,
sfx_u8 customer_data_length,
sfx_u8 *customer_response,
sfx_u8 tx_repeat,
sfx_bool initiate_downlink_flag);
sfx_error_t SIGFOX_API_send_bit
(sfx_bool bit_value,
sfx_u8 *customer_response,
sfx_u8 tx_repeat,
sfx_bool initiate_downlink_flag);
sfx_error_t SIGFOX_API_set_std_config
(sfx_u32 config_words[3],
sfx_bool timer_enable);
Copies the ID of the device to the pointer given in parameter.
The ID is 4‑byte long and in hexadecimal format.
Gets the value of the PAC stored in the device. This value is
used when the device is registered for the first time on the
backend. The PAC is 8‑byte long.
Initializes the library and saves the input parameters once
(cannot be changed until SIGFOX_API_close() is
called)
– rc is a pointer on the radio configuration zone. It is
mandatory to use already existing defined RCs.
Closes the library and stops the RF.
Sends a standard Sigfox frame with customer payload.
• customer_data cannot exceed 12 bytes
• customer_data_length: length in bytes
• customer_response: received response
• tx_repeat:
– when 0, sends one Tx.
– when 1, sends three Tx.
• initiate_downlink_flag: if set, the frame sent
is followed by a receive downlink frame and an out-ofband Tx frame (voltage, temperature and RSSI).
Sends a standard Sigfox™ frame with null customer payload
(shortest frame that Sigfox library can generate).
• bit_value: bit sent
• customer_response: received response
• tx_repeat:
– when 0, sends one Tx.
– when 1, sends three Tx.
• initiate_downlink_flag: if set, the frame sent
is followed by a receive downlink frame and an out-ofband Tx frame (voltage, temperature and RSSI).
Configures specific variables for standard. Parameters have
different meanings whether in FH or LBT mode.
Note: this function has no influence in DC (see
Section 11.2.21 ATS400 - Enabled channels for FCC for
details).
AN5480
Sigfox middleware programming guidelines
AN5480 - Rev 3
Secondary APIs are described in sigfox_api.h. The library can be found in the
Middlewares\Third_Party\SigfoxLib directory.
page 15/77
6.1.1 Open the Sigfox library
ST_SIGFOX_API_open must be called to initialize the Sigfox library before any other operation is performed.
This API requires the RC argument number representing the radio configuration zone (see Section 2.2 Regional
radio resource).
For radio control zones 2 and 4, the FCC (federal communications commission) requires frequency hopping so
the transmission frequency is not fixed (see Section 6.1.3 Set standard configuration for more details on how to
map the macro channels).
6.1.2 Send frames/bits
ST_SIGFOX_API_send_frame is the main Sigfox library function. This blocking function handles message
exchange between the end node and the base stations.
An important parameter of this function is the initiate_downlink_flag that selects different transmission
behaviors:
• initiate_downlink_flag = 0: The library requests only uplink frame. The sent frame is transmitted
once if tx_repeat = 0, or three times if tx_repeat = 1, with a 500 ms pause (see Figure 1).The
transmit payload can be maximum 12‑byte long.
• initiate_downlink_flag = 1: The frame to be sent is transmitted three times with a 500 ms
pause. A 25 s Rx window then opens 20 s after the end of the first repetition (see Figure 2). If the
reception is successful, the received 8-byte downlink frame is stored in the buffer location indicated by the
customer_response buffer.
AN5480
Sigfox Core library
6.1.3 Set standard configuration
The FCC allows the transmitters to choose certain macro channels to implement a frequencyhopping pattern authorized by the standard. The channel map is specified in the first argument of
SIGFOX_API_set_std_config, that consists of an array of three 32-bit configuration words.
A macro-channel consists of six micro channels centered about the center frequency of the macro channel and
separated by 25 kHz. For example, in the 902.2 MHz macro channel, the six micro channels are 902.1375 MHz,
902.1625 MHz, 902.1875 MHz, 902.2125 MHz, 902.2375 MHz, and 902.2625 MHz.
A typical Sigfox frame lasts between 200 ms and 350 ms at 600 bit/s, and FCC mandates a max dwell time of
400 ms. A transmitter cannot return to a given channel before 20 s. Therefore, at least 20 / 0.4 = 50 channels
must be used for continuous transmission.
Actually, a device only transmits a few frames per day (144 messages maximum). Enabling one macro channel
only and inserting 10 s delays between two groups of three repeated frames (one frame per micro channel means
six micro channels) pass the regulation limits.
AN5480 - Rev 3
page 16/77
AN5480
Sigfox Core library
Each bit of the config_words[0,1,2] array represents a macro channel according to the mapping described in the
table below.
Table 12. Macro channel mapping
Bit
0 902.2 911.8 921.4
1 902.5 912.1 921.7
2 902.8 912.4 922
3 903.1 912.7 922.3
4 903.4 913 922.6
5 903.7 913.3 922.9
6 904 913.6 923.2
7 904.3 913.9 923.5
8 904.6 914.2 923.8
9 904.9 914.5 924.1
10 905.2 914.8 924.4
11 905.5 915.1 924.7
12 905.8 915.4 925
13 906.1 915.7 925.3
14 906.4 916 925.6
15 906.7 916.3 925.9
16 907 916.6 926.2
17 907.3 916.9 926.5
18 907.6 917.2 926.8
19 907.9 917.5 927.1
20 908.2 917.8 927.4
21 908.5 918.1 927.7
22 908.8 918.4 928
23 909.1 918.7 928.3
24 909.4 919 928.6
25 909.7 919.3 928.9
26 910 919.6 929.2
27 910.3 919.9 929.5
28 910.6 920.2 929.8
29 910.9 920.5 930.1
30 911.2 920.8 930.4
31 911.5 921.1 930.7
config_words[0]
Frequency mapping (MHz)
config_words[1]
Frequency mapping (MHz)
config_words[2]
Frequency mapping (MHz)
AN5480 - Rev 3
A macro channel is only enabled when the corresponding config_words[x] bit is set to 1. For example, bit 0 of
config_words[0] corresponds to channel 1 while bit 30 of config_words[1] corresponds to channel 63. At least nine
macro channels must be enabled to meet the FCC specifications.
page 17/77
In the following long message configuration example, channels 1 to 9 are enabled with frequencies ranging from
902.2 MHz to 904.6 MHz:
• config_words[0] = [0x0000 01FF]
• config_words[1] = [0x0000 0000]
• config_words[2] = [0x0000 0000]
By default, the Sigfox application sets one macro channel with timer_enable = 1. The macro channel 1 in
RC2 has a 902.2 MHz operational frequency and the macro channel 63 in RC4 has a 920.8 MHz operational
frequency). This is the short message configuration operational for Sigfox (see defined RCx_SM_CONFIG value in
sigfox_api.h file).
A delay (timer_enable) is implemented to avoid one micro channel to be re-used with an interval lower
than 20 s. When using one macro channel only (six micro channels) performing three repetitions, this delay
corresponds to 10 s. When using two macro channels (12 micro channels), the delay automatically becomes 5 s.
For certification test purposes, timer_enable may be set to 0, but must be set to 1 otherwise. The default
settings can nevertheless be modified using the ATS400 command (Section 11.2.21 ) to speed up the
certification process.
6.2 Sigfox Addon RF protocol library
This library is used to test the device for Sigfox Verified certification. Ultimately, this library can be removed from
the build once certified.
AN5480
Sigfox Addon RF protocol library
Table 13. Sigfox Addon Verified library
Function Description
sfx_error_t
ADDON_SIGFOX_RF_PROTOCOL_API_test_mode
(sfx _rc_enum_t rc_enum, sfx_test_mode_t test_mode);
Executes the test modes needed for the
Sigfox Verified certification:
• rc_enum: rc at which the test
mode is run
• test_mode: test mode to run
sfx_error_t
ADDON_SIGFOX_RF_PROTOCOL_API_monarch_test_ mode
(sfx_rc_enum_t rc_enum, sfx_test_mode_t test_mode,
This function executes the Monarch test
modes needed for Sigfox RF and protocol
tests.
sfx_u8 rc_capabilities);
This library is located in Middlewares\Third_Party\Sgfx\SigfoxLibTest\.
AN5480 - Rev 3
page 18/77
6.3 Cmac library
The Cmac library stores the keys, the PAC and the IDs.
sfx_u8 SE_API_get_device_id
(sfx_u8 dev_id[ID_LENGTH]);
sfx_u8 SE_API_get_initial_pac (sfx_u8 *initial_pac);
sfx_u8 SE_API_secure_uplink_message
(sfx_u8 *customer_data,
sfx_u8 customer_data_length,
sfx_bool initiate_downlink_frame,
sfx_se_frame_type_t frame_type,
sfx_bool *send_rcsync,
sfx_u8 *frame_ptr, sfx_u8 *frame_length);
sfx_u8 SE_API_verify_downlink_message
(sfx_u8 *frame_ptr, sfx_bool *valid);
AN5480
Cmac library
Table 14. Cmac APIs
Function Description
This function copies the device ID in
dev_id.
Gets the initial PAC.
Generates an uplink frame bitstream.
Authenticates a received message and
decrypts its payload.
The Cmac library is located in directory \Middlewares\Third_Party\Sgfx\Crypto.
Note: • This library interfaces the se_nvm functions to store/retrieve SFX_SE_NVMEM_BLOCK_SIZE bytes from the
non-volatile memory.
• se_api.h is the interface to the Sigfox secure element that can be either a physical secure element, or
emulated by firmware with the Cmac library and the Credentials library.
AN5480 - Rev 3
page 19/77
6.4 Credentials library
The Credentials library can access the keys, the PAC and the IDs. It can also encrypt data with the Sigfox key.
void CREDENTIALS_get_dev_id(uint8_t* dev_id);
void CREDENTIALS_get_initial_pac (uint8_t* pac);
sfx_bool CREDENTIALS_get_payload_encryption_fl
ag(void);
sfx_error_t CREDENTIALS_aes_128_cbc_encrypt
(uint8 _t* encrypted_data, uint8_t* data_to_encrypt,
uint8_t block_len);
sfx_error_t CREDENTIALS_wrap_session_key
(uint8_t *data, uint8_t blocks)
sfx_error_t
CREDENTIALS_aes_128_cbc_encrypt_with_session_key
(uint8_t *encrypted_data,
uint8_t *data_to_encrypt, uint8_t blocks)
AN5480
Credentials library
Table 15. Credentials APIs
Function Description
Gets the device ID.
Gets the device initial PAC.
Gets the encryption flag. Sets
to false by default (see
Section 11.2.10 ATS411 - Payload
encryption).
Encrypts data with the secret
key. The secret key can be
set to CMAC_KEY_PRIVATE
or CMAC_KEY_PUBLIC (see
Section 11.2.9 ATS410 - Encryption
key).
Derives a session key based on the
Sigfox secret key
Encrypts data with the session key.
6.5 Monarch library
The Monarch APIs are defined in sigfox_monarch_apis.h.
sfx_error_t
SIGFOX_MONARCH_API_execute_rc_scan
(sfx_u8 rc_capabilities_bit_mask, sfx_u16 timer,
sfx_timer_unit_enum_t unit, sfx_u8
(* app_callback_handler)
(sfx_u8 rc_bit_mask, sfx_s16 rssi));
sfx_error_t
SIGFOX_MONARCH_API_stop_rc_scan(void);
Table 16. Monarch APIs
Function Description
Starts a Monarch scan.
• sfx_u8
rc_capabilities_bit_mask
• sfx_u16 timer: scan duration
value
• sfx_timer_unit_enum_t
unit: unit of timer
• app_callback_handler:
function called by the Sigfox library
when the scan is completed
Stops an ongoing Monarch scan.
AN5480 - Rev 3
page 20/77
7 SubGHz_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
AN5480
SubGHz_Phy layer middleware description
AN5480 - Rev 3
page 21/77
7.1 Middleware 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 17. Radio_s structure callbacks
Callback Description
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.
AN5480
Middleware radio driver structure
AN5480 - Rev 3
page 22/77
7.2 Radio IRQ interrupts
The possible sub-GHz radio interrupt sources are detailed in the table below.
Bit Source Description Packet type Operation
txDone
0
rxDone
1
PreambleDetected
2
SyncDetected
3
HeaderValid
4
HeaderErr
5
Err
6
CrcErr
CadDone
CadDetected
8
Timeout
9
Radio IRQ interrupts
Table 18. Radio IRQ bit mapping and definition
Packet transmission finished
Packet reception finished
Preamble detected
Synchronization word valid GFSK
Header valid
Header error
Preamble, sync word, address, CRC or
length error
CRC error
Channel activity detection finished
Channel activity detected
Rx or TX timeout LoRa and GFSK Rx and Tx
LoRa and GFSK
LoRa
GFSK
LoRa7
AN5480
Tx
Rx
CAD
For more details, refer to the product reference manual.
AN5480 - Rev 3
page 23/77
8 EEPROM driver
The EEPROM interface (sgfx_eeprom_if.c) is designed above ee.c to abstract the EEPROM driver. The
EEPROM is physically placed at EE_BASE_ADRESS defined in the utilities_conf.h.
Function Description
void E2P_Init ( void );
void E2P_RestoreFs
( void );
Void E2P_Write_XXX
E2P_Read_XXX
AN5480
EEPROM driver
Table 19. EEPROM APIs
DEFAULT_FACTORY_SETTINGS is written when the EEPROM is empty.
DEFAULT_FACTORY_SETTINGS are restored .
Writes data in the EEPROM. For example:
void E2P_Write_VerboseLevel(uint8_t verboselevel);
Reads XXX from the EEPROM For example:
sfx_rc_enum_t E2P_Read_Rc(void);
AN5480 - Rev 3
page 24/77
Loading...