Maintaining firmware version

To effectively deploy a Matter product, it is essential to implement application version management. This versioning is crucial for managing firmware upgrades on devices. It is also displayed within ecosystem applications, as provided by the Basic Information cluster.

There are two primary approaches for maintaining versioning:

  • Utilizing a VERSION file as detailed on the Application version management page of the Zephyr Project documentation. This method involves defining the version information in a specific file format.

  • Implementing dedicated Kconfig configurations. This approach uses Kconfig system configurations to set and manage the versioning details.

Choose the approach that best aligns with your project requirements and infrastructure.

Note

These approaches should not be used simultaneously.

Using VERSION file

To implement versioning based on a VERSION file, you must create a file named VERSION within the application directory and ensure it contains the appropriate content:

VERSION_MAJOR =
VERSION_MINOR =
PATCHLEVEL =
VERSION_TWEAK =

Note

You must assign a value to at least one of the variables. If not, the VERSION file will cause error.

For example:

VERSION_MAJOR = 2
VERSION_MINOR = 5
PATCHLEVEL = 99
VERSION_TWEAK = 0

A VERSION file is responsible for assigning values in the following format for:

  • MCUboot version: MAJOR . MINOR . PATCHLEVEL + TWEAK. The above example would be formatted as 2 . 5 . 99 + 0.

  • Matter OTA: in the 32-bit integer where each variable is 8 bits long. The above example would be formatted as 0x02056300.

Using Kconfig options

Depending on how you transfer the updated images to the device, you need to use different Kconfig options.

Device Firmware Upgrade over Matter versioning

When using DFU over Matter, you must edit the prj.conf file in the application directory. Add the following Kconfig options to change the version:

Additionally, since Nordic chips use MCUboot Image Tool, you need to also edit the CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION Kconfig option, with a value in the following format: "MAJOR . MINOR . PATCHLEVEL + TWEAK".

For example:

CONFIG_CHIP_DEVICE_SOFTWARE_VERSION=33907456
CONFIG_CHIP_DEVICE_SOFTWARE_VERSION_STRING="2.5.99+0"
CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION="2.5.99+0"

Where 33907456 is 0x02056300, the hexadecimal versioning of 2.5.99+0.

Device Firmware Upgrade over Bluetooth LE versioning

For DFU over Bluetooth LE, you need to edit the CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION Kconfig option in the prj.conf file in the application directory. Set its value in the following format: "MAJOR . MINOR . PATCHLEVEL + TWEAK".

Performing Device Firmware Upgrade

After properly configuring the application version, you can perform device firmware upgrade as explained in Performing Device Firmware Upgrade in the nRF Connect examples.