Control Echo Buttons

Echo Buttons contain full-color LEDs that you can use to enhance the skill experience. For example, you can use the LEDs to differentiate users, queue timing-based gameplay, or just to set the mood. This topic describes how to light up the buttons using animation sequences.

Animating the Buttons

Your skill can modify the behavior of each connected Echo Button, or multiple Echo Buttons at once, by including the GadgetController.SetLight directive in response to any request from Alexa. To use this directive, your skill metadata must include the Gadget Controller interface.

To understand the SetLight directive, visualize that you are asking the Amazon Echo device to deliver commands to each individual Echo Button. Each SetLight directive wraps a single command to deliver, but the same message will be broadcast to each Echo Button that is specified in the directive. You can also send the command to all connected Echo Buttons at once by not specifying a specific button.

The following figure shows how your skill interacts with the Gadget Controller to send commands to Echo Buttons.

Controlling Echo Buttons

The following example shows the general structure of the SetLight directive.

{
   "type": "GadgetController.SetLight",
   "version": 1,
   "targetGadgets": [ "gadgetId1", "gadgetId2" ],
   "parameters": {
      "triggerEvent": "none",
      "triggerEventTimeMs": 0,
      "animations": [ 
       {
          "repeat": 1,
          "targetLights": ["1"],
          "sequence": [ 
           {
              "durationMs": 10000,
              "blend": false,
              "color": "0000FF"
           }
          ] 
        }
      ]
    }
 }

The following is a description of each field. For detailed API information, see the GadgetController Interface Reference.

  • type – The type of directive, which is GadgetController.SetLight.
  • version – The version of this directive. Set this to 1.
  • targetGadgets – The gadget IDs of the buttons that will receive the animations. You find the gadget IDs by using a roll call. You can broadcast the same command to all connected Echo Buttons by leaving this array empty or omitting the targetGadgets field altogether.
  • parameters – The animation-specific arguments, all of which are required:
    • triggerEvent – The action that triggers the animation. It has three possible values. You can send three directives to a single Echo Button simultaneously to populate each of the trigger events, but each subsequent command to the same Echo Button that addresses the same trigger event overwrites the one that you previously set. The possible values for triggerEvent are as follows:
      • buttonDown – Play the animation when the button is pressed. This replaces the current buttonDown animation. If a buttonDown animation is currently playing, the new animation replaces it immediately. Otherwise, the new animation will play on subsequent presses of the button.
      • buttonUp – Play the animation when the button is released. This replaces the current buttonUp animation. If a buttonUp animation is currently playing, the new animation replaces it immediately. Otherwise, the new animation will play on subsequent releases of the button.
      • none – Play the animation as soon as it arrives.
    • triggerEventTimeMs – The delay in milliseconds to wait after the trigger event before playing the animation.
    • animations – One animation. An animation is a sequence of steps to be sent in a specific order.

Defining Animations

Inside an animation, you provide a sequence of steps. Each step defines the duration that it will last, the color that will be displayed in that interval, and whether the interval displays the full color the whole time, or whether the color will be interpolated up to that key color over the course of the interval (that is, whether the color will be blended).

The following is the general structure of animations.

"animations": [ 
 {
     "repeat": someNumber,
     "targetLights": ["1"],
     "sequence": [ 
     {
       "durationMs": someNumber,
       "blend": true, // or false
       "color": "colorInRGBHex"
      },
     {
       "durationMs": someNumber,
       "blend": true, // or false
       "color": "colorInRGBHex"
      }
    ] 
  }
]

The following is a description of each field. For detailed API information, see the GadgetController Interface Reference.

  • repeat – The number of times to play this animation. Minimum: 0. Maximum: 255.
  • targetLights – A list of light addresses on the target gadgets that this animation will be applied to. Because the Echo Button has one light only, set this to 1 to signify that this animation should be sent to light one.
  • sequence – The animation steps to render in order. The maximum number of steps that you can define is 38. The minimum is 0 (though a zero-step animation sets the animation for that trigger to blank, clearing any animation that is currently set for that trigger). Each step has the following fields:
    • durationMs – the duration in milliseconds to render this step. The minimum is 1. The maximum is 65,535.
    • color – The color in RGB hexadecimal values to render. The format is RRGGBB. There are a number of Node.js libraries available for working with color. Remember to remove the # after you convert the value to hexadecimal.

      Due to the limitations of the hardware, some colors do not look as expected when rendered on Echo Buttons. You may need to experiment to find colors that work well with your skill. For examples of how colors might appear when rendered on Echo Buttons, see Echo Button Animations.
    • blendtrue to interpolate from the previous color into this one over the course of this directive's durationMs.

Supported Animation Sizes

