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
  • Request format
  • Response Format
• Data validation
• Command reference
  • CMD_BATTERY (0x09)
  • CMD_ERASE (0x03)
  • CMD_STATUS (0x02)
  • CMD_VERSION (0x08)
  • CMD_WRITE (0x05)
  • CMD_WRITE_METADATA (0x10)
  • CMD_WRITE_SIGNATURE (0x11)

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
• 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
0x00	ERR_NONE	Command was successful.
0x01	ERR_UNKNOWN	Command is unsupported.
0x02	ERR_INVALID	Firmware image is invalid.
0x03	ERR_CKSUM	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 Checksum field of each request from the Echo device, and the gadget must provide a Checksum in the response.
• CRC of the entire binary image – The Echo device sends the CRC of the entire binary image in the CRC32 field of the CMD_WRITE_METADATA command. 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 the CMD_WRITE commands. 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) the CMD_WRITE_SIGNATURE payload (reserved 4 bytes + OTAVersion 4 bytes + the rest of the signature) and 2) all of the CMD_WRITE data except for the trailing zeroes in the last CMD_WRITE.

Command reference

This section describes requests and responses for the following commands:

• CMD_BATTERY
• CMD_ERASE
• CMD_STATUS
• CMD_VERSION
• CMD_WRITE
• CMD_WRITE_METADATA
• CMD_WRITE_SIGNATURE

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
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The command ID.	0x09
Reserved	1	Reserved.	0x00
Checksum	2	Checksum for this request.	Sum of all non-escaped bytes in the Command and Reserved fields.
End of frame	1	End of frame indicator.	0xF1

Response Fields

Field	Type	Description	Value
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The ID of the command that this response applies to.	0x09
Error	1	The error status of the command, as reported by the gadget.	An error code. 0x00 means success.
Battery level	1	Indicator of the readiness of the gadget to perform the update.	Range: 0 - 100. Above 0x0A = the gadget is ready to perform the update. Below 0x0A = the gadget is not ready to perform the update.
Checksum	2	Checksum for this response.	Sum of all non-escaped bytes in the Command, Error and Battery level fields.
End of frame	1	End of frame indicator.	0xF1

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
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The command ID.	0x03
Reserved	1	Reserved.	0x00
Checksum	2	Checksum for this request.	Sum of all non-escaped bytes in the Command and Reserved fields.
End of frame	1	End of frame indicator.	0xF1

Response Fields

Field	Number of Bytes	Description	Value
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The ID of the command that this response applies to.	0x03
Error	1	The error status of the command, as reported by the gadget.	An error code. 0x00 means success.
Checksum	2	Checksum for this response.	Sum of all non-escaped bytes in the Command and Error fields.
End of frame	1	End of frame indicator.	0xF1

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
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The command ID.	0x02
Reserved	1	Reserved.	0x00
Checksum	2	Checksum for this request.	Sum of all non-escaped bytes in the Command and Reserved fields.
End of frame	1	End of frame indicator.	0xF1

Response Fields

Field	Number of Bytes	Description	Value
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The ID of the command that this response applies to.	0x02
Error	1	The error status of the command, as reported by the gadget.	An error code. 0x00 means success.
Flash status	1	Indicates whether the flash buffer is being erased or copied.	0x00 = The flash buffer is ready for reading or writing. 0x01 = The flash buffer is being erased. 0x03 = The flash buffer is being copied.
Checksum	2	Checksum for this response.	Sum of all non-escaped bytes in the Command and Error, and Flash status fields.
End of frame	1	End of frame indicator.	0xF1

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
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The command ID.	0x08
Reserved	1	Reserved.	0x00
Checksum	2	Checksum for this request.	Sum of all non-escaped bytes in the Command and Reserved fields.
End of frame	1	End of frame indicator.	0xF1

Response Fields

