Smart Home Capability Interfaces

When you build a product with the Alexa Connect Kit (ACK), you specify the interactions between your device, Alexa, and the Alexa app. If you build a smart fan, for example, consider the following questions:

Which Alexa utterances does my fan support?
Which features does my fan support? For example, can users power my fan on and off? Can they change the speed?

To support features like these, you must choose the appropriate smart home capability interface.

Communicate with Alexa

Devices built with ACK use the smart home capability interfaces to communicate to Alexa.
These interfaces provide the Alexa utterances needed for voice operation of your device, and they enable the Alexa app to display device controls. Any ACK-based product you create can be powered on with the default Alexa.PowerController capability. To customize your product, you can modify or remove capabilities. For example, a colored smart light device can support the PowerController, BrightnessController, and ColorController interfaces. These interfaces let users 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
`BrightnessController`	Control the brightness of a device, such as a smart light bulb.
`ColorController`	Change the color of a device, such as a light bulb.
`ColorTemperatureController`	Control the color temperature of a device that supports tunable white light.
`Cooking`	Control the cooking functions of a cooking appliance. Not all functions of `Alexa.Cooking` and related `Alexa.Cooking` interfaces are supported.
`DeviceUsage.Estimation`	Report the energy use of a device that estimates energy use.
`DeviceUsage.Meter`	Report the energy use of a device that measures energy use.
`ModeController`	A generic controller that provides a list of values to control device properties, such as the rinse cycle of a washing machine.
`PercentageController`	Control properties of a device that can expressed as a percentage, such as a light bulb set to 20 percent brightness.
`PowerController`	Control the power state of a device.
`ProactiveNotificationSource`	Notify a user when the device needs attention, such as when an oven finishes baking a cake.
`RangeController`	A generic controller that provides a range of values to control device properties, such as the speed setting of a fan from 1 to 10.
`TemperatureSensor`*	Report temperature for a device that measures temperature, such as a thermostat.
`ThermostatController`*	Control the target temperature and mode of a device that manages temperature automatically, such as a furnace, air conditioner, ceiling fan, or water heater.
`TimeHoldController`*	Pause a device, such as a microwave oven, while it’s cooking.
`ToggleController`	A generic controller that provides an on/off toggle to control device properties like fan oscillation.

Improve product design

The smart home interfaces you choose define the Alexa utterances that control your product. For example, when a user says the Alexa service interprets the utterance and sends an Alexa.PowerController.TurnOn directive to the ACK service. The ACK service then routes it to your device and controls the hardware. The following table shows how users can interact with your ACK-based device.

Example product	Description	Capability interface
Tea kettle	Controls the power of the kettle.	`PowerController`
Dimmer switch	Sets the brightness level of a light bulb.	`BrightnessController`
Fan	Sets the speed of a fan.	`RangeController` or `ModeController`

Enhance Alexa app design

When you create a product with ACK, you don’t need to build your own companion app to control your devices. Instead, you use pre-built smart home components in the Alexa app. When you include a smart home capability in your design, the Alexa app automatically gives users access to the relevant controls. For example, if you support a feature with a ToggleController interface, users see an on/off toggle in the Alexa app. If you support a feature with the ModeController interface, users see a drop-down menu in the app.

Examples

ModeController
RangeController
ToggleController

ModeControllerThe ModeController interface lets users control device settings by selecting from a list of values. For example, a user can control the speed of a fan by choosing Low, Medium, or High from a drop-down menu in the Alexa app.

ModeController implementation

When you use a ModeController interface, the voice interaction model is already built for you.
When you use the ModeController interface, each drop-down option can have one or more friendly names and an associated numeric value. For example, to control dryer temperature, you might have three heat settings: Low, Medium, and High. These settings translate into the following values.
- Value 1, friendly name: Low
- Value 2, friendly name: Easy care or Medium
- Value 3, friendly names: Max or High
You can define multiple friendly names for both ModeController and its options. However, the Alexa app displays only the first friendly name. The other friendly names are used for voice interaction only.
You can use multiple ModeControllers on a single device, but each one must have a unique instance id.
You can also set ModeController as a non-controllable display. For example, it can display the current state of the device in the Alexa app.

RangeControllerThe 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 shows users a sliding selector.

RangeController implementation

When you use a RangeController interface, the voice interaction model is already built for you.
When you use a RangeController interface, you define the following variables.
- Unit type, such as degrees or percentage
- Minimum and maximum range values
- Precision, which are the steps between values
- Presets, which are named options for each value, such as maximum or medium
You can define multiple friendly names for both RangeController and each preset. The Alexa app displays only the first friendly name. The other friendly names are used for voice interaction only.
You can use multiple RangeControllers on a single device. Each RangeController must have a unique instance id.

