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.

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.

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

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.

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.

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"
                }
              }
            ]
          }
        }
      ]
    }
  }

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.

Related topics

• Product Design
• ACK Development Tutorials