Firmware Update Examples and Models#

To perform firmware updates, you need an Initiator, a Distributor, and at least one Target node. This section describes the setup to run the Distributor and Target nodes examples provided in the Bluetooth mesh SDK, and the procedures to create an update image archive. See Getting Started with Silicon Labs Bluetooth Mesh Development for an introduction to configuring and building your own projects, and for a guide to additional resources.

The Initiator and Stand-alone Updater are not discussed in this document. However, these functionalities are demonstrated using the Silicon Labs Bluetooth Mesh mobile app, described in Firmware Update Demonstration and Firmware Update with Stand-alone Updater, respectively.

Firmware storage is an important part of the device firmware update process. The flash memory is managed by and accessed via the bootloader. See Bootloader Configurations for Firmware Updates for the flash configurations. The table in Appendix – Silicon Labs Product Positioning for Bluetooth Mesh DFU is a recommendation of the Silicon Labs parts for running the DFU roles.

The Bluetooth Mesh Distributor and Target node examples are available as SLC workspaces which means both the example app and matching bootloader are created during workspace generation. Both application and bootloader projects can be built as a single step and the workspace postbuild step merges the two binaries into a single one.

Note: The SLC workspace is often called solution in Simplicity Studio.

Distributor Solution#

The Distributor solution is provided as a pre-built demo binary image, ready to download and use, and a corresponding example project that you can modify and then build for the target part. The precompiled demo is only available for selected EFR32xG21 and EFR32xG24 parts.

This section describes how to build the solution and run the example application on a Silicon Labs device. The example is only available for a limited set of parts, including selected xG21 and xG24 parts.

Open Simplicity Studio 6 with a compatible SoC wireless kit connected to the computer. Open the Devices page in the vertical navigation bar on the left and select your part.

1. Click the Example Projects & Demos tab.

2. To see only the solution projects, turn off Demos and Examples.

3. Under Technology Type, filter on Bluetooth Mesh.

4. Add dfu distributor keyword to the filter text box

5. Next to the Bluetooth Mesh – SoC DFU Distributor with Internal Storage Bootloader or Bluetooth Mesh – SoC DFU Distributor with External Storage Bootloader, click CREATE, modify project settings, click FINISH.

6. Build and flash the solution to the device.

The example has the components that are required for the Distributor functionality installed by default. To enable the Distributor functionality in other Bluetooth mesh projects, install the DFU distributor component that automatically brings the necessary model components:

1. Open the project .slcp file from Project page located in the vertical navigation bar of Simplicity Studio 6.

2. Click the Software Components tab.

3. Select the DFU distributor component under Bluetooth Mesh > DFU Roles and click Install.

This component automatically installs the following model components:

• Bluetooth Mesh > Models > Firmware Update > Firmware Distribution Server

• Bluetooth Mesh > Models > Firmware Update > Firmware Update Client

• Bluetooth Mesh > Models > Transport > BLOB Transfer Client

• Bluetooth Mesh > Models > Transport > BLOB Transfer Server

See DFU Model Configurations for the configurations of these Firmware Update and BLOB Transfer models.

Target Node Solution#

A Target node is a node whose firmware is to be updated.

The Target solution is provided as a pre-built demo binary image, ready to download and use, and a corresponding example project that you can modify and then build for the target part. The precompiled demos are only available for a limited set of parts, including selected EFR32xG21, xG22 and xG24 parts and MGM21, BGM22 modules. The examples can be built for any part supported by the Bluetooth Mesh SDK.

This section describes how to build the solution and run the example application on a Silicon Labs device. The example is only available for a limited set of parts, including selected xG21, xG22, xG24, xG27 SoC (and modules).

Open Simplicity Studio 6 with a compatible SoC wireless kit connected to the computer. Open the Devices page in the vertical navigation bar on the left and select your part.

1. Click the Example Projects & Demos tab.

2. To see only the solution projects, turn off Demos and Examples.

