STM32WBA Bluetooth® LE – Firmware update over the air

1. Firmware update over the air profile

1.1. Overview

The firmware update over the air (FUOTA) service provides the possibility to receive a new application to be installed, while the current application is running. It requires to add the FUOTA service & characteristics to the current application.
​ The FUOTA application allows to:​

• download the new Bluetooth® LE application in a Free Area – Download slot​,
• update/download a new User Data file​,
• jump to the Application Install Manager​.
  

The Application Install Manager allows to:​

• replace the Bluetooth® LE application to be used after reboot​,
• download user data in any place in the CM33 user flash.​
  

GATT server memory mapping example

There are 4 regions with fixed size and address, not modified along the firmware update.

• One region (page 0 and page 1) that contains the Application Install Manager.
  • This region shall be at the boot address of the CPU out of power on.
  • The Application Install Manager is a full binary with its own vector table.​
• One region that contains the NVM and User Data.
  • The address is fixed and can be placed anywhere in the mapping.
  • It is possible to split the NVM from the User Data into several regions, at different location in the memory.​
• 1 Active Slot (from page 2) and 1 Download Slot:
  • They have same size and are placed anywhere in the memory.
  • The Active slot contains the Application (User + OTA) binary.
  • The Download slot is used only to store the application update to be applied.​
    
• The Keyword_User is used to ensure the firmware update has been fully received.
  • The Keyword_User is placed at the end of the binary. It shall be defined with a magic value (0x94448A29) that cannot be found anywhere else in the firmware.
  • A variable containing the address of the Keyword_User is placed just after the vector table, at a fixed address. This variable is initialized with the address of the Keyword_User. This address is defined at link time. The linker file can be used to ensure the Keyword_User is placed at the end of the binary.​
    

One advantage of this solution is that it does not need any post-script, in addition to the standard build process.
This mechanism only ensures that the expected amount of bytes is written in the flash. It does not protect against data that may not be properly written in the flash. ​

1.2. Implementation

The firmware update over the air (FUOTA) profile is intended to demonstrate the multiple capabilities of the STM32WBA Bluetooth^® LE solution. It acts as:

• GAP central & GATT server (Router service) device to be connected and controlled by an smartphone.
• GAP peripheral & GATT client device to control end device (P2P FUOTA Server, HR FUOTA Server).

The FUOTA service is a generic attribute profile (GATT) based on the low-energy profile defined by STMicroelectronics with proprietary UUIDs (128 bits) including three characteristics, described below.

The heart rate FUOTA and peer to peer FUOTA projects provided within the STM32CubeWBA MCU Package are described below.

Overall application diagram

The structure of the FUOTA service is described below:

Bluetooth® LE FUOTA service specification
Service Characteristic Mode UUID Size FUOTA service 0000FE20-cc7a-482a-984a-7f2ed5b3e58f Base Address Write without response 0000FE22-8e22-4541-9d4c-21edae82ed19 5 Confirmation Indicate 0000FE23-8e22-4541-9d4c-21edae82ed19 1 Raw Data Write without response 0000FE24-8e22-4541-9d4c-21edae82ed19 240

The FUOTA service is composed of three characteristics:

FUOTA service - Base address characteristic

Byte Index [0:7] [8:31] [32:39] Name Action Address Offset (MSB First) Nb sectors to erase (8K/Sector) Value 0x00: STOP All Upload 0x01: START User Data Upload 0x02: START Application File Upload 0x06: End Of File Transfer 0x07: File Upload Finish 0x08: Cancel Upload 128 bits aligned (4 lower bits equal to 0) Default: 0x080000 Min: 0x004000 Max: 0x0FEFF0 Default: 0x00 (Not used by application) Min: 0x01 Max: 0x3F (63 sectors)

The smartphone or web Bluetooth^® application uses this characteristic to:

• indicate the action to perform.
• provide the address where the new application is stored​ (8K bytes page offset).
• inform about the sectors to erase.​

