Pair and Connect a Gadget to an Echo Device Over Classic Bluetooth

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.

This topic describes how to establish a Classic Bluetooth (BR/EDR) 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 Classic Bluetooth.

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

Overview
Discovery phase
Pairing phase
RFCOMM connection phase
Alexa Gadgets Toolkit directives and events
Troubleshooting

Overview

The following figure shows how a gadget and an Echo device establish a Classic Bluetooth connection with which to exchange Alexa Gadgets directives and events. The steps are explained after the figure.

Pairing and Connection Flow for an Alexa Gadget and an Echo Device over Classic Bluetooth

Discovery phase

The Echo device and the gadget discover each other over Classic Bluetooth as follows:

The user puts the gadget into pairing mode. This procedure depends on the gadget. For example, a button gadget might use a long press. If your gadget has a touchscreen, a user could enable pairing through an option on the screen.
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.
The Echo device scans for Bluetooth devices within range by sending out an inquiry request.
The gadget responds to the Echo device's inquiry request with an Extended Inquiry Response (EIR) that contains the parameters listed in Extended Inquiry Response settings.

Pairing phase

After finding the gadget and connecting to it over the link layer, the Echo device pairs with the gadget using the standard Bluetooth Secure Simple Pairing (SSP) process. To do so, the gadget must use the parameters listed in Pairing parameters. In addition to a pairing request and response, pairing entails the exchange of information such as I/O capabilities, link keys, and so on.

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.

RFCOMM connection phase

The Echo device then sends the gadget a request to connect to its RFCOMM server. For this connection to be established, the gadget's local Service Discovery Protocol (SDP) database must contain the settings listed in SDP database settings.

Alexa Gadgets Toolkit directives and events

The Echo device and the gadget now exchange the following information using 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.

Troubleshooting

If you encounter problems pairing or connecting your gadget to an Echo device, review the following tips.

Problem: The gadget cannot pair to the Echo device

Possible cause	Tips
The gadget's Bluetooth stack is not configured correctly.	Make sure that your gadget is configured with the settings specified in Pairing parameters. Check if the manufacturer of your gadget's embedded platform provides sample code for Bluetooth pairing.

Problem: The gadget can pair to an Echo device, but does not receive an RFCOMM connection request from the Echo device

Possible cause	Tips
The gadget did not send an SDP connection request to the Echo device.	Check if the manufacturer of your gadget's embedded platform provides sample code that sends an SDP service search request to a peer device. This search request will initiate an SDP connection with the Echo device. You can find the connection workflow in Pairing and Connection Flow for Alexa Gadgets over Classic Bluetooth.
The Echo device does not recognize the gadget as an Alexa Gadget. Instead, the Echo device thinks the gadget is a regular Bluetooth device.	Make sure that your gadget is configured with the settings specified in Extended Inquiry Response settings, because the Echo device relies on EIR to identify if a Bluetooth device is an Alexa Gadget. Check if the manufacturer of your gadget's embedded platform provides sample code that configures EIR settings. In addition, the ConnectionHelpers/EIR directory of the Alexa Gadgets Sample Code GitHub repository contains an implementation of EIR. Because the Echo device might cache the gadget's Bluetooth settings, the Echo device might not recognize your gadget immediately after you modify the gadget's EIR settings. Therefore, unpair your gadget, put your gadget in pairing mode, have the Echo device scan for Bluetooth devices so that it picks up the gadget's updated EIR settings, and then pair your gadget again.
The Echo device recognizes the gadget as an Alexa Gadget, but the Echo device fails to get the correct SDP response from the gadget.	The Echo device needs to discover which port your gadget's RFCOMM server is listening to so that it can send an RFCOMM connection request to the correct port. Therefore, make sure that your gadget is configured with the SDP database settings specified in SDP database settings. Check if the manufacturer of your gadget's embedded platform provides sample code that sets up an SDP server. In addition, the ConnectionHelpers/SDP directory of the Alexa Gadgets Sample Code GitHub repository contains a sample SDP data entry for the Cypress platform.

Problem: The gadget can pair to and receive an RFCOMM connection request from an Echo device, but does not receive an `Alexa.Discovery.Discover` directive from the Echo device

Possible cause Tips

Possible cause	Tips
The gadget's RFCOMM server is not set up correctly.	There is no need to debug the gadget's EIR and SDP settings because if the gadget receives an RFCOMM connection request from the Echo device, you know that 1) the Echo recognizes your gadget as an Alexa Gadget, and 2) the Echo device knows which RFCOMM port to connect to. The gadget's RFCOMM server is the possible cause because if the RFCOMM connection is successful, the Echo device sends an `Alexa.Discovery.Discover` directive to the gadget. The manufacturer of your gadget's embedded platform might provide SPP sample code that sets up an RFCOMM server.

The gadget's RFCOMM server is not set up correctly.

There is no need to debug the gadget's EIR and SDP settings because if the gadget receives an RFCOMM connection request from the Echo device, you know that 1) the Echo recognizes your gadget as an Alexa Gadget, and 2) the Echo device knows which RFCOMM port to connect to.
The gadget's RFCOMM server is the possible cause because if the RFCOMM connection is successful, the Echo device sends an Alexa.Discovery.Discover directive to the gadget.
The manufacturer of your gadget's embedded platform might provide SPP sample code that sets up an RFCOMM server.