3 Firmware Image Builder (pyfwimagebuilder)

Introduction

The Image Builder (pyfwimagebuilder) is a Command Line Interface (CLI) that converts the application hex file (*.hex) into another format (*.img) that is directly understood by the bootloader client. The image builder tool also requires bootloader_configuration.toml that is generated by the MPLAB Code Configurator (MCC) Melody 8-Bit MDFU Client library. The bootloader_configuration.toml file contains various device parameters that are added to the generated image file. These parameters enable the bootloader client to identify the specific device used to create the application. A few examples of device parameters are: Device ID, Flash row size, application start address, memory unlock keys, etc. These parameters in the image file help the bootloader client to perform the initial image verification by extracting the Device ID information and comparing it with the Device ID of the target device.

pyfwimagebuilder Workflow

Note: Make sure to have Python 3.8 or later installed and accessible by the command line interface.
  1. Open the Windows Command Prompt.

  2. Install the pyfwimagebuilder using the command:

    pip install pyfwimagebuilder

  3. Execute the below command to generate the embedded application image file:

    pyfwimagebuilder  build [-i input.hex]  [-c bootloader_configuration.toml]  [-o output.img]
Note: pyfwimagebuilder can be invoked directly in MPLAB X IDE as a postBuild step.
Note: The .toml file will be inside Booloader Project Folder > mcc_generated files > bootloader > configurations > bootloader_configurtion.toml.

Example to decode the image binary file:

  1. Download the .toml and .img files
  2. Open terminal in the download directory with the file
  3. Run the below command:
    pyfwimagebuilder decode -i .\output.img -c bootloader_configuration.toml