Your Alexa Consoles
Sign In
?
Sign In
Support

GadgetController Interface Reference

The Gadget Controller interface enables your skill to control Echo Buttons. This interface works with compatible Amazon Echo devices only. With the Gadget Controller interface, you can send animations to illuminate the buttons with different colors in a specific order.

Configuring Your Skill to Use the Gadget Controller Interface

To use Gadget Controller directives, you must specify the Gadget Controller interface in your skill metadata.

Gadget Controller Directives

The Gadget Controller interface provides the following directives:

Directive Description
GadgetController.SetLight Sends Alexa a command to modify the behavior of connected Echo Buttons.

When including a directive in your response, set the type property to the directive that you want to send. Include directives in the directives array in your response. The following is the format of a request with a GadgetController.SetLight directive in it.

{
  "version": "1.0",
  "sessionAttributes": {},
  "shouldEndSession": boolean,
  "response": {
    "outputSpeech": string,
    "reprompt": string,
    "directives": [
    {
       "type": "GadgetController.SetLight",
       "version": 1,
       "targetGadgets": [ "gadgetId1", "gadgetId2" ],
       "parameters": {
          "triggerEvent": string,
           "triggerEventTimeMs": number,
           "animations": [ 
           {
             "repeat": number,
             "targetLights": ["1"],
              "sequence": [ 
              {
                "durationMs": number,
                "blend": boolean,
                "color": string
              }
             ] 
            }
          ]
        }
      }
    ]
  }
}

For the full response format, see Response Format in the JSON Interface Reference for Custom Skills.

SetLight Directive

Sends a command to animate the LEDs of connected Echo Buttons. The following example shows the general form of the 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"
           }
          ] 
        }
      ]
    }
 }
Parameter Description Type Required
type Must be set to GadgetController.SetLight. string yes
version The version of the directive. Must be set to 1. number yes
targetGadgets The gadget IDs that will receive the command. An empty array, or leaving this parameter out, signifies that all gadgets will receive the command. array no
parameters Arguments that pertain to animating the buttons. object yes

parameters object

This object contains instructions on how to animate the buttons.

Parameter Description Type Required

triggerEvent

The action that triggers the animation. Possible values:

  • buttonDown: Play the animation when the button is pressed.
  • buttonUp: Play the animation when the button is released.
  • none: Play the animation as soon as it arrives.

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.

enum

yes

triggerEventTimeMs

The delay in milliseconds to wait after the trigger event before playing the animation. Minimum: 0. Maximum: 65,535.

number

yes

animations

One or more animations.

object

yes

animations object

This object contains a sequence of instructions to be performed in a specific order, along with the number of times to play the overall animation.

Parameter Description Type Required

repeat

The number of times to play this animation. Minimum: 0. Maximum: 255.

number

yes

targetLights

An array of strings that represent the light addresses on the target gadgets that this animation will be applied to. Because the Echo Button has one light only, use ["1"] to signify that this animation should be sent to light one.

array

yes

sequence

The animation steps to render in order. The maximum number of steps that you can define depends on the number of target gadgets that you specify.

To calculate the maximum number of steps that you can include in the sequence array, 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.

The minimum number of steps 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 must have the following fields, all of which are required:

  • durationMs: The duration in milliseconds to render this step. Minimum: 1. Maximum: 65,535.
  • color: The color to render specified in RGB hexadecimal values. 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.
  • blend: A boolean that indicates whether to interpolate from the previous color into this one over the course of this directive's durationMs.

array

yes

Gadget Controller Requests

This section contains the types of requests that Alexa might send your skill when you use the Gadget Controller interface.

System.ExceptionEncountered Request

If a GadgetController directive that you send fails (for example, you send an invalid animation sequence), then your skill will be invoked with a standard System.ExceptionEncountered request. Any directives included in the response are ignored.

{
  "type": "System.ExceptionEncountered",
  "requestId": "string",
  "timestamp": "string",
  "locale": "string",
  "error": {
    "type": "string",
    "message": "string"
  },
  "cause": {
    "requestId": "string"
  }
}

Parameters

Parameter Description Type
type System.ExceptionEncountered string
requestId A unique identifier for the specific request. string
timestamp Provides the date and time when Alexa sent the request as an ISO 8601 formatted string. Used to verify the request when hosting your skill as a web service. string
locale A string indicating the user's locale. For example: en-US. string
error An object with error information. object
error.type The specific type of error (INVALID_RESPONSE, DEVICE_COMMUNICATION_ERROR, INTERNAL_ERROR). string
error.message A description of the error the device has encountered. string
cause.requestId The requestId for the request that caused the error. string

Valid Response Types

Your skill cannot return a response to System.ExceptionEncountered.

Service Interface Reference (JSON)

Request Format and Standard Request Types:

Interfaces: