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

Microchip defined OTA profile and service enable firmware upgrades over the BLE link using Generic Attribute Profile (GATT). The Bluetooth LE OTA protocol defines the communication between the OTAU target and OTAU manager. A mobile device (iOS®/Android) or any Bluetooth LE device that implements the OTA GATT client protocol can serve as the OTAU manager to transfer the upgrade firmware to the OTAU target. The OTAU target implements the OTA GATT server protocol to receive the new firmware image.
Note:
  • 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.

Here are the basics of how an OTA DFU process works over a BLE link:
  1. 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.
  2. The OTAU target (such as the PIC32CX-BZ6 and PIC32WM-BZ6/PIC32-BZ6 device) queries the OTAU manager and fetches the new firmware image.
  3. The device then decrypts, validates, and applies the image.
Figure 11-1. Bluetooth® LE OTA DFU Process

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.

Figure 11-2. Bluetooth® LE OTA DFU Firmware Architecture

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.
Note: For more details on the MCHP OTA Profile and Service Middleware, refer to the Microchip Over the Air (OTA) Profile section of the MPLAB Harmony Wireless BLE in the Reference Documentation from Related Links.

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.
Note: For more details on the DFU Middleware, refer to the Device Firmware Update (DFU) section of the MPLAB Harmony Wireless BLE in the Reference Documentation from Related Links.

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.
Figure 11-3. Bluetooth® LE OTA DFU Firmware Architecture – H3 Code

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.

There are three characteristics defined under the service. The following table provides the details:
Table 11-1. OTA Service Characteristic Support Requirements
Characteristic NameUniversally Unique Identifier (UUID)PropertiesPermissions
OTA Feature4D434850-22E4-4246-AF03-0C4A2F906358ReadEncryption required
OTA Data4D434850-34D9-40A6-BA7E-56F57C8CD478WriteWithoutResponse, NotifyEncryption required
OTA Control Point4D434850-9327-45DE-8882-C97F39028A76WriteEncryption required
For more details on the OTAU service and profile, refer to the following documents:
  • 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.

Figure 11-4. 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.
Figure 11-5. Bluetooth® LE OTA DFU Image File Definition
  • 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

The following steps explain the Bluetooth® Low Energy (Bluetooth® LE) OTA DFU image distribution procedure:
  1. Encrypted and signed Bluetooth LE OTAU bin file generation using signature and OTA configurator from MPLAB X tools device properties.
  2. Store the generated OTAU file in the OTAU manager.
  3. Transfer the OTAU Flash image over Bluetooth LE OTA profile/service to OTAU target.
  4. The target device uses its AES key to decrypt the received image and stores it in embedded Flash slot 1.
  5. 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.
Figure 11-8. Bluetooth® LE OTA DFU Image Distribution Procedure

11.1.6 Bluetooth Low Energy OTA DFU Implementation

The following steps explain how to add the Bluetooth® Low Energy (Bluetooth® LE) OTA DFU functionality to a Microchip Bluetooth® LE application.
  1. The first five sections describe how to enable OTA DFU features in a general Bluetooth® LE application that serves as the OTAU target.
  2. 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
  1. Open any Bluetooth® LE application based on MCC (example project/custom created project).
  2. Launch MPLABx Code Configurator (MCC).
Figure 11-9. MPLABx Code Configurator
Pull-in MCC Components
To implement OTA DFU functionality using MCC, the user must follow these steps:
  1. 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.
    1. 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
  2. The user can configure the BLE OTA APP SERVICE component according to the requirement. The following steps are as follows:
    1. 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.
    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
All the required configurations are automatically done when the “BLE OTA APP SERVICE” component is added. Verify if the Project Graph window has all the expected MCC configurations.
Note: Depending on the application you are adding OTA DFU features to, your project graph may include other components, but the OTA DFU specific components and their configurations are listed below.
  1. BLE OTA profile and OTA Service Components - Enable Server Role. This module generates the code needed for MCHP defined BLE OTA profile and service.

  2. 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.
  3. 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.
  4. FreeRTOS stack size Set the size to be 5120 bytes.
  5. 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.
  6. 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.
  7. 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.
  8. 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

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

  2. 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);
  3. 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"
  4. 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.

  5. Define the timer message ID's in APP_MsgId_T structure in app.h.

    APP_TIMER_OTA_TIMEOUT_MSG,
    APP_TIMER_OTA_REBOOT_MSG,
  6. 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();
    }
  7. 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"
  8. Change "BLE_GAP_EVT_ENCRYPT_STATUS" to "GAP_STATUS_SUCCESS" in “app_ble_conn_handler.c”.
  9. Compile the project for no errors.
Note: Within the Project Properties, the .bin file can be generated by clicking the “Create OTA File” button.
The generated file will be located in the “[project_name].X” folder where the project was created.

API documentation reference:

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

Attention:
Note: Before proceeding to below steps, close the OTA application project and reopen the project. This step is mandatory for "SignFirmware" and "OTA" bin generation MPLABX script to be loaded into project environment.
  1. Right click on the project and select Properties.

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

  3. After completing the above steps, click Apply, then OK to take the changes into effect.

11.1.6.4 Unified Image Generation

  1. Compile the project for no errors.

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

    1. signed.unified.hex - This is signed unified image along with bootloader. This is the current image to be programmed on the device.

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

  1. Assume that ble_sensor is the OTAU Target and we wish to upgrade the firmware with a new ble_sensor application.
    1. Follow step 1 in Project Properties Configuration for Current/Running Firmware to open the “Header” section for the new project firmware.
    2. Change the AUTH_MTHD to “ECDSA p256+SHA256”.
    3. 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.
    4. 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.
    5. Click Apply, then OK to apply the changes to the project properties and to close the window.
    6. Launch MCC on the new firmware project.
    7. 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.
    8. Generate the code.
    9. Perform any application firmware updates for the new firmware revision. In the case of ble_sensor, we will change the BLE_SENSOR_VERSION in app.c to the same version number as the DIS and FW_IMG_REV.
    10. Clean and Build the project.
  2. Reopen the project properties and open the OTA window.
    1. 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.
    2. Select “Create OTA File” and the file will be generate in the .X folder:

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:

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

    2. Turn on mobile Bluetooth and select “OTA DFU" tab of Microchip Bluetooth Data App on the mobile device.
    3. 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.
    4. 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.
    5. Click the ‘Select Image’ option to choose the available firmware file.
    6. The OTAU firmware image file copied in the step 1 will be visible on screen. Click on that image.
    7. After confirming the FW version press OK button.
    8. Firmware update will be initiated and the progress will be shown in mobile app. The process would take few seconds.
    9. 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.
    10. 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.
    11. 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.