Bluetooth LE OTAP protocol

The protocol consists of a set of commands (messages) which allow the OTAP Client to request or be notified about the available images on an OTAP Server and to request the transfer of parts of images from the OTAP Server.

All commands with the exception of the image data transfer commands are exchanged through the OTAP Control Point characteristic of the OTAP Service. The data transfer commands are sent only from the OTAP Server to the OTAP Client either via the OTAP Data characteristic of the OTAP Service or via a dedicated Credit Based Channel assigned to a L2CAP PSM.

Protocol design considerations

The OTAP Client is a GAP Peripheral device, and therefore has limited resources. This is why the OTAP Protocol was designed in such a way that it is at the discretion of the OTAP Client if, when, how fast and how much of an available upgrade image is transferred from the OTAP Server. The OTAP Client also decides which is the image transfer method based on its capabilities. Two image transfer methods are supported at this moment: the ATT Transfer Method and the L2CAP PSM CoC Transfer Method.

The ATT Transfer Method is supported by all devices which support Bluetooth LE but it has the disadvantage of a small data payload size and a larger Bluetooth LE stack protocols overhead leading to a lower throughput. This disadvantage has been somewhat reduced by the introduction of the Long Frames feature in the Bluetooth LE specification 4.2 Link Layer which allows for a larger ATT_MTU value. The L2CAP PSM CoC Transfer Method is an optional feature available for devices running a Bluetooth stack version 4.1 and later. The protocol overhead is smaller and the data payload is higher leading to a high throughput. The L2CAP PSM Transfer Method is the preferred transfer method and it is available on all Bluetooth LE Devices if the application requires it.

Based on application requirements and device resources and capabilities the OTAP Clients can request blocks of OTAP images divided into chunks. To minimize the protocol overhead and maximize throughput an OTAP Client makes a data block request specifying the block size and the chunk size and the OTAP Server sends the requested data chunks (which have a sequence number) without waiting for confirmation. The block size, chunk size and number of chunks per block are limited and suitable values must be used based on application needs.

The OTAP Client can stop or restart an image block transfer at any time if the application requires it or a transfer error occurs. The OTAP Server implementation can be almost completely stateless. The OTAP Server does not need to remember what parts of an image have been transferred, this is the job of the OTAP Client which can request any part of an image at any time. This allows it to download parts of the image whenever and how fast its resources allow it. The OTAP Server simply sends image information and image parts on request.

The Bluetooth LE OTAP Protocol is designed to be used not only on Bluetooth LE transport medium but on any transport medium, for example a serial communication interface or another type of wireless interface. This may be useful when transferring an upgrade image from a PC or a mobile device to the OTAP Server to be sent via Bluetooth LE to the OTAP Clients which require it. In the OTAP Demo Applications the embedded OTAP Server relays OTAP commands between an OTAP Client and a PC via a serial interface and using a FSCI type protocol. Effectively the OTAP Client downloads the upgrade image from the PC and not from the OTAP Server. Other transfer methods may be used based on application needs.

Parent topic:Bluetooth LE OTAP protocol

Bluetooth Low Energy OTAP commands

The Bluetooth LE OTAP Commands general format is shown below. A command consists of two parts, a Command ID, and a Command Payload as shown in the table below.

Field Name	CmdId	CmdPayload
Size (Bytes)	1	variable

Commands are sent over the transport medium starting with the Command ID and continuing with the Command Payload.

All multibyte command parameters in the Command Payload are sent in a least significant octet first order (little endian).

A summary of the commands supported by the Bluetooth LE OTAP Protocol is shown in the table below. Each of the commands is then detailed in its own section.

CmdId	Command Name
0x01	New Image Notification
0x02	New Image Info Request
0x03	New Image Info Response
0x04	Image Block Request
0x05	Image Chunk
0x06	Image Transfer Complete
0x07	Error Notification
0x08	Stop Image Transfer

New image notification command

This command can be sent by an OTAP Server to an OTAP Client, usually immediately after the first connection, to notify the OTAP Client of the available images on the OTAP Server.

(Bytes)

|Description|Total Size (CmdId+Payload)| |—–|—-|—|———-|————————|———–|—————————-| |0x01|New Image Notification|S->C|ImageId|2|Short image identifier used for transactions between the OTAP Server and OTAP Client. Should be unique for all images on a server.|15| |ImageVersion|8|Image file version. Contains sufficient information to identify the target hardware, stack version and build version.| |ImageFileSize|4|Image file size in bytes.|

The ImageId parameter should not be ‘0x0000’, which is the reserved value for the current running image or 0xFFFF, which is the reserved value for “no image available”.

Parent topic:Bluetooth Low Energy OTAP commands

New image info request command

This command can be sent by an OTAP Client to an OTAP Server to inquire about available upgrade images on the OTAP Server.

(Bytes)

|Description|Total Size (CmdId+Payload)| |—–|—-|—|———-|————————|———–|—————————-| |0x02|New Image Info Request|C->S|CurrImageId|2|Id of the currently running image. Should be 0x0000.|11| |CurrImageVer|8|Version of the currently running image. A value of all zeroes signals that the client is looking for all images available on an OTAP Server. A value of all zeroes requests information about all images on the server.|

