Request a firmware review
Menu
Firmware teams setting up builds, signing and release tags

Build one version scheme for people, MCUboot and Zephyr

Enter major, minor and patch, a pre-release tag, the CI build number, the commit and the hardware revision. The builder writes the same version in four forms.

Key characteristics

Inputs
Major, minor, patch, pre-release, build, commit, hardware
Output
SemVer string, imgtool version, VERSION file, file name
Default example
Fictional LW-1 1.2.0 release candidate for Rev D
Runs
In your browser with nothing sent

Builder: Build one version scheme for people, MCUboot and Zephyr

A fictional example is filled in. Change any field; the output updates as you type. Nothing leaves your browser.

Output

Semantic version for people and release notes
  1.2.0-rc.2+b217.g3f9c2a1.revd

Image version in the MCUboot image header (major.minor.revision+build)
  1.2.0+217

Zephyr application VERSION file
  VERSION_MAJOR = 1
  VERSION_MINOR = 2
  PATCHLEVEL = 0
  VERSION_TWEAK = 217
  EXTRAVERSION = rc.2

File name for the signed image
  revd_1.2.0-rc.2_b217.signed.bin

Pre-release builds should not go to customer devices; MCUboot compares only the numbers, not the pre-release tag.

A firmware version does several jobs at once. People read it in release notes and support tickets. The bootloader compares it to decide whether an image is newer. The build system stamps it into the binary, and the file name on the release server has to tell one build from another at a glance. Set by hand in four places, these drift apart. This builder takes one set of numbers and writes all four forms, so the notes, the image header and the file agree.

How to use it

  1. Enter major, minor and patch for the release.
  2. For test builds, pick a pre-release type (alpha, beta or rc) and its number. Choose none for a customer release.
  3. Enter the CI build number, the short Git commit hash and a hardware revision code.
  4. Copy the output into your build configuration, or download it.

What each part means

Part What it is for Where it comes from
Major, minor, patch The Semantic Versioning core: major for incompatible changes, minor for compatible new features, patch for compatible fixes Your release plan
Pre-release Marks a build that is not final; SemVer ranks 1.2.0-rc.2 below 1.2.0 Your test plan
CI build number Tells two builds of the same version apart Your CI system’s run counter
Commit The exact source the build came from Git
Hardware revision The board the image is built for Your board revision naming

Reading the default example

Example (fictional). Loamwick’s second release candidate of LW-1 firmware 1.2.0, CI build 217 from commit 3f9c2a1, for Rev D boards. The builder writes the semantic version 1.2.0-rc.2+b217.g3f9c2a1.revd, the MCUboot image header version 1.2.0+217, a Zephyr VERSION file with VERSION_MAJOR = 1, VERSION_MINOR = 2, PATCHLEVEL = 0, VERSION_TWEAK = 217 and EXTRAVERSION = rc.2, and the file name revd_1.2.0-rc.2_b217.signed.bin. It warns that pre-release builds should not go to customer devices, because MCUboot compares only the numbers, not the pre-release tag.

Take the warning literally. The version field in MCUboot’s image header holds four numbers and nothing else: major and minor in one byte each, the revision (patch) in two bytes and the build number in four. The “rc.2” never reaches the device. To the bootloader, this release candidate and the final 1.2.0 differ only in build number, so keep release candidates on your own test units.

Why the build number is 217. Zephyr’s documentation limits each numeric field of the VERSION file to one byte, 0 to 255, and Zephyr’s build stops with an error when VERSION_TWEAK or PATCHLEVEL is larger. By default Zephyr also signs MCUboot images with major.minor.patch+tweak taken from the VERSION file, so the tweak is what lands in the header. The builder warns when any of these numbers passes 255. If your CI counter is already larger, keep the full CI build number in the semantic version and the file name, and use a small per-release counter below 256 for VERSION_TWEAK; or set Zephyr’s MCUBOOT_IMGTOOL_SIGN_VERSION option explicitly, in the documented major.minor.revision+build format, so the header carries the full build number.

How it builds the strings

  • Semantic version: major.minor.patch, a hyphen and the pre-release with its number, then a plus sign and the build metadata (b and the build number, g and the commit, and the hardware code). SemVer says build metadata is ignored when comparing versions, so two builds that differ only after the plus sign rank the same.
  • MCUboot version: major.minor.patch+build.
  • Zephyr VERSION file: the same numbers in its five fields, with the pre-release as EXTRAVERSION.
  • File name: the hardware code, the version with its pre-release tag, and the build number.

The builder warns if major or minor is above 255, patch above 65,535 or the build number above 4,294,967,295 (the MCUboot field sizes), if any of the four numbers is above 255 (the Zephyr VERSION file limit), if the commit is not 7 to 40 hexadecimal characters, or if a pre-release has no number.

Limits

  • One spelling of the pre-release. The builder writes rc.2 everywhere, because Zephyr’s EXTRAVERSION accepts dots and the dot matters: SemVer compares numeric parts as numbers, so rc.10 sorts after rc.2, while plain rc10 sorts before rc2.
  • Downgrade protection is a separate setting. MCUboot can refuse older images by comparing versions, which its documentation limits to overwrite-only updates, or by a security counter kept on the device. The version scheme feeds those checks but does not turn them on.

What to do next

Put the version into your notes with the release notes builder, and confirm the version, build number and commit are embedded in the image as part of the firmware release checklist. If the image is close to filling its slot, the flash budget calculator shows how much room is left. A version scheme is part of our firmware development work from the first build, and the updates and releases section of Field Update covers release engineering in more depth.

Send us your board and your plan.

A firmware review reads your schematics, code, flash layout and update plan, and ends with a written plan: what to build first, what could go wrong in the field and how updates will reach your devices.

Request a firmware review

Or email sales@fumbar.com, or call (720) 675-4202.