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