Generic Controller Interfaces
Generic controller interfaces are general-purpose interfaces that you can use to model different components of a smart home device in your Alexa skills. For details about smart home skills, see Understand Smart Home Skills.
Currently, the generic controller interfaces are the following:
Alexa.DataController
– support retrieval and deletion of customer data.Alexa.ModeController
– model properties of a device that the user can set to one of a list of values.Alexa.RangeController
– model properties of a device that the user can set to one of a range of values.Alexa.SimpleEventSource
– model stateless events on a device, such as a button press on a remote switch or smart button device. Users can connect the events to Alexa Routines.Alexa.ToggleController
– model properties of a device that the user can set to on or off.
Choose the most specific controller available to model components of your devices, because the more specific the controller, the more natural the utterances are for your user. However, the generic controllers allow you to support functions that might not be available by default with more specific controllers, such as the ability to implement multiple instances of a controller for a single device, and support for semantics.
Correspondence of specific and generic controllers
The following table lists the generic controllers, and examples of corresponding specific controllers, that you can use to model components of your devices.
Generic controller | Corresponding specific controllers |
---|---|
|
— |
|
|
|
|
| |
|
Multiple instances
When you implement a specific controller interface in the Alexa skill for your device, you can only implement one instance of the interface. When you implement a generic controller interface in your Alexa skill, you can implement multiple instances of the controller. You specify an instance
name for each instance of the controller in the discover response for your skill. For details and sample code, see the documentation for each generic interface.
The following scenarios are examples of implementing multiple instances of generic controllers:
-
For a washing machine device, implement one instance of the
Alexa.ModeController
interface namedWasher.WashCycle
to model the wash cycle. Implement a second instance of theAlexa.ModeController
interface namedWasher.WashTemperature
to model the water temperature. -
For a ceiling fan with a light, implement one instance of the
Alexa.RangeController
interface namedFan.Speed
to model the fan speed. Implement a second instance of theAlexa.RangeController
interface namedFan.Light
to model the brightness of the light. -
For a stove with a cooktop and an oven, implement one instance of the
Alexa.ToggleController
interface namedOven.Light
to model the oven light. Implement a second instance of theAlexa.ToggleController
interface namedStovetop.ResidualHeat
to model the safety feature that warns users when there is residual heat and the cooktop is too hot to touch. -
For a remote switch with three buttons, implement one instance of the
Alexa.SimpleEventSource
interface for each button and define one or more events per button.
Utterances
Both specific and generic controllers use a pre-built voice-interaction model, which means that when you use them, the utterances that users say to Alexa are already defined for you. Usually you choose the most specific controller available to model components of your devices, because the more specific the controller, the more natural the utterances are for your user.
The following table compares utterances for generic controllers and specific controllers. In these examples, a generic controller is used for the same device as a specific controller. For the generic controllers, the user must say the name of the instance, or a friendly name replacement for it, in the utterance.
Example Device | Generic Controller Utterances | Specific Controller Utterances |
---|---|---|
A smart thermostat with a mode named automatic. The user named the thermostat "Bedroom Thermostat" in the Alexa app. | If you model the thermostat with Alexa.ModeController :"Alexa, set the Thermostat Mode on the Bedroom Thermostat to automatic." |
If you model the thermostat with Alexa.ThermostatController :"Alexa, set the Bedroom Thermostat to automatic." |
A speaker that controls volume on a smart television. The user named the television "Living Room TV" in the Alexa app. | If you model the volume with Alexa.RangeController :"Alexa, turn Speaker Volume down on the Living Room TV." |
If you model the volume with Alexa.Speaker :"Alexa, turn the volume down on the Living Room TV." |
A smart plug. The user plugged a portable heater into the plug and named the plug "Desk Heater" in the Alexa app. | If you model the power with Alexa.ToggleController :"Alexa, turn on the Desk Heater." |
If you model the power with Alexa.PowerController :"Alexa, turn on the Desk Heater." |
Semantics
Use semantics to enable additional features, such as additional user utterances and notifications when your device requires attention. To use semantics, include a semantics object in your discovery response.
Semantics for user utterances
When you implement generic controllers you can optionally enable additional utterances for your users by using semantics. When you use semantics, you manually map the phrases "open", "close", "raise", and "lower" to the directives of your controller. For example, if you have a Alexa.ToggleController
for a garbage can lid, you can map the phrase "open" to the TurnOn
directive. For details and sample code, see the documentation for each generic interface.
Alexa.ModeController
instance, you can't map the phrase "open" on any other Alexa.ModeController
instances, any Alexa.RangeController
instances, or any Alexa.ToggleController
instances for the endpoint. You can use the same semantic phrase "open" across other endpoints that you report.
The following examples show some user utterances that use semantics:
Alexa, open the garage door.
Alexa, close the garbage can lid.
Alexa, raise the bedroom blinds.
Alexa, lower the living room blinds.
Semantics for Alexa hunches
You can use semantics to enable Alexa hunches for your device to conserve energy on behalf of users. For details about hunches, see What Are Alexa Hunches? and Enable Alexa to Proactively Act on Hunches Without Customers Needing to Ask.
Alexa.ToggleController
.The semantics for Alexa hunches are Alexa.Actions.SetEcoOn
, Alexa.Actions.SetEcoOff
, Alexa.States.EcoOn
, and Alexa.States.EcoOff
. For an example discovery response that includes support for Alexa hunches, see discovery response example for a water heater.
Semantics for announcements
You can use semantics to enable announcement to the user when your device requires attention. For example, Alexa can notify a user when their washing machine cycle has completed, or when their automatic vacuum cleaner gets stuck. Before Alexa begins to send announcements to the user, the customer must opt-in to announcement notifications in the Alexa app.
Alexa.ModeController
and Alexa.RangeController
only. To enable semantics for announcements, you map the state of your device to one of the Alexa states in your discovery response. For more details about announcements and announcement format, see ProactiveNotificationSource.
Alexa.Cooking
.Restrictions
The following restrictions apply to skills that use generic controllers:
- You can't use generic controllers to control devices that belong to a Smart Home Device Group.
- If you use semantics for user utterances, each semantic phrase must be unique across all controller instances in your skill.
Related topics
Last updated: Jan 26, 2024