Pairing and Connection Flow for Alexa Gadgets over Bluetooth Low Energy
This topic describes how to establish a Bluetooth Low Energy (BLE) connection between a gadget and an Echo device that have never been paired, or whose pairing information has been removed.
For the process by which a paired gadget can reconnect to an Echo device after becoming disconnected from it, see Reconnection Flow for Alexa Gadgets over Bluetooth Low Energy.
For Alexa Gadgets Toolkit issues related to Bluetooth, see Bluetooth on the known issues page.
- Phase 1: Device discovery
- Phase 2: Connection and pairing
- Phase 3: GATT discovery
- Phase 4: Handshake
- Phase 5: Alexa Gadgets Toolkit directives and events
The following figure shows how a gadget and an Echo device establish a BLE connection with which to exchange Alexa Gadgets directives and events. The steps are explained after the figure.
Phase 1: Device discovery
The Echo device and the gadget discover each other over BLE as follows:
- The user puts the gadget into advertising mode. This procedure depends on the gadget. For example, a button gadget might use a long press. Gadgets with touchscreens might enable the user to initiate this process through an option on the screen. Once in advertising mode, the gadget starts broadcasting advertisement packets.
- The user puts the Echo device into pairing mode. For Echo devices without a screen, a user can put an Echo device into pairing mode by using the Amazon Alexa app. In the Alexa app, the user goes to Settings, selects the Echo device, and then selects Pair Alexa Gadget under Connected Devices. If the Echo device has a screen, the user follows on-screen instructions to initiate pairing. Once in pairing mode, the Echo device starts scanning for Bluetooth devices within range.
- The Echo device discovers and reads the gadget's advertisement packet, which contains the data listed in Advertisement packet for pairing.
Phase 2: Connection and pairing
After finding the gadget, the Echo device pairs with the gadget using the Bluetooth LE Secure Connections pairing process. Encryption is mandatory. When pairing is complete, the gadget and the Echo device do not need to be paired again, even after they are disconnected, unless they have become unpaired.
Phase 3: GATT discovery
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
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
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
- The gadget responds with a
Discover.Responseevent 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.