# Smart Home Cook Trait Schema

`action.devices.traits.Cook` - This trait belongs to devices that can cook food according to various food presets and supported cooking modes.

Examples of these device types include [Multicooker](https://developers.home.google.com/cloud-to-cloud/guides/multicooker), [Pressure cooker](https://developers.home.google.com/cloud-to-cloud/guides/pressurecooker),
[Blender](https://developers.home.google.com/cloud-to-cloud/guides/blender), and [Microwave](https://developers.home.google.com/cloud-to-cloud/guides/microwave). Cook commands may include the quantity and name of
the food, such as "Two cups of brown rice", where "brown rice" is a food preset for the device.

This trait does not handle cooking time or cooking temperature.
See [Timer](https://developers.home.google.com/cloud-to-cloud/traits/timer) and [TemperatureControl](https://developers.home.google.com/cloud-to-cloud/traits/temperaturecontrol)
for more information.

## Device ATTRIBUTES

Devices with this trait may report the following
attributes as part of the [`SYNC`](https://developers.home.google.com/cloud-to-cloud/intents/sync) operation. To learn
more about handling `SYNC` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/sync).

| Attributes | Type | Description |
|---|---|---|
| `supportedCookingModes` | *Array* | **Required.** Cooking modes supported by this device. |
| `[*item, ...*]` | *String* | Cooking mode. Supported values: `UNKNOWN_COOKING_MODE` `BAKE` `BEAT` `BLEND` `BOIL` `BREW` `BROIL` `CONVECTION_BAKE` `COOK` `DEFROST` `DEHYDRATE` `FERMENT` `FRY` `GRILL` `KNEAD` `MICROWAVE` `MIX` `PRESSURE_COOK` `PUREE` `ROAST` `SAUTE` `SLOW_COOK` `SOUS_VIDE` `STEAM` `STEW` `STIR` `WARM` `WHIP` |
| `foodPresets` | *Array* | Presets for certain types of food. |
| `[*item, ...*]` | *Object* | Food preset. |
| `food_preset_name` | *String* | **Required.** Internal name of the food preset, which will be used in commands and states. This name can be non-user-friendly, and is shared across all languages. |
| `supported_units` | *Array* | **Required.** Contains all of the units supported by the device for a specific food. |
| `[*item, ...*]` | *String* | Supported unit. Supported values: `UNKNOWN_UNITS` `NO_UNITS` `CENTIMETERS` `CUPS` `DECILITERS` `FEET` `FLUID_OUNCES` `GALLONS` `GRAMS` `INCHES` `KILOGRAMS` `LITERS` `METERS` `MILLIGRAMS` `MILLILITERS` `MILLIMETERS` `OUNCES` `PINCH` `PINTS` `PORTION` `POUNDS` `QUARTS` `TABLESPOONS` `TEASPOONS` |
| `food_synonyms` | *Array* | **Required.** Food name synonyms for the preset in each supported language. |
| `[*item, ...*]` | *Object* | Food name. At least one item with a `lang` value of `en` is required in order to provide language fallback. |
| `synonym` | *Array* | **Required.** Synonyms for the preset, should include both singular and plural forms, if applicable. |
| `[*item, ...*]` | *String* | Preset synonym name. At least one item with a `lang` value of `en` is required in order to provide language fallback. |
| `lang` | *String* | **Required.** Language code (ISO 639-1). See [supported languages](https://developers.home.google.com/cloud-to-cloud/traits#supported-languages). |

#### Examples

*Device with only one cooking mode and no preset.*

```
{
  "supportedCookingModes": [
    "BAKE"
  ]
}
```

*Device with multiple cooking modes and food presets.*

```
{
  "supportedCookingModes": [
    "COOK",
    "WARM"
  ],
  "foodPresets": [
    {
      "food_preset_name": "white_rice",
      "supported_units": [
        "CUPS"
      ],
      "food_synonyms": [
        {
          "synonym": [
            "White Rice",
            "Rice"
          ],
          "lang": "en"
        }
      ]
    },
    {
      "food_preset_name": "brown_rice",
      "supported_units": [
        "CUPS"
      ],
      "food_synonyms": [
        {
          "synonym": [
            "Brown Rice"
          ],
          "lang": "en"
        }
      ]
    }
  ]
}
```

## Device STATES

Entities with this trait may report the following
states as part of the [`QUERY`](https://developers.home.google.com/cloud-to-cloud/intents/query) operation. To learn
more about handling `QUERY` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute).

| States | Type | Description |
|---|---|---|
| `currentCookingMode` | *String* | **Required.** Describes the current cooking mode set on the device, from the `supportedCookingModes` attribute. Only one mode may be reported. If no mode is currently selected, this should be set to NONE. |
| `currentFoodPreset` | *String* | The `food_preset_name` of the current food cooking in the device, from the `foodPresets` attribute. Only one food may be reported. If no food is currently selected, this should be set to NONE. |
| `currentFoodQuantity` | *Number* | Defines the current amount of food cooking associated with the `currentFoodUnit`, if a quantity was specified. Should not be reported if nothing is currently cooking, or if there is no quantity associated with this food preset. |
| `currentFoodUnit` | *String* | The unit associated with the `currentFoodQuantity`, from the preset's list of `supported_units`. |

#### Examples

*Is my oven cooking?*

```
{
  "currentCookingMode": "BAKE"
}
```

*What's cooking in my rice cooker right now?*

```
{
  "currentCookingMode": "COOK",
  "currentFoodPreset": "brown_rice",
  "currentFoodQuantity": 2,
  "currentFoodUnit": "CUPS"
}
```

## Device COMMANDS

Devices with this trait may respond to the following
commands as part of the [`EXECUTE`](https://developers.home.google.com/cloud-to-cloud/intents/execute) operation. To learn
more about handling `EXECUTE` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute#handle_execute_intents).

### `action.devices.commands.Cook`

Start or stop cooking.

#### Parameters

| Parameters | Type | Description |
|---|---|---|
| `start` | *Boolean* | **Required.** True to start cooking, false to stop current cooking mode. |
| `cookingMode` | *String* | Requested cooking mode for the device, from the `supportedCookingModes` attribute. |
| `foodPreset` | *String* | The name of the food preset requested by the user, from `foodPresets` attribute. |
| `quantity` | *Number* | The quantity of the food requested by the user. |
| `unit` | *String* | The unit associated with the `quantity`, from `supported_units` attribute. |

#### Examples

*Start baking in my oven.*

```
{
  "command": "action.devices.commands.Cook",
  "params": {
    "start": true,
    "cookingMode": "BAKE"
  }
}
```

*Stop baking in my oven.*

```
{
  "command": "action.devices.commands.Cook",
  "params": {
    "start": false,
    "cookingMode": "BAKE"
  }
}
```

*Start cooking 2 cups of white rice in my rice cooker.*

```
{
  "command": "action.devices.commands.Cook",
  "params": {
    "start": true,
    "cookingMode": "COOK",
    "foodPreset": "white_rice",
    "quantity": 2,
    "unit": "CUPS"
  }
}
```

## Device ERRORS

See the full list of [errors and exceptions](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions).

- `deviceDoorOpen` - The door of the device is open.
- `deviceLidOpen` - The lid of the device is open.
- `fractionalAmountNotSupported` - The user requested a fractional amount for this food preset, but it isn't supported by this device.
- `amountAboveLimit` - The user requested a quantity that was over the maximum.
- `unknownFoodPreset` - The user requested a food preset not supported by the device.