Smart Home Skill Device Templates

You can connect virtually any type of device to Alexa using the Smart Home Skill API. For smart home skills, the voice-interaction model is already built for you. You decide how you want the user to interact with your device, and then in your skill, you implement the capability interfaces that enable those interactions. For example, if your device is a lamp, and you want the user to be able to turn the lamp on and off, you implement the Alexa.PowerController interface in your skill.

Most devices implement multiple interfaces to enable voice interaction with multiple features. For the full list of smart home interfaces, see List of Capability Interfaces and Supported Locales.

To help you get started, in this document we provide a set of device templates. Each template recommends a set of interfaces that you could implement for the device. You can modify these recommendations by adding or removing interfaces to suit the needs of your specific device.

Overview

You describe device endpoints that support Alexa interfaces by using the standard discovery mechanism described in Alexa.Discovery. In your discovery response, you identify the interfaces that you support, and provide configuration for any interfaces that require it. For more information, and see the documentation for each interface.

In your discovery response, you identify the display category of your device. The display category determines the icon and placement of your device in the Alexa app. For the full list of display categories, see display categories.

All smart home skills must implement the top-level Alexa interface. We recommend that all smart home skills also implement the Alexa.EndpointHealth interface. You use the EndpointHealth interface to report the connectivity status of your device to Alexa as either OK or UNREACHABLE.

Blinds

In addition to the pre-built voice-interaction model, you can use semantics to enable additional utterances. The blinds in this example use semantics with a mode controller so the user can say "open", "close", "raise", and "lower" to control the blinds. For more information, see the semantics object.

The user can interact with the blinds in this example by using utterances such as the following.

Alexa, open the blinds.
Alexa, close the blinds.
Alexa, raise the blinds.
Alexa, lower the blinds.

In your Alexa skill, we recommend that you use INTERIOR_BLIND as the display category.

If your blinds can raise and lower to a range of positions, we recommend that you implement the following interfaces. For an example discovery response, see example with semantics for blinds.

Interface Purpose
RangeController Create a range controller named Blind.Lift so the user can control height of the blinds.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

If your blinds only fully open and fully close, we recommend that you implement the following interfaces. For an example discovery response, see example with semantics for blinds.

Interface Purpose
ModeController Create a mode controller named Blinds.Position, with modes named Position.Up and Position.Down so the user can open and close the blinds.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Camera

The user can interact with a camera by using utterances such as the following.

Alexa, talk to my front door camera.
Alexa, show the last activity at my front door.

In your Alexa skill, we recommend that you use CAMERA as the display category and implement the following interfaces.

Interface Purpose
RTCSessionController The user can communicate remotely with the camera.
MediaMetadata The user can view and manage recordings from the camera.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The The base interface for all Alexa skills.

Color-changing light bulb

The user can interact with a color-changing light bulb by using utterances such as the following.

Alexa, turn on the Living Room Light.
Alexa, set the Living Room Light to blue.
Alexa, set the Living Room Light to fifty percent.
Alexa, make the Living Room Light warm white.

In your Alexa skill, we recommend that you use LIGHT as the display category and implement the following interfaces.

Interface Purpose
PowerController The user can turn the device on and off.
ColorController The user can control the color of the light.
BrightnessController The user can control the brightness of the light.
ColorTemperatureController The user can control the color temperature of the light.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Dimmable light bulb

The user can interact with a dimmable light bulb by using utterances such as the following.

Alexa, turn on the Kitchen Light.
Alexa, set the Kitchen Light to eighty percent.

In your Alexa skill, we recommend that you use LIGHT as the display category and implement the following interfaces.

Interface Purpose
PowerController The user can turn the device on and off.
BrightnessController The user can control the brightness of the light.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Dimmer switch

The user can interact with a dimmer switch by using utterances such as the following.

Alexa, turn on the Bedroom Light.
Alexa, set the Bedroom Light to twenty percent.

In your Alexa skill, we recommend that you use SWITCH as the display category and implement the following interfaces.

Interface Purpose
PowerController The user can turn the device on and off.
BrightnessController The user can control the brightness of the light.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Entertainment device

The user can interact with an entertainment device such as a television, streaming device, or game console, by using utterances such as the following.

Alexa, turn on the Living Room TV.
Alexa, change the input to HDMI 3 on the Living Room TV.
Alexa, change channel to twelve on the Living Room TV.
Alexa, set the volume of the Living Room TV to twenty-five.
Alexa, pause the Living Room TV.

In your Alexa skill, use TV, STREAMING_DEVICE, GAME_CONSOLE, SPEAKER, or other appropriate display category. We recommend that you implement the following interfaces. For an example discovery response that indicates support for these interfaces, see discovery response example for an entertainment device.

Interface Purpose
PowerController The user can turn the device on and off.
InputController The user can change the input of the device.
ChannelController The user can change the channel of the device.
Speaker The user can set, adjust, mute, and unmute the volume of the device.
PlaybackController The user can play, stop, and pause the device.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Garage door opener

In addition to the pre-built voice-interaction model, you can use semantics to enable additional utterances. The garage door in this example uses semantics with a mode controller so the user can say "open" and "close" to control the garage door. For more information, see Using semantics to enable additional utterances.

The user can interact with the garage door opener in this example by using utterances such as the following.

Alexa, open the garage door.
Alexa, close the garage door.

