Your Alexa Dashboards
Sign In
?
Sign In
Your Alexa Dashboards Settings

Alexa.Cooking.TimeController Interface

The Alexa.Cooking.TimeController interface describes messages used control cooking appliances that operate on time and an optional power level. Directives in this interface are sent when a customer requests cooking for a specified time at a specified power-level and adjustments to the cooking time. This interface must be used with the Alexa.Cooking Can also be used in conjunction with Alexa.Cooking.PresetController for more cooking options.

For information about skills and additional interfaces related to cooking, see Build Smart Home Skills for Cooking Appliances.

Discovery

In addition to the standard discovery format, the TimeController discovery response should include a configuration object with the following fields.

Property Description Type Required
supportedsupportedCookingModes Specifies the cooking modes supported for this appliance’s implementation of the TimeController interface. Must contain TIMECOOK and the first cooking mode specified is used as the default cooking mode. Array of CookingMode objects that must include TIMECOOK. Yes
enumeratedPowerLevels Identifies the EnumeratedPowerLevel values supported by this cooking appliance. When no power levels are specified, a customer can control the appliance with IntegralPowerLevel values only String array, which can be empty. Yes
integralPowerLevels Identifies the integralPowerLevel values supported by this cooking appliance. String array, which can be empty. Yes
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 No

The following example depicts a Discover.Response event for a microwave that supports the TimeController interface.

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "ff746d98-ab02-4c9e-9d0d-b44711658414"
        },
        "payload": {
            "endpoints": [{
                "endpointId": "uniqueIdOfApplianceEndpoint",
                "manufacturerName": "the manufacturer name of the endpoint",
                "friendlyName": "Microwave",
                "description": "a description that is shown to the customer",
                "displayCategories": [
                    "MICROWAVE"
                ],
                "cookie": {},
                "capabilities": [{
                        "type": "AlexaInterface",
                        "interface": "Alexa",
                        "version": "3"
                    },
                    {
                        "type": "AlexaInterface",
                        "interface": "Alexa.Cooking.TimeController",
                        "version": "3",
                        "properties": {
                            "supported": [{
                                    "name": "cookTime"
                                },
                                {
                                    "name": "powerLevel"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        },
                        "configuration": {
                            "supportsRemoteStart": false,
                            "enumeratedPowerLevels": ["LOW", "MEDIUM", "HIGH"],
                            "integralPowerLevels": [],
                            "supportedCookingModes": ["TIMECOOK", "DEFROST", "REHEAT"]
                        }

                    }
                ]
            }]
        }
    }
}

Directives

The control and query directives in this interface are supported in skills that target the following language:

  • English (US)

See Develop Smart Home Skills in Multiple Languages for more information.

CookByTime

Request to cook the food in the appliance for the specified duration and at an optional power level.

User: Alexa, 2 minutes on the microwave

Example Request

{
  "directive": {
    "header": {
      "namespace": "Alexa.Cooking.TimeController",
      "name": "CookByTime",
      "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": {
        "cookTime": {
            "value": "PT3M"
        },
        "cookingPowerLevel": {
            "@type": "EnumeratedPowerLevel",
            "value": "LOW"
        }
    }
  }
}

Payload details

Field Description Type Required
cookTime Specifies how long the cooking appliance should run. Duration object Yes
cookingMode If present, Alexa will specify one of the supported cooking modes described in the interface’s discovery for the appliance. Typically, if present this is DEFROST or REHEAT. When not present, it indicates that the cookingMode should be chosen by the appliance. For instance, a microwave could choose TIMECOOK. CookingMode object No
cookingPowerLevel Specifies the power level at which to cook. If not specified, the appliance should use it’s default power level. EnumeratedPowerLevel or IntegralPowerLevel value. No
foodItem The type of food to cook, if it was specified. FoodItem object No

AdjustCookTime

Adds the specified amount of time to the existing cooking session.

User: Alexa, 30 more seconds to the microwave.

Example

{
  "directive": {
    "header": {
      "namespace": "Alexa.Cooking.TimeController",
      "name": "AdjustCookTime",
      "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": {
        "cookTimeDelta": "PT30S"
    }
  }
}

Payload Details

Field Description Type Required
cookTimeDelta Duration Yes This property indicates how much time to add to the cooking session.

Properties and Events

For this interface, you must reply:

  • Synchronously, which means you send a Response to Alexa from the Lambda function.

When you send a Response, you should include the state of reportable properties in the context of the message.

Reportable Properties

Property Name Type Description
requestedCookTime Duration The amount of time the user requested when initiating the cook cycle.
cookingPowerLevel EnumeratedPowerLevel or IntegralPowerLevel Can be optionally returned if the cooking appliance is set to a power level.

Response

If the CookByTime directive was successfully handled, you must respond synchronously with a Response event. Report the value of all relevant properties in the context of the message.

Example Response

In this example, the endpoint supports Cooking and Cooking.TimeController.

{
    "event": {
        "context": {
            "properties": [{
                    "namespace": "Alexa.Cooking",
                    "name": "cookingMode",
                    "value": "TIMECOOK",
                    "timeOfSample": "2017-08-31T23:30:00Z",
                    "uncertaintyInMilliseconds": 0
                },
                {
                    "namespace": "Alexa.Cooking",
                    "name": "cookCompletionTime",
                    "value": "2017-08-31T23:55Z",
                    "timeOfSample": "2017-08-31T23:30:00Z",
                    "uncertaintyInMilliseconds": 0
                },
                {
                    "namespace": "Alexa.Cooking",
                    "name": "isCookCompletionTimeEstimated",
                    "value": false,
                    "timeOfSample": "2017-08-31T23:30:00Z",
                    "uncertaintyInMilliseconds": 0
                },
                {
                    "namespace": "Alexa.Cooking",
                    "name": "isHolding",
                    "value": false,
                    "timeOfSample": "2017-08-31T23:30:00Z",
                    "uncertaintyInMilliseconds": 0
                },
                {
                    "namespace": "Alexa.Cooking",
                    "name": "foodItem",
                    "value": {
                        "foodName": "Rice Pilaf",
                        "foodCategory": "Rice",
                        "foodQuantity": {
                            "@type": "VOLUME",
                            "value": "2",
                            "unit": "US_FLUID_CUP"
                        }
                    },
                    "timeOfSample": "2017-08-31T23:30:00Z",
                    "uncertaintyInMilliseconds": 0
                },
                {
                    "namespace": "Alexa.Cooking.TimeController",
                    "name": "cookTime",
                    "value": "PT25M",
                    "timeOfSample": "2017-08-31T23:30:00Z",
                    "uncertaintyInMilliseconds": 0
                },
                {
                    "namespace": "Alexa.Cooking.TimeController",
                    "name": "cookingPowerLevel",
                    "value": {
                        "@type": "EnumeratedPowerLevel",
                        "value": "HIGH"
                    },
                    "timeOfSample": "2017-08-31T23:30:00Z",
                    "uncertaintyInMilliseconds": 0
                }
            ]
        },
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token":"access-token-from-Amazon"
            },
            "endpointId": "appliance-001"
        },
        "payload": {}
    }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. For cooking-specific errors such as an appliance door is open, see Alexa.Cooking.ErrorResponse. For generic errors, such as a device is offline, see Error.Response.

Interface Description
Alexa.Cooking Provides directives for cooking when no preset option is available.
Alexa.Cooking.TimeController Provides directives for cooking by time interval.
Alexa.TimeHoldController Provides directives for pausing or resuming an endpoint.