Receive Echo Button Events

This topic provides an overview of how your skill receives input from Echo Buttons.

Overview

To receive input from Echo Buttons, your skill sends directives to, and receives notifications from, a component within Alexa called the Game Engine. The Game Engine enables your skill to define Input Handlers that filter button presses into named events that it forwards to your skill when conditions in the Input Handler definition are met.

For example, you can define an event for "the first time a player presses a red button." In this case, the Game Engine will only notify your skill under that condition. It won't, for example, notify your skill when a player presses a yellow button, or a player presses a red button the second time. Each skill instance can have only one active Input Handler at a time, and you can define up to 32 different Input Handler events for a single Input Handler. If a skill has an active Input Handler, Echo Button presses interrupt text-to-speech (TTS).

Skill Interaction with Alexa

The Game Engine doesn't change the way that your skill receives requests from, or responds to, Alexa, it just provides additional directives and events that your skill can use when it exchanges information with Alexa in the usual way. The exchange of information is as follows:

  • Skill to Game Engine – To send directives to the Game Engine, respond to any request from Alexa.
  • Game Engine to skill – The Game Engine sends your skill Input Handler events in the form of requests, similar to any other event request from Alexa.

The following figure shows how your skill and the Game Engine interact.

Receiving Echo Button Input

Skill Flow

The following is the typical flow of a skill that interacts with Echo Buttons:

  1. Starting Input Handlers – Your skill starts an Input Handler by responding to any request from Alexa. In the response, your skill includes a directive that configures the Input Handler parameters. These configurations include the conditions under which your skill should be notified of events, the length of the timeout window, and so on. As usual, you can also include voice output and any other available directives. To learn more about starting an Input Handler, see Starting Input Handlers.
  2. Receiving Input Handler events from the Game Engine – Your skill receives Input Handler events through requests from Alexa. These events are triggered when the event conditions that your skill defined are met. The payload of the event includes a list of the raw button events that contributed to the event conditions being met. To learn more about receiving events from the Game Engine, see Receiving Input Handler events from the Game Engine.
  3. Stopping Input Handlers – An Input Handler stops either because the skill configured it to stop under certain conditions, the skill explicitly stopped the Input Handler using a directive, the Input Handler timed out after the length of time that the skill specified, or the user quit the skill. To learn more about stopping an Input Handler, see Stopping Input Handlers.

Important Points About Input Handlers

Three important things to remember are:

  • Only one Input Handler is active at a time – When you start a new Input Handler, it replaces the previous Input Handler.
  • Input Handlers are meant to receive input for sections of your skill, not for an entire skill – That is, as your skill runs, it typically starts and stops Input Handlers many times. For example, your skill must first take a roll call to find out which Echo Buttons are connected and ready to use. To implement roll call, you might configure an Input Handler to notify you when each button is pressed once. After roll call ends, you might start a new Input Handler, and configure it for a certain type of gameplay. For example, you might configure an Input Handler to send your skill an event when a user presses the buttons in a certain winning sequence.
  • Expect old events – Although only one Input Handler can be active at any time, your skill must be prepared to receive and discard events that an earlier Input Handler generated. This is because it is possible for an earlier event to be "in transit" to the skill, while the skill has moved on and started a new Input Handler. Your skill must check the originatingRequestIdof incoming events against the requestId that the skill saved when it started the current Input Handler.

The following figure shows an example of the life span of Input Handlers for a three-question trivia game.

Trivia Game Input Handlers

Starting Input Handlers

You start an Input Handler by sending a GameEngine.StartInputHandler directive in response to any request from Alexa. In this directive, you specify the conditions under which your skill should be notified of Echo Button events.

Each call to StartInputHandler replaces any existing Input Handler with a new Input Handler.

The following is the general structure of the StartInputHandler directive.

