Editor's note: we are happy to announce that some of the updates noted below - the new Mode, Range, and Toggle capability interfaces - are now generally available in the US. Learn more.
Today we announced two important updates to the Smart Home Skill API, available today in Preview to developers in the US, which let you extend voice control to any device—from the simplest wall plug to the most complex appliance—and to any feature of your device. First, we are adding Toggle, Range, and Mode capability interfaces, which you can use like building blocks to model the full feature set of your devices. The second update is the ability to use both custom intents and smart home directives in one skill. You no longer need to create a second custom skill when you want to add voice control for your device’s unique features or have a more conversational experience, and your customers only need to enable a single skill.
To get a first look at the Smart Home Skill API updates, check out our technical documentation.
Connect Any Device to Alexa with Flexible Building Block APIs
We’re adding three new capability interfaces: Alexa.ToggleController, Alexa.RangeController, and Alexa.ModeController to the Smart Home Skill API (Preview) that allow you to connect the features of any device to Alexa. You can customize these new capabilities to provide native integration for settings or features of a device that follow an on/off, numeric, or enumeration pattern. To provide fine control of your device, you can combine multiple instances of these capabilities as building blocks together with any of the dozens of existing capability interfaces like Alexa.ContactSensor. This enables you to provide voice control to anything from simple devices like plugs, to complex home appliances like washers and dryers with several toggles, multiple groups of settings, and many modes of operation. Alexa already supports the most common smart device features, such as turning on lights and locking doors; these new primitives give you the flexibility to control many more.
Alexa.ToggleController - The Alexa.ToggleController interface enables Alexa to control on/off based settings like “oscillate” on a fan, enabling/disabling the guest network of a network router, or starting/stopping a zone of a sprinkler system. By using the ToggleController interface, your customers can use on/off-based voice utterances like “Alexa, turn on child-lock on the dishwasher,” “Alexa, start the ice maker,” or “Alexa, enable auto-mode on the fan.”
Alexa.RangeController - The Alexa.RangeController interface provides an integration for numeric settings like the speed of a fan, the temperature of a shower, or other measurement values. By using the Alexa.RangeController interface, your customers can ask "Alexa, turn up the fan speed," or "Alexa, what is the temperature of the shower?"
Alexa.ModeController - The Alexa.ModeController interface provides an integration for settings that can be one of several named states or modes. These possible modes may be ordered, like low, medium, and high modes, or unordered, such as wash cycles of "Normal", "Delicates", or "Permanent Press". By using the Alexa.ModeController interface, your customers can use utterances such as "Alexa, set the wash cycle to delicates."
Declaring devices is done the same way as other capabilities interfaces such as Alexa.ColorController, Alexa.LockController, or Alexa.Speaker. With these new APIs, however, a single device can include multiple instances of Alexa.ToggleController, Alexa.RangeController, and Alexa.ModeController. This allows you to easily combine collections of settings that map the features of your device, however complicated they might be, to Alexa.
For example, a fan implementing the building block APIs could have three toggle settings with friendly names like “Auto Mode,” “Night Mode,” and “Oscillate.” This allows a customer to control each with phrases like, “Start Auto Mode,” “Turn on Night Mode,” or “Enable Oscillate.” These capabilities are defined on the device with three Alexa.ToggleControllers; one for each of the toggle settings defined.
Digging deeper, a Smart Home Discovery response describing a dishwasher appliance with multiple instances of Alexa.ToggleController capability interfaces in the capabilities array of an endpoint could look something like the following:
"endpoints": [
{
"endpointId": "endpoint-dishwasher",
"friendlyName": “dishwasher”,
...
"capabilities": [
{
"type”: "AlexaInterface",
"interface”: "Alexa.ToggleController",
"version”: "3",
"instance": "SampleManufacturer.Washer.AutoDry",
...
},
{
"type”: "AlexaInterface",
"interface”: "Alexa.ToggleController",
"version”: "3",
"instance": "SampleManufacturer.Washer.Buzzer",
...
}
]
}
]Toggle, Range, and Mode capabilities also support a new mechanism for specifying a list of capability friendly names, allowing you to customize what words customers can use to control their device. For example, the SampleManufacturer.Washer.Buzzer toggle instance in the previous example could have a Friendly Name of "Buzzer", with alternatives such as "Beeper" or "Alarm". This enables customers to more easily discover and naturally use this toggle by giving them additional names for the buzzer.
The Range and Mode capabilities allow further customization of names, with Range allowing named "presets" corresponding to particular numeric values, and Mode allowing named "modes.” For example, an electric tea kettle with various temperature set points might provide aliases for each type of tea that should steep at a particular temperature so customers could say “Alexa, set the tea kettle to 212 degrees Fahrenheit,” or simply “Alexa, set the tea kettle to boiling.” In this example, the value of the Range of 212 F and “boiling” represent the same Range value. If we look at the Smart Home Discovery response for a device that specifies might specify natural aliases for an Alexa.RangeController we could see a collection of capability presets that looks like the following:
{
"rangeValue": 212,
"presetResources": {
"friendlyNames": [
{
"@type": "text",
"value": {
"text": "boiling"
}
},
{
"@type": "text",
"value": {
"text": "very hot"
}
}
]
}
}For names of your device features or settings, you will also be able to take advantage of catalogs of pre-defined terms that are automatically localized to new regions. For terms that are specific to your devices or brand, you can provide translations in each language you support and Alexa will take care of choosing the right language.
Any functionality modeled using Toggle, Range, and Mode is available for customers to use as part of an Alexa Routine as well. For example, say “Alexa, good morning,” and your shower automatically turns to the customer’s pre-defined settings. Or “Alexa, good night,” and the fan turns down to night mode as the lights blink out. When you model your devices’ features with the native smart home device capabilities, Alexa knows how to make your devices work together to create a smarter, more comfortable, and productive home. The Alexa.ToggleController, Alexa.RangeController, and Alexa.ModeController capability interfaces make it even easier for you to let Alexa to control any smart home device.
For more technical information, see Connect Any Device to Alexa, the Alexa Skills Kit Capability Interface Message Guide, and the device templates documentation.
Use Multiple Skill Types in a Single Alexa Skill
Customers no longer need to search for and enable multiple skills to access all the features of their Alexa-connected device. Having to enable multiple skills also meant that you would have to configure and maintain separate skills for custom and smart home functionality. Now, you can publish and maintain a single skill that enables both the smart home and custom features of your device. This reduces effort for you and simplifies the customer experience.
Implementing multiple skill types in a single skill involves adding an additional model to a base skill either from the Alexa Developer Console, through SMAPI directly, or via the Alexa Skills Kit Command-Line Interface (ASK CLI) and updating your skill logic to handle requests from those models. You can also update existing skills through the Alexa Developer Console.
For example, adding multiple models from the Alexa Developer Console is simply part of the skill configuration workflow.
After adding a model to your skill, you will need to properly handle the functionality of the model in your skill logic in the same way you would previously handle custom, video, or smart home requests in separate skills.
For example, if you have an existing skill that uses a smart home model and you would like to update it to use a custom model, you would also need to add skill logic to handle the session requests from the custom interaction model either manually or with one of the Alexa Skill Kit Software Development Kits (SDKs) for Node.js, Java, or Python. In practical terms, this means evaluating the incoming request and responding appropriately to incoming custom session or smart home directive requests.
If you build a skill that combines video with smart home or custom skills, you will need to start the skill configuration workflow with the video skill. This is because the first run experience of a video skill requires users to associate a service provider with an AV device.
For more information on using multiple models in your skills, see Create Skills that Combine Models and the Alexa.CustomIntent Interface for declaring custom intents during device discovery.
The new updates are backwards-compatible and will be available later this year. To get a first look at the Smart Home Skill API updates, check out our technical documentation. To begin development using these new capabilities, apply to join the Smart Home Skill API (Preview). Your feedback is important to us and we are excited to see what you will connect to Alexa.