ToggleControllerThe ToggleController interface lets you control settings on a device by using an on/off toggle. In the Alexa app, ToggleController renders as a single toggle with an on/off state.

ToggleController implementation

When you use a ToggleController interface, the voice interaction model is already built for you.
You can define multiple friendly names for ToggleController. The Alexa app displays only the first friendly name. The other friendly names are used for voice interaction only.
You can use multiple ToggleControllers on a single device. Each ToggleController must have a unique instance id.

Example: Define the capability interfaces for a fan

The following smart fan example shows you how to work with capability interfaces. This example defines both the utterances a user can say to control the fan and the experience they see in the Alexa app. It also identifies the interfaces the fan uses and explains how they function.

ACK feature	Example
Device type	Fan
Basic functionality	Control fan speed
Alexa utterances
Alexa app settings	Display a fan speed selector with Low, Medium, and High settings
Alexa capability interfaces	`ModeController` with instance id value of `1`
Supported modes or ranges	Low mode with a value of `1` Medium mode with a value of `2` High mode with a value of `3`
Friendly name for the controller	`ModeController` uses a friendly name of Speed
Resulting directive	`ModeController` `SetMode` directive with instance id value of `1` and mode value of `3`
Possible errors	User requests fan speed adjustments beyond supported values, such as a request to decrease the speed when the fan is already set to Low
Error response	State that `ModeController` value is out of range, and provide response that states acceptable values
Additional comments	If a user tries to change the speed of a fan that’s 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 or Max. You could also set a synonym for the Speed setting, such as Airflow. With these two friendly names, a user could control your fan with the following utterance. For more details, 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. Then use the smart home capabilities editor to add, remove, and edit your product’s smart home capabilities. The following image shows a product built in the ACK developer console. Here, you can add your smart home capabilities in the supplied JSON editor. In this example, the product contains the necessary JSON to support the Alexa.ModeController interface.

Show full Alexa.ModeController JSON example

 {
     "type": "AlexaInterface",
     "interface": "Alexa.ModeController",
     "instance": "1",
     "version": "3",
     "properties": {
       "supported": [
         {
           "name": "mode"
         }
       ],
       "retrievable": true,
       "proactivelyReported": true,
       "nonControllable": false
     },
     "capabilityResources": {
       "friendlyNames": [
         {
           "@type": "text",
           "value": {
             "text": "Speed",
             "locale": "en-US"
           }
         }
       ]
     },
     "configuration": {
       "ordered": true,
       "supportedModes": [
         {
           "value": "1",
           "modeResources": {
             "friendlyNames": [
               {
                 "@type": "text",
                 "value": {
                   "text": "Low",
                   "locale": "en-US"
                 }
               }
             ]
           }
         },
         {
           "value": "2",
           "modeResources": {
             "friendlyNames": [
               {
                 "@type": "text",
                 "value": {
                   "text": "Medium",
                   "locale": "en-US"
                 }
               },
             ]
           }
         },
         {
           "value": "3",
           "modeResources": {
             "friendlyNames": [
               {
                 "@type": "text",
                 "value": {
                   "text": "High",
                   "locale": "en-US"
                 }
               }
             ]
           }
         }
       ]
     }
   }

### Support capability interfaces for your host microcontroller unit (HMCU) app For details about supporting capability interfaces in your HMCU application logic, see Support Alexa Interfaces with the ACK Device SDK. ### Edit a virtual product The following instructions explain how to edit your virtual product in the ACK developer console.

Log in to the ACK developer console.
Click Products, and then click the product you want to edit.
Next to Alexa smart home capabilities, click Edit.

Get Started

Product Development Guidelines

Tutorials

Troubleshooting

Reference

Communicate with Alexa

Improve product design

Enhance Alexa app design

Examples

ModeController implementation

RangeController implementation

ToggleController implementation

Example: Define the capability interfaces for a fan

Friendly names

​Communicate with Alexa

​Improve product design

​Enhance Alexa app design

​Examples

​ModeController implementation

​RangeController implementation

​ToggleController implementation

​Example: Define the capability interfaces for a fan

​Friendly names

​Related topics

Communicate with Alexa

Improve product design

Enhance Alexa app design

Examples

ModeController implementation

RangeController implementation

ToggleController implementation

Example: Define the capability interfaces for a fan

Friendly names

Related topics