Bluetooth Low Energy OTAP image file format

The Bluetooth LE OTAP Image file has a binary file format. It is composed of a header followed by a number of sub-elements. The header describes general information about the file. There are some predefined sub-elements of a file but an end manufacturer could add manufacturer-specific sub-elements. The header does not have details of the sub-elements. Each element is described by its type.

The general format of an image file is shown in the table below.

Image File Element

Value Field Length (bytes)

Description

Header

Variable

The header contains general information about the image file.

Upgrade Image Sub-element

Variable

This sub-element contains the actual binary executable image, which is copied into the flash memory of the target device. The maximum size of this sub-element depends on the target hardware.

Image File CRC Sub-element

2

This is a 16-bit CCITT type CRC which is calculated over all elements of the image file with the exception of the Image File CRC sub-element itself. This must be the last sub-element in an image file.

Each sub-element in a Bluetooth LE OTAP Image File has a Type-Length-Value (TLV) format. The type identifier provides forward and backward compatibility as new sub-elements are introduced. Existing devices that do not understand newer sub-elements may ignore the data.

The following table shows the general format of a Bluetooth LE Image File sub-element.

Subfield

Size (Bytes)

Format

Description

Type

2

uint16

Type Identifier – determines the format of the data contained in the value field

Length

4

uint32

Length of the Value field of the sub-element.

Value

variable

uint8[]

Data payload

Some sub-element type identifiers are reserved while others are left for manufacturer-specific use. The table below shows the reserved type identifiers and the manufacturer-specific ranges.

Type Identifiers

Description

0x0000

Upgrade Image

0x0001 – 0xefff

Reserved

0xf000 – 0xffff

Manufacturer-Specific Use

The OTAP Demo applications use two of the manufacturer-specific sub-element type identifiers while the rest remain free to use. The two are shown in the table below along with a short description.

Manufacturer-specific Type Identifiers

Sub-element Name

Notes

0xf000

Sector Bitmap

Bitmap that signals the bootloader the sectors of the internal flash, which should be overwritten and which should remain as is.

0xf100

Image File CRC

16-bit CRC that is computed over the image file with the exception of the CRC sub-element itself.

Bluetooth Low Energy OTAP header

The format and fields of the Bluetooth Low Energy OTAP Header are summarized in the table below.

Octets

Data Types

Field Name

Mandatory/Optional

4

Unsigned 32-bit integer

Upgrade File Identifier

M

2

Unsigned 16-bit integer

Header Version

M

2

Unsigned 16-bit integer

Header Length

M

2

Unsigned 16-bit integer

Header Field Control

M

2

Unsigned 16-bit integer

Company Identifier

M

2

Unsigned 16-bit integer

Image ID

M

8

8 byte array

Image Version

M

32

Character string

Header String

M

4

Unsigned 32-bit integer

Total Image File Size

M

The fields are shown in the order they are placed in memory from the first location to the last.

The total size of the header without the optional fields (if defined by the Header Field Control) is 58 bytes.

All the fields in the header have a little endian format with the exception of the Header String field which is an ASCII character string.

A packed structure type definition for the contents of the Bluetooth LE OTAP Header can be found in the otap_interface.h file.

Upgrade file identifier

Fixed value 4 byte field used to identify the file as being a Bluetooth LE OTAP Image File. The predefined value is “0x0B1EF11E”.

Parent topic:Bluetooth Low Energy OTAP header

Header version

This 2 byte field contains the major and minor version number. The high byte contains the major version and the low byte contains the minor version. The current value is “0x0100” with the major version “01” and the minor version “00”. A change to the minor version means the OTA upgrade file format is still backward compatible, while a change to the major version suggests incompatibility.

Parent topic:Bluetooth Low Energy OTAP header

Header length

Length of all the fields in the header including the Upgrade File Identifier field, Header Length field and all the optional fields. The value insulates existing software against new fields that may be added to the header. If new header fields added are not compatible with current running software, the implementations should process all fields they understand and then skip over any remaining bytes in the header to process the image or CRC sub-element. The value of the Header Length field depends on the value of the Header Field Control field, which dictates which optional header fields are included.

Parent topic:Bluetooth Low Energy OTAP header

Header field control

This is a 2-byte bit mask that specifies the optional fields present in the OTAP Header.

In case no optional fields are defined, this whole field is reserved and should be set to “0x0000”.

Parent topic:Bluetooth Low Energy OTAP header

Company identifier

This is the company identifier assigned by the Bluetooth SIG. The Company Identifier used for the OTAP demo applications is “0x01FF”.

Parent topic:Bluetooth Low Energy OTAP header

Image ID

This is a unique short identifier for the image file. It is used to request parts of an image file. This number should be unique for all images available on a Bluetooth LE OTAP Server.

  • The value 0x0000 is reserved for the current running image.

  • The value 0xFFFF is reserved as a “no image available” code for New Image Info Response commands.

This field value must be used in the ImageID field in the New Image Notification and New Image Info Response commands.

Parent topic:Bluetooth Low Energy OTAP header

Image version

This is the full identifier of the image file. It should allow a Bluetooth LE OTAP Client to identify the target hardware, stack version, image file build version, and other parameters if necessary. The recommended format of this field (which is used by the OTAP Demo applications) is shown below but an end device manufacturer could choose different format. The subfields are shown in the order they are placed in memory from the first location to the last. Each subfield has a little-endian format, if applicable.

Subfield

Size (bytes)

Format

Description

Build Version

3

uint8[]

Image build version.

Stack Version

1

uint8

0x41 for example for Bluetooth Low Energy Stack version 4.1.

Hardware ID

3

uint8[]

Unique hardware identifier.

End Manufacturer Id

1

uint8

ID of the hardware–specific to the end manufacturer

This field value must be used in the ImageVersion field in the New Image Notification and New Image Info Response commands.

Parent topic:Bluetooth Low Energy OTAP header

Header string

This is a manufacturer-specific string that may be used to store other necessary information as seen fit by each manufacturer. The idea is to have a human readable string that can prove helpful during the development cycle. The string is defined to occupy 32 bytes of space in the OTAP Header. The default string used for the Bluetooth LE OTAP demo application is “BLE OTAP Demo Image File”.

Parent topic:Bluetooth Low Energy OTAP header

Total image file size

The value represents the total image size in bytes. This is the total of data in bytes that is transferred over-the-air from the server to the client. In most cases, the total image size of an OTAP upgrade image file is the sum of the sizes of the OTAP Header and all the other sub-elements on the file. If the image contains any integrity and/or source identity verification fields then the Total Image File Size also includes the sizes of these fields.

Parent topic:Bluetooth Low Energy OTAP header

Parent topic:Bluetooth Low Energy OTAP image file format

Parent topic:Over the Air Programming (OTAP)