12.1 Bootloader

Introduction

A bootloader is a small application that can be used to upgrade firmware on a target device without the need for an external programmer or debugger. For PIC32CXBZ2 standalone bootloader, it provides below functionalities:

Device Firmware Upgrade over Serial(UART) interface, this is also called DFU over Serial.
Provide functionality support for wireless Over The Air Update, which is also called OTAU.
Provide various approaches to verify and authenticate firmware if enabled.
Display Console message if enabled

PIC32CXBZ2 Standalone Bootloader Component

PIC32CXBZ2 bootloader is a standalone Harmony component used to configure bootloader code for PIC32CXBZ2 device. Click here to know about PIC32CXBZ2 standalone bootloader component, user can find more information as listed below:

Memory layout of PIC32CXBZ2 device
Boot memory information
Image metadata definition
Working of Bootloader
Flow diagram of Bootloader
Bootloader configuration options
Bootloader and DFU API usage

Bootloader Example Code

PIC32CX-BZ2/WB45 bootloader provided two methods to enter DFU mode, one is GPIO Trigger, another is Timber Based Trigger. Later section will have more detailed information about them.

For bootloader using GPIO Trigger method, user can find example code in wireless_apps_pic32cxbz2_wbz45\apps\bootloader\bootloader, and precompiled hex file at wireless_apps_pic32cxbz2_wbz45\apps\bootloader\bootloader\precompiled_hex\bootloader.X.production.hex

For bootloader using Timer Based Trigger method, user can find a precompiled hex file at wireless_apps_pic32cxbz2_wbz45\apps\bootloader\bootloader\precompiled_hex\bootloader_timer.X.production.hex. Since Timer Based Trigger bootloader creation is very similar to GPIO Trigger, there is no example code provided for it.

Creating Bootloader From Scratch Using MCC

This section explains the steps required by a user to configure and generate a PIC32CXBZ2 standalone bootloader from scratching using MCC. User can find the bootloader example code(GPIO Trigger) generated using MCC in the path wireless_apps_pic32cxbz2_wbz45\apps\bootloader\bootloader

Generated Bootloader example has the following configurations:

Enabled UART DFU
Enabled console to display messages
Enabled GPIO Trigger
Hardware requried is WBZ451 Curiosity Board, DFU mode is triggered by pressing SW2(GPIO PB4) on the board
Automatically reboot firmware after DFU is finished

WBZ451 Curiosity Board is the hardware required to run this bootloader example, the board top view is shown in figure-1.

Figure 12-1. WBZ451 Curiosity Board.
WBZ451 Curiosity Board Top View

Following are the steps to create the bootloader example(GPIO Trigger) from scratch.

Note: New users of MPLAB Code Configurator are recommended to go through the overview.

Create a new MCC Harmony Project -- link for instructions, selecting WBZ451 as Target Device.
After MCC is launched, in Device Resource window, expand Harmony – Wireless – Driver, select Bootloader and add the component. Accept all the dialog messages by clicking Yes on message prompt. This will resolve dependencies among components and add connection in the graph.

Figure 12-3. Confirmation for Components Auto-activiation.

3. In the project graph window, select Bootloader component to show its Configuration Options. In the Configuration Options, enable Bootloader UART DFU, verify it is GPIO Trigger mode and port PB4 is selected as GPIO trigger port. PB4 is chosen as it is connected to SW2 on WBZ451 Curiosity board. Then enable Console and leave ECC Public Key and Supported Authentication Methods to default.

Figure 12-5. Bootloader Options for GPIO Trigger

GPIO Trigger is the option to trigger DFU mode, where user needs to hold the GPIO button during reset to put the bootloader into DFU mode. Use GPIO Port and GPIO Pin option to change the port and pin based on user hardware.

Note: Other than GPIO Trigger, another trigger option Timer Based Trigger is also provided, where bootloader will be in DFU mode for amount of time before jumping to the user application. User can change the DFU Wait Time in Milliseconds to change the amount of time. By selecting Timer Based Trigger, a 32bit timer component TC0 is asked to be activated, click YES to accept adding TC0 and accept its connection. Following figures illustrate the Timer Based Trigger options and message prompt of adding TC0.

Figure 12-6. Bootloader Options for Timer Based Trigger.
Timer Based Trigger mode options

Figure 12-7. Comfirmation for Components Auto-activiation. Click YES to Activate TC0 Component

Note: For Supported Authentication Methods, 3 methods are provided: None, SHA256, and ECDSA256. Authentication methods with ECC Public Key are used to configure firmware authentication methods, including verifying firmware completion status and authenticating firmware vendor. For more details about these configurations, user can refer to here.

4. In the project graph window, selecting the Bootloader component, right click the dependency of UART, select SERCOM0 in the Satisfiers list. Then SERCOM0 component will be added into project graph.

Figure 12-8. Dependency of UART.
Select SERCOM0 in UART Satisfiers

Figure 12-9. Project Graph Window.
Select SERCOM0 to Configure

5. Select SERCOM0 component to open its Configuration Options, change Receive Pinout and Transmit Pinout according to WBZ451 Curiosity board. Leave other settings to default.

Figure 12-10. SERCOM0 Options.
Configure Receive Pinout and Transmit Pinout

6. Expand tree of Peripherals, select and add RCON component. Verify RCON options, just leaving it as default is okay.

Figure 12-11. Device Resources Window.
Harmony - Peripherals - RCON

Figure 12-12. Project Graph Window.
Select RCON to Check its Options

Note: RCON provides software reset function, adding RCON component is for enabling automatical firmware reboot after DFU completion.

7. Then press Generate to generate the code.

Figure 12-13. Generate Bootloader Code.
Press MCC Generate Button to Generate the Code

