OTA files

Use an OTA file to perform an OTA upgrade. The OTA file format consists of an OTA header describing what is present in the file followed by one or more sub-elements containing the upgrade data. The OTA file format is described in the ZCL Spec §11.4.

The OTA file is included alongside other firmware files in each release. The file with the .ota extension contains the application firmware update, and the file with the .otb extension contains updates for both the firmware and the bootloader. The recommended bootloader version is listed in each firmware release's XML file—if the target device has an older version, we strongly recommend that you perform the OTA update using the .otb file. Updating a device with the same or newer bootloader version as the recommended version will not change the bootloader, but will update the application.

OTA header

The OTA header contains information about the upgrade data contained in the file. An OTA server needs to parse this file in order to get information that will be requested by a file. The OTA header format is (ZCL Spec §11.4.2):

Offset Length Name Description
0 4 OTA upgrade file identifier Unique identifier for an OTA file - will always be 0x0BEEF11E.
4 2 OTA header version

Version for the OTA header format - The OTA header version supported by XBee 3 firmwares is 0x0100.
6 2 OTA header length The length in bytes of this OTA header.
8 2 OTA header field control Indicates what optional fields are present.
10 2 Manufacturer code The manufacturer code for the image.
12 2 Image type

One of two values:

  • 0x0000 for a firmware upgrade
  • 0x0100 for a file system upgrade
14 4 File version

Contains the version information for this upgrade. See File version definition for more information on how to interpret this field.

Note It is important to parse this value from the OTA file itself instead of inferring it from the file name, as the software compatibility number is not included elsewhere.
18 2 Zigbee stack version

The Zigbee stack version used by the application. This field is informational for the server and is not used during the upgrade process.

Note For XBee 3 Zigbee firmwares, the value of this field is 2 indicating Zigbee Pro—see ZCL Spec §11.4.2.8 for a full list of values. The actual Zigbee stack profile used by the device may differ depending on the value of the  ZS command.
20 32 OTA header string A human-readable string to identify the OTA file.
52 4 Total image size

The total size of the OTA file, including the OTA header.

Note This field contains incorrect information in most older firmware files and should not be used in the update process. The total size of the file should be determined using an external method.

Note All fields—except for the OTA header string—are in little endian byte order. Optional fields may be present at the end of the OTA header, they have been omitted here as they are not used in the XBee 3 upgrade process.

File version definition

The file version is a 32-bit integer—sent in little-endian byte order—containing information on a firmware version. It is divided into two fields:

For example, a file version of 0x0100100A indicates that the software compatibility number is 1 and the version number is 100A. 0x0200300B indicates that the software compatibility number is 2 and the version is 300B.

Sub-elements

All data after the OTA header is organized into sub-elements. Most OTA files will contain a single sub-element: the upgrade image. Sub-elements are arranged as tag-length-value triplets, as shown in the table below.

Offset

 Length

Field name

Description 

0

 2

Sub-element tag

The tag for the sub-element, in little-endian format. This is usually 0x0000 for 'upgrade image'—this is the case for both firmware upgrades and file system upgrades.

2

 4

Sub-element length

The length of the sub-element data (n) in little-endian format.

6

 n

Sub-element data

The data to be transferred. This is either the contents of a .gbl firmware image or a signed file system image.