Smart Home Capability Interfaces
When you build a product with the Alexa Connect Kit (ACK), you define the interactions between your device, Alexa, and the Alexa app. For example, if you build a smart fan, you can define these interactions by asking yourself as the following questions:
- What Alexa utterances does my fan support? For example, "Alexa, turn on my bedroom fan."
- What features does my fan support? For example, can a user power your fan on and off? Can they change the speed?
To support your features, you must choose the appropriate smart home capability interfaces.
How to use capability interfaces with ACK
Devices built with ACK use the Alexa Smart Home Skill API and smart home capability interfaces to communicate to Alexa.
These interfaces provide the relevant Alexa utterances to control your device by voice and the relevant controls displayed in your Alexa app. When you first create your product with the ACK console, it comes with the default Alexa.PowerController
capability (so you can power your device on). However, you can choose to include or remove capabilities to customize your product.
For example, if your device is a colored smart light, you might support the PowerController
, BrightnessController
, and ColorController
interfaces. These interfaces allow a user to turn your light on and off, change the brightness level, and change the color.
The following table lists the Alexa smart home interfaces that ACK supports.
Interface (Alexa.*) | Description | SDK support |
---|---|---|
Control the brightness of a device, such as a smart light bulb. |
SDK 4, SDK 3 | |
Change the color of a device, such as a color-changing light bulb. |
SDK 4, SDK 3 | |
Control the color temperature of a device that supports tunable white light. |
SDK 4, SDK 3 | |
Control the cooking functions of a cooking appliance. Not all functions of |
SDK 4, SDK 3 | |
Report the energy use of a device that estimates energy use. |
SDK 4 | |
Report the energy use of a device that measures energy use. |
SDK 4 | |
A generic controller that provides a list of values to control device properties. For example, the wash cycle of a washing machine. |
SDK 4, SDK 3 | |
Control properties of a device that can expressed in percentage. For example, a light bulb set to twenty percent brightness. |
SDK 4, SDK 3 | |
Control the power state of a device. |
SDK 4, SDK 3 | |
Notify a user when their device needs attention. For example, notify a user when their oven finishes cooking food. |
SDK 4, SDK 3 | |
A generic controller that provides a range of values to control device properties. For example, the speed setting of a fan from one to ten. |
SDK 4, SDK 3 | |
Report temperature for a device that measures temperature, such as a thermostat. |
SDK 4 | |
Control the target temperature and mode of devices that manage temperature automatically, such as furnaces, air conditioners, ceiling fans, water heaters, and others. |
SDK 4 | |
Pause a device. For example, pauses a microwave oven while it's cooking. |
SDK 4, SDK 3 | |
A generic controller that provides an on or off toggle to control device properties. For example, the oscillation feature of a fan. |
SDK 4, SDK 3 |
How capability interfaces influence ACK product design
The smart home interfaces you choose define the Alexa utterances that control your product. For example, when a user says "Alexa, turn on my fan", the Alexa service interprets the utterance and sends an Alexa.PowerController.TurnOn
directive to the ACK service. The ACK service then routes it your device and controls the hardware.
The following table provides examples of how a user might interact with your ACK-based device.
Example product | Example utterance | Description | Capability interface |
---|---|---|---|
Tea kettle |
"Alexa, turn on the tea kettle." |
Controls the power of the kettle. | |
Dimmer switch |
"Alexa, dim the bedroom light to fifty percent." |
Sets the brightness level of a light bulb. | |
Fan |
"Alexa, set the fan speed to high." |
Sets the speed of the fan. |
How capability interfaces influence Alexa app design
The interfaces you choose also influence your Alexa app design.
When you build an ACK-based product, you don't need to build your own companion app to control your devices. Instead, you leverage prebuilt smart home components in the Alexa app. When you include a smart home capability in your design, the Alexa app automatically provides access to the relevant controls.
For example, if you support a feature with a ToggleController
interface, users see a single on and off toggle in the Alexa app. If you support a feature with the ModeController
interface, users see a drop down button in the app.
Examples
The ModeController
interface allows users to control device settings by choosing an option from a list of values. For example, a user might control the speed of a fan by choosing a relevant value, such as Low, Medium, or High. In the Alexa app, ModeController
renders as a button that displays a drop down list when pressed.
Implementation details
- When you use a
ModeController
interface, the voice interaction model is already built for you. For example, "Alexa, set the wash cycle to cottons". - When you use the
ModeController
interface, each drop-down option can have one or more friendly names and an associated numeric value. For example, if you're controlling the speed of a fan, you might have three different speed options, such as Low, Medium, and High. These values translate into the following three values:- Value 1, friendly name: Low.
- Value 2, friendly name: Medium.
- Value 3, friendly names: High or Turbo.
- You can define multiple friendly names for both
ModeController
and its options. However, the Alexa app only displays the first friendly name. The other friendly names are used for voice interaction only. - You can use multiple
ModeController
's on a single device, but eachModeController
needs to have a unique instance id. - You can set
ModeController
as a non-controllable display. For example, to display the current state of the device in the Alexa app.
The RangeController
interface allows users to control device settings by selecting a number within a minimum and maximum range, such as the speed setting on a fan (1 to 10). In the Alexa app, RangeController
renders as a line with a sliding toggle.
Implementation details
- When you use a
RangeController
interface, the voice interaction model is already built for you. For example, "Alexa, set the bedroom fan speed to 7". - When you use a
RangeController
interface, you define the following: - You can define multiple friendly names for both
RangeController
and each preset. The Alexa app only displays the first friendly name. The other friendly names are used for voice interaction only. - You can use multiple
RangeController
's on a single device. EachRangeController
needs to have a unique instance id.
The ToggleController
interface allows users to control settings on a device by using an on and off toggle. In the Alexa app, ToggleController
renders as a single toggle with an on/off state.
Implementation details
- When you use a
ToggleController
interface, the voice interaction model is already built for you. For example, "Alexa, turn off economy mode." - You can define multiple friendly names for
ToggleController
. The Alexa app only displays the first friendly name. The other friendly names are used for voice interaction only. - You can use multiple
ToggleController
's on a single device. EachToggleController
needs to have a unique instance id.
Example: Define the capability interfaces for a fan
The following example lists the hypothetical properties of a smart fan. This example defines both the utterances a user might say to control the fan and the experience they might see in the Alexa app. It also defines the interfaces used by the fan and how they should function.
ACK feature | Example |
---|---|
Device type |
Fan |
Basic functionality |
Control the speed of a fan. |
Alexa utterances |
"Alexa, set Fan to High" or "Alexa, increase Fan speed". |
Alexa app settings |
Display a fan speed selector with Low, Medium, and High settings. |
Alexa capability interfaces |
|
Supported modes or ranges |
Low mode with a value of |
Friendly name for the controller |
|
Resulting directive |
|
Possible errors |
User requests fan speed adjustments beyond supported values. For example, a request to decrease the speed when the fan is already set to Low. |
Error response |
State that the |
Additional comments |
If a user tries to change the speed of a fan that's already powered off, the fan should turn on. |
Friendly names
To give your users more flexibility in how they speak to Alexa, you can provide multiple friendly names for some capabilities. For example, using the previous fan example, you could set a synonym for the High mode setting, such as Turbo.
You could also set another synonym for the Speed setting, such as Airflow. With these two friendly names, a user could control your fan by saying "Alexa, set airflow to turbo." For more details about friendly names, see Friendly Name Resources and Assets.
Add capability interfaces to your virtual product
To test your smart home capabilities, create a virtual product in the ACK developer console. After you create your virtual product, you can add, remove, and edit its smart home capabilities using the smart home capabilities editor.
For example
The following image shows a product built with the ACK developer console. Here, you can add your smart home capabilities in the supplied JSON editor. In this example, the product contains the applicable JSON to support the Alexa.ModeController
interface.
To edit a virtual product
- Log-in to the ACK developer console.
- Click Products, then click the product you want to edit.
- Next to Alexa smart home capabilities, click Edit.
Add support capability interfaces in your HMCU application
For more details about supporting capability interfaces in your HMCU application logic, see Support Alexa Interfaces with the ACK Device SDK.