Build Smart Home Skills for Cooking Appliances

Smart home skills created for cooking appliances like microwave ovens give customers voice access to cooking. For example, with the appropriately-configured smart home skill, a customer can say, "Alexa, cook a frozen pizza in the microwave" and the microwave starts cooking in the preset pizza mode.

This document provides an overview of the technical requirements as well as specific directives and properties for smart home skills that target cooking appliances.

Get started

If this is your first time creating a smart home skill, you should review the existing documentation as a prerequisite to this document. You will need to be familiar how to create a smart home skill and write the code for a Lambda function that handles smart home requests from Alexa. For more information see:

Target v3 and English

In the developer console, when you create a skill for cooking appliances, you need to select v3 (preferred) and English (US) as the target version and language for the skill. This will ensure your skill receives messages for requests related to cooking appliances.

Message format

Alexa first sends a discovery request to your skill's Lambda function and you describe the target cooking appliance in the response. Each appliance is an endpoint described by a list of interface capabilities. Each interface defines the directives that Alexa can send to the skill and events that can be sent from the skill back to Alexa. An interface also defines reportable properties that you might send in an event to describe the current state of the endpoint. After discovery, Alexa sends your skill a directive as a result of a customer request and details of the request. You respond with an event that indicate the request was handled successfully, or an error message. Alexa can then respond appropriately to the customer.

For more information about directive and event message formats, see Smart Home Skill Message Reference.

How food and cooking modes are described

Alexa uses information in the customer request to decide what kind of cooking directive to send. Alexa sends preset and timed cooking directives over more general directives, but the directives sent are also based on the endpoint capabilities disclosed in discovery. The directive includes details about the food to cook.

Following is an example of a cooking request:

User: Alexa, cook a 2 1/2 pound copper river salmon fillet in the microwave

In this case, there is a preset on this appliance for FISH, so Alexa sends a CookByPreset directive with details about the food.

Example directive

{
    "directive": {
        "header": {
            "namespace": "Alexa.Cooking.PresetController",
            "name": "CookByPreset",
            "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-skill"
            },
            "endpointId": "appliance-001",
            "cookie": {}
        },
        "payload": {
            "presetName": "fish",
            "name": "foodItem",
            "value": {
                "foodName": "copper river salmon",
                "foodCategory": "FISH",
                "foodQuantity": {
                    "@type": "WEIGHT",
                    "value": "2.5",
                    "unit": "POUND"
                }
            },
            "cookingMode": "PRESET"
        }
    }
}

Food

In a directive, food is represented with a FoodItem object, which in turn contains a foodQuantity and foodCategory field. Alexa uses the food name specified by the user to categorize it. For Alexa would put "sockeye salmon fillet", in the FISH category.

A foodQuantity will be one of the following:

When you receive a directive that contains food, you use the @type field to determine the foodQuantity type, and then parse the rest of the description based on the type. Alexa uses a small set of units to describe the count, weight or volume of a food, but you can choose from a larger list in your messages to Alexa. The supported values are described in the following enumerations:

Cooking mode

When a user asks to defrost or bake an item, Alexa identifies this as the cooking mode for the food. The cooking mode is sent in the payload of a directive in the cookingMode field, which takes a CookingMode value. A cooking mode can a predetermined cooking mode such as DEFROST, or PRESET, which indicates a cooking mode programmed into the appliance. You specify all of the cooking modes your appliance supports in the discovery response. See Configuration Payload for more details.

Representing time

There are two different ways to represent time related to cooking operations:

  • Duration: Describes a cooking duration
  • DateTime: Used to describe when a cooking operation started or finished.

Preset catalogs

Preset cooking relies on a catalog that you provide to us. Catalogs can vary by brand, appliance type, and model. You identify the catalog to use when you provide discovery for an appliance, and items from that catalog are sent in directives to your skill. To submit a preset cooking catalog for Alexa to use, complete the following steps.

  • Send email to alexa-kitchen-presets@amazon.com. In the subject line provide:

    • Appliance brand
    • Appliance type
    • Appliance model

    Example email request:

    To: alexa-kitchen-presets@amazon.com
    Subject: Brand: some appliance brand, Appliance type: some appliance type, Appliance model: some appliance model

  • You will receive a response within two weeks with:

    • Details of how to format your preset information in Excel and where to upload the Excel file that contains your preset catalog.
    • A preset catalog ID, which is a unique identifier for this catalog. The ID is between 3 and 63 characters long, and contains only numbers, lower case letters, and hyphens. You specify this value in a discovery response for the appliance.

Discovery for cooking appliances

When you describe cooking appliances in initial device discovery you provide a display category, describe the capabilities associated with each device, and properties that you support for each capability. You will also provide some configuration values that further describe the cooking appliance. The required configuration values are described in each interface topic.

Display category

Provide the displayCategory for the endpoint, which enables it to display properly in the Alexa app. Currently cooking endpoints can be described with the following display category.

  • MICROWAVE - Indicates the endpoint is a microwave oven

Configuration payload

Following is a list of configuration properties and interfaces where you will provide them. See each interface topic for more details.

Property Description Type Interface(s)
supportedCookingModes Specifies the cooking modes supported for each interface. The first cooking mode specified is used as the default cooking mode. An array of CookingMode values. Cooking interface, requires OFF
Cooking.PresetController, cannot contain OFF
Cooking.TimeController, requires TIMECOOK
enumeratedPowerLevels Specifies the named power levels supported by this endpoint. If no enumerated power levels are specified, users cannot control the power level using an enumerated value such as "LOW" or "HIGH". An array of EnumeratedPowerLevel values. TimeController
integralPowerLevels Optional numeric power levels supported by this endpoint. When no integral power levels are specified, Alexa will not allow users to control the power level using a integral value. The default is an empty array. An array of IntegralPowerLevel values. TimeController
presetCatalogId The identifier for the preset catalog to use for this controller. See Preset catalogs for more information. String PresetController
supportsRemoteStart True to indicates the appliance starts with an Alexa voice command, otherwise false indicates the appliance is set to the specified cooking mode, but does not start until the customer presses the start button on the appliance. The default is false. Boolean Cooking, PresetController TimeController

Discovery example

The following code example shows how you might describe a cooking appliance that supports timed and preset cooking. For more information on general device discovery messages, see Alexa.Discovery.

Example Discovery Response for a Microwave

{
    "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": {
                            "supportedCookingModes": ["DEFROST", "REHEAT", "OFF"]
                        }
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.Cooking.TimeController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                    "name": "cookTime"
                                },
                                {
                                    "name": "powerLevel"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "enumeratedPowerLevels": ["LOW", "MEDIUM", "HIGH"],
                            "integralPowerLevels": [],
                            "supportedCookingModes": ["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",
                            "supportedCookingModes": ["DEFROST", "REHEAT"],
                            "supportsRemoteStart": true
                        }
                    }
                ]
            }]
        }
    }
}

Interfaces for cooking appliances

As mentioned previously, message formats are are defined in interfaces, which are organized by device capability. The table below lists interfaces that describe cooking capabilities and other capabilities that you will need to implement for your skill.

Operation Capability Interface
Discover and describe endpoints. Implemented by all smart home skills. Alexa.Discovery
Start cooking when a preset does not apply, stop cooking, or change the cooking mode of an appliance Alexa.Cooking
Cook by time Alexa.Cooking.TimeController
Cook using appliance presets Alexa.Cooking.PresetController
Pause or resume cooking Alexa.TimeHoldController
Describe the API message version supported by the skill. Implemented by all smart home skills Alexa interface
Describe the current state of an endpoint. Implemented by all smart home skills Alexa.EndpointHealth

Errors

Errors can occur because the customer asks for something that cannot be completed, or there is a communication issue between the skill and the cooking appliance.

  • For errors that occur because the customer requests a cooking operation that isn't allowed, the appliance door is open or other cooking-specific errors, see the Alexa.Cooking.ErrorResponse topic.
  • For more generic communication errors, see the Alexa.ErrorReponse topic.

Learn More

For detailed steps to implement a skill, see Steps to Build a Smart Home Skill. For more details on message formats for directive sent from Alexa and how to respond, see Smart Home Skill Message Reference.