Choose capability interfaces
Before you start building, identify the features of your device and map each feature to the appropriate capability interface.Inventory your device features
List every feature of your device that you want customers to control with voice or view in the Alexa app. For each feature, decide the customer action, such as turning the device on and off, changing a setting, or reading a sensor value. For each action, determine the values that your device accepts and whether the customer can change the value or read the value. The following example shows a feature inventory for a smart fan.| Device feature | Customer action | Value | Customer controllable |
|---|---|---|---|
| Power | Turn on or off | On, off | Yes |
| Fan speed | Set speed, increase speed, decrease speed | Number range: 1–10 | Yes |
| Oscillation | Turn oscillation on or off | On, off | Yes |
| Temperature | View ambient temperature | Numeric | No (read-only) |
Map features to interfaces
After you complete the inventory, map each feature to the appropriate capability interface. The interfaces you choose determine the voice commands your customers can use, how your device appears in the Alexa app, and which properties Alexa can report. Alexa provides three categories of interfaces:-
Specific interfaces – Purpose-built interfaces for common device features, such as
Alexa.PowerControllerorAlexa.ThermostatController. These interfaces provide the most natural voice interactions because Alexa understands the context. -
Generic controller interfaces – Flexible interfaces that you can use to model device properties, such as
Alexa.ModeControllerandAlexa.RangeController. Use a generic controller when no specific interface matches your feature. For more details, see Generic Controller Interfaces. - Custom capability interfaces – When your device has a specialized feature that doesn’t map to any specific or generic controller interface, you can define a custom interface. You add custom interfaces to your code in the same way as pre-built interfaces. For details, see Add Custom Capabilities.
Alexa.PercentageController or Alexa.RangeController, but if you implement the Alexa.BrightnessController interface instead, Alexa provides built-in support for the phrase
If your device is a cooking appliance, energy device, entertainment device, or security device, review the interfaces and guidance for that category. For details, see Smart Home Add-on Types.
Prerequisites
Before you begin, make sure that you have the following items:- Amazon developer account — You can use an existing Amazon account to sign in, or you can create a new Amazon developer account. The account is free.
- Amazon Web Services (AWS) account — The AWS account gives you access to resources as part of the free tier of services. You host your add-on code on AWS Lambda.
- Device cloud — Cloud infrastructure that interacts with your devices and can associate customers with their devices. You can use AWS IoT or your own cloud provider.
- Smart device — Your device, such as a light, thermostat, camera, lock, that connects to the device cloud. Your add-on communicates with your device, or device cloud, by using communication channels supported by your device.
- Alexa-enabled device, such as an Amazon Echo — Make sure that you sign in to the Echo with the same credentials as your Alexa developer account.
- Alexa app — Installed on your mobile device. For instructions about how to download the Alexa app, see Download the Alexa app on the Amazon website. Make sure that you sign in to the Alexa app on your mobile device with the same credentials as your Alexa developer account.
- Programming knowledge — Familiarity with JSON and one of the supported programming languages for AWS Lambda add-on code: Node.js, Java, Python, C#, Go, Ruby, or PowerShell.
- OAuth 2.0 provider — An OAuth server for account linking. You can use the Amazon Login with Amazon (LWA) authorization server or you can choose your own OAuth 2.0 provider.
- Capability interfaces — Selected capability interfaces that match the features of your device.
- Familiarity with the certification requirements — Review the policy, security, and Works with Alexa (WWA) certification requirements.
Add-on development steps
To build, test, and publish a smart home add-on, complete the following steps. Each step links to a dedicated topic with detailed instructions.- Create and Configure a Smart Home Add-on.
- Implement Smart Home Add-on Code.
- Test and Debug Your Smart Home Add-on.
- Publish and Certify Your Smart Home Add-on.

