Data Packet for 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.

When a gadget and an Echo device exchange data over a Classic Bluetooth connection, they use Serial Port Profile (SPP). This topic describes the packet format for this case.

Packet format
Cases that your gadget must handle

Packet format

Because packets can break up into multiple parts during transmission, the Alexa Gadgets interfaces use the following rules to denote packet boundaries:

Each packet must begin with a start of frame (SOF) = 0xF0.
Each packet must end with an end of frame (EOF) = 0xF1.
To escape characters in the payload, use ESC = 0xF2.

A packet is as follows:

The components of the packet are:

Description	Number of Bytes	Value
Start of frame (SOF)	1	Always `0xF0`
Packet ID	1	Always `0x02`
Error ID	1	Always `0x00`
Sequence ID	1	Rotating sequence that increments every time a packet is sent. Special characters (SOF, EOF, and ESC) are skipped.
Payload	Varies	The complete directive or event in protocol buffer format as described in Protocol Buffer Format for Alexa Gadgets. The payload must be reformatted to escape special characters (SOF, EOF, and ESC) using the following formula: Result = `(ESC<<8 \| ESC^Byte)`. Therefore, one byte is replaced by two bytes.
Checksum	2	A big-endian checksum that is calculated using the following formula: `Packet ID + Error ID + Payload (without escape)` Important: When you calculate the checksum, do not escape the payload. However, do escape the checksum itself when you encode and send the packet.
End of frame (EOF)	1	Always `0xF1`

Cases that your gadget must handle

In a Classic Bluetooth RFCOMM connection, the gadget receives data from the Echo device in a stream buffer, not necessarily packet by packet. The gadget's RFCOMM server attempts to fill the stream buffer with every byte it receives, and periodically flushes the buffer and returns the data to the application layer (and thus your packet-processing code) using a callback.

You therefore need to make sure that your gadget's packet-processing code operates on the packets extracted from the stream buffer, not the stream buffer itself. As such, your gadget must be able to handle cases where it receives:

One packet
Multiple packets
A fraction of a packet

For an example of how to extract packets from a stream buffer, see the Alexa Gadgets Sample Code GitHub repository.

Last updated: Feb 14, 2022