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
  • Streams
  • Transactions
• Packet format
  • Acknowledgement (ACK) packets
• Header
• Payload types
  • Control stream payload
    • Envelope
    • Response
    • Specific control stream payloads
  • Alexa stream payload
• ACK packet details
• Result codes
• Example packet sequences
  • Example with small MTU
  • Example with larger MTU
  • Example with length extender

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).

Acknowledgement (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:

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
• Alexa stream payload

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:

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;
}

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;
}

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; 
}

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; 
}

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:

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.

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.