Bluetooth: Peripheral Alexa Gadgets

The Peripheral Alexa Gadgets sample demonstrates how a Bluetooth® LE device can connect to an Amazon Echo device using the Alexa Gadgets Bluetooth Service and Profile.

Documentation for the Gadgets Service and Profile can be found at Alexa Gadgets Bluetooth LE.

Before a Gadget can be connected to an Amazon Echo device, you must register it with Amazon. See Alexa Gadgets Setup for information on how to do this.

Overview

When connected, the sample performs the handshake procedure and informs the peer of its supported capabilities. Directives sent by the connected peer are printed as log messages when CONFIG_LOG is set. Additionally, when the “wake word” State Update directive is received, LED 3 on the development kit is turned on.

Gadget capabilities

During the handshake procedure, the Gadget peripheral reports which capabilities it supports. Capabilities determine which interface directives the Gadgets will receive, as listed in Alexa Gadgets Interfaces.

The following table shows the mapping between capability configuration and supported interfaces:

Capability option

Interface

CONFIG_BT_ALEXA_GADGETS_CAPABILITY_ALERTS

Alerts interface

CONFIG_BT_ALEXA_GADGETS_CAPABILITY_MUSICDATA

Alexa.Gadget.MusicData interface

CONFIG_BT_ALEXA_GADGETS_CAPABILITY_SPEECHDATA

Alexa.Gadget.SpeechData interface

CONFIG_BT_ALEXA_GADGETS_CAPABILITY_STATELISTENER

Alexa.Gadget.StateListener interface

CONFIG_BT_ALEXA_GADGETS_CAPABILITY_NOTIFICATIONS

Alexa Gadgets Notifications interface

Gadget Custom Directives and Events

Custom directives sent from the peer to the Gadget are propagated using the BT_GADGETS_EVT_CUSTOM event. Custom directives do not require defining any additional data format.

This sample includes a rudimentary custom event type that lets you send a JSON-formatted string with your chosen custom event name and namespace, using the function bt_gadgets_profile_custom_event_json_send.

By default, the sample is configured to respond to the “Color cycler” custom skill. For instructions on how to create this custom skill, see Alexa Gadgets Github color cycler. Note that the skill code and configuration procedure is the same, even though the sample from this link uses a Raspberry Pi as a Gadget.

For more complex custom event types, you must define a custom event structure as described in Alexa Gadgets Custom Event. The custom event protobuf must be encoded using pb_encode() and the encoded buffer must be transmitted using bt_gadgets_profile_custom_event_send.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

nRF52 DK

PCA10040

nrf52dk_nrf52832

nrf52dk_nrf52832

nRF52 DK (emulating nRF52810)

PCA10040

nrf52dk_nrf52810

nrf52dk_nrf52810

The sample also has the following requirements:

External dependencies

This sample has some specific external dependencies.

Tools

This sample depends on an external protobuf compiler tool - Nanopb.

This tool must be downloaded manually.

Download Nanopb version 0.4.2 for your platform from the Nanopb Downloads site and extract the downloaded file to either this sample directory, the nRF Connect SDK installation directory, the tools folder in the nRF Connect SDK installation directory, or any other location where CMake can find it through a standard system PATH. Note that this sample directory is searched automatically for the presence of Nanopb. For example, if you are using Windows, download and extract nanopb-0.4.2-windows-x86.zip to this sample directory.

Once the Nanopb tool has been downloaded, the build process is the same as for other samples. The tool is invoked automatically by CMake.

Gadget registration

When registering the Gadget, you will receive two identifier strings:

  1. Device Amazon ID

  2. Device secret

You must update the CONFIG_BT_ALEXA_GADGETS_AMAZON_ID and CONFIG_BT_ALEXA_GADGETS_DEVICE_SECRET configuration options in prj.conf with the values that you received during the registration.

User interface

LED 1:

On when connected.

LED 2:

On when the handshake with a peer is completed.

LED 3:

On when the wake word directive (Alexa.Gadget.StateListener) is received.

LED 4:

Toggles when the Color Cycler skill is used.

Button 4:

Erases all bond information when a button is held during a power cycle or reset.

Building and running

This sample can be found under samples/bluetooth/alexa_gadget in the nRF Connect SDK folder structure.

See Building and programming an application for information about how to build and program the application.

Testing

After programming the sample to your development kit, test it by performing the following steps:

  1. Optionally, set up log monitoring:

  1. Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.

  2. Connect to the kit with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.

  1. Reset the kit.

  2. Follow these instructions to pair your Echo device with the sample: Alexa Gadgets Pairing.

  3. Observe that LED 1 turns on to indicate that a connection has been established.

  4. Observe that LED 2 turns on to indicate that the Alexa Gadgets handshake has been completed.

  5. Say the “Alexa” wake word to your Echo device and observe that LED 3 turns on.

  6. If you are monitoring the log output from the COM port, observe log activity during Alexa queries.

Dependencies

This sample uses the following nRF Connect SDK libraries:

In addition, it uses the following Zephyr libraries:

  • include/zephyr/types.h

  • boards/arm/nrf*/board.h

  • Kernel Services:

    • include/kernel.h

  • Bluetooth:

    • include/bluetooth/bluetooth.h

    • include/bluetooth/gatt.h

    • include/bluetooth/hci.h

    • include/bluetooth/uuid.h