{
  "type": "GameEngine.StartInputHandler",
  "timeout": 5000,
  "proxies": [],
  "recognizers": {},
  "events": {}
}

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

  • type – The type of directive, which is GameEngine.StartInputHandler.
  • timeout – The maximum run time for this Input Handler, specified in milliseconds. You are required to declare this upper bound, but you can later specify events with conditions on which to end the Input Handler earlier. The maximum timeout value is 90 seconds, or 90,000 milliseconds.
  • proxies – Temporary identifiers to assign to gadgets that your skill hasn’t yet discovered. For more information about proxies, see Proxies.
  • recognizers – Named, declarative functions that produce an outcome of true or false. You can provide a maximum of 20 recognizers, or you can leave this empty if you don't have any to declare. For more information about recognizers, see Recognizers.
  • events – Groups of recognizers together in boolean logical relationships that, when met, will trigger an invocation of your skill in the form of an InputHandlerEvent request. When you set up an Input Handler, you must define at least one event, and you can define as many as 32. For more information about defining events, see Define Echo Button Events.

Receiving Input Handler events from the Game Engine

After your skill starts an Input Handler by responding to a request from Alexa, your skill will receive Input Handler events as GameEngine.InputHandlerEvent requests from Alexa.

These requests contain button event information in two forms: Input Handler events and raw button events.

  • Input Handler events – These are named events that you define when you start an Input Handler. For example, your skill might define an event called winningSequence that notifies the skill when a player presses the buttons in a certain order. Input Handler events are what trigger the Game Engine to report an event to your skill. To learn more, see Define Echo Button Events.
  • Raw button events – These correspond to a press or release of a button. In JSON, the raw button events are inputEvents within the Input Handler events object. You can configure the Input Handler to include all the raw button events since the Input Handler started, just the ones that triggered your Input Handler event conditions, or none at all.

The following is an example of a request that contains events.

{
  "version": "1.0",
  "session": {
    "application": {},
    "user": {}
   }, 
  "request": {
    "type": "GameEngine.InputHandlerEvent",  
    "requestId": "amzn1.echo-api.request.406fbc75-8bf8-4077-a73d-519f53d172a4",
    "timestamp": "2017-08-18T01:29:40.027Z",
    "locale": "en-US",
    "originatingRequestId": "amzn1.echo-api.request.406fbc75-8bf8-4077-a73d-519f53d172d6",
    "events": [
      {       
        "name": "myEventName",
        "inputEvents": [
          {
            "gadgetId": "someGadgetId1",
            "timestamp": "2017-08-18T01:32:40.027Z",
            "action": "down",
            "color": "FF0000"
          }
        ]
      }
    ]
  }
}

In addition to the fields that are common to all Alexa Skills Kit requests (type, requestId, timestamp, and locale), the fields are as follows:

  • originatingRequestId – The request ID of the request to which you responded with a StartInputHandler directive. You should store this request ID to use as a filter to reject any old asynchronous Input Hander events that come in after you've started a new Input Handler.
  • events – A list of named Input Handler events that triggered the request. When an event's conditions become true, the event is sent to your skill only once. However, there may be multiple named events within one request if more than one such event became true at the same time.
  • name – The name of the event as you defined it in your StartInputHandler directive.
  • inputEvents – A chronologically ordered report of the raw button events that contributed to this Input Handler event. You can analyze this list to discover things like intervals between events, or conformance to some function with which to judge player performance. Raw button events have the following fields:
    • gadgetId – The permanent identifier of the Echo Button. This is the gadget ID you discovered in roll call.
    • action – This is down for a button press or up for a button release.
    • color – The hexadecimal RGB values of the button LED at the time of the event.
    • timestamp – The raw button event's original moment of occurrence, in ISO format.

For detailed API information, see the Game Engine Interface Reference.

Stopping Input Handlers

To end an Input Handler ahead of schedule, reply to any request with a GameEngine.StopInputHandler directive and include the originating requestId that you saved from the original request that you responded to when you started the Input Handler.

If you attempt to stop an old or nonexistent Input Handler, Alexa will ignore the request and leave any active Input Handler running. The Input Handler will run until it times out, is stopped by an event, or the user ends the skill.

The StopInputHandler directive has the following form.

{
  "type": "GameEngine.StopInputHandler",
  "originatingRequestId": "amzn1.echo-api.request.406fbc75-8bf8-4077-a73d-519f53d172a4"
}

The fields are as follows:

  • type – The type of directive, which is GameEngine.StopInputHandler.
  • originatingRequestId – The request ID of the request to which you responded with a StartInputHandler directive.

Should a user explicitly quit your skill (for example, by saying "Alexa, quit"), then Alexa will automatically terminate your open Input Handler in the same way, and your skill will not be invoked with any further Input Handler events.