nrfutil v5.1.0

Customizing the init packet

If you have created a custom DFU bootloader that uses an init packet of a format different than the one used in the BLE Secure DFU Bootloader, you can customize nrfutil to use this different init packet format.

To customize the tool, you must have cloned the nrfutil GitHub repository (see Installing from sources).
The init packet is a packet that is sent before the actual firmware images in a Device Firmware Update. It contains metadata about the DFU, such as the size and type of the image, version information, and compability requirements.

If you use the default packet format as described in the BLE Secure DFU Bootloader example, you do not need to modify nrfutil. If you define a custom init packet format, however, you must modify both your DFU bootloader implementation and nrfutil to use this new format.

The format of the init packet is defined in a Protocol buffers (.proto) file. This file can be compiled into different formats, ensuring that you use the same init packet format in you DFU bootloader implementation and in nrfutil.

Important: The init packet definition requires the proto2 version of the protocol buffers language. Do not include syntax = "proto3"; in your protocol buffer file, because this would cause the file to be interpreted as a proto3 language version file.

Complete the following steps to customize the init packet:

  1. Modify the protocol buffer file to suit your needs.
    In the nrfutil GitHub repository, the file is located at nordicsemi/dfu/dfu-cc.proto. In the BLE Secure DFU Bootloader example in the nRF5 SDK, it is located at examples/dfu/bootloader_secure/dfu-cc.proto. Ensure that both files have the exact same content.
  2. Download and install the Protocol compiler from Google.
  3. Adapt nrfutil to use the new init packet format:
    1. Compile the protocol buffer file to generate the corresponding Python file.
      In the folder that contains your dfu-cc.proto file, enter the following command (where dest_folder is an empty folder where the protocol compiler will write its output):
      protoc --python_out=dest_folder dfu-cc.proto
    2. Copy or move the created file dest_folder/dfu_cc_pb2.py to nordicsemi/dfu/, overwriting the existing file.
    3. If you added new information to the init packet: Adapt nrfutil to include command-line options for new fields and add the information provided through these options to the init packet.
      To adapt the tool, you must edit the Python source files. The contents of the init packet are defined in the files nordicsemi/dfu/init_packet_pb.py and nordicsemi/dfu/package.py. The command-line options are defined in nordicsemi/__main__.py.
    If you installed nrfutil to the local Python site-packages and script folder or created a self-contained executable, you must repeat that procedure after editing the source files.
  4. Adapt your DFU bootloader implementation to use the new init packet format:
    1. Make sure that the dfu-cc.proto file in the request handling folder of your DFU bootloader implementation (by default, this is the examples/dfu/dfu_req_handling/ folder in the SDK) is the same file that you used to adapt nrfutil.
    2. In the DFU bootloader implementation folder, enter the following command:
      protoc -odfu-cc.pb dfu-cc.proto
      This command creates the file dfu-cc.pb.
    3. If you are not working in the examples/dfu/dfu_req_handling/ folder, copy the dfu-cc.options file from that folder to your implementation folder.
    4. Run the nanopb_generator.py script (located in the external/nano-pb/generator/ folder) to generate the required dfu-cc.pb.c and dfu-cc.pb.h files.
      If you are working in examples/dfu/dfu_req_handling/, enter the following command:
      python ../../../external/nano-pb/generator/nanopb_generator.py dfu-cc.pb -f dfu-cc.options
      If you are working in a different folder, adapt the path to the script.
    5. Compile your DFU bootloader.
    For more information about this procedure, see the readme file in the BLE Secure DFU Bootloader folder in the SDK.