11 Firmware and OTA Updates
This section documents how to enable firmware updates in the design, whether it is serial or Over The Air (OTA)
11.1 Device Firmware Upgrade Over Bluetooth Low Energy
Introduction
One of the highly important features of wirelessly connected devices is the capability of Over-The-Air Device Firmware Update (OTA DFU). The end-users increasingly demand this functionality to:
-
Address issues and security vulnerabilities.
-
Ship products to market faster and have the option of delaying lower priority features and rolling them out to devices in the field.
The PIC32CX-BZ6 and PIC32WM-BZ6/PIC32-BZ6 family of devices supports OTA upgrade through Bluetooth® Low Energy (Bluetooth® LE).
- The OTA DFU updates program flash memory but does not include Device Configuration register. The users can check Device Configuration register in the “System” section of the MCC project graph.
- After performing OTA DFU and using MPLAB® IDE or IPE to program the devices, the programmed firmware cannot run. It is a known issue. Program the firmware once again (totally twice) to fix the issue.
Secure BLE OTA DFU Process
With the increasing popularity of OTA DFU capability in IoT devices, these devices are getting exposed to vulnerabilities and security threats. Therefore, it is important to ensure that the device’s OTA DFU process is secure and reliable. To send an upgradable image reliably and securely, sign and encrypt the image.
- Upload the Bluetooth LE OTA DFU file (firmware image encrypted, signed) to the OTAU manager. OTAU manager can be a smartphone or any Bluetooth LE device that supports OTA client.
- The OTAU target (such as the PIC32CX-BZ6 and PIC32WM-BZ6/PIC32-BZ6 device) queries the OTAU manager and fetches the new firmware image.
- The device then decrypts, validates, and applies the image.

