Provisioning and Configuration After a Device Firmware Update#

A device may become unprovisioned after a firmware update depending on how configuration data in the new firmware is changed. This section provides information on how to possibly avoid re-provisioning the device after updating the device firmware.

Updating Device Firmware from an SDK Version prior to Simplicity SDK 2025.6.0#

A new model storage format has been introduced in Simplicity SDK 2025.6.0. If you are creating a new project, the new model storage library protocol/bluetooth/build/gcc/cortex-m33/mesh_app/release/libbtmesh_model_storage_v2.a is added to your project and it will use the new model storage format.

If you are migrating your project from an old SDK, the new model storage format is the default option and therefore model configuration data may not be read properly from NVM3 when a device has been upgraded to new firmware.

To use the old model storage format in your project, install the Backwards compatible persistent storage for Mesh model configuration data component and you will find the old model storage library protocol/bluetooth/build/gcc/cortex-m33/mesh_app/release/libbtmesh_model_storage_v1.a added to your project.

Note: uninstalling the component will use the new model storage format.

backwards compatible persistent storagebackwards compatible persistent storage

With the new model storage format you can flexibly make DCD changes and may not need to re-provision the device after a firmware update. We recommend using the migration library to convert your model configuration data in NVM3 from the old format to the new format to benefit from the flexibility. To use the migration library, install the Mesh model configuration data migration to current persistent storage format component.

migration to current persistent storagemigration to current persistent storage

Changing Device Composition Data in New Firmware#

The default implementation of the Firmware Update Server component in older SDKs performs a factory reset when applying the new firmware to the device. It means a device will become unprovisioned after a firmware update. The default implementation has been changed in Simplicity SDK 2025.6.0. The new implementation of the Firmware Update Server component performs a factory reset when there is model or element deletion in the device composition data of the new firmware.

The default implementation is weak functions implemented in app/btmesh/common/btmesh_firmware_update_server/sl_btmesh_firmware_update_server_api.c. The weak functions can be overridden in application by providing a strong implementation of sl_btmesh_fw_update_server_metadata_check_start() and sl_btmesh_firmware_update_server_metadata_check_step().

The Firmware Update Server component assumes the metadata contains the Composition Data Page 0 from the new firmware and uses the metadata check to compare it with the Composition Data Page 0 in the device.

  sc = sl_btmesh_node_compare_dcd(DCD_PAGE_0, len, metadata, &diff);

  if (sc != SL_STATUS_OK) {
    return BTMESH_FW_UPDATE_SERVER_METADATA_CHECK_ERROR;
  }

The metadata check sets additional_information to BTMESH_FW_UPDATE_SERVER_ADDITIONAL_INFORMATION_UNPROVISION if the result of the DCD comparison is SIG model deletion, vendor model deletion, or element deletion.

  if (diff & sl_btmesh_node_sig_model_removed
      || diff & sl_btmesh_node_vendor_model_removed
      || diff & sl_btmesh_node_element_removed) {
    fw_additional_information = BTMESH_FW_UPDATE_SERVER_ADDITIONAL_INFORMATION_UNPROVISION;
  }

  *additional_information = fw_additional_information;
  return BTMESH_FW_UPDATE_SERVER_METADATA_CHECK_SUCCESS;

In sl_btmesh_fw_update_server_apply(), a factory reset is performed before applying the firmware, if the metadata check reported that the device will be unprovisioned.

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

Note: The app/btmesh/script/generator/FirmwareArchiveGenerator.py script in SDK is a tool used to generate a firmware image in compliance with the Bluetooth Mesh DFU specification. It retrieves the content of the Composition Data Page 0 from the ELF file and sets it as the metadata.

Changing Stack Configuration in New Firmware#

When upgrading device firmware, the new firmware may fail to run node or provisioner initialization if stack configurations in old and new firmware mismatch. One common mistake is decreasing the value of some memory configurations so that the stack will allocate a memory buffer that is not big enough to store the configuration data from NVM3. This includes but is not limited to:

  • The number of models in new firmware is less than the one in old firmware

  • The number of application bindings is less than the one in old firmware

  • The number of subscriptions is less than the one in old firmware

The source code of device composition data configured in Bluetooth Mesh Configurator is generated in autogen/sl_btmesh_dcd.c and autogen/sl_btmesh_dcd.h. The stack configuration configured in the Mesh Stack Configuration editor is stored in config/sl_btmesh_config.h.