Discover Echo Buttons
The term Echo Button discovery refers to two different processes:
- Bluetooth pairing – This is the process that users take to pair their Echo Buttons with their Amazon Echo device. For more information, see How Echo Buttons Work.
- Roll call – This is the process by which a skill determines how many Echo Buttons, and the gadget IDs of the buttons, that the user wants to use with the skill. This is the subject of this topic.
In this topic, we first describe the goals of roll call, and then how to implement it.
Roll Call Goals
Because Echo Buttons enter sleep mode to preserve battery life, the Echo Buttons will likely be asleep when a user launches your skill. The user might also have a different number of buttons than your skill requires. For example, your skill might need three buttons, but the user has only paired two to this device, or has paired four. For these reasons, your skill should begin with a roll call.
A quiz game, for instance, might have a roll call phase asking each player to buzz in. An action game might ask the players to press all the Echo Buttons that they want to use, from left to right, to wake up the buttons and simultaneously learn about their spatial layout.
Your goals during roll call are as follows:
- Wake up the Echo Buttons and make sure that they are connected.
- Get the gadget ID for each Echo Button that you discover. Your skill will use these gadget IDs later to perform tasks like identify which player buzzed in, or to set the order in which you want the buttons to light up.
- Produce a semantic mapping for your game. The timestamps of the raw button events within the event information will tell you the order that they were pressed in.
If you want to support drop in and drop out play, you should repeat this roll call procedure in response to a voice intent and update your internal gadget ID mapping. For example, if you have identified a player order among Echo Buttons during roll call and subsequently refer to your players by number, then you could add an intent to support the utterance "Alexa, drop Player 3 from the game."
Performing Roll Call
To begin roll call, respond to any prior request from Alexa (for example, your launch intent) with a response that includes verbal instructions to your players
and an appropriate
Imagine that you want to refer to a group of three buttons as "first", "second" and "third" during your game. You could begin by using a
GadgetController directive to set the
LED animations for all three buttons to blue, and then have Alexa ask, "Great! Now, press these three blue buttons in order, from left to right."
To set this up, your
GameEngine.StartInputHandler directive must include three recognizers, one for each button. The purpose is to detect if each button is pressed at least once. Set up the recognizers to recognize any
down event, anywhere in the history. When all three recognizers are active, the
complete event will fire and the Input Handler will stop. Otherwise, the Input Handler will time out and fire a
failed event instead. In that case, the Input Handler will send all the raw button events that have occurred since the Input Handler started, so that you can determine if the player has pressed anything at all.
Because Echo Buttons enter sleep mode to preserve battery life, when your skill is launched it is not likely that the Echo Buttons will actually be turned on and connected. There could also be fewer than or more than the number of buttons that your skill requires. For these reasons, your skill must begin with some form of a roll call.
The following example sets up roll call for a skill that requires three buttons. It therefore sets up an Input Handler to notify the skill when three buttons have been pressed, or if 30 seconds have passed without three buttons being pressed.