The CurrImageId parameter should be set to 0x0000 to signify the current running image.

The CurrImageVer parameter should contain sufficient information about the target device for the OTAP Server to determine if it has an upgrade image available for the requesting OTAP Client.

A value of all zeroes for the CurrImageVer means that an OTAP Client is requesting information about all available images on an OTAP Server and the OTAP Server should send a New Image Info Response for each image.

Parent topic:Bluetooth Low Energy OTAP commands

New image info response command

This command is sent by the OTAP Server to the OTAP Client as a response to a New Image Information Request Command.

(Bytes)

|Description|Total Size (CmdId+Payload)| |—–|—-|—|———-|————————|———–|—————————-| |0x03|New Image Info Response|S->C|ImageId|2|Image Id. Value 0xFFFF is reserved as “no image available”|15| |ImageVersion|8|Image file version.| |ImageFileSize|4|Image file size.|

The ImageId parameter with a value of 0xFFFF is reserved for the situation where no upgrade image is available for the requesting device.

Parent topic:Bluetooth Low Energy OTAP commands

Image block request command

This command is sent by the OTAP Client to the OTAP Server to request a part of the upgrade image after it has determined the OTAP Server has an upgrade image available.

When an OTAP Server Receives this command it should stop any image file chunk transfer sequences in progress.

(Bytes)

|Description|Total Size (CmdId+Payload)| |—–|—-|—|———-|————————|———–|—————————-| |0x04|Image Block Request|C->S|ImageId|2|Image Id|16| |StartPosition|4|Start position of the image block to be transferred.| |BlockSize|4|Requested total block size in bytes.| |ChunkSize|2|Should be optimized to the TransferChannel type. The maximum number of chunks per block is 256. Value is in bytes.| |TransferMethod|1|0x00 - ATT

0x01 – L2CAP PSM Credit based channel

| |L2capChannelOrPsm|2|0x0004 - ATT

Other values – PSM for credit based channels

|

The ImageId parameter contains the ID of the upgrade image.

The StartPosition parameter specifies the location in the image upgrade file at which the requested block starts.

The BlockSize and ChunkSize parameters specify the size in bytes of the block to be transferred and the size of the chunks into which a block is separated. The ChunkSize value must be chosen in such a way that the total number of chunks can be represented by the SeqNumber parameter of the Image Chunk Command. At the moment this parameter is 1 byte in size so there are a maximum of 256 chunks per block. The chunk sequence number goes from 0 to 255 (0x00 to 0xFF). If this condition is not met or the requested block is not entirely into the image file bounds an error is sent to the OTAP Client when the OTAP Server receives this misconfigured Image Block Request Command.

The maximum value of the ChunkSize parameter depends on the maximum ATT_MTU and L2CAP_MTU supported by the Bluetooth LE stack version and implementation.

The TransferMethod parameter is used to select the transfer method which can be ATT or L2CAP PSM CoC. The L2capChannelOrPsm parameter must contain the value 0x0004 for the ATT transfer method and another value representing the chosen PSM for the L2CAP PSM transfer method. The default PSM for the Bluetooth LE OTAP demo applications is 0x004F for both the OTAP Server and the OTAP Client although the specification allows different values at the 2 ends of the L2CAP PSM connection. The PSM must be in the range reserved by the Bluetooth specification which is 0x0040 to 0x007F.

The optimal value of the ChunkSize parameter depends on the chosen transfer method and the Link Layer payload size. Ideally it must be chosen in such a way that full packets are sent for every chunk in the block.

The default Link Layer payload is 27 bytes form which we subtract 4 for the L2CAP layer and 3 for the ATT layer (1 for the ATT Cmd Opcode and 2 for the Handle) leaving us with a 20 byte OTAP protocol payload. From these 20 bytes we subtract 1 for the OTAP CmdId and 1 for the chunk sequence number leaving us with an optimum chunk size of 18 for the ATT transfer method – which is the default in the demo applications. For the L2CAP PSM transfer method the chosen default chunk size is 111. This was chosen so as a chunk fits exactly 5 link layer packets. The default L2CAP payload of 23 (27 - 4) multiplied by 5 gives us 115 from which we subtract 2 bytes for the SDU Length (which is only sent in the first packet), 1 byte for the OTAP CmdId and 1 byte for the chunk sequence number which leaves exactly 111 bytes for the actual payload.

If the Link layer supports Long Frames feature then the chunk size should be set according to the negotiated ATT MTU for the ATT transfer method. From the negotiated ATT MTU (att_mtu) subtract 3 bytes for the ATT layer (1 for the ATT Cmd Opcode and 2 for the Handle) then subtract 2 bytes for the OTAP protocol (1 for the CmdId and 1 for the chunk sequence number) to determine the optimum chunk size (optimum_att_chunk_size = att_mtu – 3 – 2). For the L2CAP PSM transfer method the chunk size can be set based on the maximum L2CAP SDU size (max_l2cap_sdu_size) from which 4 bytes should be subtracted, 2 for the SDU Length and 2 for the OTAP protocol (optimum_l2cap_chunk_size = max_l2cap_sdu_size – 3 – 2). In some particular cases reducing the L2CAP chunk size could lead to better performance. If the L2CAP chunk size needs to be reduced it should be reduced so it fits exactly a number of link layer packets. An example of how to compute an optimal reduced L2CAP chunk size is given in the previous paragraph.

