Reconnection Flow for Alexa Gadgets over Bluetooth Low Energy

Note: Submit your skill and see it come to life.

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.

If a gadget and an Echo device are paired over Bluetooth Low Energy (BLE) but have become disconnected, the Echo device and gadget can reconnect as described in this topic.

For Alexa Gadgets Toolkit issues related to Bluetooth, see Bluetooth on the known issues page.

Overview
Phase 1: Device discovery
Phase 2: Connection
Phase 3: GATT discovery
Phase 4: Handshake
Phase 5: Alexa Gadgets Toolkit directives and events

Overview

The following figure shows how an Echo device connects to a gadget that it was paired to but disconnected from. The steps are explained after the figure.

Bluetooth Low Energy Reconnection Flow with an Alexa Gadget

Phase 1: Device discovery

If the gadget and the Echo device become disconnected, the Echo device continually scans and attempts to reconnect to the gadget. Therefore, anytime the gadget is paired but not connected to the Echo device, your gadget should advertise itself like it does in the initial connection, except that the advertisement packet should be the advertisement packet for reconnection. The Echo device then discovers and receives the gadget's advertisement packet.

Phase 2: Connection

The gadget and the Echo device re-establish a link-layer connection.

Phase 3: GATT discovery

In this step, which is identical to the GATT connection phase in the initial connection flow, the Echo device and the gadget negotiate the maximum transmission unit (MTU), which is the maximum length of the data packets that the gadget and the Echo device will exchange over BLE going forward. The Echo device and the gadget negotiate this value by exchanging the largest MTU that they each can support and choosing the lower of the two. During this negotiation, we recommend that your gadget specify its MTU as the maximum packet length that the gadget can support. Choosing a higher MTU size prevents unnecessary fragmentation of packets over the air, and therefore helps reduce latency and defragmentation overhead.

The Echo device then sends the gadget a request to connect to its Generic Attribute Profile (GATT) server. For this connection to be established, the gadget's local database must contain the settings listed in GATT settings. The GATT settings define the role of the Echo device and the gadget and how they will exchange data over a BLE connection. The Echo device also enables notifications on the Rx characteristic (attribute), so that the gadget will be able to transmit data to the Echo device.

Phase 4: Handshake

As in the initial connection flow, after the gadget and the Echo device establish a connection, the gadget must send the Echo device a protocol version (PV) packet. Upon receiving the PV packet, the Echo device determines whether it can communicate with the gadget based on the protocol versions that the gadget supports. Depending on this decision, the Echo device either continues the data exchange or closes the connection because it cannot communicate with the gadget.

If the Echo device has determined that it can communicate with the gadget further, the Echo device gets additional information from the gadget using a control stream. During this phase, the Echo device obtains the gadget's device attributes such as I/O capabilities, supported hardware features, and other features that the gadget supports. To do so, the Echo device queries the gadget for its device information, and the gadget responds with a device information packet. The Echo device then queries the gadget for its supported features, and the gadget responds with a device features packet.

Phase 5: Alexa Gadgets Toolkit directives and events

As in the initial connection flow, now that the Echo device and the gadget are connected, and Alexa has the gadget's information and supported features, the Echo device and the gadget exchange the following information using an Alexa stream (protocol buffer format):

The Echo device sends the gadget a Discover directive.
The gadget responds with a Discover.Response event that, along with other information, contains a hash of the DSN and the device type secret that your gadget was assigned when you registered it in the developer portal.
The Echo device and the gadget exchange directives and events that are defined by the Alexa Gadgets Toolkit interfaces.