OTA Update Commands (Classic Bluetooth)
This page describes the commands that an Echo device sends to a gadget to perform an over-the-air (OTA) update to the gadget's firmware over Classic Bluetooth. For an overview of the overall procedure, see OTA Update Process (Classic Bluetooth).
A command is a request that the Echo device sends to the gadget. The gadget may then send the Echo device a response. We first describe the format of the packets that contain the requests and responses. We then provide a list of specific commands and the fields within the associated requests and responses.
Packet format
This section describes the format of the packets that an Echo device and a gadget exchange during the OTA update process.
As with directives and events, the Echo device and the gadget exchange packets for OTA updates using serial port protocol (SPP) over Bluetooth. However, the packet format for OTA updates is slightly different than the packet type that is used to exchange directives and events. The OTA update also uses a separate RFCOMM connection. (The RFCOMM UUID for OTA updates is 0x1101, whereas the RFCOMM UUID for directives and events is 0x1201.)
The packets for OTA updates conform to the following rules:
- For packet-level synchronization, the following special byte values are defined:
- Start of frame (SOF) =
0xF0 - End of frame (EOF) =
0xF1 - Escape (ESC) =
0xF2
- Start of frame (SOF) =
- All packets begin with a SOF byte and end with an EOF byte.
- If the data within a packet includes a SOF, EOF, or ESC value, the value is "escaped" by inserting the ESC byte followed by the original value XOR'd with ESC.
- Packets have a maximum non-escaped length of 264 bytes.
Request format
Requests from the Echo device to the gadget are in the following format:
Response Format
The gadget must respond to every command that the Echo device sends it. Responses from the gadget are in the following format:
Error codes
The following are the possible values of the Error field within the response:
| Error Code | Error Type | Description |
|---|---|---|
|
|
|
Command was successful. |
|
|
|
Command is unsupported. |
|
|
|
Firmware image is invalid. |
|
|
|
Invalid checksum in the command packet. |
Data validation
There are two types of data validation involved in OTA updates:
- Checksum of the individual requests and responses – This checksum enables the gadget and the Echo device to verify that the individual requests and responses are not corrupted. The checksum is in the
Checksumfield of each request from the Echo device, and the gadget must provide aChecksumin the response. - CRC of the entire binary image – The Echo device sends the CRC of the entire binary image in the
CRC32field of theCMD_WRITE_METADATAcommand. The gadget can use this CRC in multiple ways. For example, to verify that the gadget received the image from the Echo device correctly, the gadget can compare this CRC to the CRC that it calculated using the data it received from all theCMD_WRITEcommands. The gadget can also use the CRC to verify that it downloaded the image to flash correctly. When you calculate the CRC of the entire binary image, include 1) theCMD_WRITE_SIGNATUREpayload (reserved 4 bytes +OTAVersion4 bytes + the rest of the signature) and 2) all of theCMD_WRITEdata except for the trailing zeroes in the lastCMD_WRITE.
Command reference
This section describes requests and responses for the following commands:
CMD_BATTERY (0x09)
The purpose of this command is to query whether the gadget is in a state sufficient to perform the OTA update. Because battery level is an example of a factor that might affect this decision, this command is called CMD_BATTERY for now, but is subject to change.
Regardless of the influencing factors, the gadget should return a value above 0x0A to indicate that it is ready for the update, or a value below 0x0A to indicate that it is not ready.
Request Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The command ID. |
|
|
|
1 |
Reserved. |
|
|
|
2 |
Checksum for this request. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
Response Fields
| Field | Type | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The ID of the command that this response applies to. |
|
|
|
1 |
The error status of the command, as reported by the gadget. |
An error code. |
|
|
1 |
Indicator of the readiness of the gadget to perform the update. |
Range: |
|
|
2 |
Checksum for this response. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
CMD_ERASE (0x03)
This command requests the gadget to erase its flash buffer.
An erasure can take several seconds to complete. Therefore, after sending CMD_ERASE, the Echo device sends the gadget a CMD_STATUS command repeatedly until the gadget returns 0x00 to indicate that erasure is complete.
Request Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The command ID. |
|
|
|
1 |
Reserved. |
|
|
|
2 |
Checksum for this request. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
Response Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The ID of the command that this response applies to. |
|
|
|
1 |
The error status of the command, as reported by the gadget. |
An error code. |
|
|
2 |
Checksum for this response. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
CMD_STATUS (0x02)
This command requests the flash buffer status from the gadget. The purpose is to determine the completion of writes and erasures of the flash buffer.
Request Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The command ID. |
|
|
|
1 |
Reserved. |
|
|
|
2 |
Checksum for this request. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
Response Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The ID of the command that this response applies to. |
|
|
|
1 |
The error status of the command, as reported by the gadget. |
An error code. |
|
|
1 |
Indicates whether the flash buffer is being erased or copied. |
|
|
|
2 |
Checksum for this response. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
CMD_VERSION (0x08)
This command requests the gadget to return the OTA version of the firmware image that is currently installed.
Request Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The command ID. |
|
|
|
1 |
Reserved. |
|
|
|
2 |
Checksum for this request. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
Response Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The ID of the command that this response applies to. |
|
|
|
1 |
The error status of the command, as reported by the gadget. |
An error code. |
|
|
4 |
32-bit unsigned integer, big endian, that specifies the OTA version of the firmware that is currently installed on the gadget. |
Before the gadget receives its first firmware update, its OTA version must be |
|
|
2 |
Checksum for this response. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
CMD_WRITE (0x05)
This command, which the Echo device sends repeatedly, downloads the binary image from the Echo device to the gadget. The Echo device sends this command after it sends CMD_WRITE_METADATA and CMD_WRITE_SIGNATURE.
Note the following information about the CRC calculation for CMD_WRITE:
- The gadget can calculate the CRC incrementally as it receives each
CMD_WRITE. When the gadget receives the lastCMD_WRITE, it has the CRC of the entire image, and can compare that to theCRC32that it received fromCMD_WRITE_METADATA. - The last
CMD_WRITEpacket might contain trailing zeroes to pad the data size to 256 bytes. You should not write or consider these trailing zeroes in the CRC calculation. You can drop the trailing zeroes by tracking the total size of the data received inCMD_WRITEand comparing that to the size of the data received inCMD_WRITE_METADATA.
Request Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The command ID. |
|
|
|
1 |
Reserved. |
|
|
|
4 |
The address, in little endian, at which to write the current section of the OTA image. |
This value starts at |
|
|
256 |
Up to 256 bytes of data to be written at the location specified by the |
Any value. |
|
|
2 |
Checksum for this request. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
Response Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The ID of the command that this response applies to. |
|
|
|
1 |
The error status of the command, as reported by the gadget. |
An error code. |
|
|
2 |
Checksum for this response. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
CMD_WRITE_METADATA (0x10)
This command writes the metadata of the image to the gadget's flash. It is the first "write" command that the Echo device sends to the gadget during the writing phase of the OTA update. Next it sends CMD_WRITE_SIGNATURE, and then it sends CMD_WRITE repeatedly.
Request Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The command ID. |
|
|
|
1 |
Reserved. |
|
|
|
4 |
The file descriptor sector. |
Always |
|
|
4 |
The file size in big endian notation. |
For example, a file size of 164,136 ( |
|
|
4 |
The CRC32 value of the entire binary image file (no padding, no escaping). |
For example, a CRC32 of |
|
|
The rest of the packet. |
This is undefined padding. |
All bytes are typically |
|
|
2 |
Checksum for this request. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
Response Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The ID of the command that this response applies to. |
|
|
|
1 |
The error status of the command, as reported by the gadget. |
An error code. |
|
|
2 |
Checksum for this response. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
CMD_WRITE_SIGNATURE (0x11)
This command, which the Echo device sends after CMD_WRITE_METADATA but before CMD_WRITE, writes signature data to the gadget's flash. Note the following:
- The payload of this command is considered to be the first sector of the OTA image, so it is included in the CRC calculation of
CMD_WRITE_METADATA. - The gadget must store the
OTAVersionin its non-volatile memory as its new OTA version, and then respond to this command with error code0x00to indicate that it received the command.
Request Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The command ID. |
|
|
|
1 |
Reserved byte in the header. |
|
|
|
4 |
The file descriptor sector. |
Always |
|
|
4 |
Reserved bytes in the payload. |
N/A |
|
|
4 |
The version of the OTA update. |
N/A |
|
|
The rest of the packet. |
The signature data, which you can ignore. |
N/A |
|
|
2 |
Checksum for this request. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
Response Fields
| Field | Number of Bytes | Description | Value |
|---|---|---|---|
|
|
1 |
Start of frame indicator. |
|
|
|
1 |
The ID of the command that this response applies to. |
|
|
|
1 |
The error status of the command, as reported by the gadget. |
An error code. |
|
|
2 |
Checksum for this response. |
Sum of all non-escaped bytes in the |
|
|
1 |
End of frame indicator. |
|
