Data Packet for Bluetooth Low Energy
This topic describes the packet format that Echo devices and gadgets use to exchange data over Bluetooth Low Energy (BLE).
For Alexa Gadgets Toolkit issues related to Bluetooth, see Bluetooth on the known issues page.
- Concepts
- Packet format
- Header
- Payload types
- ACK packet details
- Result codes
- Example packet sequences
Concepts
To understand the packets that Echo devices and gadgets exchange over BLE, you need to be familiar with the concepts of streams and transactions.
Streams
Streams provide a way to separate packets into different types. Gadgets must support the following streams:
- Control stream – This stream enables Echo devices and gadgets to communicate. The payloads for these packets manage the gadget configuration, exchange device information during the initial handshake, and so on.
- Alexa stream – Echo devices and gadgets use this stream to send directives and events for all Alexa Gadgets Toolkit interfaces.
- Over-the-air (OTA) stream – Echo devices and gadgets use this stream to update the gadget's firmware in the OTA update process.
At any given time, there is only one control stream, one Alexa stream, and one OTA stream (if applicable). Each packet belongs to one of these streams, which is specified in the stream ID field of the packet's header. The stream ID enables the receiver (gadget or Echo device) to interpret the packet's payload.
Transactions
Transactions are logical chunks of data that can be acted upon. A transaction can be a single packet of data or multiple packets of data, depending on the MTU size. The transaction type, which is at offset 12 in the header of each packet, specifies whether the packet is at the beginning, end, or middle of the transaction. The combination of transaction ID and stream ID uniquely identifies a message.
Packet format
Packets are binary and each field is stored as big endian. Each packet consists of a header and a payload. The header contains a stream ID, transaction ID, and so on. The format of the payload depends on the stream type (control stream or Alexa stream).
Acknowledgment (ACK) packets
If the Echo device requests it, the gadget must send the Echo device an ACK packet in response to the last packet of the transaction. ACK packets have the same overall packet structure as other packets, but certain fields must be set to the values specified in ACK packet details.
To determine if the transaction requires an ACK, the gadget should check the ACK flag (offset 14) in the header of the last packet of the transaction. Note that you can identify the last packet of the transaction by the packet's transaction type (offset 12): in a multiple-packet transaction, the last packet's transaction type will be 10; in single-packet transactions, the packet's transaction type will be 00.
The ACK packet must use the same stream ID and transaction ID of the transaction being acknowledged. Both the control stream and the Alexa stream support ACK packets. Currently, the Echo device can request that the gadget send an ACK packet, but not vice versa.
Header
Each packet has a header. The size of the packet's header depends on two factors:
- Location of the packet within the transaction – The header of the first packet of the transaction contains an additional 24 bits (a reserved field and a transaction length field).
- Payload length field extension – The payload length field in the header can either be unextended (8 bits) or extended (16 bits). The one-bit length extender field indicates whether the payload length is extended.
The following are visual representations of headers with unextended and extended payload length fields. As indicated, some fields are only present in the first packet of the transaction. For examples of Alexa.Discovery.Discover
directive headers for different MTU and total transaction length sizes, see Example packet sequences.
Header with unextended payload length field

Header with extended payload length field