FUOTA service - Confirmation characteristic
Byte Index 0 Name File Upload Indication Value 0x01: Reboot 0x02: Ready To Receive File 0x03: Error Not Free

The smartphone or web Bluetooth^® application uses this characteristic to inform about:

• Ready To Receive File: ready to receive the new binary application.​
• Reboot: the new file is fully received.​
• Error not free: not ready to receive a new binary application.

FUOTA Service - Raw data characteristic
Byte Index [0..239] Name Raw Data (LSB First) Value File Data

The smartphone or web Bluetooth^® application uses this characteristic to transfer the file.
Raw Data size is limited to 240 bytes, multiple of 16 bytes, the minimum flash writes access size.
240 bytes is the maximum size multiple of 16 bytes behind the negotiated maximum ATT MTU size 251 bytes.
Only size multiple of 16 bytes lower than 240 bytes are allowed.

1.3. Implementation example

Example of flow diagram between STM32WBAs & ST Bluetooth® LE Toolbox smartphone application.

1.4. Advertising data

At start up, application with FUOTA starts fast advertising (80ms/100ms).
Data advertised are composed as follows:

Heart rate FUOTA advertising packet
Description Length AD Type Value Device Name 6 0x09 HR_XX (XX: last byte of BD address) Service UUID 3 0x03 0x180D (HRS) Manufacturer Data 15 0xFF See table below Flags 2 0x01 0x06 (GeneralDiscoverable, BrEdrNotSupported)

Manufacturer data are encoded following STMicroelectronics BlueST SDK v2, as described below:

STMicroelectronics manufacturer advertising data
Byte Index 0 1 2-3 4 5 6 7 8 9 10-15 Function Length Manufacturer ID Company BlueST SDK Version Board ID Firmware ID Option 1 Option 2 Option 3 Device Address Value 0x0F 0xFF 0x0030 STMicro 0x02 0x8B Nucleo-WBA 0x89 - HR Sensor 0x00 0x00 0x01 - FUOTA 0x08E12Axxxx

2. Requirements

2.1. Software and Hardware requirements

For software and hardware requirements refer to STM32WBA Build BLE Project wiki page.

2.2. Collector applications compatibility

The STM32CubeWBA FUOTA projects (heart rate FUOTA and P2P FUOTA) are compatible with the following remote interfaces:

• ST BLE Sensor
• ST BLE Toolbox
• Web Bluetooth^® interface

3. STM32WBA FUOTA example description

3.1. Project directory

The FUOTA service embedded in BLE_HeartRate_ota and BLE_p2pServer_ota applications, as well as the Application Install Manager, are available by downloading STM32CubeWBA MCU Package. Refer to How to Build a Bluetooth® LE project wiki page for project directory information.

3.2. Project description

3.2.1. Structure

Software project structure with the most important parts:

Application Install Manager project structure

Heart rate FUOTA project structure
Main applicative part files Services management Bluetooth® Low Energy libraries Link Layer System integration files WARNING: Do not modify the files in Middlewares folder

3.2.2. Applications Role

3.2.2.1. Application Install Manager

Once the firmware update is fully received, the Application Install Manager installs it from the Download Slot to the Active Slot.
When there is no firmware update to be installed, it jumps on the reset vector of the application. It cannot be updated with FUOTA​.

3.2.2.2. User Application

This is a single binary implementing both the user and the FUOTA application.
The FUOTA application is responsible for downloading the firmware update in the Download slot.
This binary (including both the User and the FUOTA application) can be updated with FUOTA​.

3.2.2.3. Flow

FUOTA flow diagram between Application Install Manager and FUOTA user application

FUOTA Steps

Alternatively, it could be possible to run in parallel both the user service and the OTA service.
In that case, it is possible to download a new firmware update while the user service keeps running.
Once the firmware download is completed, the application reboots the device to install it.​
When the Standby Mode is set in the User FUOTA Application, to preserve RAM integrity of the User FUOTA Application, after each wake up reset from the Standby Mode, the User FUOTA Application must be run immediately with a minimum RAM use (skip of Application Install Manager tasks).