3. Under Technology Type, filter on Bluetooth Mesh.

4. Add dfu target keyword to the filter text box

5. Next to the Bluetooth Mesh - SoC DFU Target with Internal Storage Bootloader or Bluetooth Mesh - SoC DFU Target with External Storage Bootloader, click CREATE, modify project settings, click FINISH.

6. Build and flash the solution to the device.

Note: EFR32xG22 parts have limited support for Bluetooth Mesh.

The examples have the components that are required for the Target node functionality installed by default. To enable the Target node functionality in other Bluetooth mesh projects, install the DFU target node component that automatically brings the necessary model components:

1. Open the project .slcp file from Project page located in the vertical navigation bar of Simplicity Studio 6.

2. Click the Software Components tab.

3. Select the DFU target node component under Bluetooth Mesh > DFU Roles in the left panel and click Install.

This component automatically installs the following model components:

• Bluetooth Mesh > Models > Firmware Update > Firmware Update Server

• Bluetooth Mesh > Models > Transport > BLOB Transfer Server

See the section below for the configurations of these Firmware Update and BLOB Transfer models.

DFU Model Configurations#

This section describes the main settings of the Firmware Update and BLOB Transfer models. Open the project .slcp file from Project page located in the vertical navigation bar of Simplicity Studio 6.

1. Click the Software Components tab.

2. Select Bluetooth Mesh > Models > Firmware Update or Bluetooth Mesh > Models > Transport in the left panel.

3. Click the gear icon next to the model to be configured.

Firmware Distribution Server#

Configuration of Bluetooth Mesh > Models > Firmware Update > Firmware Distribution Server (sl_btmesh_fw_distribution_server_config.h):

Firmware Update Server#

Configuration of Bluetooth Mesh > Models > Firmware Update > Firmware Update Server (sl_btmesh_firmware_update_server_config.h):

The weak functions for the Firmware Update Server model are mostly implementation-dependent and can be overwritten in the application:

See <sdk>/bluetooth_mesh_middleware/common/btmesh_firmware_update_server/sl_btmesh_firmware_update_server_api.h for further information.

A Target node will become unprovisioned by default after a firmware update. You can overwrite this behavior in the following functions:

• sl_btmesh_fw_update_server_metadata_check_start() or sl_btmesh_firmware_update_server_metadata_check_step() – set another value to *additional_information. The additional information is provided to the Bluetooth mesh stack and will appear in the Firmware Update Status and Firmware Update Firmware Metadata Status messages.

  *additional_information = BTMESH_FW_UPDATE_SERVER_ADDITIONAL_INFORMATION_UNPROVISION;

  if (BOOTLOADER_OK == bootloader_setImageToBootload(idx)) {
    // Erase persistent mesh data stored in NVM and make the node unprovisioned
    // only based on the result of metadata check
    if (fw_additional_information == BTMESH_FW_UPDATE_SERVER_ADDITIONAL_INFORMATION_UNPROVISION) {
      // Reset node
      sl_btmesh_node_reset();
      // Erase NVM data
      app_btmesh_nvm_erase_all();
    }
    // Delay install
    app_timer_start(&timer, 1000, apply_step, NULL, true);
    apply_cntdwn = APPLY_DELAY;
  }

BLOB Transfer Client#

Configuration of Bluetooth Mesh > Models > Transport > BLOB Transfer Client (sl_btmesh_blob_transfer_client_config.h):

The weak functions for the BLOB Transfer Client model are mostly implementation-dependent and can be overwritten in the application:

See <sdk>/bluetooth_mesh_middleware/common/btmesh_blob_transfer_client/sl_btmesh_blob_transfer_client.h for further information.

BLOB Transfer Server#

Configuration of Bluetooth Mesh > Models > Transport > BLOB Transfer Server Core (sl_btmesh_blob_transfer_server_config.h):

