Registering a gadget in the Alexa Voice Service Developer Console

To create a gadget that works with your Echo device, you first need to register a new gadget in the Alexa Voice Service Developer Console.

1. Sign in to the Alexa Voice Service Developer Console. If you don't already have a developer account, create one.

2. If you haven't registered an AVS product in the past, click GET STARTED.

3. Click PRODUCTS, and then click CREATE PRODUCT.

4. Fill out the requested information, select Alexa Gadget as the product type, and then click FINISH.

5. In the pop-up, click OK.

6. You will be taken to a list of your products. Click on the gadget you just created.

7. At the top, you'll see an Amazon ID and Alexa Gadget Secret. You'll need these for the following steps to create your Alexa Gadget. Keep this ID and Secret private because they uniquely identify your gadget.

To learn more, refer to Register a Gadget in the Alexa Gadgets Toolkit documentation.

Installation

To setup your Raspberry Pi as an Alexa Gadget, you will need to download and install some Python and Debian packages. To run the following commands, you will need to be connected to your Pi via SSH or VNC, or be running them directly using a keyboard, mouse, and monitor connected to your Pi. Make sure your Pi is connected to the internet.

Download Alexa-Gadgets-Raspberry-Pi-Samples repo from GitHub using one of the following ways:

• Using git clone:

  • In your terminal:

    git clone https://github.com/alexa/Alexa-Gadgets-Raspberry-Pi-Samples.git
    

  • If you didn't clone the repo directly on your Pi, you can transfer it to your Pi using the scp command

    scp -r Alexa-Gadgets-Raspberry-Pi-Samples pi@192.168.0.1:~/Alexa-Gadgets-Raspberry-Pi-Samples
    

  Note: Replace 192.168.0.1 with the IP address of your Pi.

• Using GitHub Web UI:

  • Click on the Clone or download button and click on Download ZIP.
  • Unzip the downloaded Alexa-Gadgets-Raspberry-Pi-Samples-master.zip file:

    unzip Alexa-Gadgets-Raspberry-Pi-Samples-master.zip
    

  • If you didn't download & unzip the repo directly on your Pi, you can transfer it to your Pi using the scp command

    scp -r Alexa-Gadgets-Raspberry-Pi-Samples-master pi@192.168.0.1:~/Alexa-Gadgets-Raspberry-Pi-Samples
    

  Note: Replace 192.168.0.1 with the IP address of your Pi.

Once you have the Alexa-Gadgets-Raspberry-Pi-Samples repo on your Pi, go into the Alexa-Gadgets-Raspberry-Pi-Samples folder

cd /home/pi/Alexa-Gadgets-Raspberry-Pi-Samples/

Here, you will find the launch.py script which is the single point of entry for setting up your gadget and launching the example projects.

To setup your gadget, run the launch script with --setup argument, which will let you configure your gadget's credentials; install & update the libraries for Bluetooth, protobuf, interacting with GPIOs, etc; and configure the transport mode (Classic Bluetooth / BLE).

sudo python3 launch.py --setup

Note: Since the gadget needs a reliable Bluetooth connection with the Echo device, the A2DP Bluetooth profile will be disabled as part of the setup. If you would like to re-enable it please follow the Troubleshooting guide below.

If you already have registered your gadget using the Registering a gadget in the Alexa Voice Service Developer Console section, you can press y and enter your gadget's Amazon ID and Alexa Gadget Secret so that the setup script automatically configures all the examples with your gadget's credentials.

The Pi will update and install the Debian & Python dependencies.

For the gadget to successfully communicate with your Echo device over BLE, a modification to the bluez-5.50 is needed to enable notification callbacks after reconnection with a paired Echo device. The launch script will enable you to download the bluez-5.50 package, modify it, and install it to your Pi. To use Alexa Gadgets Raspberry Pi Samples you will need to read and agree to the Terms and Conditions. If you agree, enter 'AGREE' else enter 'QUIT' to quit the installation.

Once all the dependencies are installed, you will be asked to choose the transport mode to use to communicate with the Echo device. You can enter 'BT' if you would like to choose Classic Bluetooth, or you can enter 'BLE' to choose Bluetooth Low Energy.

Once the launch script configures the gadget based on the transport mode selected, a SUCCESS message will be printed.

If you're using Pi in Desktop mode (using Pi with a display), you should disable the Pi Bluetooth menu to prevent two bluetooth clients (your gadget script and the Pi Bluetooth client) handling the bluetooth connections at the same time (which might lead to connectivity issues). To disable the Pi Bluetooth menu right click on bluetooth icon on the top right of your screen, select Remove "Bluetooth" From Panel and reboot your Pi.

Projects

The best way to get familiar with creating your own gadget, is to reference the example projects that are a part of this project.

You can find example projects in the /home/pi/Alexa-Gadgets-Raspberry-Pi-Samples/src/examples folder. The Kitchen Sink example is a great place to start.

Projects include:

• Kitchen Sink Gadget: Create an Alexa Gadget that prints messages in response to directives from Alexa Gadgets Toolkit interfaces, including wake word detection, alarms, timers, notifications, and reminders.
• Color Cycler Gadget: Create an Alexa Gadget with an LED and a button, that uses Custom Directives to cycle through different colors and uses Custom Events to report the LED color when the button is pressed. This project requires an Alexa skill.
• Wake Word Gadget: Create an Alexa Gadget that turns an LED on and off in sync with the detection of the wake word.
• Notification Flag Gadget: Create an Alexa Gadget that rotates a servo motor to raise and lower a flag when a notification is received or cleared on a paired Echo device.
• Timer Gadget: Create an Alexa Gadget that reacts to a single timer set on an Echo device. A servo rotates a disc to indicate the remaining duration of the timer, when the timer expires, and when a timer is canceled.

Running the example projects

To run a gadget example you can use the launch script with --example argument as follows:

sudo python3 launch.py --example example_name

The example_name defines the name of the example located in the /home/pi/Alexa-Gadgets-Raspberry-Pi-Samples/src/examples folder. For the launch script to be able to correctly identify your example using the example_name, the names of the example folder and the script (along with its .ini config file) should have the same name.

For e.g. the folder structure for the Kitchen sink example looks as follows:

...
|-- examples
    |-- kitchen_sink
        |-- kitchen_sink.py
        |-- kitchen_sink.ini
        ...
    ...

You can also launch an example by providing the path to the example's python script as follows:

sudo python3 launch.py --example path/to/example.py

Note: Please ensure that your example script also has a .ini config file accompanying it. Please follow the specifications for the .ini config file mentioned in the Configuration section.

How does this work?

This Python software enables the creation of an Alexa Gadget by handling the connection of the gadget to an Echo device over Classic Bluetooth or Bluetooth Low Energy, and responding to messages based on the Alexa Gadget Toolkit capabilities you specify.

Configuration

Each gadget you create, including the examples, requires a configuration file that specifies the Amazon ID and Alexa Gadget Secret you created in the Alexa Voice Service Developer Console, as well as a specification of the capabilities of your gadget.

In each example, there is a .ini file that includes this information. For example, the Kitchen Sink gadget's configuration looks like:

[GadgetSettings]
amazonId = YOUR_GADGET_AMAZON_ID
alexaGadgetSecret = YOUR_GADGET_SECRET

[GadgetC