Understand the Alexa Gadgets Toolkit
The Alexa Gadgets Toolkit enables you to build your own Alexa Gadget. An Alexa Gadget is an Alexa-connected accessory that interacts with compatible Amazon Echo devices over Bluetooth. By using the Alexa Gadgets Toolkit, you can:
- Access your gadget from an Alexa skill – Your skill can trigger gadget behaviors, and act on information it receives from your gadget. To support this, you define a Custom Interface and then use the Custom Interface Controller to access the information from an Alexa skill.
- Trigger gadget behaviors in reaction to Alexa's native capabilities – Outside of a skill, your gadget can receive the following information from the Echo device that it is connected to:
- Speechmark data – Enables your gadget to synchronize to Alexa's text-to-speech in real time. This information is provided through the SpeechData interface.
- Notifications – Enables the gadget to inform users that new content is available from Alexa domains or an enabled Alexa skill. This information is accessible through the Notifications interface.
- Timers, alarms, and reminders – Enables your gadget to be notified of the setting and clearing of the Echo device's timers, alarms, and reminders. This information is available through a combination of the Alerts interface (Beta) and the StateListener interface.
- Wake word detection – Informs your gadget that the user said the Echo device's wake word. Your gadget gets this information through the StateListener interface.
- Current time – Provides your gadget the current time on the Echo device. This time information (Beta) is available through the StateListener interface.
- Tempo data of songs from Amazon Music – Sends your gadget tempo data for Amazon Music that the Echo device is playing. You access this through the MusicData interface (Beta).
Your gadget can support all of the interfaces listed previously, but only Custom Interfaces can be accessed from an Alexa skill.
This topic provides an overview of how gadgets interact with Alexa, lists the Echo devices that support gadgets, and discusses things to know before you get started.
How gadgets interact with Alexa
Instead of communicating with Alexa directly, gadgets interact with Alexa through a compatible Echo device over Bluetooth. Gadgets use the directives and events defined by the Alexa Gadgets interfaces to exchange information with the Echo device. The Echo device handles all communications with Alexa.
The following figure shows how a gadget interacts with an Echo device, and where the Alexa Gadgets interfaces fit in.
The following steps describe the communication flow between a gadget, an Echo device, the Alexa cloud, and a skill:
- Bluetooth pairing – The gadget and the Echo device connect over Bluetooth as follows:
- The user puts the gadget in Bluetooth pairing mode, and then activates pairing mode on the Echo device. To activate pairing mode on an Echo device without a screen, the user uses the Alexa app. If the Echo device has a touchscreen, the user initiates pairing by selecting an option on the screen.
- The Echo device searches for a gadget to pair with. If the pairing is successful, the gadget and the Echo device connect over Bluetooth.
- Discovery – The Echo device sends the gadget a directive to query its details and capabilities. The gadget responds with an event that contains this information.
- Information flow – From then on, the gadget and the Echo device communicate as follows, depending on the interface type:
- Custom Interfaces – The skill sends custom directives to the gadget via the Alexa cloud and the Echo device. The gadget sends custom events to the skill via the Echo device and the Alexa cloud.
- Alexa Gadgets Toolkit interfaces – The Echo device sends directives (such as wake word detection, alerts, and so on) to the gadget, if the gadget declared support for them in the discovery phase described previously.
Echo devices that support gadgets
The following table lists the Echo devices that support gadgets, and which Bluetooth protocol(s) the Echo devices can use to communicate with a gadget.
| Echo device | Bluetooth support |
|---|---|
|
Echo (1st, 2nd, 3rd, and 4th generation) |
|
|
Echo Dot (1st, 2nd, 3rd, and 4th generation) |
|
|
Echo Dot Kids Edition (2nd, 3rd, and 4th generation) |
Classic BT and BLE |
|
Echo Dot with Clock (3rd and 4th generation) |
Classic BT and BLE |
|
Echo Flex |
Classic BT and BLE |
|
Echo Input |
Classic BT and BLE |
|
Echo Plus (1st and 2nd generation) |
Classic BT and BLE |
|
Echo Show (1st and 2nd generation) |
Classic BT and BLE |
|
Echo Show (5, 8, and 10) |
Classic BT and BLE |
|
Echo Spot |
Classic BT and BLE |
|
Echo Studio |
Classic BT and BLE |
Before you get started
Before you create a gadget, keep the following in mind:
- Locales – You may only distribute, sell, or market for sale Alexa Gadgets in the following territories: Australia, Austria, Brazil, Canada, France, Germany, India, Ireland, Italy, Japan, Mexico, New Zealand, Spain, the United Kingdom, and the United States.
- Bluetooth connections – The Echo Dot and Echo Spot only support up to three Bluetooth connections. If you encounter challenges when pairing your gadget, ensure that the Echo device has enough Bluetooth connections available.
- Software version – Ensure that your Echo device has the following or higher software version:
- Echo (1st gen), Echo Dot (1st gen) – 635556820
- Echo (2nd gen), Echo Plus (1st gen), Echo Dot (2nd gen) – 635559320
- Echo Dot (3rd gen), Echo Plus (2nd gen) – 2315741060
- Echo Show (1st and 2nd gen), Echo Spot – 641574920
- Echo Show 5 – 2584218500
- Echo Input – 2315741060
- Echo Dot with Clock, Echo Flex, Echo Studio – First version released
- Pairing and connectivity status – To validate whether your gadget is successfully paired to an Echo device, do the following:
- Echo devices without a screen – Go to Alexa Devices > [Echo device] > Bluetooth Devices in the Alexa app.
- Echo devices with a screen – Go to Settings > Bluetooth Devices on the screen of the Echo device.