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 QSG183: Bluetooth Mesh SDK Quick-Start Guide for Bluetooth Mesh 1.1 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.

Distributor Example Application#

The Distributor example application 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 example project and run the example application on a Silicon Labs device. The example is only available for a limited set of parts, including selected EFR32xG12, xG21 and xG24 parts.

Open Simplicity Studio 5 with a compatible SoC wireless kit connected to the computer. Select the part in Debug Adapters view to open the Launcher perspective.

1. Click the Example Projects & Demos tab.

2. To see only the example projects, turn off Demos.

3. Under Technology Type, filter on Bluetooth Mesh.

4. Next to the Bluetooth Mesh – SoC DFU Distributor, click CREATE, modify project settings, click FINISH.

5. Build and flash the project 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 in Project Explorer view of the Simplicity IDE perspective.

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 Applications#

A Target node is a node whose firmware is to be updated. The Bluetooth mesh examples provided in the Bluetooth mesh SDK except Bluetooth Mesh – NCP Empty and Bluetooth Mesh – SoC Empty have the firmware update functionality enabled by default, i.e., are Target nodes.

These example applications are provided both as prebuilt demo binary images, ready to download and use, and corresponding example projects 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 EFR32xG13, xG21 and xG24 parts and BGM13 and MGM21 modules. The examples can be built for any part supported by the Bluetooth Mesh SDK.

Note: EFR32xG22 parts have limited support for Bluetooth Mesh.

To build an example project for the device firmware update target, refer to the procedure described in Distributor Example Application.

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 in Project Explorer view of the Simplicity IDE perspective.

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 in Project Explorer view of the Simplicity IDE perspective.

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:

Firmware Update Server#

Configuration of Bluetooth Mesh > Models > Firmware Update > Firmware Update Server:

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

See <sdk>/app/bluetooth/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 the following functions in sl_btmesh_firmware_update_server_api.c and modify the code described below to change the behavior:

• sl_btmesh_fw_update_server_apply() – remove sl_btmesh_node_reset() and sl_bt_nvm_erase_all().

  if (BOOTLOADER_OK == bootloader_setImageToBootload(idx)) {
    // Reset node
    sl_btmesh_node_reset();
    // Erase NVM data
    sl_bt_nvm_erase_all();
    // Delay install
    sl_simple_timer_start(&timer, 1000, apply_step, NULL, true);
    apply_cntdwn = APPLY_DELAY;
  }

• sl_btmesh_fw_update_server_metadata_check_start() – 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;

• 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;

BLOB Transfer Client#

Configuration of Bluetooth Mesh > Models > Transport > BLOB Transfer Client:

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

See <sdk>/app/bluetooth/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:

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 application in Simplicity Studio does not automatically generate the OTA DFU update images (GBL files). The GBL files need to be created separately by running a script located in the project's root folder. Two scripts are provided in the SDK examples:

• create_bl_files.bat (for Windows)

• create_bl_files.sh (for Linux / Mac)

Define two environmental variables, PATH_SCMD and PATH_GCCARM shown in the following table, before running the script.

Running the create_bl_files script creates six GBL files in a subfolder named output_gbl. The file named application.gbl is the firmware update image.

If you use a bootloader that supports LZMA compression of the firmware update image, as described in Compressed Update Image, you must compress the GBL file with the –compress option of the commander utility. The create_bl_files script does not support compressed GBL update image generation. Therefore, run the following commands instead of the create_bl_files script and then the file named application-lzma.gbl is the firmware update image. Change soc_btmesh_empty.axf to the name of your project firmware image in the command line below.

arm-none-eabi-objcopy -O srec -R .text_apploader* -R .text_signature* soc_btmesh_empty.axf application.srec
commander gbl create application-lzma.gbl --app application.srec --compress lzma

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). For more information on using the Simplicity Commander commands, see Simplicity Commander Reference Guide.

Step 2: creating a manifest file#

Create 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_file": "application.gbl",
            "firmware_id": "4181C01592"
        }
    }
}

Step 3 – making an update image archive#

Run the following command to generate a zipped tar archive:

tar czf firmware.gz application.gbl manifest.json