9.1 Bootloader

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 PIC32CXBZ3/WBZ35 standalone bootloader, it provides below functionalities:

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

• Memory layout of PIC32CXBZ3/WBZ35 device

• Boot memory information

• Image metadata definition

• Working of Bootloader

• Flow diagram of Bootloader

• Bootloader configuration options

• Bootloader and DFU API usage

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_pic32cxbz3_wbz35\apps\bootloader\bootloader, and precompiled hex file at wireless_apps_pic32cxbz3_wbz35\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_pic32cxbz3_wbz35\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.

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

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

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

1. Create a new MCC Harmony Project -- link for instructions, selecting WBZ351 as Target Device.

2. After MCC is launched, in Device Resource window, expand Harmony – Wireless – PIC32CX-BZ System Services , select Bootloader and add the component.

3. Accept all the dialog messages by clicking Yes on message prompt. This will resolve dependencies among components and add connection in the graph. Continue and click yes for next couple of options, this allows MCC to add/remove the dependencies

4. After completing auto-activation, the resulting project graph is as below.

5. Select bootloader component and satisfy the UART dependency (sercom0 for WBZ351 curiosity board)

6. Default configuration - UART DFU is connected to Port A, Pin 4; this is SW3 on WBZ351 curiosity board

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.

Tip: 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 show Timer Based Trigger options and message prompt of adding TC0.

7. Click on the SERCOM0 component and Configure the Baud rate if required (default is 115200)

8. Check the configuration option for QSPI_BAUD_RATE (default is 16 MHz)

9. In project resources, select Generate option.

10. After project files generation has been completed, go to project properties, and select boot flash option from the header pane.

11. Configure MD_SEQ_NUM as desired.

For applications that require to always jump to the bootloader from ROM, ensure that this number is smaller than the application images

Example:

Bootloader MD_SEQ_NUM = 0x00000001

Application MD_SEQ_NUM = any value greater than 0x00000001

For applications scenario where ROM firmware needs to jump to bootloader only if there is no other valid application; make sure that the application MD_SEQ_NUM is smaller than the bootloader MD_SEQ_NUM.

Example:

Bootloader MD_SEQ_NUM = 0xFFFFFFFE

Application MD_SEQ_NUM = any value smaller than 0xFFFFFFFE

After programming MD_SEQ_NUM, select OK

12. On the IDE Tools bar, click Clean and Build Main Project to build the 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.

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

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.

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.

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

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.

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

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.