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

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 color-changing 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. For example, the wash cycle of a washing machine.

SDK 4, SDK 3

PercentageController

Control properties of a device that can expressed in percentage. For example, a light bulb set to twenty percent brightness.

SDK 4, SDK 3

PowerController

Control the power state of a device.

SDK 4, SDK 3

ProactiveNotificationSource

Notify a user when their device needs attention. For example, notify a user when their oven finishes cooking food.

SDK 4, SDK 3

RangeController

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

TemperatureSensor*

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

SDK 4

ThermostatController*

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

TimeHoldController*

Pause a device. For example, pauses a microwave oven while it's cooking.

SDK 4, SDK 3

ToggleController

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.

PowerController

Dimmer switch

"Alexa, dim the bedroom light to fifty percent."

Sets the brightness level of a light bulb.

BrightnessController

Fan

"Alexa, set the fan speed to high."

Sets the speed of the fan.

RangeController or ModeController

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

ModeController

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 each ModeController 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.
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 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:
    • Unit type, such as degrees or percentage.
    • Minimum and maximum value of the range.
    • Precision, which are the steps between values.
    • Presets, which are named options for each value. For example, maximum or medium.
  • 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. Each RangeController needs to have a unique instance id.
ToggleController

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

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. For example, a request to decrease the speed when the fan is already set to Low.

Error response

State that the ModeController value is out of range. Provide a response that states the acceptable values.

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

  1. Log-in to the ACK developer console.
  2. Click Products, then click the product you want to edit.
  3. 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.