OTA Update Commands (Classic Bluetooth)

Note: Sign in to the developer console to build or publish your skill.

Note: On December 31, 2021, we paused support for third-party device makers working with Alexa Gadgets, while we work to create an even better developer and customer experience. Please stay tuned to the Amazon developer portal for updates. In the interim, please visit the landing pages for Alexa Voice Service, Alexa Connect Kit, and Alexa Skills Kit to discover ways you can provide new customer experiences with voice.

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

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`

Last updated: Feb 14, 2022