fota: clarify File Version field format from OTA Header

docs/configuring/configuring_libraries.rst

@@ -63,7 +63,23 @@ Other :ref:`Zigbee FOTA Kconfig options <lib_zigbee_fota_options>` can be used w
 
 Because the Zigbee OTA DFU performs the upgrade using the `DFU target`_ library, the are several non-Zigbee Kconfig options that must be set to configure the update process:
 
-* ``CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION`` - This option specifies the current image version.
+* ``CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION`` - This option specifies the current image version in the format ``"major.minor.patch"`` or ``"major.minor.patch+build"``.
+  Each component must be in the range of 0 to 255.
+  This version string is converted to a 32-bit integer and stored in the Zigbee OTA File Version field according to the Zigbee Cluster Library specification.
+
+  The File Version field format follows the recommended structure of four 8-bit integers in Binary Coded Decimal (BCD):
+
+  * ``major`` component → Application Release (bits 31-24)
+  * ``minor`` component → Application Build (bits 23-16)
+  * ``patch`` component → Stack Release (bits 15-8)
+  * ``build`` component → Stack Build (bits 7-0)
+
+  For example, ``"1.2.3+4"`` becomes ``0x01020304`` in the OTA header and is displayed as ``01020304`` in the generated ``.zigbee`` filename.
+
+* ``CONFIG_ZIGBEE_FOTA_FILE_VERSION_STACK`` - When enabled, this option automatically populates the Stack Release and Stack Build components of the OTA file version with the ZBOSS stack version (``ZBOSS_MAJOR`` and ``ZBOSS_MINOR``).
+  Only the ``major`` and ``minor`` components from ``CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION`` are used for the Application Release and Application Build.
+  For example, with ``"1.5.0+0"`` and ZBOSS 4.2, the OTA version becomes ``0x01050402``.
+
 * ``CONFIG_DFU_TARGET_MCUBOOT`` - This option enables updates that are performed by MCUboot.
 * ``CONFIG_IMG_MANAGER`` - This option enables the support for managing the DFU image downloaded using MCUboot.
 * ``CONFIG_IMG_ERASE_PROGRESSIVELY`` - This option instructs MCUboot to erase the flash memory progressively.

docs/configuring/configuring_zboss_traces.rst