11.1.1 Bluetooth Low Energy OTA DFU Firmware Architecture
The following figure illustrates the Bluetooth® LE OTA DFU firmware architecture of the PIC32CX-BZ6.
MCHP OTA Profile and Service Middleware
- Defines and handles the Microchip-defined Bluetooth LE GATT server and profile for getting the upgradable image over a Bluetooth LE link.
- Implements OTA state management and error handling.
- Implements defragmentation and decryption of the received new image.
DFU Middleware
- DFU APIs for writing the OTA image into embedded Flash.
- This module provides DFU capabilities common across the different supported transport mediums like UART and Bluetooth LE.
OTA Event Handling
- OTA events from “MCHP OTA Profile and Service” middleware is sent to application for DFU permission. For more details, refer to the BLE_OTA from Related Links.
OTA DFU Encryption Key Management
- Trigger new Flash image authentication by calling bootloader API.
- Timeout handling in case of failure/error while receiving the image.
Bootloader
- Bootloader is responsible for
authentication and activation of new firmware, booting into the application,
optionally entering into Serial DFU mode to get new image over serial
interface. For more details, refer to the PIC32CX-BZ2 Standalone
Bootloader Component Help section of the MPLAB Harmony PIC32CX-BZ
System Services in the Reference Documentation from Related
Links.Note: Bootloader code is running from boot ROM in the PIC32CX-BZ6 and PIC32WM-BZ6 family of devices.
11.1.2 Memory Management
The PIC32CX-BZ6 and PIC32WM-BZ6/PIC32-BZ6 family of devices has enough embedded Flash memory to hold the new upgradable OTA image until the new image is authenticated. The device receives the image in blocks over the Bluetooth® LE link. If the image is encrypted, the device decrypts it and stores it in embedded Flash slot 1. Once the device receives the complete image, it validates the image’s signature. Then, a device reset triggers the bootloader in the boot Flash region to load the image from slot 1 to slot 0. The new firmware then starts executing.
11.1.3 Microchip Defined Bluetooth Low Energy OTA DFU Profile
The Bluetooth® Low Energy (Bluetooth® LE) OTA
DFU profile is a GATT based profile. It is designed to perform DFU OTA. In general, the
mobile performs the OTAU client role and the Bluetooth LE device acts in the server
role. Microchip’s proprietary service, the OTAU service, uses a 16-byte service UUID.
The device contains only one instance of the OTA service. The Bluetooth LE device
instantiates the OTA service as a primary service. Set the service Universally Unique
Identifier (UUID) value to 4D434850-253D-46B3-9923-E61B8E8215D7
.
Characteristic Name | Universally Unique Identifier (UUID) | Properties | Permissions |
---|---|---|---|
OTA Feature | 4D434850-22E4-4246-AF03-0C4A2F906358 | Read | Encryption required |
OTA Data | 4D434850-34D9-40A6-BA7E-56F57C8CD478 | WriteWithoutResponse, Notify | Encryption required |
OTA Control Point | 4D434850-9327-45DE-8882-C97F39028A76 | Write | Encryption required |
- For more details on Bluetooth LE OTA profile, refer to the MPLAB® Harmony Wireless BLE in Reference Documentation from Related Links.
- For more details on Bluetooth LE OTA service, refer to the MPLAB® Harmony Wireless BLE in Reference Documentation from Related Links.
11.1.4 Bluetooth Low Energy OTA DFU Image File Definition
The Bluetooth® Low Energy (Bluetooth® LE) OTA DFU file contains the OTAU header and the upgradable Flash image. The OTAU manager (such as a smartphone or GATT client) loads this file and sends it to the OTAU target over the Bluetooth LE link. The following figure illustrates the Bluetooth LE OTA DFU image file definition.
- Flash Image: The flash image consists of a meta-data header and executable firmware. The system programs this complete image content into the device’s Flash slot 1.
- Meta-data Header: The Flash image contains a metadata header, metadata payload and metadata footer. These components provide the bootloader firmware with information such as the location of the firmware image, security decryption details, signature, sequence number and more. Digital signatures ensure the authenticity of the image and the integrity of the data. A digital signature also ensures that the data in the image remains unmodified (preserving integrity) and intact as it was generated at the source. Refer to Meta Data Header Format of the MPLAB Harmony Wireless BLE in the Reference Documentation from Related Links.
- OTAU File Encryption: The user can configure the system to encrypt the executable firmware. Encrypting the image ensures data confidentiality, preventing unauthorized parties from accessing the image’s contents. Only the end device can decrypt the image. The system uses the AES128-CBC encryption method. The system encrypts only the firmware image and does not encrypt the OTAU header.
- Bluetooth LE OTAU Header: The Bluetooth LE OTAU header contains OTAU file information for the Bluetooth LE OTA DFU client (for example, a mobile application) to perform OTA DFU procedures. The system does not send this header over-the-air to the OTAU target.
- Total Header length: 16 bytes
- Bluetooth LE OTAU header version
(HEADER_VER): 1 byte
- 0x01: PIC32CX-BZ6 and PIC32WM-BZ6/PIC32-BZ6
- Others: RFU
- Flash Image is encrypted or not (FLASH_IMG_ENC): 1 byte
- 0x00: Firmware image is not encrypted
- 0x01: Firmware image is encrypted by AES-CBC method
- Others: RFU
- Checksum: 2 bytes
- Contains the checksum value for the entire OTAU file.
- Flash image ID (FLASH_IMG_ID): 4 byte
- Identity number of Flash image.
- Flash image revision/version (FLASH_IMG_REV): 4 byte
- OTAU file type (FILE_TYPE): 1 byte
- 0x01: Bluetooth LE OTAU file
- 0x02: Bluetooth LE with Zigbee® combo OTAU file
- Others: RFU
- Reserved: 3 bytes
- OTA file is
.bin
file which can be generated from MPLAB X tools environment as illustrated below. The detail steps for image generation is explained later. - The following figure illustrates the
Bluetooth LE OTA header and encryption key configuration:
Figure 11-6. Bluetooth® LE OTA Header and Encryption Key Configuration in MPLAB X
- The following figure illustrates the meta-data header configuration:
Figure 11-7. Meta-data Header Configuration in MPLAB® X
11.1.5 Bluetooth Low Energy OTA DFU Image Distribution Procedure
- Encrypted and signed Bluetooth LE OTAU bin file generation using signature and OTA configurator from MPLAB X tools device properties.
- Store the generated OTAU file in the OTAU manager.
- Transfer the OTAU Flash image over Bluetooth LE OTA profile/service to OTAU target.
- The target device uses its AES key to decrypt the received image and stores it in embedded Flash slot 1.
- After the device receives the complete image, it resets. The bootloader authenticates the new image and, if valid, copies it from slot 1 to slot 0.
11.1.6 Bluetooth Low Energy OTA DFU Implementation
- The first five sections describe how to enable OTA DFU features in a general Bluetooth® LE application that serves as the OTAU target.
- The last two sections explain how to create the Bluetooth® LE OTA DFU file and how to use Microchip Bluetooth Data (MBD) as an OTAU manager to upgrade the OTAU target with the Bluetooth® LE OTA DFU file.
11.1.6.1 MCC Component and Code Generation
Prerequisites
- Open any Bluetooth® LE application based on MCC (example project/custom created project).
- Launch MPLABx Code Configurator (MCC).
Pull-in MCC Components
- From the Device Resources window, click + symbol next to BLE OTA
APP SERVICE. This action adds BLE OTA APP SERVICE component
to the project graph.
- After adding this component, the MCC automatically adds all required dependent components. Click Yes to accept dependencies when prompted.
Figure 11-10. Adding Bluetooth® LE OTA Application Service - The user can configure the BLE OTA APP SERVICE component according to the
requirement. The following steps are as follows:
- Disable Flash Image ID – This option checks for Image ID. If this option is enabled the upgradable image must have the same ID of current image, only then OTA upgrade procedure will happen. In the Project Properties tab, set the “Flash Image ID:” prefix to 0x9F and the remaining numbers should be above 0. For example, use 2.
- Enable Image Decryption – If the upgradable image is secured (encrypted using AES128 CBC), this configuration has to be enabled to do decryption of the received image. The AES key must match with the key in Bluetooth LE OTA DFU bin file generation configuration. Do not accept any dependencies after enabling the “Enable Image Decryption”. The user must ensure to click No to any dependency pop-ups at this point.
Figure 11-11. BLE OTA APP SERVICE Configuration Steps Note: Do not accept any crypto related dependencies after enabling the “Enable Image Decryption”. Click No to these dependency pop-ups if they are displayed.Figure 11-12. Components Auto-Activation Confirmation Pop-up
Verifying Configurations
-
BLE OTA profile and OTA Service Components - Enable Server Role. This module generates the code needed for MCHP defined BLE OTA profile and service.
- BLE_Stack component - DFU Module enable - This module generates the code
needed for device firmware upgrade middleware for writing the OTA image into
Embedded Flash.
- BLE_Stack component -
Advertising and Scan data payload is configured for manufacturer specific service
UUID and local name. BLE OTA Microchip Data (MBD) mobile app expects service UUID as
“0xDAFE” to filter the PIC32-BZ6.
- FreeRTOS stack size Set the
size to be 5120 bytes.
- App Timer Service component -
The BLE OTA procedure requires error handling and initializing the state in case of
failure in receiving the image. There are two software timers based on FreeRTOS
systick is used.
APP_TIMER_OTA_TIMEOUT
for error handling.APP_TIMER_OTA_REBOOT
for resetting the device after successful image reception. - RCON component - As mentioned
above
APP_TIMER_OTA_REBOOT
timer is used for resetting the device after successful image reception. Device reset is performed using SW reset in RCON module. - DIS BLE Service - Device Info
Service is BT SIG defined service. This service can be used to hold the firmware
version. When upgrading the Image, OTAU manager gets the current running image
version. OTA server in device can use firmware version from DIS and send to OTAU
manager. Using the FW from DIS is just optional. The “Firmware Revision” number will
be seen in the MBD app but it must match the “
FW_IMG_REV
” in the project properties in the “Header” section.If DIS is not needed for customer application, DIS component can be removed and the below code for sending firmware version must be modified. - FreeRTOS Total Heap Size - Set
the “Total Heap Size” to be 75,812.
Generating a Code
For more details on code generation, refer to MPLAB Code Configurator (MCC) Code Generation from Related Links.
Files and Routines Automatically Generated by MCC
After generating the code from MCC tool by clicking Generate button. The project folder structure is as follows:
11.1.6.2 OTA Application Development
Compile MCC auto generated project:
- Compile the MCC auto generated project as the following.
Addressing the mandatory error (if not already done): User action required in app_user_edits.c. Follow the steps mentioned in the note and do the necessary changes. Then comment the #error message as below.
Call BLE OTA Init function, DIS service Init function, and start advertising in
app.c
and add the include files.#include "app_ota/app_ota_handler.h" #include "ble_dis/ble_dis.h" APP_OTA_HDL_Init(); BLE_DIS_Add(); BLE_GAP_SetAdvEnable(0x01,0x00);
Call BLE OTA event handler function in
"app_ble/app_otaps_handler.c"
.APP_OTA_EvtHandler(p_event);
#include "../app_ota/app_ota_handler.h"
Uncomment timer message ID's in "app_timer/app_timer.c" needed for OTA error handling and reboot timer. When the timer is fired, the related message is posted in freeRTOS application task queue.
Define the timer message ID's in APP_MsgId_T structure in
app.h
.APP_TIMER_OTA_TIMEOUT_MSG,
APP_TIMER_OTA_REBOOT_MSG,
Call OTA timer handlers in APP_Tasks() in "app.c".
else if(p_appMsg->msgId == APP_TIMER_OTA_TIMEOUT_MSG)
{
APP_OTA_Timeout_Handler();
}
else if(p_appMsg->msgId== APP_TIMER_OTA_REBOOT_MSG)
{
APP_OTA_Reboot_Handler();
}
Call BLE gap connected/disconnected event handler in "app_ble/app_ble_handler.c" . app_ble_conn_handler.c handles the events and also restarts the Advertising when disconnected.
APP_BleGapConnEvtHandler(p_event);
#include "../app_ble_conn_handler.h"
-
Change "BLE_GAP_EVT_ENCRYPT_STATUS" to "GAP_STATUS_SUCCESS" in “
app_ble_conn_handler.c
”. - Compile the project for no errors.
API documentation reference:
OTA Profile Middleware API's - For more details, refer to the following path BLE Software > Wireless BLE > BLE Software Specification > BLE Memory Usage > BLE Memory Usage for PIC32CX-BZ6 on clicking MPLAB Harmony Wireless BLE.
11.1.6.3 Project Properties Configuration for Current/Running Firmware
MPLABX Tools environment allows to configure and append the Metadata header into application
image. The needed script and sample private key .pem
files are added
into project folder (.X
) when the OTA code was generated from MCC. For
example, the BLE sensor application contains the
java_friendly_private_key.pem
for BLE OTA header authentication
Right click on the project and select Properties.
- Adds Metadata header into application image.
Refer to Meta-data Header Configuration for more details on header format. There
are configurable parameters like Firmware Rev (version), authentication method and
manufacturer ID. Configure as per requirement.
-
Step1: “FW_IMG_REV” – Firmware version of current running firmware. This must be same as version in DIS service.
- Step2: “Auth Method” - There
are 3 Supported authenticated methods
-
Signature validation (ECDSA256-SHA256) – most secure, and data integrity check. Signature is encrypted using ECDSA private key. 256-bit ECDSA Public key to be programmed in device to do signature decryption. openssl (example commands: https://techdocs.akamai.com/iot-token-access-control/docs/generate-jwt-ecdsa-keys) is one of the open tools to generate ECDSA public/private key pair. Sample private key is available in project folder .X. Public key is input in Bootloader project.
-
Hash validation (SHA-256) – less security, and data integrity check.
-
No validation (None) – no security, no integrity check.
-
Warning:Ensure to keep "Sequence number" as non-zero value and not 0xFFFFFFFF.
-
After completing the above steps, click Apply, then OK to take the changes into effect.
11.1.6.4 Unified Image Generation
Compile the project for no errors.
MPLABX generated hex image will be available in project production folder dist\default\production. There are 3 new images created as an outcome of "SignFirmware" MPLABX script. These images are the valid images which has the metadata header appended.
signed.unified.hex - This is signed unified image along with bootloader. This is the current image to be programmed on the device.
-
signed.hex - This image is signed image without bootloader. This does not work if bootloader is not present on the device.
11.1.6.5 Programming the Current Application Image using MPLABX IDE
Build the project after completing all the above changes and program on Curiosity board:
Now the device (OTAU Target) is running the application with OTA capability, and able to be upgraded using OTAU manager like mobile phone.
11.1.6.6 Upgradable Image .bin
File Generation
This section explains how to generate the .bin
file for a general BLE
application. This section assumes that the ble_sensor application is the OTAU Target and
that the new upgradable .bin
file will also come from the ble_sensor
application.
- Assume that ble_sensor is the OTAU
Target and we wish to upgrade the firmware with a new ble_sensor application.
- Follow step 1 in Project Properties Configuration for Current/Running Firmware to open the “Header” section for the new project firmware.
- Change the AUTH_MTHD to “ECDSA p256+SHA256”.
- Change the
FW_IMG_REV
to the new firmware version. In this example, we will upgrade from 1.0.0.0 to 1.0.0.1. - Select the Private Key File that was generated by the OTAU Target project as
explained in “Project Properties Configuration for Current/Running
Firmware”. For more details refer to the Project Properties Configuration
for Current/Running Firmware from Related Links.
- Click Apply, then OK to apply the changes to the project properties and to close the window.
- Launch MCC on the new firmware project.
- Open the “Device Information Service” Configuration Options and change the
Firmware Revision to the same version that you put for
FW_IMG_REV
in the project properties. - Generate the code.
- Perform any application firmware updates for the new firmware revision. In
the case of ble_sensor, we will change the
BLE_SENSOR_VERSION
inapp.c
to the same version number as the DIS andFW_IMG_REV
. - Clean and Build the project.
- Reopen the project properties and open the OTA window.
- Set the AES key, Init Vector, and Flash Image ID as the same as configured
in step 1 of subsection “Pull-in MCC Components” in the section “MCC
Component and Code Generation”. Rename the OTA file.
- Select “Create OTA File” and the file will be generate in the
.X
folder:
- Set the AES key, Init Vector, and Flash Image ID as the same as configured
in step 1 of subsection “Pull-in MCC Components” in the section “MCC
Component and Code Generation”. Rename the OTA file.
11.1.7 BLE OTA DFU Demo
The following BLE OTA demo steps are common for any application implementing OTA functionality.
BLE sensor application is the sample project which implements OTA functionality as explained in
the above steps. The current image with OTA capability and new upgradable .bin
(ble_sensor_OTA.bin
) is also available in <Discover
Path>\apps\ble\advanced_applications\ble_sensor\precompiled_hex
for your
reference. This section assumes that the user has the ble_sensor
application programmed to a PIC32-BZ6 Curiosity Board as the
OTAU Target and are upgrading the firmware with a new firmware version of ble_sensor
which was generated in “Upgradable image .bin file generation”.
Hardware Requirement:
Tool | Qty |
PIC32-BZ6 Curiosity Board | 1 |
Micro USB cable | 1 |
Android/iOS Mobile | 1 |
Smartphone App: Microchip Bluetooth Data (MBD) iOS/Android app available in stores
-
Demo steps:
- To perform the OTAU, the
upgradable firmware bin file created in Upgradable Image
.bin
File Generation must be stored in the MBD app. Send the upgradable bin file to the mail. Refer to the following screenshots to store the image received on mail into MBD app.- iOS Mobile:
-
Android Mobile:
- Turn on mobile Bluetooth and
select “OTA DFU" tab of Microchip Bluetooth Data App on the mobile
device.
- Power On the OTA capable
target device ( PIC32CX-BZ6 and PIC32WM-BZ6/PIC32-BZ6 ) which was
programmed with
ble_sensor.X.production.signed.hex
from\apps\ble\advanced_applications\ble_sensor\precompiled_hex
. Device will be advertising. Click on "SCAN" button in mobile app and the device be visible in scanned list. - Click on intended device from
the scanned list. The mobile app will request to "Pair" with the device.
Select "Pair". Mobile app will now get connected with OTA Target device.
"Connected" message will appear for a short while.Note: After pairing with the device, you must forget the device in the Bluetooth settings of the mobile phone if you attempt to reconnect to the device using MBD on the same mobile device.
- Click the ‘Select Image’ option to choose the available firmware file.
- The OTAU firmware image file copied in the step 1 will be visible on screen.
Click on that image.
- After confirming the FW
version press OK button.
- Firmware update will be
initiated and the progress will be shown in mobile app. The process would
take few seconds.
- Once the complete image is
transferred, "OTA Update successfully" status will be shown in mobile app.
Click on "OK" and then device will perform authentication of the image. If
validation is successful, then system reboot automatically.
- On bootup, device does the authentication of new image in Slot1 and then copies the new image to Slot0. Now the new image will be running from Slot0.
- To verify whether the running
image on the target is newly upgraded image, follow steps 2 to 7 and check
the current version. Additionally, if you are testing ble_sensor application
and followed the steps in "Upgradable image .bin file generation" you will
be able to see the firmware update in a terminal emulator like TeraTerm when
the NMCLR button is pressed after the OTA DFU completion.
- To perform the OTAU, the
upgradable firmware bin file created in Upgradable Image