STMicroelectronics FUOTA Application note

AN5411
Application note
I-CUBE-LRWAN embedding FUOTA, application implementation

Introduction

This application note describes the FUOTA application embedded in the expansion software (I-CUBE-LRWAN) implementation on STM32L4 Series devices, and explains how to make use of the overall FUOTA process in order to provide the components needed for a FUOTA campaign.
This document applies within the framework of a FUOTA project, and is intended for teams or individuals, either internal or external to ST. It particularly targets FUOTA project integrators, or those integrating FUOTA modules in a wider system implementing end-device functions.
LoRa® is a type of wireless telecommunication network designed to allow long range communication at a very low bit rate, enabling long-life battery operated sensors. LoRaWAN® defines the communication and security protocol to ensure
interoperability with LoRa networks.
AN5411 - Rev 2 - March 2021 For further information contact your local STMicroelectronics sales office.
www.st.com

1 General information

This document applies to STM32L476xx Series Arm®-based microcontrollers.
Note: Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.
AN5411
General information
AN5411 - Rev 2
page 2/33
AN5411
Overview

2 Overview

The FUOTA application in I-CUBE-LRWAN is compliant with the LoRa Alliance® specification protocol (LoRaWAN version V1.0.3) [1].
The FUOTA feature is implemented in the application layer, and is based on and compliant with the specific functionalities defined by the LoRA Alliance. These functionalities allow a multicast group (Remote Multicast Setup Spec V1.0.0 [4]) to be set up, to fragment and to send data packets (Fragmented Data Block Transport Specification v1.0.0 [3]) and finally to synchronize clocks (LoRaWAN Application Layer Clock Synchronization Specification v1.0.0 [5]) so that all devices can agree on the start of a FUOTA session.
Note: Throughout this application note, the IAR™ EWARM IDE is used as an example to provide guidelines for project
configuration.

2.1 Application supports

The firmware update over-the-air (FUOTA) application supports:
full firmware upgrade image (the entire firmware image is sent to the end-device)
only applicable in Class-C mode
only runs on STM32L476xx targets
third-party middleware, mdedTLS (open source code) for the cryptographic services.
2.2

Terms and acronyms

