8 Firmware and OTA Updates

1. Open any BLE application based on MCC (Example project/ Custom created project).

2. Launch MPLABx Code Configurator (MCC).

Pull-in MCC Components

The following steps explain the components/configurations needed for OTA functionality alone.

Click “+” symbol “BLE OTA APP SERVICE” component from “Device Resources” of MCC to project graph. When the component is added, the dependent components also getting added automatically. Accept Dependencies or satisfiers, select “Yes” in order to add the dependent components.

1. Configure “BLE OTA APP SERVICE” component as the following, based on the need:

   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. Within the project properties, set the “Flash Image ID” prefix to 0x9F and the remaining numbers should be above 0, for example, use 2 as shown below.
   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 BLE OTA DFU bin file generation configuration as shown below. Do not accept any dependencies after the “Enable Image Decryption” is enabled. Select “No” to any dependency popups at this point.

   

Note: Do not accept any Crypto related dependencies after the “Enable Image Decryption” is enabled. Select “No” to these dependency popups if they are displayed.

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

For more details on code generation, refer to MPLAB Code Configurator (MCC) Code Generation from Related Links.

After generating the code from MCC tool by clicking Generate button. The project folder structure is as follows:

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:

• OTA Profile Middleware API's

• OTA Application level API's

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

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.

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.

      

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

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: