How to Control Your Cooking Devices with the Smart Home Skill API
Today we announced updates to the Smart Home Skill API to enable you to design skills that target cloud-connected microwave ovens. Here is an overview of how to connect your microwave to Alexa.
To create a skill for a microwave, follow the steps to build a smart home skill. However, describing food takes Alexa to a new level with the Smart Home Skill API. There are a few things to note when targeting a microwave, including:
- Understand how Alexa processes customer requests and chooses directives to send
- Understand how food is described in a directive or an event
- Know how to describe a microwave in your device discovery response
How Alexa Determines the Cooking Directive to Send
When a customer asks Alexa to cook something, Alexa will ask follow-up questions as needed to determine how to describe the food being cooked and what directive to send.
There are four interfaces related to cooking that define directives. Here’s how Alexa chooses the directive to send your skill.
- If timed cooking applies and is supported, Alexa sends a time-cooking directive (described by the Alexa.Cooking.TimeController interface).
-or-
- If a preset applies and is supported, Alexa sends a preset cooking directive (described by the Alexa.Cooking.PresetController interface).
- If the request is to pause or resume cooking, and they are supported, Alexa sends a hold or resume directive (described by Alexa.TimeHoldController).
- If none of the previous interfaces apply or are supported, Alexa sends a general cooking directive (described by the Alexa.Cooking interface).
For microwaves, you should always implement the Alexa.Cooking interface, but then you can choose additional interfaces to implement based on the capabilities of your endpoints. See each interface topic for more details and examples.
How Alexa Describes Food
If a customer specifies the type and quantity of food to cook, Alexa will send this information with the directive to your skill. However, when needed, Alexa uses what’s called a multi-turn dialog to find out the type and quantity of food to cook.
For example:
Customer: Defrost the chicken in the microwave
Alexa: What is the weight of the food you are defrosting?
Customer: 2 pounds
Alexa uses the food name specified by the customer to determine the food’s category. FoodCategory is an enumeration and contains entries such as MEAT, PASTA and POPCORN. Alexa understands that “chicken” means the CHICKEN category, and more complex things like “steak” means MEAT.
Either the customer will specify the number, weight or volume of the food to cook, or Alexa will ask questions until she knows. FoodQuantity, in a directive from Alexa, is polymorphic, meaning it can contain multiple descendant types; a Weight, Volume or FoodCount. The type will be specified by the @type field of the foodQuantity, which then determines the other fields sent.
In general, the list of food quantity units that Alexa can send is smaller than the list of food quantity units she understands. This means you can describe food with a long list of units and Alexa will understand the information in your response event. For more information, see Weight and Volume.
The food from the example multi-turn dialog might be described like the following:
{
"name":"foodItem",
"value":{
"foodName":"chicken",
"foodCategory":"CHICKEN",
"foodQuantity":{
"@type":"WEIGHT",
"value":"2",
"unit":"POUND"
}
}
}How You Describe Microwave Ovens in a Discovery Response
When you describe a microwave appliance in a discovery response, there are two you need to do:
- Set the displayCategory to MICROWAVE.
- Include configuration properties so Alexa knows if your devices support presets, the cooking modes supported, and more. This is in addition to the properties and interfaces you normally describe in a smart home discovery response.
In this example discovery response that describes a microwave, the microwave supports timed and preset cooking and the configuration properties are specified accordingly:
{
"event":{
"header":{
"namespace":"Alexa.Discovery",
"name":"Discover.Response",
"payloadVersion":"3",
"messageId":"ff746d98-ab02-4c9e-9d0d-b44711658414"
},
"payload":{
"endpoints":[
{
"endpointId":"microwave-001",
"manufacturerName":"the manufacturer name of the endpoint",
"friendlyName":"Microwave",
"description":"a description that is shown to the customer",
"displayCategories":[
"MICROWAVE"
],
"cookie":{
"key1":"key/value pairs to reference this endpoint.",
"key2":"There can be multiple entries",
"key3":"use for reference purposes.",
"key4":"Do not use to maintain current endpoint state."
},
"capabilities":[
{
"type":"AlexaInterface",
"interface":"Alexa.Cooking",
"version":"3",
"properties":{
"supported":[
{
"name":"cookingMode"
},
{
"name":"cookCompletionTime"
},
{
"name":"isCookCompletionTimeEstimated"
},
{
"name":"isHolding"
},
{
"name":"foodItem"
}
],
"proactivelyReported":true,
"retrievable":true
},
"configuration":{
"cookingModes":[
"TIMECOOK",
"DEFROST",
"REHEAT"
]
}
},
{
"type":"AlexaInterface",
"interface":"Alexa.Cooking.TimeCooking",
"version":"3",
"properties":{
"supported":[
{
"name":"cookTime"
},
{
"name":"powerLevel"
}
],
"proactivelyReported":true,
"retrievable":true
},
"configuration":{
"enumeratedPowerLevels":[
"LOW",
"MEDIUM",
"HIGH"
],
"integralPowerLevels":[
],
"cookingModes":[
"TIMECOOK",
"DEFROST",
"REHEAT"
],
"supportsRemoteStart":true
}
},
{
"type":"AlexaInterface",
"interface":"Alexa.Cooking.PresetController",
"version":"3",
"properties":{
"supported":[
{
"name":"presetName"
},
{
"name":"foodDoneness"
}
],
"proactivelyReported":true,
"retrievable":true
},
"configuration":{
"presetCatalogId":"microwave-001-catalog",
"cookingModes":[
"DEFROST",
"REHEAT"
],
"supportsRemoteStart":true
}
}
]
}
]
}
}
}Get Started with Your Cooking Skill
Alexa handles many of the complexities of writing a skill for cooking appliances. She either interprets customer requests or asks enough questions until she understands their goal. Keep these tips in mind as you started developing skills for microwave ovens:
- If you have never built a smart home skill before, review the basics. See Smart Home Skill API Message Reference and Steps to Build a Smart Home Skill before you move on to the next step.
- If you have built a smart home skill previously and just want to focus on skills for microwave ovens, see Build Skills for Cooking Appliances.
- Describing food is a more complex domain for Alexa than other smart home offerings. Make sure you test and thoroughly vet your skill before you submit it for certification.