@@ -211,13 +211,13 @@ For information on configuring USB trace logs in this scenario, see the :ref:`Zi
    Before proceeding with the following steps, first check if your Zigbee application has USB enabled or is currently using USB.
    If your application is already using a virtual COM port through native USB, use a device name that is different from the default ``CDC_ACM_0`` when creating a new virtual COM port for printing trace logs.
    For example, if ``CDC_ACM_0`` is already in use, create a virtual COM port named ``CDC_ACM_1``.
-   Additionally, you must set the :kconfig:option:`CONFIG_USB_COMPOSITE_DEVICE` Kconfig option when configuring multiple virtual COM ports.
+   Additionally, you must set the ``CONFIG_USB_COMPOSITE_DEVICE`` Kconfig option when configuring multiple virtual COM ports.
 
    Refer to the :ref:`Zigbee NCP <zigbee_ncp_sample>` documentation page for an example in which one virtual COM port instance is already configured, and an additional instance must be created.
 
 To configure trace logs using native USB, complete the following steps:
 
-1. Set the Kconfig option :kconfig:option:`CONFIG_ZBOSS_TRACE_USB_CDC_LOGGING`.
+1. Set the Kconfig option ``CONFIG_ZBOSS_TRACE_USB_CDC_LOGGING``.
    This also enables the necessary USB Kconfig options.
 
 #. Create a virtual COM port that will be used for printing ZBOSS trace logs by extending the DTS overlay file for the selected board by running the following command:

resources/zb_add_ota_header.py

@@ -140,12 +140,37 @@ def __add_optional_fields(self, fields_length, field_control_bit_mask, fields_fo
             self.__additional_fields.append(fields_values)
 
 def convert_version_string_to_int(s):
-    """Convert from semver string "1.2.3", to integer 1020003"""
-    match = re.match(r'^([0-9]+)\.([0-9]+)\.([0-9]+)(?:\+[0-9]+)?$', s)
+    """Convert from semver string to a 32-bit integer for OTA file version.
+
+    Converts version components into a packed integer where each component occupies one byte:
+    - "1.2.3" → 0x01020300 (decimal 16909056)
+    - "1.2.3+4" → 0x01020304 (decimal 16909060)
+
+    The returned integer is:
+    - Packed into the OTA binary header as a 4-byte little-endian value
+    - Formatted as an 8-digit hex string (e.g., "01020300") in the output filename
+
+    Args:
+        s: Version string in format "major.minor.patch" or "major.minor.patch+build"
+
+    Returns:
+        Integer where bits are arranged as: [major][minor][patch][build]
+        with each component occupying 8 bits (0-255 range per component)
+    """
+    match = re.match(r'^([0-9]+)\.([0-9]+)\.([0-9]+)(?:\+([0-9]+))?$', s)
     if match is None:
-        raise ValueError('application-version-string parameter must be on the format x.y.z or x.y.z+t')
-    js = [0x100*0x10000, 0x10000, 1]
-    return sum([js[i] * int(match.group(i+1)) for i in range(3)])
+        raise ValueError('application-version-string parameter must be in format x.y.z or x.y.z+b '
+                        'where x=major, y=minor, z=patch, b=build (all non-negative integers)')
+    js = [0x100*0x10000, 0x10000, 0x100, 1]
+    groups = [int(match.group(i+1)) if match.group(i+1) else 0 for i in range(4)]
+
+    # Validate that each component fits in one byte (0-255)
+    component_names = ['major', 'minor', 'patch', 'build']
+    for i, (component, name) in enumerate(zip(groups, component_names)):
+        if component > 255:
+            raise ValueError(f'Version component {name}={component} exceeds maximum value of 255')
+
+    return sum([js[i] * groups[i] for i in range(4)])
 
 def hex2int(x):
     """Convert hex to int."""
@@ -160,7 +185,10 @@ def parse_args():
     parser.add_argument('--application', required=True,
                         help='The application firmware file.')
     parser.add_argument('--application-version-string', required=True,
-                        help="The application version string, e.g. '2.7.31'. Will be converted to an integer, e.g. 20731.")
+                        help="The application version string, e.g. '2.7.31' or '1.2.3+4'. "
+                             "Converted to a 32-bit integer where each component occupies one byte: "
+                             "'2.7.31' becomes 0x02071F00 (stored in binary header, displayed as '02071F00' in filename). "
+                             "Format: 'major.minor.patch' or 'major.minor.patch+build' (each 0-255).")
     parser.add_argument('--zigbee-manufacturer-id', required=False, default=OTA_HEADER_MANUFACTURER_WILDCARD, type=hex2int,
                         help='Manufacturer ID to be used in Zigbee OTA header.')
     parser.add_argument('--zigbee-image-type', required=False, default=OTA_HEADER_IMAGE_TYPE_WILDCARD, type=hex2int,

subsys/lib/zigbee_fota/Kconfig

@@ -70,6 +70,21 @@ config ZIGBEE_FOTA_COMMENT
 	help
 	  Firmware comment to be used in Zigbee OTA header.
 
+config ZIGBEE_FOTA_FILE_VERSION_STACK
+	bool "Use ZBOSS version for stack release and build in OTA file version"
+	help
+	  When enabled, the OTA file version field will be constructed using:
+	  - Application Release: major component from CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION
+	  - Application Build: minor component from CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION
+	  - Stack Release: ZBOSS_MAJOR from zb_version.h
+	  - Stack Build: ZBOSS_MINOR from zb_version.h
+
+	  When disabled (default), all four version components (major.minor.patch+build)
+	  from CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION are used directly as:
+	  [Application Release][Application Build][Stack Release][Stack Build]
+
+	  This follows the Zigbee OTA Version field format of four 8-bit integers in BCD.
+
 config ENABLE_ZIGBEE_FOTA_MIN_HW_VERSION
 	bool "Enable Zigbee OTA minimum hw version"
 

subsys/lib/zigbee_fota/src/dfu_multi_target.c

@@ -12,12 +12,17 @@
 #include <pm_config.h>
 #include "dfu_multi_target.h"
 
+#ifdef CONFIG_ZIGBEE_FOTA_FILE_VERSION_STACK
+#include <zb_version.h>
+#endif
+
 #define DFU_TARGET_SCHEDULE_ALL_IMAGES -1
 
 union dfu_multi_target_ver {
 	uint32_t uint32_ver;
 	struct {
-		uint16_t revision;
+		uint8_t build_num;
+		uint8_t revision;
 		uint8_t minor;
 		uint8_t major;
 	};
@@ -138,7 +143,13 @@ uint32_t dfu_multi_target_get_version(void)
 	} else {
 		image_ver.major = mcuboot_header.h.v1.sem_ver.major;
 		image_ver.minor = mcuboot_header.h.v1.sem_ver.minor;
+#ifdef CONFIG_ZIGBEE_FOTA_FILE_VERSION_STACK
+		image_ver.revision = ZBOSS_MAJOR;
+		image_ver.build_num = ZBOSS_MINOR;
+#else
 		image_ver.revision = mcuboot_header.h.v1.sem_ver.revision;
+		image_ver.build_num = mcuboot_header.h.v1.sem_ver.build_num;
+#endif
 	}
 
         return image_ver.uint32_ver;