Increment Your Device Firmware Version

Internet of things (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, represented by 12 in the previous example.

MINOR

Small, backward-compatible updates, represented by 5 in the previous example.

PATCH

Backward-compatible bug fixes, represented by 0 in the previous example.

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.

0x00YYYYMMDDxxyybb

For example, 0x0020240213010000 represents February 13, 2024, version 1.0.0. The following table explains what each set of characters represents.

Characters Meaning Comments

0x

Hexadecimal

Indicates that the number is base 16, not base 10.

00

Character positions used when number is converted to a hexadecimal value

Serves as a placeholder. For example, 0x0020240213010000 converts to 9045691070480384, which is the version number you use in the ota.prop file.

YYYYMMDD

Date

Indicates the year, month, and day on which the firmware was built. For example, 20231231 stands for December 31, 2023.

xx

Major version

Increment only if there are significant feature changes to your firmware, such as the addition of touch controls.

yy

Minor version

Increment for every OTA firmware image pushed to customers' devices. When the major version (xx) is incremented, the minor version starts over from 0, such as 2.0.0.

bb

Build number

Increment for every internal build you push OTA to engineers, QA analysts, and beta testers. When 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.

Was this page helpful?

Last updated: Nov 27, 2023