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.

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.

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

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.

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.

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.

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.

Related topics

• Product Design
• ACK Development Tutorials
• Product Design Best Practices

Last updated: Nov 27, 2023