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	www.st.com
For further information contact your local STMicroelectronics sales office.

AN5480

Overview

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.

	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 - Rev 3	page 2/77

AN5480

Sigfox standard

2Sigfox 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.1End-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.2Regional 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.

	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	869.525	905.2	922.2	922.3	922.3	866.3		869.1
	(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
			Frequency		Frequency
	Medium access	Duty	hopping	Carrier	hopping	Carrier	Duty cycle 1%
		cycle 1%	Max on time	sense	Max on time	sense
			400 ms/20 s		400 ms/20 s
	CS center frequency (MHz)			923.2	NA	923.3
	CS bandwidth (kHz)		NA	200	NA	200		NA
	CS threshold (dBm)			-80	NA	-65

2.3Rx/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.

Figure 1. Timing diagram for uplink only

Tx1

Tx2

Tx3

Interframe Tx

Interframe Tx

Interframe Tx

End timeout

Figure 2. Timing diagram for uplink with downlink

Tx1

Tx2

Tx3

Rx window

TxOOB

StartTx

Interframe TRx

Interframe TRx

OOB_ACK

delay

delay

Rx delay

Rx timeout

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

	RC	StartTx delay	Interframe	Rx delay	Rx timeout	OOB_ACK	End timeout
			Tx/TRx			delay
	RC1	0 s	500 ms	20 s	25 s		NA
	RC2						10 s
	RC3c	100 ms max	500 ms + LBT	19 s	34 s
		(start LBT)
	RC4	10 s	500 ms	20 s	25 s	1.4 s
	RC5	100 ms max	500 ms + LBT	19 s	34 s		NA
		(LBT)
	RC6	0 s	500 ms	20 s	25 s
	RC7

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.

2.4Listen 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.5Monarch

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.1Monarch 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.

Figure 3. Monarch beacon

Time

(ss:mm:ss)

Time

Time

Time

Time

(0:2:30)

(0:7:30)

(0:12:30)

(0:17:30)

Beacon

Beacon time bound

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
	RC2	905 180 000	1024	1260.3
	RC3
	RC4	922 250 000	1260.3
	RC5		1024	1489.4
	RC6	866 250 000
	RC7	869 160 000	1260.3

2.5.2Monarch 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

AN5480

SubGHz HAL driver

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 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.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.

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();

AN5480 - Rev 3	page 7/77

AN5480

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.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.

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

Table 6. BSP radio switch

	Function	Description
	int32_t BSP_RADIO_Init(void)	Initializes the RF switch.
	BSP_RADIO_ConfigRFSwitch(BSP_RADIO_Switch_TypeDef Config)	Configures the radio switch.
	int32_t BSP_RADIO_DeInit (void)	De-initializes the RF switch.
	int32_t BSP_RADIO_GetTxConfig(void)	Returns the board configuration:
		high power, low power or both.
	The RF states versus the switch configuration are given in the table below.

Table 7. RF states versus switch configuration

RF state	FE_CTRL1	FE_CTRL2	FE_CTRL3
High-power transmission	Low	High	High
Low-power transmission	High	High	High
Reception	High	Low	High

AN5480 - Rev 3	page 8/77

AN5480

RF wakeup time

4.3RF wakeup time

The sub-GHz radio wakeup time is recovered with the following API.

Table 8. BSP radio wakeup time

Function	Description
uint32_t BSP_RADIO_GetWakeUpTime(void)	Returns RF_WAKEUP_TIME value.

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.

Table 9. BSP radio TCXO

Function	Description
uint32_t BSP_RADIO_IsTCXO (void)	Returns IS_TCXO_SUPPORTED value.

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.

Table 10. BSP radio SMPS

Function	Description
uint32_t BSP_RADIO_IsDCDC (void)	Returns IS_DCDC_SUPPORTED value.

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.

AN5480 - Rev 3	page 9/77

AN5480

STM32WL Nucleo-64 board schematic

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

Control switchs 1 and 2

System clock

TCXO control voltage

Control switch 3

Debug line 2 and 3	Debug line 1

AN5480 - Rev 3	page 10/77

AN5480

Sigfox Stack description

5Sigfox 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.1Sigfox 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

AN5480

Architecture

5.2Architecture

5.2.1Static view

The figure below details the main design of the firmware for the Sigfox application.

Figure 5. Static Sigfox architecture

		Sigfox application
		(AT_Slave or PushButton)
radio.h	Sigfox middleware
	sigfox_api.h		rf_protocol_api.h
Cmac	Monarch	Sigfox	Sigfox test	Utilities
library	library	library	library	NVM (E2P)
se_api	mn_api	mcu_api	rf_api	Timer server
	SubGHz_Phy middleware			Sequencer
		radio.c
				Debug trace
	radio_driver.c			Low-power
				mode
			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

AN5480

Architecture

5.2.2Dynamic view

The message sequence chart (MSC) in the figure below depicts the dynamic calls between APIs in Tx mode (for one transmission).

Figure 6. Transmission MSC

Application		Sigfox Core		MANUF_API		Radio		Idle
		library

SIGFOX_API_ send_frame

RF_API_init
rf_mode: SFX_RF_MODE_TX
RF_API_change_				Return
frequency(frequency)	Radio.SetChannel			Interrupt
	(frequency)
Get EEPROM power
	Radio.SetTxConfig
	(MODEM_SIGFOX_TX,
	Power, datarate,
	timeout)
	Radio.Send
	(stream, size)
	SEQ_WaitEvt		<![if ! IE]> <![endif]>MCU stop	<![if ! IE]> <![endif]>Tx ON
	CFG_SEQ_Evt_TxTimout
	Callback	SUBGHZ_Radio_IRQHandler
	SEQ_SetEvt
	CFG_SEQ_Evt_TxTimout
RF_API_stop	Radio.Sleep()

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.

Figure 7. Reception MSC

Sigfox Core		MANUF_API		Radio		Idle
library

RF_API_init

rf_mode: SFX_RF_MODE_RX Radio.SetTxConfig (MODEM_SIGFOX_RX)

Return

RF_API_change_

frequency(frequency) RF_API_change_ Interrupt frequency(frequency)

	MCU_API_timer_start		T 25 s
			onTimerTImoutEvt
	RF_API_wait_frame		CFG_SEQ_Evt_TxTimout
			Radio.RxBoosted(0)
								<![if ! IE]> <![endif]>MCU stop		<![if ! IE]> <![endif]>Rx ON
			SEQ_WaitEvt
			CFG_SEQ_Evt_TxTimout
			Callback		SUBGHZ_Radio_IRQHandler
			SEQ_SetEvt
			CFG_SEQ_Evt_TxTimout
	RF_API_stop		Radio.Sleep()
	MCU_API_timer_stop		T

AN5480 - Rev 3	page 13/77

AN5480

Required STM32 peripherals to drive the radio

5.3Required 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 - Rev 3	page 14/77

AN5480

Sigfox middleware programming guidelines

6Sigfox middleware programming guidelines

6.1Sigfox 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	Copies the ID of the device to the pointer given in parameter.
	(sfx_u8 *dev_id);	The ID is 4 byte long and in hexadecimal format.
	sfx_error_t SIGFOX_API_get_initial_pac	Gets the value of the PAC stored in the device. This value is
	(sfx_u8 *initial_pac);	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
	sfx_error_t SIGFOX_API_open	(cannot be changed until SIGFOX_API_close() is
		called)
	(sfx_rc_t *rc);	– rc is a pointer on the radio configuration zone. It is
		mandatory to use already existing defined RCs.
	sfx_error_t SIGFOX_API_close(void);	Closes the library and stops the RF.
		Sends a standard Sigfox frame with customer payload.
	sfx_error_t SIGFOX_API_send_frame	•	customer_data cannot exceed 12 bytes
	(sfx_u8 *customer_data,	•	customer_data_length: length in bytes
		•	customer_response: received response
	sfx_u8 customer_data_length,
		•	tx_repeat:
	sfx_u8 *customer_response,
			–	when 0, sends one Tx.
	sfx_u8 tx_repeat,		–	when 1, sends three Tx.
	sfx_bool initiate_downlink_flag);	•	initiate_downlink_flag: if set, the frame sent
			is followed by a receive downlink frame and an out-of-
			band Tx frame (voltage, temperature and RSSI).
		Sends a standard Sigfox™ frame with null customer payload
		(shortest frame that Sigfox library can generate).
	sfx_error_t SIGFOX_API_send_bit	•	bit_value: bit sent
	(sfx_bool bit_value,	•	customer_response: received response
	sfx_u8 *customer_response,	•	tx_repeat:
			–	when 0, sends one Tx.
	sfx_u8 tx_repeat,
			–	when 1, sends three Tx.
	sfx_bool initiate_downlink_flag);	•	initiate_downlink_flag: if set, the frame sent
			is followed by a receive downlink frame and an out-of-
			band Tx frame (voltage, temperature and RSSI).
	sfx_error_t SIGFOX_API_set_std_config	Configures specific variables for standard. Parameters have
		different meanings whether in FH or LBT mode.
	(sfx_u32 config_words[3],	Note: this function has no influence in DC (see
	sfx_bool timer_enable);	Section		11.2.21 ATS400 - Enabled channels for FCC for
		details).
	Secondary APIs are described in sigfox_api.h. The library can be found in the
	Middlewares\Third_Party\SigfoxLib directory.

AN5480 - Rev 3	page 15/77

AN5480

Sigfox Core library

6.1.1Open 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.2Send 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.

6.1.3Set 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	config_words[0]	config_words[1]	config_words[2]
		Frequency mapping (MHz)	Frequency mapping (MHz)	Frequency mapping (MHz)
	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

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.

AN5480 - Rev 3	page 17/77

AN5480

Sigfox Addon RF protocol library

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.2Sigfox 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.

Table 13. Sigfox Addon Verified library

	Function		Description
	sfx_error_t	Executes the test modes needed for the
		Sigfox Verified certification:
	ADDON_SIGFOX_RF_PROTOCOL_API_test_mode	•	rc_enum: rc at which the test
	(sfx _rc_enum_t rc_enum, sfx_test_mode_t test_mode);		mode is run
		•	test_mode: test mode to run
	sfx_error_t	This function executes the Monarch test
	ADDON_SIGFOX_RF_PROTOCOL_API_monarch_test_ mode
	(sfx_rc_enum_t rc_enum, sfx_test_mode_t test_mode,	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

AN5480

Cmac library

6.3Cmac library

The Cmac library stores the keys, the PAC and the IDs.

Table 14. Cmac APIs

			Function		Description
		sfx_u8 SE_API_get_device_id			This function copies the device ID in
		(sfx_u8 dev_id[ID_LENGTH]);			dev_id.
		sfx_u8 SE_API_get_initial_pac (sfx_u8 *initial_pac);			Gets the initial PAC.
		sfx_u8	SE_API_secure_uplink_message
		(sfx_u8 *customer_data,
		sfx_u8	customer_data_length,
		sfx_bool initiate_downlink_frame,			Generates an uplink frame bitstream.
		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		Authenticates a received message and
		(sfx_u8 *frame_ptr, sfx_bool *valid);			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

AN5480

Credentials library

6.4Credentials library

The Credentials library can access the keys, the PAC and the IDs. It can also encrypt data with the Sigfox key.

Table 15. Credentials APIs

	Function		Description
	void CREDENTIALS_get_dev_id(uint8_t* dev_id);		Gets the device ID.
	void CREDENTIALS_get_initial_pac (uint8_t* pac);		Gets the device initial PAC.
	sfx_bool CREDENTIALS_get_payload_encryption_fl		Gets the encryption flag. Sets
			to false by default (see
	ag(void);		Section 11.2.10 ATS411 - Payload
			encryption).
	sfx_error_t CREDENTIALS_aes_128_cbc_encrypt		Encrypts data with the secret
			key. The secret key can be
	(uint8 _t* encrypted_data, uint8_t* data_to_encrypt,		set to CMAC_KEY_PRIVATE
			or CMAC_KEY_PUBLIC (see
	uint8_t block_len);		Section 11.2.9 ATS410 - Encryption
			key).
	sfx_error_t CREDENTIALS_wrap_session_key		Derives a session key based on the
	(uint8_t *data, uint8_t blocks)		Sigfox secret key
	sfx_error_t
	CREDENTIALS_aes_128_cbc_encrypt_with_session_key		Encrypts data with the session key.
	(uint8_t *encrypted_data,
	uint8_t *data_to_encrypt, uint8_t blocks)
6.5	Monarch library
	The Monarch APIs are defined in sigfox_monarch_apis.h.
	Table 16. Monarch APIs
	Function		Description
		Starts a Monarch scan.
	sfx_error_t	•	sfx_u8
	SIGFOX_MONARCH_API_execute_rc_scan		rc_capabilities_bit_mask
		•	sfx_u16 timer: scan duration
	(sfx_u8 rc_capabilities_bit_mask, sfx_u16 timer,
			value
	sfx_timer_unit_enum_t unit, sfx_u8	•	sfx_timer_unit_enum_t
	(* app_callback_handler)		unit: unit of timer
		•	app_callback_handler:
	(sfx_u8 rc_bit_mask, sfx_s16 rssi));
			function called by the Sigfox library
			when the scan is completed
	sfx_error_t	Stops an ongoing Monarch scan.
	SIGFOX_MONARCH_API_stop_rc_scan(void);

AN5480 - Rev 3	page 20/77

AN5480

SubGHz_Phy layer middleware description

7SubGHz_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 - Rev 3	page 21/77

AN5480

Middleware radio driver structure

7.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 17. Radio_s structure callbacks
Callback		Description
RadioInit		Initializes the radio.
RadioGetStatus		Returns the current radio status.
RadioSetModem		Configures the radio with the given modem.
RadioSetChannel		Sets the channel frequency.
RadioIsChannelFree		Checks if the channel is free for the given time.
RadioRandom		Generates a 32-bit random value based on the RSSI readings.
RadioSetRxConfig		Sets the reception parameters.
RadioSetTxConfig		Sets the transmission parameters.
RadioCheckRfFrequenc		Checks if the given RF frequency is supported by the hardware.
RadioTimeOnAir		Computes the packet time on air in ms, for the given payload.
RadioSend		Sends the buffer of size. Prepares the packet to be sent and sets the radio in
		transmission.
RadioSleep		Sets the radio in Sleep mode.
RadioStandby		Sets the radio in Standby mode.
RadioRx		Sets the radio in reception mode for the given time.
RadioStartCad		Starts a CAD (channel activity detection).
RadioSetTxContinuousWave		Sets the radio in continuous wave transmission mode.
RadioRssi		Reads the current RSSI value.
RadioWrite		Writes the radio register at the specified address.
RadioRead		Reads the radio register at the specified address.
RadioSetMaxPayloadLength		Sets the maximum payload length.
RadioSetPublicNetwork		Sets the network to public or private. Updates the sync byte.
RadioGetWakeUpTime		Gets the time required for the board plus radio to exit Sleep mode.
RadioIrqProcess		Processes radio IRQ.
RadioRxBoosted		Sets the radio in reception mode with max LNA gain for the given time.
RadioSetRxDutyCycle		Sets the Rx duty-cycle management parameters.
RadioTxPrbs		Sets the transmitter in continuous PRBS mode.
RadioTxCw		Sets the transmitter in continuous unmodulated carrier mode.

AN5480 - Rev 3	page 22/77

AN5480

Radio IRQ interrupts

7.2Radio IRQ interrupts

The possible sub-GHz radio interrupt sources are detailed in the table below.

Table 18. Radio IRQ bit mapping and definition

Bit	Source	Description	Packet type	Operation
0	txDone	Packet transmission finished		Tx
1	rxDone	Packet reception finished	LoRa and GFSK
2	PreambleDetected	Preamble detected
3	SyncDetected	Synchronization word valid	GFSK
4	HeaderValid	Header valid	LoRa	Rx
5	HeaderErr	Header error
	Err	Preamble, sync word, address, CRC or	GFSK
6		length error
	CrcErr	CRC error
7	CadDone	Channel activity detection finished	LoRa	CAD
8	CadDetected	Channel activity detected
9	Timeout	Rx or TX timeout	LoRa and GFSK	Rx and Tx

For more details, refer to the product reference manual.

AN5480 - Rev 3	page 23/77

AN5480

EEPROM driver

8EEPROM 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.

		Table 19. EEPROM APIs
	Function	Description
	void E2P_Init ( void );	DEFAULT_FACTORY_SETTINGS is written when the EEPROM is empty.
	void E2P_RestoreFs	DEFAULT_FACTORY_SETTINGS are restored .
	( void );
	Void E2P_Write_XXX	Writes data in the EEPROM. For example:
		void E2P_Write_VerboseLevel(uint8_t verboselevel);
	E2P_Read_XXX	Reads XXX from the EEPROM For example:
		sfx_rc_enum_t E2P_Read_Rc(void);

AN5480 - Rev 3	page 24/77