In your Alexa skill, we recommend that you use GARAGE_DOOR as the display category and implement the following interfaces. For an example discovery response, see example with semantics for a garage door opener.

Interface Purpose
ModeController Create a mode controller named GarageDoor.Position, with modes named Position.Up and Position.Down so the user can open and close the garage door.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Guitar amplifier

The following shows how to connect a smart guitar amplifier to Alexa. The device in this example is fictional, but provides an example for how to connect any device to Alexa. As with other devices, this example chooses the most specific interfaces, such as PowerController, Speaker, and EqualizerController whenever possible. This example then leverages the flexibility of the ToggleController, RangeController, and ModeController interfaces to cover of all its functions.

The user can interact with the guitar amp in this example by using utterances such as the following.

Alexa, turn on the Awsome Amp.
Alexa, set the volume of the Awsome Amp to six.
Alexa, set the bass on the Awsome Amp to three.
Alexa, turn on overdrive on the Awsome Amp.
Alexa, set the gain on the Awsome amp to four.
Alexa, set the Awsome Amp to Metal.
Alexa, boost the gain.
Alexa, make me sound like Pearl Jam.
Alexa, what do all these dials do?

In your Alexa skill, we recommend that you use SPEAKER as the display category and implement the following interfaces. For an example discovery response that indicates support for these interfaces, see discovery response example for a guitar amp.

Interface Purpose
PowerController The user can turn the device on and off.
Speaker The user can set, adjust, mute, and unmute the volume of the device.
EqualizerController The user can set and adjust the bass, mid, and treble of the device.
ToggleController Create a toggle controller named Overdrive so the user can turn the overdrive feature of the amplifier on and off.
RangeController Create a range controller named Gain so the user can control the gain (also called drive) of the amplifier.
ModeController Create a mode controller named Preset so the user can select pre-defined or user-saved settings.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Lock

The user can interact with a lock by using utterances such as the following.

Alexa, lock the Front Door.

In your Alexa skill, we recommend that you use SMARTLOCK or DOOR as the display category and implement the following interfaces.

Interface Purpose
LockController The user can lock and unlock the device.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Plug

The user can interact with a plug by using utterances such as the following.

Alexa, turn on the End Table Lamp.

In your Alexa skill, we recommend that you use SMARTPLUG as the display category and implement the following interfaces.

Interface Purpose
PowerController The user can turn the device on and off.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Switch

The user can interact with a switch by using utterances such as the following.

Alexa, turn on the Bathroom Fan.

In your Alexa skill, we recommend that you use SWITCH as the display category and implement the following interfaces.

Interface Purpose
PowerController The user can turn the device on and off.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Tower fan

The user can interact with the tower fan in this example by using utterances such as the following.

Alexa, turn on the Living Room Fan.
Alexa, turn on Oscillate on the Living Room Fan.
Alexa, set the Living Room Fan Speed to five.
Alexa, turn up the Speed on the Living Room Fan.
Alexa, set the air Speed on the Living Room Fan to Maximum.

In your Alexa skill, we recommend that you use FAN as the display category and implement the following interfaces. For an example discovery response for a fan that supports oscillation and speed, see example with both range and toggle controllers.

Interface Purpose
PowerController The user can turn the device on and off.
ToggleController "Oscillate" Create a toggle controller named Oscillate so the user can turn the oscillate feature of the fan on and off.
RangeController "Fan Speed" Create a toggle controller named Oscillate so the user can control the speed of the fan.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Wall thermostat

The user can interact with a wall thermostat by using utterances such as the following.

Alexa, set thermostat to 20.
Alexa, make it warmer in here.

In your Alexa skill, we recommend that you use THERMOSTAT as the display category and implement the following interfaces.

Interface Purpose
ThermostatController The user can control a device that controls temperature.
TemperatureSensor The device senses and reports temperature.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Wi-Fi router

You can model a Wi-Fi router as described following. You can also use the Alexa.Networking APIs if they better suit the needs of your specific device. For more information, see Understand Networking and Wi-Fi Skills.

The user can interact with a Wi-Fi router by using utterances such as the following.

Alexa, turn on Guest Wi-Fi on the Wireless Router.
Alexa, turn on Guest Wi-Fi.
Alexa, set the Traffic Priority on the Guest Wi-Fi to Video Games.
Alexa, set the Guest Wi-Fi to Movies.

In your Alexa skill, we recommend that you use OTHER as the display category and implement the following interfaces. For an example discovery response that indicates support for these interfaces, see discovery response example for a Wi-Fi router.

Interface Purpose
ToggleController Create a toggle controller named Guest Network so the user can turn the router on and off.
ModeController Create a mode controller named Traffic Priority so the user can select which type of traffic the router assigns the highest priority.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.

Window air conditioner (AC) unit

The user can interact with an air conditioner by using utterances such as the following.

Alexa, set the AC to twenty-five degrees for four hours.
Alexa, make it cooler in here.

In your Alexa skill, we recommend that you use THERMOSTAT as the display category and implement the following interfaces. If your air conditioner has a fan setting that blows cold air at different speeds, you can also implement the RangeController interface. For an example discovery response, see discover response example for an air conditioner.

Interface Purpose
PowerController The user can turn the device on and off.
ThermostatController The user can control a device that controls temperature.
TemperatureSensor The device senses and reports temperature.
EndpointHealth Report the connectivity status of the device to Alexa.
Alexa The base interface for all Alexa skills.