Configuration of Bluetooth Mesh > Models > Transport > BLOB Transfer Server (dfu_dist/dfu_target - sl_btmesh_blob_transfer_server_dfu_<dist/target>_config.h):

Creating the Update Image Archive#

An update image archive is a gzip archive file that consists of:

• Manifest: a file named manifest.json, which is in the format of JavaScript Object Notation (JSON). It contains a description of the firmware package, including the name of the firmware image file and an optional metadata file for the update.

• Firmware Image: the firmware image file in GBL format, as identified in the manifest file.

• Metadata: an optional file provided by the vendor and identified in the manifest file, that may provide metadata for the firmware image.

This section describes the procedure to generate a firmware image, manifest file, and update image archive.

Step 1: Generating a firmware image#

Building a C-based Bluetooth mesh solution in Simplicity Studio automatically generates the OTA DFU update images (GBL files). The solution and each project in the solution have their own post build file (slpb) which specifies which post build actions shall be executed and their parameters. The GBL files are generated as post build steps.

If the GBL creation needs to be customized (e.g. compression, encryption) then open the .slpb file from Project page located in the vertical navigation bar to launch Post Build Editor in Simplicity Studio 6. The Post Build Editor can be used to modify the post build steps in Simplicity Studio 6. The post build steps execute Simplicity Commander commands in the background. You can find more details on the following pages:

• Post-Build Editor (PBE)

• Simplicity Commander

• Execute a Project Post-Build File

Two GBL files are generated into the <workspace-path>/artifact and <workspace-path>/<app-name>/artifact directories by post build steps:

• <app-name>.gbl: use when application shall be updated

• <workspace-name>.gbl: use when both bootloader and application shall be updated

If you use a bootloader that supports LZMA compression of the firmware update image, as described in Compressed Update Image, you should compress the GBL file by selecting lzma option from Compression drop-down menu in Post Build Editor for each GBL generation step.

For more information about the GBL file format, see Silicon Labs Gecko Bootloader User’s Guide for GSDK 4.0 and Higher (series 1 and 2 devices).

Step 2: creating a manifest file and firmware archive#

Run FirmwareArchiveGenerator.py from <sdk>/bluetooth_mesh_middleware/script/generator to generate the firmware archive.

python FirmwareArchiveGenerator.py -i <workspace-path>/<app-name> -o <workspace-path>/<app-name>/artifact/archive

ℹ️ Note: The pyelftools package is required to run FirmwareArchiveGenerator.py. Install it using pip install pyelftools before executing the command.

The script creates a file named manifest.json that is a text file in JSON format containing the name of the firmware update image, the firmware ID and optionally the name of the metadata file. The format of the manifest/firmware/firmware_id member is Base16. The manifest/firmware/metadata_file member contains the metadata file name if present. The following is an example of the content of the manifest.json file.

{
  "manifest": {
    "firmware": {
      "firmware_image_file": "btmesh_soc_dfu_target.gbl",
      "metadata_file": "btmesh_soc_dfu_target_metadata.bin",
      "firmware_id": "ff02736f6362746d747267745f7631"
    }
  }
}

The script extracts the firmware ID and metadata from the out (elf) file by default. The firmware ID is extracted from a constant variable, which stores the SL_BTMESH_FW_UPDATE_SERVER_FWID_CFG_VAL configuration parameter of Firmware Update Server model in the application. The metadata is extracted from a constant variable, which stores the Device Composition Data (DCD) Page 0 configured by Bluetooth Mesh Configurator in the application.

If you want to provide the firmware ID and metadata file manually, you can use the following command line options:

• --fwid <firmware_id>: specify the firmware ID as hexadecimal string

• --metadata <metadata>: specify the metadata as hexadecimal string The script creates the standard gzip archive <app-name>.gz in the specified output directory.

The script runs the equivalent of the following command to create the gzip archive:

tar czf btmesh_soc_dfu_target_firmware.gz btmesh_soc_dfu_target.gbl btmesh_soc_dfu_target_metadata.bin manifest.json