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?

    User: Alexa, turn on my bedroom fan.
    User: Alexa, set the fan on low.
    User: Alexa, stop the fan.

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

Communicate with Alexa

Devices built with ACK use the Alexa Smart Home Skill API and 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 product you create in the ACK console 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 SDK support

BrightnessController

Control the brightness of a device, such as a smart light bulb.

SDK 4, SDK 3

ColorController

Change the color of a device, such as a light bulb.

SDK 4, SDK 3

ColorTemperatureController

Control the color temperature of a device that supports tunable white light.

SDK 4, SDK 3

Cooking

Control the cooking functions of a cooking appliance. Not all functions of Alexa.Cooking and related Alexa.Cooking interfaces are supported.

SDK 4, SDK 3

DeviceUsage.Estimation

Report the energy use of a device that estimates energy use.

SDK 4

DeviceUsage.Meter

Report the energy use of a device that measures energy use.

SDK 4

ModeController

A generic controller that provides a list of values to control device properties, such as the rinse cycle of a washing machine.

SDK 4, SDK 3

PercentageController

Control properties of a device that can expressed as a percentage, such as a light bulb set to 20 percent brightness.

SDK 4, SDK 3

PowerController

Control the power state of a device.

SDK 4, SDK 3

ProactiveNotificationSource

Notify a user when the device needs attention, such as when an oven finishes baking a cake.

SDK 4, SDK 3

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.

SDK 4, SDK 3

TemperatureSensor*

Report temperature for a device that measures temperature, such as a thermostat.

SDK 4

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.

SDK 4

TimeHoldController*

Pause a device, such as a microwave oven, while it's cooking.

SDK 4, SDK 3

ToggleController

A generic controller that provides an on/off toggle to control device properties like fan oscillation.

SDK 4, SDK 3

Improve 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 to your device and controls the hardware.

The following table shows how users can interact with your ACK-based device.

Example product Example utterance Description Capability interface

Tea kettle

User: Alexa, turn on the tea kettle.

Controls the power of the kettle.

PowerController

Dimmer switch

User: Alexa, dim the bedroom light to 50 percent.

Sets the brightness level of a light bulb.

BrightnessController

Fan

User: Alexa, set the fan speed to high.

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

The 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.

    User: Alexa, set the wash cycle to hot.

  • 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.
RangeController

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

RangeController implementation

  • When you use a RangeController interface, the voice interaction model is already built for you.

    User: Alexa, set the bedroom fan speed to 7.

  • 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.
ToggleController

The 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.

    User: Alexa, turn off economy mode.

  • 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

User: Alexa, set fan to high.
User: Alexa, increase fan speed.

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.

User: Alexa, set airflow to turbo.

For 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.

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.

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