The fields in the header are as follows:
Offset (bits) | Length (bits) | Description | Value |
---|---|---|---|
0 | 4 |
The stream ID. |
|
4 | 4 |
The transaction ID. |
A number that is unique per transaction for a stream ID at any given point of time. Packets that belong to different streams can have the same transaction ID at the same time. |
8 | 4 |
Sequence number. Since this is four bits long, it supports in-place sequencing of up to 16 packets at a given point in time. Sequence numbers can roll over. When packets are out of order (and therefore sequence numbers are out of order), you should drop the transaction. For example, 0 after 16 is in order, but 10 after 16 is out of order. |
A number that is incremented per transaction. |
12 | 2 |
Transaction type, which indicates where the packet is within the transaction. The transaction type and protocol of a single transaction are defined by the first packet of the transaction. |
|
14 | 1 |
Acknowledgement (ACK) flag. |
|
15 | 1 |
Length extender. |
|
16 | 8 | Reserved. This is only present in the first packet of the transaction. |
|
24 | 16 | Total transaction length. This is only present in the first packet of the transaction. Single-packet transactions should include this field. | Transaction length, in bytes. |
40 or 16 | 8 or 16 |
Payload length. Every packet has its own payload length. |
Payload length, in bytes. |
Payload types
Each payload is in protocol buffer format using proto3 syntax. The payload can be one of two types, depending on the stream type:
Control stream payload
The control stream enables an Echo device and a gadget to communicate. Each control stream message consists of an envelope, which contains a payload.
Envelope
The control stream payload's envelope, in protocol buffer format, is as follows:
message ControlEnvelope {
Command command = 1;
oneof payload {
// Response
Response response = 9;
// Messages
// ...
}
}
enum Command {
NONE = 0;
GET_DEVICE_INFORMATION = 20;
GET_DEVICE_FEATURES = 28;
UPDATE_COMPONENT_SEGMENT = 94;
APPLY_FIRMWARE = 95;
}
Response
When the gadget receives a supported control stream message from the Echo device, the gadget must send a control stream message in response. The response message can have a payload, depending on the command associated with that message. If a gadget receives a control stream message that it does not understand, it should respond with a result code of UNSUPPORTED
.
message Response {
ErrorCode error_code = 1;
oneof payload {
// Optional data
}
}
enum ErrorCode {
SUCCESS = 0;
UNKNOWN = 1;
UNSUPPORTED = 3;
}
Specific control stream payloads
Control stream packets that the gadget and the Echo device exchange can have one of the following payloads:
Message | Command ID | Who sends it | When it's used |
---|---|---|---|
20 |
Echo device |
||
20 |
Gadget |
||
28 |
Echo device |
||
28 |
Gadget |
||
94 |
Echo device |
||
94 |
Gadget |
||
95 |
Echo device |
||
95 |
Gadget |
DeviceInformation command (Command ID 20)
To query the gadget for its device information during the handshake, the Echo device sends the gadget a control envelope with the command set to 20 (GET_DEVICE_INFORMATION
). For an example of this packet, see the sample code described in Bluetooth Low Energy Handshake Sample Code.
DeviceInformation response
When the Echo device queries the gadget for its device information during the handshake, the gadget must respond with a packet that contains a control envelope with a payload that contains device information.
For an example of this packet, see the sample code described in Bluetooth Low Energy Handshake Sample Code.
message DeviceInformation {
string serial_number = 1;
string name = 2;
repeated Transport supported_transports = 3;
string device_type = 4;
}
enum Transport {
BLUETOOTH_LOW_ENERGY = 0;
}
Field Name | Description | Value | Required |
---|---|---|---|
|
Unique device serial number (DSN) of the gadget. |
The same string as the |
Yes |
|
A user-friendly name of the gadget. This name can be changed by a user. |
The same string as the |
Yes |
|
A collection of transports that the gadget supports. This field enables the Echo device to choose the best transport to communicate with the gadget over. |
A list of supported transports. This value is currently [ |
Yes |
|
Unique device type assigned by Amazon. |
The same string as |
Yes |
DeviceFeatures command (Command ID 28)
To query the gadget for its device features during the handshake, the Echo device sends the gadget a control envelope with the command set to 28 (GET_DEVICE_FEATURES
). For an example of this packet, see the sample code described in Bluetooth Low Energy Handshake Sample Code.
DeviceFeatures response
When the Echo device queries the gadget for its device features, the gadget must respond with a packet that specifies the features that the gadget supports. For an example of this packet, see the sample code described in Bluetooth Low Energy Handshake Sample Code.
message DeviceFeatures {
uint64 features = 1;
uint64 device_attributes = 2;
}
Field Name | Description | Value | Required |
---|---|---|---|
|
The features that the gadget supports. |
A |
Yes |
|
Reserved. |
A |
Yes |
UpdateComponentSegment command (Command ID 94)
If the Alexa service determines that the gadget needs an OTA update, the Echo device sends the gadget an UpdateComponentSegment
message. For an example of this packet, see the sample code described in Bluetooth Low Energy Handshake Sample Code.
message UpdateComponentSegment {
string component_name = 1;
uint32 component_offset = 2;
uint32 segment_size = 3;
string segment_signature = 4;
}
Field Name | Description | Value | Required |
---|---|---|---|
|
The component name. |
A string. |
Yes |
|
The offset of the component, in bytes. |
A |
Yes |
|
The size of the firmware image, in bytes. |
A |
Yes |
|
The SHA-256 signature of the firmware image. |
A base-16-encoded string that represents the SHA-256 hash of the entire firmware image. |
Yes |
UpdateComponentSegment response
After the gadget receives the entire firmware image, it must respond to the UpdateComponentSegment
command with a message that specifies command ID 94 but does not have a payload.
ApplyFirmware command (Command ID 95)
During an OTA update, the Echo device sends the gadget an ApplyFirmware
message to instruct the gadget to use the new firmware. For an example of this packet, see the sample code described in Bluetooth Low Energy Handshake Sample Code.
message ApplyFirmware {
FirmwareInformation firmware_information = 1;
bool restart_required = 2;
}
message FirmwareInformation {
uint32 version = 1;
string name = 2;
repeated FirmwareComponent components = 3;
string locale = 4;
string version_name = 5;
}
message FirmwareComponent {
uint32 version = 1;
string name = 2;
uint32 size = 3;
string signature = 4;
}
Field Name | Description | Value | Required |
---|---|---|---|
|
Message that contains information such as the new firmware version, name, and so on. |
One |
Yes |
|
Reserved. |
Ignore this value. |
Yes |
|
The version of the firmware that is being installed on the gadget. |
A |
Yes |
|
The version string that corresponds to the version of the firmware image that was uploaded to the Alexa cloud. |
A version string. Example: |
Yes |
|
Message that contains information such as the firmware version, component name, and so on. |
One |
Yes |
|
String that contains the language and country. |
May be null or blank. |
Yes |
|
The version name. |
Currently the same as |
Yes |
|
The firmware version. |
Currently the same as |
Yes |
|
The component name. |
A string. |
Yes |
|
The size of the firmware image, in bytes. |
A |
Yes |
|
Reserved. |
Ignore this value. |
Yes |
ApplyFirmware response
Immediately after the gadget receives the ApplyFirmware
command, it must respond with a message that specifies command ID 95 but does not have a payload.
Alexa stream payload
For information on the Alexa stream payload format, see Protocol Buffer Format for Alexa Gadgets.
ACK packet details
If the ACK flag (offset 14) is set in the header of the last packet of the transaction, the gadget must respond with an ACK packet. Note that you can identify the last packet of the transaction by the packet's transaction type (offset 12): in a multiple-packet transaction, the last packet's transaction type will be 10; in single-packet transactions, the packet's transaction type will be 00.
The ACK packet has the same overall packet structure as other packets, but its field values are restricted to certain values as follows:
Offset (bits) | Length (bits) | Description | Value |
---|---|---|---|
0 |
4 |
The stream ID of the packet that requested the acknowledgement. |
One of the following: |
4 | 4 |
The transaction ID of the packet that requested the acknowledgement. |
The associated transaction ID. |
8 | 4 | Sequence number. | This can be any value. |
12 | 2 |
Transaction type. |
|
14 | 1 |
Whether this packet is an ACK or a NACK. |
|
15 | 1 |
Length extender. |
|
16 | 8 |
Reserved. |
|
24 | 8 |
Length of the ACK packet, in bytes. |
|
32 | 8 |
Reserved. |
|
40 | 8 |
A result code, which depends on whether this is an ACK or a NACK. |
|
Result codes
Some messages contain a result code in their payload. Result codes are mostly used in response messages. Unless otherwise noted, the gadget and the Echo device are only expected to differentiate between two types of result codes: success and not success. While the specific error message does not typically make a functional difference, result codes can help with debugging.
For some messages, any result code but success is a reason to disconnect because without a success response to these messages, the core functionality of the gadget cannot be guaranteed. If the following messages receive an error response, a disconnect will occur:
GetDeviceInformation
GetDeviceFeatures
The following table lists all of the result codes that can be used in response to a message.
Error | Hex value | Description |
---|---|---|
|
|
The message was valid and acted on (if applicable) successfully. |
|
|
The message was valid but resulted in a failure or error. |
|
|
The message was invalid because it contained a command or other field that was not supported by the receiver. This should be used for any command that the receiver doesn't support. It should also be used for cases where the message could not be acted on because of the state of the receiver. For example, the Echo device might send a |
Example packet sequences
The following figures show example packet sequences for an Alexa.Discovery.Discover
directive with different MTU and total transaction length sizes. One example uses the payload length extender also.
Example with small MTU
In the following example, the MTU is 23 bytes and the total transaction length is 35 bytes.

Example with larger MTU
In the following example, the MTU is 247 bytes and the total transaction length is 490 bytes.

Example with length extender
In the following example, the MTU is 247 bytes, the total transaction length is 490 bytes, and the first packet uses the length extender to signify that the payload is 16 bits.

Last updated: Feb 14, 2022