Increment Your Device Firmware Version

IoT and smart home devices must support multiple versions for different uses. To map these firmware iterations to specific device capabilities, you must identify them with separate version numbers.

Firmware versioning process

Each Alexa Connect Kit (ACK) device type is associated with a single set of fundamental capabilities. During the registration process, these static capabilities are mapped to the device serial number. When you release an over-the-air (OTA) firmware update, such as support for a controller or a new mode, the version is incremented. The new version number associates the additional device capabilities with the firmware update.

Semantic versioning

The ACK firmware update process follows the principles of semantic versioning, which relies on version numbers to indicate the extent of code modification. The recommended versioning schema for ACK devices follows the MAJOR.MINOR.PATCH pattern, such as 12.5.0. For details, see Semantic Versioning, and refer to the following table.

Version Incrementation

MAJOR

Breaking changes

MINOR

Small, backward-compatible updates

PATCH

Backward-compatible bug fixes

Before you make an OTA update, set up a consistent versioning process. An organized process helps you increment your host microcontroller unit (HMCU) application correctly and release it to the right users. To update your HMCU firmware OTA, you must give it a version number that's later than the current number.

The HMCU application callback function ACKUser_GetFirmwareVersion() must specify the HMCU version number as a return value. This value, a 64-bit unsigned integer, converts to a decimal that's used in the ota.prop file. The following hexadecimal ID is the semantic versioning schema recommended for ACK devices, and the table explains what each digit represents.

0x00YYYYMMDDxxyybb

Characters Meaning Comments

YYYYMMDD

Date

Year, month, and day on which the firmware was built.

xx

Major version

Increment only if there are significant feature changes in your firmware.

yy

Minor version

Increment for every OTA firmware image pushed to your devices in the field (that is, to end users). When the major version (xx) is incremented, the minor version starts over from 0.

bb

Build number

Increment for every internal build you push OTA to engineers, QA analysts, and beta testers. Once tests are complete, increment the minor version and restart the build number from 0. Then push the promoted firmware to your devices in the field.