8. To make the Bootloader code be fit into 24KB boot memory of PIC32CXBZ2, manually find and replace ecc.c and crypt_ecc_pukcl.c with files provided in wireless_pic32cxbz_wbz\utilities\pic32cx-bz\tempBtl

9. To enable firmware auto reboot after DFU completion, it need host end to send a new command to bootloader. This new command is device Reset command defined to 0x12. To add this command definition, open file progexec.h, add code as below:

#define DEVICE_RESET_CMD 0x12

Figure 12-14. Code Change in File progexec.h.
Add RESET_CMD Definition

Then in file progexec.c, function program_exec_main(), add code to handle device Reset command, call RCON_SoftwareReset() to start software reset. Code added is shown in below figure.

Figure 12-15. Code Change in File progexec.c.
Add RESET_CMD Command Handler

Note: Firmware auto reboot also needs host end modification to send 0x12 command to reset device after DFU completion, so far only PC GUI tool(MicrochipUtilityTool.exe) is modified and supported it, Python scripts as another way have not been modified to support it.

10. On the IDE Tools bar, click Clean and Build Main Project to build the code, bootloader.X.production.hex file will be generated. User can also find precompiled hex files under folder wireless_apps_pic32cxbz2_wbz45\apps\bootloader\bootloader\precompiled_hex.

Figure 12-16. Build Bootloader Code.
Click **Clean and Build Main Project** to Build Code

While generated bootloader hex file should be added to user aplication as Loadable File, they shouldn't be used alone. Followings are talking about a few simple steps need to be handled at user application side.

Configure User Application to Use Bootloader

To use Bootloader with a user application, there are a few steps to be configured at user application project. These steps are common to any user application that wants to have Bootloader capability, these steps include:

Add Bootloader Services component onto user application project and generate code
Add Bootloader as Loadable File/Project to create unified image
Program unified image to device.

Add Bootloader Services Component and Generate Code

Open any user application project with MPLAB X IDE, click on MCC icon on Tools bar to launch MPLAB Code Configurator to open project graph.

In Device Resource window, expand Harmony – Wireless – Driver, select Bootloader Services component and add it. This component generates the supporting linker file and MPLABX script needed for adding metadata header into application image(Project Properties is added with SignFirmware settings). Use Firmware Signature Verification API in Bootloader is the only option in Bootloader Services component. For DFU via UART, it is not necessary to enable firmware signature and verification, although user can do so if needs. While for OTAU, user must enable firmware signature and verification, by clicking on check box to Use Firmware Signature Verification API in Bootloader.

(Following project graph is just an example, user may have different graph depending on their application.)

Figure 12-17. User Application Add Bootloader Services.
Add Bootloader Services and Configure

After Bootloader Services component is added and configured, press Generate button to generate the user application code. In the generated new code, some code about bootloader service is added, as well as project’s linker script file is also automatically changed to reflect bootloader functionality.

Figure 12-18. Generate User Application Code.
Press **Generate** button to Generate User Application Code

Also in the updated new project, SignFirmware setting is added into Project Properties. (if not see it, try close and open MPLABX to refresh the project.) It's strongly recommended to enable Authen Method as SHA256 or ECDSA256-SHA256 in SignFirmware setting. If user choose None, since there is no firmware integrity check, if any issue happens during image saving into slot1, as new image may not be complete, the firmware may become non-functional at next restart. So None option is not secure for firmware upgrade.

ECDSA256-SHA256: firmware signature validation and data integrity check.

SHA256: firmware data integrity check.

None: no security, no integrity check.

Figure 12-19. SignFirmware - Auth Method - ECDSA256-SHA256.
Firmware signature and integrity check

Figure 12-20. SignFirmware - Auth Method - SHA256.
Firmware integrity check

Note: Sequence Number cannot be 0x00000000 or 0xffffffff, which are invalid values.

Add Bootloader as Lodable File/Project to Create Unified Image

Once the new code is generated and configured, user need to add Bootloader as a loadable project/loadable hex file in the updated project. This enables MPLAB X IDE to merge both user application and bootloader and make an unified firmware by creating an unified image file.

To add Bootloader as loadable file, expand application project’s tree, right click Loadables, select Add Loadable File, then browse and add the bootloader hex file.

Figure 12-21. User Application Add Loadable File.
Right Click **Loadables** and Add Loadable File

Figure 12-22. Add Loadable File.
Select Bootloader Precompiled Hex File as Loadable File

To add bootloader as loadable project, expand application project’s tree, right click Loadables, select Add Loadable Project, then browse and add the bootloader project.

Figure 12-23. User Application Add Loadable Project.
Right Click **Loadables** and Add Loadable Project

Figure 12-24. Add Loadable Project.
Select Bootloader Project as Loadable Project

After Loadable File or Project is added, then on the IDE Tools bar, click Clean and Build Main Project icon to rebuild the project.

Figure 12-25. Build to Create Unified Image. Click **Clean and Build Main Project** to Create
Unified Image Merged Both User Application and Bootloader

After code is built, a few files is generated under path firmware\ble_sensor.X\dist\default\production. The file named as signed.unified.hex is the unified image merged with both user application and bootloader. By programing this unified image, user application will have bootloader capability. The file named as signed.bin file is the target binary image file that bootloader use for DFU. If user has any modifications on user application firmware, user can build and generate this binary file, then use bootloader to upgrade device to new image.

Program Unified Image

As mentioned above, user need to program device with unified image to make user application to have bootloader capability, to do this, on the IDE Tools bar, click Make and Program Device Main Project icon to program device, the unified image will be programmed into device.

Now the device with user application will have bootloader functionality, referring the guidance in Device Firmware Upgrade Over Serial, user can run Device Firmware Upgrade by using the bootloader.