Field	Number of Bytes	Description	Value
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The ID of the command that this response applies to.	0x08
Error	1	The error status of the command, as reported by the gadget.	An error code. 0x00 means success.
Version	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 0. After that, the gadget gets its OTA version from CMD_WRITE_SIGNATURE during the update process.
Checksum	2	Checksum for this response.	Sum of all non-escaped bytes in the Command, Error, and Version fields.
End of frame	1	End of frame indicator.	0xF1

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 last CMD_WRITE, it has the CRC of the entire image, and can compare that to the CRC32 that it received from CMD_WRITE_METADATA.
• The last CMD_WRITE packet 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 in CMD_WRITE and comparing that to the size of the data received in CMD_WRITE_METADATA.

Request Fields

Field	Number of Bytes	Description	Value
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The command ID.	0x05
Reserved	1	Reserved.	0x00
Address	4	The address, in little endian, at which to write the current section of the OTA image.	This value starts at 0x00 0x02 0x00 0x00 and increments by 256 each time. For example, the next sector would be 0x00 0x03 0x00 0x00.
Data	256	Up to 256 bytes of data to be written at the location specified by the Address field.	Any value.
Checksum	2	Checksum for this request.	Sum of all non-escaped bytes in the Command, Reserved, Address, and Data fields.
End of frame	1	End of frame indicator.	0xF1

Response Fields

Field	Number of Bytes	Description	Value
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The ID of the command that this response applies to.	0x05
Error	1	The error status of the command, as reported by the gadget.	An error code. 0x00 means success.
Checksum	2	Checksum for this response.	Sum of all non-escaped bytes in the Command and Error fields.
End of frame	1	End of frame indicator.	0xF1

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
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The command ID.	0x10
Reserved	1	Reserved.	0x00
Address	4	The file descriptor sector.	Always 0x00 0x00 0x00 0x00.
Size	4	The file size in big endian notation.	For example, a file size of 164,136 (0x02 0x81 0x28) bytes would be represented as 0x00 0x02 0x81 0x28.
CRC32	4	The CRC32 value of the entire binary image file (no padding, no escaping).	For example, a CRC32 of 0xA4 0xA2 0xA7 0xD6 would be represented as 0xA4 0xA2 0xA7 0xD6.
Padding	The rest of the packet.	This is undefined padding.	All bytes are typically 0xFF.
Checksum	2	Checksum for this request.	Sum of all non-escaped bytes in the Command, Reserved, Address, Size, CRC32, and Padding fields.
End of frame	1	End of frame indicator.	0xF1

Response Fields

Field	Number of Bytes	Description	Value
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The ID of the command that this response applies to.	0x10
Error	1	The error status of the command, as reported by the gadget.	An error code. 0x00 means success.
Checksum	2	Checksum for this response.	Sum of all non-escaped bytes in the Command and Error fields.
End of frame	1	End of frame indicator.	0xF1

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 OTAVersion in its non-volatile memory as its new OTA version, and then respond to this command with error code 0x00 to indicate that it received the command.

Request Fields

Field	Number of Bytes	Description	Value
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The command ID.	0x11
Reserved	1	Reserved byte in the header.	0x00
Address	4	The file descriptor sector.	Always 0x00 0x01 0x00 0x00.
Reserved	4	Reserved bytes in the payload.	N/A
OTAVersion	4	The version of the OTA update.	N/A
Signature	The rest of the packet.	The signature data, which you can ignore.	N/A
Checksum	2	Checksum for this request.	Sum of all non-escaped bytes in the Command, Reserved, and Signature fields.
End of frame	1	End of frame indicator.	0xF1

Response Fields

Field	Number of Bytes	Description	Value
Start of frame	1	Start of frame indicator.	0xF0
Command	1	The ID of the command that this response applies to.	0x11
Error	1	The error status of the command, as reported by the gadget.	An error code. 0x00 means success.
Checksum	2	Checksum for this response.	Sum of all non-escaped bytes in the Command and Error fields.
End of frame	1	End of frame indicator.	0xF1