Animation sizes for the LEDs on Echo Buttons are constrained by a single, binary-packed SetLight directive that fits into a single Bluetooth packet. This includes the space occupied by the addresses of target gadgets.

To calculate the maximum number of steps that you can include in the sequence array for a given trigger, use the following formula:

maxStepsPerSequence = 38 - numberOfTargetGadgetsSpecified * 3

For example, if you want to send animations to all buttons, you can send a maximum of 38 steps. If you specify one target button, then you can send at most 35 steps, and so on.

How Animations Interact

The following rules explain how the animations for the different trigger eventsnone (immediate), buttonDown, and buttonUp — interact with each other.

buttonDown and buttonUp vs. none

buttonDown and buttonUp animations play over the none animation. The none animation is not canceled or paused while the buttonDown and buttonUp animations play.

Example:

  1. The none animation is playing.
  2. A user presses a button. The buttonDown animation plays.
  3. The user releases the button. The buttonUp animation plays.
  4. The none animation continues to play as if it was playing all along.

Also note that a new none animation does not stop or replace any existing buttonDown or buttonUp animations. It just replaces the existing none animation, if any.

buttonDown vs. buttonUp

buttonDown and buttonUp animations replace each other.

Example:

  1. The buttonDown animation is set to 5 seconds and the buttonUp animation is set to 1 second.
  2. A user presses a button. The buttonDown animation starts to play.
  3. After 1 second, the user releases the button. The buttonUp animation plays.
  4. After the buttonUp animation finishes, the none animation (if any) continues playing. The buttonDown animation does not continue.

New vs. Existing none

A new none animation replaces the existing none animation. As such, to cancel a none animation that is already playing, send another none animation. This could be a reset-style animation that has a short duration (100ms) and a color of 0x000000.

New vs. Existing buttonDown

A new buttonDown animation replaces the existing buttonDown animation. As such, to stop or replace the buttonDown animation, send a new buttonDown animation. Note that you don't need to wait for a button press to replace a buttonDown animation that is already playing. The moment the Echo Button receives the new buttonDown animation, the new animation takes effect immediately.

New vs. Existing buttonUp

This is the same behavior as New vs. Existing buttonDown.

Animations to Avoid

When you program your animations, avoid using the predefined system animations described in Best Practices.

Examples

The following are examples of animating Echo Buttons on different trigger conditions: none (play the animation as soon as it arrives), buttonUp, and buttonDown.

Example of Playing an Animation Immediately

The following is an example of a directive to play the animation as soon as it arrives at the specified buttons. It sets the color to a dim red initially, blends up to blue in one second, holds on blue for half a second, and then quickly blends back down to red. It is set to repeat this sequence three times.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "outputSpeech": "Ready?... Go!",
    "reprompt": "Keep going!",
    "shouldEndSession": false,
    "directives": [
      {
        "type": "GadgetController.SetLight",
        "version": 1,
        "targetGadgets": [ "gadgetId1", "gadgetId2" ],
        "parameters": {
          "triggerEvent": "none",
          "triggerEventTimeMs": 0,
          "animations": [
            {
              "repeat": 3,
              "targetLights" : [ "1" ],
              "sequence": [
                {
                  "durationMs": 10,
                  "color": "330000",
                  "blend": false
                },
                {
                  "durationMs": 1000,
                  "color": "0000FF",
                  "blend": true
                },
                {
                  "durationMs": 500,
                  "color": "0000FF",
                  "blend": false
                },
                {
                  "durationMs": 200,
                  "color": "330000",
                  "blend": true
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Example of Playing an Animation on a Button Press or Release

The following is an example of setting up a white flash that fades out to a pink when the player presses a button.

Note that when either the buttonUp or buttonDown animations are played through, the LED will rejoin the none animation at the time it would have been at if it had continued playing. That is, conceptually the clock kept running on the none animation and the buttonDown and buttonUp animations just obscured it.

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "outputSpeech": "Ready?... Go!",
    "reprompt": "Keep going!",
    "shouldEndSession": false,
    "directives": [
      {
        "type": "GadgetController.SetLight",
        "version": 1,
        "targetGadgets": [ "gadgetId1", "gadgetId2" ],
        "parameters": {
          "triggerEvent": "buttonDown",
          "triggerEventTimeMs": 0,
          "animations": [
            {
              "repeat": 1,
              "targetLights" : [ "1" ],
              "sequence": [
                {
                  "durationMs": 10,
                  "color": "FFFFFF",
                  "blend": true
                },
                {
                  "durationMs": 200,
                  "color": "FFFFFF",
                  "blend": false
                },
                {
                  "durationMs": 500,
                  "color": "AA4411",
                  "blend": true
                }
              ]
            }
          ]
        }
      }
    ]
  }
}