3.2.3. Application initialization

The different steps of the application initialization are described below:

FUOTA project initialization

Initializes the system (HAL, clocks, peripherals) Infinite loop for run mode Initializes the BSP, Power Mode, trace, memory manager, NVM Waits for initialization done Initializes the Bluetooth® LE Host Stack Initializes the Bluetooth® LE GATT level Initializes the Bluetooth® LE GAP level Resets the number of registered handler Initializes the context Manages FUOTA Service notifications Register Service Handler Updates services and characteristics

3.2.4. GAP and GATT initialization and interaction

FUOTA software module interaction

and The Bluetooth^® LE FUOTA application initialization is done within app_ble.c

• Initializes the Bluetooth® Low Energy stack - initializes the device as peripheral - configures and start advertising: ADV parameters, local name, UUID - APP_BLE_init()
• Calls the services controller initialization SVCCTL_Init() - svc_ctl.c
• Manages the GAP event - SVCCTL_App_Notification()
  • HCI_LE_CONNECTION_COMPLETE - provides information of the connection interval, slave latency, supervision timeout.
  • HCI_LE_CONNECTION_UPDATE_COMPLETE- provides the new information of the connection.
  • HCI_DISCONNECTION_COMPLETE - informs the application about the link disconnection and the reason.

The services management is done by the service controller, svc_ctl.c

• Initializes the number of registered handler - SVCCTL_SvcInit()
• Manages events - SVCCTL_UserEvtRx()- from the Bluetooth® Low Energy Host Stack and redirect them to the gap event handler - SVCCTL_App_Notification

The application level of the FUOTA is done with ota_app.c':

• Initialization of the services:
  • FUOTA service - OTA_Init() - ota.c
• Initialization of the context of the application
  • Erases the Download Slot
• Receives the notification from the FUOTA service - OTA_Notification()

The FUOTA service ota.c manages the specification of the service:

• Service Init - OTA_Init()
  • Register FUOTA event handle to service controller - SVCCTL_RegisterSvcHandler(OTA_EventHandler);
  • Initializes service UUID – add FUOTA as primary services
    • Initializes Base Address characteristic
    • Initializes Confirmation characteristic
    • Initializes Raw Data characteristic
• Manages the GATT event from Bluetooth^® LE Stack - OTA_EventHandler()'
  • ACI_GATT_WRITE_PERMIT_REQ_VSEVT_CODE
    • Reception of a Write Command: Raw Data characterictic value
      • Sends an aci_gatt_write_response() with an OK or KO status.
  • ACI_GATT_ATTRIBUTE_MODIFIED_VSEVT_CODE
    • Reception of an attribute modification - Confirmation characteristics description value : ENABLE or DISABLE Indication
      • Notifies the application of the confirmation indication - OTA_Notification(OTA_CONF_INDICATE_ENABLED_EVT/OTA_CONF_INDICATE_DISABLED_EVT)
    • Reception of an attribute modification - Base Address characteristics value
      • Notifies application of the Base Address modification- OTA_Notification(OTA_BASE_ADR_WRITE_NO_RESP_EVT)
    • Reception of an attribute modification - Raw Data characteristics value
      • Notifies application of the Raw Data Modification- OTA_Notification(OTA_RAW_DATA_WRITE_NO_RESP_EVT)

4. Collector applications

4.1. Android ST Bluetooth® LE Toolbox

Android ST Bluetooth® LE Toolbox – How to

Android ST Bluetooth® LE Toolbox – How to

4.2. Web Bluetooth^®

From the Web Bluetooth^® interface Home Page, click on Web Bluetooth^® STM32WBA to access the dedicated STM32WBA web application.
The documentation for the various ST Web Bluetooth^® applications is available at this same address.