Firmware Version Parsing

Starting with FUOTA v3.1, the server uses a flexible hexadecimal pattern to parse the DevVersionAns command. A hexadecimal pattern (or "hex pattern") is a payload in the DevVersionAns format where characters can be replaced with . to match multiple possible values. This guide explains how to build hex patterns and how parsing behavior changed starting in v3.1.

Before You Begin

You need:

• Familiarity with creating campaigns and managed campaigns. See Quick Start Guide and Managed Campaigns.
• The DevVersionAns payload format used by your device, available from the device manufacturer.

What Is a Hex Pattern?

A hex pattern is a 16-character string of hexadecimal characters where . matches any single character. For example:

• 63580000........ matches 6358000008003F0F, 63580000ABCDEF12, and anything else starting with 63580000.
• The dots can appear anywhere. ..580000........ matches 0058000008003F0F, FF580000ABCDEF12, and any response containing 580000 in bytes 1 through 3.
• ................ matches everything.

Note: Before FUOTA v3.1, the only parsing pattern was the semantic version from the FW version field of the DevVersionAns command. For example, an expected_version of 0.1.2.3 would match any DevVersionAns starting with 03020100. The Managed Campaigns feature only supports the hex pattern.

Why Use Firmware Hex Patterns?

The DevVersionAns command in the Firmware Management Protocol (Section 3.2) does not specify exactly how the payload is structured. This gives device manufacturers flexibility but prevents a universal parsing schema.

The FW version (4 bytes) is commonly used in a semantic version format (0.MAJOR.MINOR.PATCH) or as the firmware CRC (Cyclic Redundancy Check), while the HW version may comprise multiple components such as the device model, module version, and bootloader version. Firmware hex patterns are a way to adopt the flexibility of the DevVersionAns payload.

Behavior Changes in v3.1

Behavior	Before v3.1	After v3.1
Extracting expected_version from image_name in the create campaign API	Automatically populated from image_name if the name has a semantic version. For image_v1.2.3.bin, expected_version would be 0.1.2.3.	The same, but converted to a hex pattern. For image_v1.2.3.bin, expected_version would be 03020100.........
expected_version input format in the create campaign API	Only semantic version with an extra 0. prefix, e.g. 0.1.2.3 or 1.2.3.	Supports both the semantic version string and the hex pattern. The server converts the semantic version automatically. 0.1.2.3 and 1.2.3 both become 03020100.........
initial_version and latest_version in the device state of a regular campaign	Formatted as a semantic version, e.g. 0.1.2.3.	Formatted as a hex pattern, e.g. 03020100.........
expected_version, initial_version, and post_update_version in the device update history	Formatted as a semantic version, e.g. 0.1.2.3.	Formatted as a hex pattern, e.g. 03020100.........

Note: Prior to v3.1, 1.2.3 was automatically converted to 0.1.2.3. This automatic conversion was fixed in v3.1 to avoid confusion about the expected format. Old history records from campaigns started before FUOTA v3.1 are not converted to the new hex format.

What's Next?

• Managed Campaigns: Use hex patterns in include_versions, exclude_versions, and expected_version.
• Upgrade Delegation: Apply the same pattern format to DevEUI filters.
• Frequently Asked Questions: Learn more about the expected_version and campaign parameters.