Parent topic:Bluetooth Low Energy OTAP commands

Image chunk command

One or more Image Chunk Commands are sent from the OTAP Server to the OTAP Client after an Image Block Request is received by the former. The image chunks are sent via the ATT Write Without Response mechanism if the ATT transfer method is chosen and directly via L2CAP if the L2CAP PSM CoC transfer method is chosen.

(Bytes)

|Description|Total Size (CmdId+Payload)| |—–|—-|—|———-|————————|———–|—————————-| |0x05|Image Chunk|S->C|SeqNumber|1|In the range 0 -> BlockSize/ChunkSize - calculated by Server, checked by Client.

The command code is present even when ATT is used.

|3 or more

The SeqNumber parameter is the chunk sequence number and it has incremental values from 0 to 255 (0x00 to 0x FF) for a maximum of 256 chunks per block.

The Data parameter is an array containing the actual image part being transferred starting from the BlockStartPosition + SeqNumber ***ChunkSizeposition in the image file and containing ChunkSize or less bytes depending on the position in the block. Only the last chunk in a block can have less than ChunkSizebytes in the Image Chunk Command data payload.

Parent topic:Bluetooth Low Energy OTAP commands

Image transfer complete command

This command is sent by the OTAP Client to the OTAP Server when an image file has been completely transferred and its integrity has been checked.

(Bytes)

|Description|Total Size (CmdId+Payload)| |—–|—-|—|———-|————————|———–|—————————-| |0x06|Image Transfer Complete|C->S|ImageId|2|Image Id|4| |Status|1|Status of the image transfer. 0x00 - Success|

The ImageId parameter contains the ID of the image file that was transferred.

The Status parameter is 0x00 (Success) if image integrity and possibly other checks have been successfully made after the image is transferred and another value if integrity or other kind of errors have occurred.

If the status is 0x00 the OTAP Client can trigger the Bootloader to start flashing the new image. The image flashing should take about 15 seconds for a 160 KB flash memory.

Parent topic:Bluetooth Low Energy OTAP commands

Error notification command

This command can be sent by both the OTAP Server and the OTAP Client when an error of any kind occurs. When an OTAP Server Receives this command it should stop any image file chunk transfer sequences in progress.

CmdId	Name	Dir	Parameters	Param Size (Bytes)	Description	Total Size (CmdId+Payload)
0x07	Error Notification	Bidir	CmdId	1	Id of the command which generated the error.	3
ErrorStatus	1	Error Status: Examples: out of image bounds, chunk too small, chunk too large, image verification failure, bad command format, image not available, unknown command

|

The CmdId parameter contains the ID of the command which caused the error (if applicable).

The ErrorStatus parameter contains the source of the error. All error statuses are defined in the otapStatus_t enumerated type in the otap_interface.h file.

Parent topic:Bluetooth Low Energy OTAP commands

Stop image transfer command

This command is sent from the OTAP Client to the OTAP Server whenever the former wants to stop the transfer of an image block which is currently in progress, or from OTAP Server to the OTAP Client when the image transfer is stopped from application (Test Tool).

(Bytes)

|Description|Total Size (CmdId+Payload)| |—–|—-|—|———-|————————|———–|—————————-| |0x08|Stop Image Transfer|C->S|ImageId|2|Image Id|3|

The ImageId parameter contains the ID of the image being transferred.

Parent topic:Bluetooth Low Energy OTAP commands

Parent topic:Bluetooth LE OTAP protocol

OTAP client–server interactions

The interactions between the OTAP Server and OTAP Client start immediately after the connection, discovery of the OTAP Service characteristics and writing of the OTAP Control Point CCC Descriptor by the OTAP Server.

The first command sent could be a New Image Notification sent by the OTAP Server to the OTAP Client or a New Image Info Request sent by the OTAP Client. The OTAP Server can respond with a New Image Info response if it has a new image for the device which sent the request (this can be determined from the ImageVerison parameter). The best strategy depends on application requirements.

After the OTAP Client has determined that the OTAP Sever has a newer image it can start downloading the image. This is done by Sending Image Block Request commands to retrieve parts of the image file. The OATP Server answers to these requests with one or more Image Chunk Commands via the requested transfer method or with an Error Notification if there are improper parameters in the Image Block Request. The OTAP Client makes as many Image Block Requests as it is necessary to transfer the entire image file.

The OTAP Client decides how often Image Block Request Commands are sent and can even stop a block transfer which is in progress via the Stop Image Transfer Command. The OTAP Client is in complete control of the image download process and can stop it and restart it at any time based on its resources and application requirements.

A typical Bluetooth LE OTAP Image Transfer scenario is shown in the message sequence chart Figure 1.

Parent topic:Bluetooth LE OTAP protocol

Parent topic:Over the Air Programming (OTAP)