Table 1. Acronyms used in this document
Acronym Definition
ABP Activation by personalization
APDU Application protocol data unit
FUOTA Firmware update over the air
FW Firmware
HAL Hardware abstraction layer
LoRa Long-range radio technology
LoRaWAN LoRa, wide-area network
MAC Media access control
MCPS MAC common part sublayer
MLME MAC sublayer management entity
MPDU Mac protocol data unit
MSC Message sequence chart
OTA Over-the-air
PLME Physical sublayer management Entity
PPDU Physical protocol data unit
SBSFU Secure boot and secure firmware update
SFU Secure firmware update
TPDU Transport protocol data unit
SAP Service access point
AN5411 - Rev 2
page 3/33
Term Definition
Firmware image A binary image (executable0 run by end-device as user application
Firmware header Meta-data describing the firmware image to be installed.
mbedTLS mbedTLS implementation of the TLS and SSL protocols and the associated cryptographic algorithm.
“.sfb” file Binary file packing the firmware header and the firmware image.

2.3 References

Reference Document
[1] LoRa Alliance Specification Protocol (LoRaWAN version V1.0.3), March 2018
[2] IEEE Std 802.15.4TM - 2011. Low-Rate Wireless Personal Area Networks (LR-WPANs)
[3]
[4] LoRa Alliance Remote Multicast Setup over LoRaWAN Specification v1.0.0, September 2018 – [TS-005]
[5]
[6] AN5056 Integration Guide for the X-CUBE-SBSFU STM32Cube Expansion Package – application note
[7] UM2262 - Getting started with the X-CUBE-SBSFU STM32Cube Expansion Package – user manual
[8] UM2073 – STM32 LoRa Expansion Package for STM32 - user manual
AN5411
References
Table 2. Terms used in this document
Table 3. Document references
LoRa Alliance Fragmented Data Block Transport over LoRaWAN Specification v1.0.0, September 2018 – [TS-004]
LoRa Alliance Application layer clock synchronization over LoRaWAN Specification v1.0.0, September 2018 – [TS-003]
AN5411 - Rev 2
page 4/33
LoRa standard and FUOTA application feature

3 LoRa standard and FUOTA application feature

This section provides a general overview of the LoRa and LoRaWAN recommendations. It deals in particular with the LoRa end-device and the FUOTA feature, which are the core subjects of this application note.
The LoRa software expansion is compliant with the LoRa Alliance LoRaWAN specification protocol [1].

3.1 Network architecture

Figure 1 shows the components and their protocol relationships, allowing the implementation of the firmware-
over-the-air feature.
Figure 1. Network diagram
AN5411
Note: In the I-CUBE-LRWAN FUOTA package, the device management block is not implemented. The LoRa Alliance
technical FUOTA working group is working on a LoRaWAN Firmware Management Protocol Specification, which documents and defines this block. The proposed implementation in the FUOTA application is a proof of concept.

3.1.1 Client/server architecture

The end-device where the software or firmware is to be updated is referred to as the end node or client. The other part of the system is referred to as the cloud or server, and provides the new software or firmware ( Figure 2).
Figure 2. Client/server architecture example
AN5411 - Rev 2
page 5/33
AN5411
End-device classes

3.1.2 End-device architecture

An end-device consists of a host MCU that reads sensor data in order to transmit the sensor reading over the LoRa network by means of the LoRa radio module.
Data is encrypted by the host MCU and the radio packet is received by the gateway, which forwards it to the network server. The network server then sends data to the application server, which has the right key to decrypt the application data.

3.2 End-device classes

LoRaWAN [1] has several end-device classes to address the various needs of a wide range of applications.
The FUOTA application described in this application note is only 'Class-C enable'. In other words the FUOTA application is validated for network infrastructure supporting only Class-C mode.
Note: The end-device supports Class-B mode. Nevertheless it is only 'Class B capable'. To be 'Class B enable' it is
mandatory to proceed to a new integration and validation phase on a network infrastructure supporting Class-B mode for the FUOTA campaign.

3.2.1 Class definition

Bi-directional end devices - Class A - (all devices) see [1]
Bi-directional end-devices with scheduled receive slots - Class B – (Beacon) see [1]
Bi-directional end-devices with maximal receive slots - Class C – (Continuous)
Class-C mode is implemented to support FUOTA. Class-C end devices have almost continuously-open receive windows (RxC where the data blocks are received), and are only closed when transmitting (Tx) and receiving (Rx1, Rx2) in Class-A mode (Figure 3).
Figure 3. Tx/Rx timing diagram (Class C)
AN5411 - Rev 2
page 6/33

3.3 FUOTA - firmware update over the air

The FUOTA update process transfers a new software image (data file) from the server to the client, and updates the current software image (version N) running on the client with the new received software image (version N+1). Obstacles to successful completion of the FUOTA update process are:
Communication. The new firmware image must be sent from the server to the client. This challenge is performed through the application-layer protocols running over LoRaWAN, which provide remote-multicast setup, fragmented data-block transport, and application-layer clock-synchronization services. The LoRaWAN Mac layer provides Class-C mode to transmit the data file in unicast or multicast mode.
Firmware update. The client must migrate from the current to the new firmware image. This task is performed by the Update_Agent module. To succed, the Update_Agent module relies on the services provided by the SBSFU application.
Memory. The software architecture must be organized so that it can be executed when the update process completes. The solution must ensure the recovery of the new software version if there are installation issues. This task is handled by the SBSFU application.
Security. When a new firmware image is sent wirelessly from server to client, several security services must be assured, such as: authentication, confidentiality and integrity. This must be done either through the LoRaWAN protocol or by means of the SBSFU application security services.

3.4 Network protocol architectures

This section describes the end-to-end network protocol architecture (see Figure 4). The following protocol exchanges are used:
MAC protocol data unit exchanges (MPDU)
application protocol of an application data unit exchanges (APDU)
LoRaWAN protocol physical protocol data unit layer (PPDU).
AN5411
FUOTA - firmware update over the air
Figure 4. LoRa network protocols
AN5411 - Rev 2
page 7/33

3.4.1 Network layer

The LoRaWAN architecture is defined in terms of blocks called layers. As shown in Figure 5, each layer is responsible for one part of the standard and offers services to higher layers. An end-device is made up of :
a PHY, which embeds the radio frequency transceiver
the MAC sublayer that provides access to the physical channel
application layers that provide access to the LoRaWAN services protocol.
AN5411
Network protocol architectures
Figure 5. LoRaWAN layers
Upper layers (apps)
MAC

3.4.2 Physical layer (PHY)

The physical layer provides two services:
the PHY data service enables the Tx/Rx of physical protocol data units (PPDUs)
the PHY management service enables the personal-area network-information base (PIB) management.

3.4.3 MAC layer

The MAC layer provides two services:
The MAC data service enables transmission and reception of MAC protocol data units across the physical layer (MPDU)
The MAC sublayer management enables the PIB management.
Phy
Physical medium (air interface)
AN5411 - Rev 2
page 8/33

3.4.4 Application layer

The application layer provides several messaging packages running over the LoRaWAN protocol. Here, FUOTA scopes the following:
A clock synchronization package (port Number 202)
Synchronizes the end-device real-time clock to the network’s GPS
Makes all end devices of a multicast group to switch to Class C temporarily and synchronously.
A fragmented-data-block transport package (port Number201)
Sets up / reports / deletes fragmentation transport sessions
Several fragmentation sessions may be supported simultaneously by an end-device
Fragmentation can be used either over multicast or unicast
Reports the status of a fragmentation session.
A remote multicast setup package (port Number 200)
Remotely creates a multicast group security context inside a group of end devices
Reports the list of multicast contexts existing in the end-device
Remotely deletes a multicast security context.
Programs a Class-C multicast session
Programs a Class-B multicast session.
Firmware management package (port Number 203) - (proof-of-concept implementation only)
Queries/manages the firmware version running on an end-device (including availability of the firmware­update version)
Queries/manages the end-device hardware version
Manages the end-device reboot at a given time.
Update agent module
Interfaces a LoRaWAN stack block to an SBSFU block
Get and transmit the complete file (after recombination) to the secure firmware update (SFU) process of the SBSFU.
User application
Sensor/actuator processing – application use cases
Required to start a FUOTA session, with some user uplinks to open useful Rx windows for the packages described above.
AN5411

Network/end-device interworking

3.5
Network/end-device interworking
This section only shows the information flow between end-device and application server at the application-layer level during a FUOTA campaign. For a complete view and description of the end-device and network interactions, refer to the STM32 LoRa expansion package user manual [8].

3.5.1 Multicast and fragmentation set-up

Time synchronization
Before seting up a FUOTA session, the end-device must have synchronized its timing with the network using either AppTimeReq or DeviceTimeReq as shown in Figure 6.
AN5411 - Rev 2
page 9/33
Network/end-device interworking
Figure 6. Message sequence chart for device timing
AN5411
Note: For the purposes of this presentation, the TimeReq sent by the MSC is divided into DeviceTimeReq and
AppTimeReq parts. The LoRaWAN specification allows a MAC command to be piggybacked in an application payload. In the current implementation DeviceTimeReq is piggybacked in the AppTimeReq payload.
Multicast, fragmentation setup and session creation (Class C only)
In order to receive a data block at the application level, it is necessary to have some exchanges between the network application layer and the end-device application layer. These exchanges are mainly to define: a Multicast Group ID, the fragmentation parameters (frag number and frag size), and the multicast Class C session (start time and end time).
AN5411 - Rev 2
page 10/33
Network/end-device interworking
Figure 7. Message sequence chart for Class-C creation
AN5411
Fragment broadcasting and secure FW update process
As soon as the end-device is synchronized (Class C), it opens its Rx window in order to receive the data fragments [3]. It stays in this state until all the data fragments are recieved.
When the complete data block (see the note below) is received, the end-device closes its Rx windows, and if everything is OK from the 'data-block transfer' point-of-view, the end-device calls the UpdateAgent to start the secure firmware update (SFU) process.
AN5411 - Rev 2
page 11/33
Network/end-device interworking
Figure 8. Message sequence chart for data block broadcasting
AN5411
End device
App layer
Device Waiting for Class C or Class B session
Device Sync / Rx Wind ON
MCPS.Ind(Frag #1)
MCPS.Ind(Frag #2)
…………
MCPS.Ind(Frag #n- 1)
MCPS.Ind(Frag #n)
Add proprietary user protocol when the data block has been fully reconstructed
Data block transferred / Rx wind OFF
End Device
End device
MAC layer
Frag #1 (201)
Frag #2 (201)
…………
Frag #n- 1 (201)
Frag #n (201)
Network
MAC layer
Network
App layer
MCPS.Req(Frag #1)
MCPS.Req(Frag #2)
………………..
MCPS.Req(Frag #n- 1)
MCPS.Req(Frag #n)
App server
Data fragments broadcasted
When the complete Data block has been received, Starts the update agent.
Note: Additional user 'proprietary' protocol statement:
The V1.0 package, and particularly Fragmented Data Transport TS-004, does not provide a way to inform the server that all data blocks have been properly received in order to rebuild the current download file. This is the case in the currently proposed implementation. The server always sends all the fragments (uncoded and coded), even if the current download file has been rebuilt before the end of the complete broadcast fragmentation transaction.
If needed, the user is responsible for implementing a 'proprietary' protocol to avoid such behavior.
For instance, when all the required fragments have been received and the current download file rebuilt, a simple crc32 can be computed and sent back to the server. The server should decide to stop broadcasting the remaining fragments.
This approach requires cooperation between the device maker and the network operator in order to define the 'proprietary' part of the protocol.
AN5411 - Rev 2
page 12/33

4 SBSFU/end-device manager relationship

4.1 Secure boot (SB)

The secure boot loader (SB) is software that permanently resides in the microcontroller's read-only memory. Secure boot checks the integrity and authenticity of the user application that is executed.
Secure boot executes every time a reset occurs and checks if there is a new firmware update process to complete.

4.2 Secure firmware update (SFU)

Secure firmware update provides a secure implementation of in-field firmware updates, enabling secure download of a new firmware image either through UART or firmware update to the end-device. Two firmware update scenarios are possible:
No new firmware to install: There is no firmware update process to complete, and secure boot (SB) does some signature verifications and branches to the current active firmware - the (Slot#0) user application.
New firmware to install: The firmware update process has to be completed. Secure boot (SB) transfers control to secure firmware update (SFU), which contains the firmware-update related software. SFU does the firmware update in Slot#1 and does a firmware swap processing from Slot#1 to Slot#0, and transfers control to secure boot. Secure boot checks if there is an firmware update to complete, and branches to the new firmware in Slot0#.
AN5411
SBSFU/end-device manager relationship
Figure 9. Boot flow with SBSFU and SBSFU memory map
AN5411 - Rev 2
page 13/33

4.3 Security

Security is ensured either through the LoRaWAN protocol, or by means of SBSFU application security services.
During a Multicast session, all the end-devices share the same session keys. There is a potential risk when one of the devices becomes compromised, as an attacker can initiate a multicast session with rogue firmware. To counter this, the SBSFU can add a layer of security by using an asymmetric cryptography scheme. When a firmware update is generated, the update is signed (TAG) with a private key by means of the PrepareImage SBSFU tool [7]. When the end-device receives the firmware update, it verifies the signatures against the file received and the public key held in the 'secure core' part of the end-device.
AN5411
Security
Figure 10. Signed firmware image
4.4

End-device memory

The firmware update over the air feature has a direct impact on the memory size (FLASH/RAM) of the end­device. The amount of memory needed depends on the maximum size of the firmware image, the technology used to manage the new firmware-update image, and also of the bootloader requirements. The current version proposes a full firmware-update feature.

4.5 Update agent

During the first step of the FUOTA update process - the transfer of the data block (firmware image) from the server to end-device, every time the end-device receives a fragment [3] coming from the server, it is stored in SRAM. When the entire data block (new firmware image) is received from the server (all fragments received and recombination done), it is transferred (written to Flash memory) by the UpdateAgent in the user workspace (Slot#1). After this, the UpdateAgent generates an NVICReset in order to transfer the control of the MCU to the secure boot loader.
Note: The full-caching mechanism approach allows the number of writes to Flash memory to be reduced. However,
this places a limit on the size of the new firmware image being downloaded. Both the caching method and the firmware image size to update depend on the end-device SRAM size.
AN5411 - Rev 2
page 14/33

5 Design overview

This package offers a FUOTA LoRa project for STM32L476 microcontrollers. The FUOTA LoRa project is split into three sub-projects : SecoreBin, SBSFU and UserApps.
The middleware is provided in source-code format, and is compliant with the STM32Cube HAL driver.
AN5411
Design overview
Figure 11. Project file structure
5.1
5.2

LoRaWAN features

LoRaWAN L2 V1.0.3
Class A (baseline) / Class C (continuous) and Class B (beacon)
Application Layer V1
Clock synchronization, fragmentation data block, and remote multicast setup
LoRaWAN RP V1.0.3
Regional parameters

SBSFU features

5.2.1 Secure boot (root-of-trust services)

Activation and checking of the necessary security mechanisms on the STM32L476 platform, to protect critical operations and secret data from attack.
Checking the authentication and integrity of the user application before execution.
AN5411 - Rev 2
page 15/33

5.2.2 Secure firmware update (SFU)

Detection of the new (encrypted) firmware version to install:
from a local download service (via the Ymodem)
pre-downloaded OTA via the user application (LoRaWAN)
Firmware version management (check for unauthorized updates or unauthorized installation)
Secure firmware update:
firmware authentication and integrity check
firmware decryption (if encryption is activated)
firmware installation
On error occurrence during the new image installation, recovery of the new firmware image (rollback to the previous valid firmware version not supported)
Execution of new installed firmware (once authenticated and integrity checked).

5.2.3 Cryptography

The official X-CUBE-SBSFU Expansion Package for STM32Cube [7] is delivered with two different cryptographic middleware libraries, either X-CUBE-CRYPTOLIB, which requires an export control agreement, or mbedTLS cryptographic services delivered as open-source code. The I-CUBE-LRWAN FUOTA application package only provides the mbedTLS option.
To use X-CUBE-CRYPTOLIB, the user must download the official X-CUBE-SBSFU Expansion Package for STM32Cube, and replace mbedTLS with X-CUBE-CRYPTOLIB in the project. These two libraries are equivalent in terms of cryptographic services.
The I-CUBE-LRWAN FUOTA package is by default configured as: Asymmetric without encryption .
AN5411
SBSFU features
Features Asymmetric with AES encryption Asymmetric without encryption Symmetric (AES GCM)
Confidentiality AES CBC encryption (firmware binary) -
Integrity SHA256 (firmware header + firmware binary) -
Authentication
Cryptographic keys in end-device
SHA256 of the firmware header is ECDSA signed
SHA256 of the firmware binary stored in the firmware header
Private AES CBS key (secret) public ECDSA

5.2.4 SBSFU configuration

Cryptographic libraries
As specified in Section 5.2.3 Cryptography, the I-Cube-LRWAN FUOTA project project integrates the third-party middleware mbedTLS (open-source code).
Public ECDSA key
Figure 12. Cryptographic library file location
AES CBC encryption (firmware binary)
AES GCM tag ( firmware header and firmware binary)
Private AES GCM key (secret)
AN5411 - Rev 2
Cryptographic default scheme
By default, the project is configured without cryptography. In this case there is no firmware encryption, only authentication and integrity are ensured.
page 16/33
AN5411
SBSFU features
Figure 13. Default cryptographic file structure
SBSFU application features
Configuration possibilities are offered through option compilation switches. By default the project supports local loader, and all the security IPS are turned off to make debug easier.
Figure 14. File structure for SBFU application features
AN5411 - Rev 2
page 17/33

5.3 Firmware architecture

Figure 15 summarizes the firmware design and the components involved in an end -device supporting the FUOTA
features.
AN5411
Firmware architecture
Figure 15. Top-level firmware design
Secure Boot Root of TRust
User application
Firmware management
Update
Secure firmware loader
Safe firmware programming
agent
Mcast Frag
Clock
sync
LmHandler
LoRaWAN
Note: As stated in Section 3.1 Network architecture, the firmware management block is not implemented.
AN5411 - Rev 2
page 18/33
FUOTA middleware programming guidelines

6 FUOTA middleware programming guidelines

This section describes the LoRaMac handler APIs.

6.1 Middleware initialization

This function initializes the LoRaMac layer. It initializes the callback primitives of the MCPS and MLME services (see [8]) and the run-time initialization of the LoRaMac layers (active region, Tx parameters, and so on).
Table 4. LmHandlerInit description
Function Description
LmHandlerErrorStatus_t LmHandlerInit ( LmHandlerCallbacks_t *callbacks);
Note: All packages (clock synchronization, remote multicast setup and fragmentation data block transport) are
mounted and activated by default within the LoRAWAN stack by means of the following constant:
#define LORAWAN_DATA_DISTRIB_MGT 1
LoRaMac handler initialization.
AN5411
This constant is set within the Projects\NUCLEO­L476RG\Applications\LoRaWAN_FUOTA\LoRaWAN_End_Node\LoRaWAN\Target\lorawan_conf.h file.

6.2 LoRaMac process

This function processes the LoRaMac events and radio events.
Function Description
void LmHandlerProcess(void );

6.3 Package registering

This function registers the required packages (PACKAGE_ID_COMPLIANCE, PACKAGE_ID_CLOCK_SYNC, PACKAGE_ID_REMOTE_MCAST_SETUP, PACKAGE_ID_FRAGMENTATION).
Function Description
LmHandlerErrorStatus_t LmHandlerPackageRegister (uint8_t id, void *params );
Table 5. LmHandlerProcess description
LoRaMac process – this function has to be called in the main loop. When no operation is pending this function requests to enter Low-power mode.
Table 6. LmHandlerPackageRegister description
Perform registration of all the packages needed by the application. These packages are dedicated for: synchronization, fragmentation, multicast setup, and compliant test.
AN5411 - Rev 2
page 19/33

6.4 LoRaWAN middleware configuration

This function configures the LoRaMAC layers (such as active region, access following keys commissioning parameters).
Table 7. LmHandlerConfigure description
Function Description
LmHandlerErrorStatus_t LmHandlerConfigure (LmHandlerParams_t *handlerParams); LoRaMAC handler configuration.

6.5 Join a LoRa network

This function sends a Join request to a LoRa network in Class A.
Table 8. LmHandlerJoin description
Function Description
void LmHandlerJoin(ActivationType_t mode );
For OTAA mode, performs a JoinReq. For ABP devices, this is a pass-through function.
AN5411
LoRaWAN middleware configuration

6.6 Check the join status

This function checks whether the device is joined to the network.
Table 9. LmHandlerJoinStatus description
Function Description
LmHandlerFlagStatus_t LmHandlerJoinStatus( void );
Check the Join device status. LORAMAC_HANDLER_SET if joined, otherwise LORAMAC_HANDLER_RESET.

6.7 LoRaWAN class change

This function requests the MAC layer to change the LoRaWAN class of the device.
Table 10. LmHandlerRequestClass description
Function Description
LmHandlerErrorStatus_t LmHandlerRequestClass(DeviceClass_t newClass );

6.8 Check the LoRaMac handler state

This function checks the state of the LoRaMac handler.
Switch Class Request. Only switching from class A to class B/C or from class B/C to class A is allowed
AN5411 - Rev 2
Table 11. LmHandlerIsBusy description
Function Description
bool LmHandlerIsBusy(void); Indicates if the LoRaMac Handler is busy. Returns true or false.
page 20/33

6.9 Send an uplink frame

This function requests the MAC layer to send a Class A uplink frame.
Function Description
LmHandlerErrorStatus_t LmHandlerSend(LmHandlerAppData_t *appData, LmHandlerMsgTypes_t isTxConfirmed,TimerTime_t *nextTxIn, bool allowDelayedTx);
AN5411
Send an uplink frame
Table 12. LmHandlerSend description
Request a data appData to be sent with an indication of whether the Tx is TxConfirmed or TxUnConfirmed.
AN5411 - Rev 2
page 21/33

7 Getting started

7.1 FUOTA programing guide

This section describes how to generate a FUOTA application (referred to as a UserApp in the SBSFU literature). The developer must follow this flow description step-by-step.

7.2 Folder structure

A top-level view of the file structure is shown in Figure 16.
AN5411
Getting started
Figure 16. Project file structure

7.2.1 How to generate a FUOTA application

The following steps must be followed to generate a FUOTA application.
1. SECoreBin
This step is needed to create the SECoreBin engine binary including all the required 'trusted' code and keys. The binary is linked to the SBSFU code in step 2.
2. Secure boot and secure firmware update (SBSFU)
This step compiles the SBSFU source code implementing the state machine and protection configurations. It links the code with the SECoreBin engine binary, including the 'trusted' code. It also generates a file that includes symbols used by the user application to call the SE interface functions.
3. User Application (FUOTA)
This step generates the user application binary file (FUOTA) that is uploaded to the device by the SFU process (UserApp.sfb).
It generates a binary file concatening the SBSFU binary, the user application (FUOTA) in clear format with the corresponding FW header added (SBSFU_UserApp.bin).
Note: For each step (1, 2 and 3), open the respective sub-project: 2_images_SECoreBin (step 1), 2_images_SBSFU
(step 2), and end node (step 3) in the dedicated IDE folder. Then regenerate (make) the respective binary file. Each sub-project is configured (in the project options) in order to call the 'postbuild.bat' file when needed.
See [7] for details on how to configure a complete SBSFU project.
AN5411 - Rev 2
page 22/33
Figure 17. Application generations steps
AN5411
Folder structure

7.2.2 How to generate a data block (new firmware update)

To generate a new piece of firmware (N+1) to be downloaded over-the-air to allow the old current firmware (N) to be updated, the I-CUBE-LRWAN package is delivered with the 'prepareimage' firmware image tool.
This tool comes from the original X-CUBE-SBSFU STM32Cube Expansion Package. For a complete and detailed description of this tool, see [7] (Appendix E).
'Prepareimage' flow:
Even if only the full-firmware update feature is supported, the diff option of the prepareimage tool should nevertheless be systematically applied. In the best case, code modification is located in adjacent sections, and the diff may generate a useful UserApp_To_Download.bin file. In the worst case, the diff result is not relevant and the UserApp_To_Download.bin file is the same as User_app.bin.
1. Generate the 'To_Download' image
python prepareimage.py diff -1 UserApp_v1.bin -2 UserApp_v2.bin UserApp_To_Download.bin -a 16 --poffset UserApp_To_Download.offset
2. Generate the clear complete firmware tag (SHA256 of the clear FW)
python prepareimage.py sha256 UserApp_v2.bin UserApp_v2.sign
3. Generate the clear 'To_Download' firmware tag (SHA256 of the clear FW)
python prepareimage.py sha256 UserApp_To_Download.bin UserApp_Download.sign
4. Generate the .sfb fimware metadata (header) and the 'To_Download' binary
python prepareimage.py pack -k ECCKEY.txt -r 44 -p 1 -v 2 -f UserApp_v2.bin
-t UserApp_v2.sign --pfw UserApp_To_Download.bin --ptag UserApp_To_Download.sign
--poffset UserApp_To_Download.offset UserApp_To_Download.sfb
Note: X-CUBE-SBSFU firmware image tool preparation readme.txt is in
<project>Middlewares\ST\STM32_Secure_Engine\Utilities\KeysAndImages folder.
AN5411 - Rev 2
page 23/33
Figure 18. File generation flow
AN5411
Folder structure
‘To_Download’ image
generation
Generate ‘Clear complete’ firmware tag
Generate Clear ‘To_Download’
fimware tag
Generate the “.sfb” firmware:
metadata (header) +
encrypted ‘To_Download’ binary
Ymodem download

7.2.3 How to download the data block (full firmware) to the end-device

There are two ways to download the firmware:
a local download via UART virtual COM using Ymodem protocol
remote download via over-the-air mechanisms proposed by the LoRaWAN protocol.
The Ymodem protocol should be used during the development phase, whereas the LoRaWAN protocol is a main feature of the product. It is up to the user to choose the right approach.
For a complete description of Ymodem usage see [7].
LoRaWAN download

7.2.4 How to create and manage a FUOTA campaign

This section does not aim to define, or show how to create, a FUOTA campaign on an application server. These aspects of a FUOTA campaign depend on the services provided by the network operator. Hence, here only the salient points relating to FUOTA campaign support are outlined.
The application server must:
support the following packages:
the synchro package (TS-003) [5]
the fragmentation package (TS-004) [3]
the MulticastSetup package (TS-005) [4]
support Class-C mode, as defined in the LoRaWAN specification V1.0.3 [1]
be compliant with the 'interop test' proposed by the FUOTA working group of the LoRa Alliance
have the capability to manage the data block (firmware image) to be downloaded.
'Interop test' is the minimum test proving that the end-device is able to receive a data block file from the server. This minimum test is shown in Section 3.5 Network/end-device interworking.

7.2.5 How to debug the end-node application

The complete system consists of a secure boot and an end-node application. When the target resets, the secure boot starts first. After some secure-boot checking the system jumps to the entry point of the end-node application. Since the end-node application is linked to the secure boot, the end-node application (UserApp.bin) cannot be downloaded directly with the debugger. In order to debug the end-node application, the following flow must be respected:
1. Flash the target with the complete system (SBSFU_UserApp.bin) using the ST Link tools.
2. Once the target is Flashed, the sub-project can be attached to the running target. Debug (with breakpoints, watch variables, and so on).
AN5411 - Rev 2
page 24/33
AN5411

Software description

3. Modifications can now only be done on the end-node application. There are two ways to reload the target with the new binary:
a. Reload the complete system (SBSFU_UserApp.bin) as described in (step 1), and attach to the target
(step 2)
b. Load the end-node application only (UserApp.sfb) via the YModem. When the target is running, attach
as described in Step 2.
For further details on how to debug an application running on SBSFU, see [8].
7.3
Software description
When the I-CUBE-LRWAN delivery is unzipped, the package has the following structure.
Figure 19. I-CUBE-LRWAN project structure
AN5411 - Rev 2
The I-CUBE-LRWAN package contains a FUOTA project. The FUOTA project is made up of three sub­projects: SECoreBin, SBSFU and LoRaWAN_End_Node. Each sub-project has a dedicated IDE folder (IAR IDE environment) containing the Lora.eww file to activate in order to start the IAR IDE debugger.
page 25/33

7.3.1 Compilation switches

7.3.1.1 Crypto switches
SE_CoreBin instantiates the crypto scheme selected with SECBOOT_CRYPTO_SCHEME.
Symbols Description Default state
SECBOOT_ECCDSA_WITHOUT_ENCRYPT_SHA256
SECBOOT_ECCDSA_WITH_AES128_CBC_SHA25
SECBOOT_AES128_GCM_AES128_GCM_AES128_GCM
7.3.1.2 Security switch
SBSFU instantiates the security item selected through SECBOOT_DISABLE_SECURITY_IPS. When this symbol is defined, all IP security protections are disabled (WRP, RDP, IWDG, DAP, and so on). See [8]
Table 13. Crypto switch descriptions
No FW encryption, only authentication and integrity are ensured.
Authentication, integrity, and confidentiality are ensured.
Authentication, integrity, and confidentiality are ensured.
AN5411
Software description
Enabled
Disabled
Disabled
Symbols Description Default state
SECBOOT_DISABLE_SECURITY_IPS Disables all security IPs simultaneously when activated. Enabled.
7.3.1.3 Debug switch
In \Projects\NUCLEO-L476RG\Applications\LoRaWAN_FUOTA\LoRaWAN_End_Node\Core\Inc\sys_conf.h
Debug mode can be enabled by setting the constant DEBUGGER_ON to 1
Lower Power mode can be enabled by setting the constant LOW_POWER_DISABLE to 0
7.3.1.4 Sensor switches
When no sensor expansion board is plugged into the setup, the constant SENSOR_ENABLED is set to 0 in
\Projects\NUCLEO-L476RG\Applications\LoRaWAN_FUOTA\LoRaWAN_End_Node\Core\Inc\sys_conf.h
7.3.1.5 Switch options
Table 15 summarizes the main application configuration options.
Functon Switch option Definition Where
STATIC_DEVICE_EUI Static or dynamic end-device identify. se-identity.h
LoRa stack
Debug DEBUGGER ON Enable MCU debug mode in Sleep, Stop and Standby modes. sys_conf.h
Sensor SENSOR_ENABLED
Power LOW_POWER_DISABLE Disabled low power. sys_conf.h
STATIC_DEVICE_ADDRESS Static or dynamic end-device address. se-identity.h
ACTIVE_REGION
Table 14. Security switch description
Table 15. Switch options
Enable the band selection. By default it is LORAMAC_REGION_EU868
Enable the call to the sensor board. It is up to the user to implement the function call to the relevant sensor.
lora_app.h
sys_conf.h
AN5411 - Rev 2
page 26/33

8 Memory footprint

8.1 End-node application

Values given in Table 16 are measured for the following IAR (EWARM Compiler 8.32) configuration
optimization: optimized for size level 3
debug option: off
trace option: off
expansion board: / SX1276MB1MAS
Table 16. End-node application memory footprint figures
Item Flash (bytes) RAM (bytes) Description
Application (user)
+LoRaWAN ClassA/C
+App Layer ClockSync
+App Layer Fragmentation
+App Layer RemoteMCast
+ LmHandler
+ FragDecoder
+ Remainder
Total
TBD
14653
806
1048
1609
2140
1484
8620
60664
76908
AN5411
Memory footprint
Memory footprint for the overall application (App_user + LoRa ClassA + LoRa stack)
The RAM caching memory to receive the data block is 67 Kbytes
Total:
60644 + 7981 (Lib) = 68625 bytes

8.2 SBSFU

Item Flash (bytes) RAM (bytes)
SE_Core.bin
Part of SFU
MbedTLS imposes a 4 Kbyte stack
Table 17. SBSFU memory footprint figures
22536
27405
5776
6709
Total:
22536 + 33181 = 55717 bytes
AN5411 - Rev 2
page 27/33

Revision history

Date Revision Changes
04-Nov-2019 1 Initial version.
22-Mar-2021 2
AN5411
Table 18. Document revision history
Updated:
Note in Section 3.1 Network architecture
User application information in Section 3.4.4 Application layer.
Section 4.2 Secure firmware update (SFU). Merged with old 'Section
4.2.1: Device update scenario' and updated content)
Section 5.1 LoRaWAN features
Table 4. LmHandlerInit description
Table 7. LmHandlerConfigure description
Table 8. LmHandlerJoin description
Table 12. LmHandlerSend description
Section 7.3.1.3 Debug switch
Section 7.3.1.4 Sensor switches
Table 15. Switch options
Table 16. End-node application memory footprint figures
Table 17. SBSFU memory footprint figures.
AN5411 - Rev 2
page 28/33
AN5411

Contents

Contents
1 General information ...............................................................2
2 Overview ..........................................................................3
2.1 Application supports ............................................................3
2.2 Terms and acronyms ...........................................................3
2.3 References....................................................................4
3 LoRa standard and FUOTA application feature .....................................5
3.1 Network architecture............................................................5
3.1.1 Client/server architecture ..................................................5
3.1.2 End-device architecture ...................................................6
3.2 End-device classes .............................................................6
3.2.1 Class definition ..........................................................6
3.3 FUOTA - firmware update over the air .............................................7
3.4 Network protocol architectures ...................................................7
3.4.1 Network layer ...........................................................8
3.4.2 Physical layer (PHY) ......................................................8
3.4.3 MAC layer ..............................................................8
3.4.4 Application layer .........................................................9
3.5 Network/end-device interworking .................................................9
3.5.1 Multicast and fragmentation set-up ...........................................9
4 SBSFU/end-device manager relationship..........................................13
4.1 Secure boot (SB)..............................................................13
4.2 Secure firmware update (SFU) ..................................................13
4.3 Security .....................................................................14
4.4 End-device memory ...........................................................14
4.5 Update agent .................................................................14
5 Design overview ..................................................................15
5.1 LoRaWAN features ............................................................15
5.2 SBSFU features ..............................................................15
5.2.1 Secure boot (root-of-trust services) .......................................15
5.2.2 Secure firmware update (SFU) ............................................16
AN5411 - Rev 2
page 29/33
AN5411
Contents
5.2.3 Cryptography ..........................................................16
5.2.4 SBSFU configuration.....................................................16
5.3 Firmware architecture ..........................................................18
6 FUOTA middleware programming guidelines ......................................19
6.1 Middleware initialization ........................................................19
6.2 LoRaMac process .............................................................19
6.3 Package registering ...........................................................19
6.4 LoRaWAN middleware configuration .............................................20
6.5 Join a LoRa network ...........................................................20
6.6 Check the join status ..........................................................20
6.7 LoRaWAN class change........................................................20
6.8 Check the LoRaMac handler state ...............................................20
6.9 Send an uplink frame ..........................................................21
7 Getting started ...................................................................22
7.1 FUOTA programing guide ......................................................22
7.2 Folder structure ...............................................................22
7.2.1 How to generate a FUOTA application .......................................22
7.2.2 How to generate a data block (new firmware update) ............................23
7.2.3 How to download the data block (full firmware) to the end-device ...................24
7.2.4 How to create and manage a FUOTA campaign ................................24
7.2.5 How to debug the end-node application ....................................24
7.3 Software description ...........................................................25
7.3.1 Compilation switches ....................................................26
8 Memory footprint .................................................................27
8.1 End-node application ..........................................................27
8.2 SBSFU ......................................................................27
Revision history .......................................................................28
Contents ..............................................................................29
List of tables ..........................................................................31
List of figures..........................................................................32
AN5411 - Rev 2
page 30/33
AN5411

List of tables

List of tables
Table 1. Acronyms used in this document .........................................................3
Table 2. Terms used in this document ............................................................4
Table 3. Document references ................................................................. 4
Table 4. LmHandlerInit description .............................................................19
Table 5. LmHandlerProcess description ......................................................... 19
Table 6. LmHandlerPackageRegister description ................................................... 19
Table 7. LmHandlerConfigure description ........................................................ 20
Table 8. LmHandlerJoin description ............................................................20
Table 9. LmHandlerJoinStatus description ........................................................ 20
Table 10. LmHandlerRequestClass description ..................................................... 20
Table 11. LmHandlerIsBusy description .......................................................... 20
Table 12. LmHandlerSend description ........................................................... 21
Table 13. Crypto switch descriptions............................................................. 26
Table 14. Security switch description ............................................................ 26
Table 15. Switch options ..................................................................... 26
Table 16. End-node application memory footprint figures............................................... 27
Table 17. SBSFU memory footprint figures ........................................................ 27
Table 18. Document revision history ............................................................. 28
AN5411 - Rev 2
page 31/33
AN5411

List of figures

List of figures
Figure 1. Network diagram...................................................................5
Figure 2. Client/server architecture example ......................................................5
Figure 3. Tx/Rx timing diagram (Class C) ........................................................6
Figure 4. LoRa network protocols .............................................................. 7
Figure 5. LoRaWAN layers ..................................................................8
Figure 6. Message sequence chart for device timing................................................ 10
Figure 7. Message sequence chart for Class-C creation ............................................. 11
Figure 8. Message sequence chart for data block broadcasting ........................................ 12
Figure 9. Boot flow with SBSFU and SBSFU memory map ........................................... 13
Figure 10. Signed firmware image ............................................................. 14
Figure 11. Project file structure ............................................................... 15
Figure 12. Cryptographic library file location ...................................................... 16
Figure 13. Default cryptographic file structure ..................................................... 17
Figure 14. File structure for SBFU application features ............................................... 17
Figure 15. Top-level firmware design............................................................18
Figure 16. Project file structure ............................................................... 22
Figure 17. Application generations steps ......................................................... 23
Figure 18. File generation flow ................................................................24
Figure 19. I-CUBE-LRWAN project structure ...................................................... 25
AN5411 - Rev 2
page 32/33
AN5411
IMPORTANT NOTICE – PLEASE READ CAREFULLY
STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.
Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of Purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein.
Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.
ST and the ST logo are trademarks of ST. For additional information about ST trademarks, please refer to www.st.com/trademarks. All other product or service names are the property of their respective owners.
Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
© 2021 STMicroelectronics – All rights reserved
AN5411 - Rev 2
page 33/33
Loading...