Smart Home Dispense Trait Schema

action.devices.traits.Dispense - This trait belongs to devices that support dispensing a specified amount of one or more physical items.

This trait also supports dispensing a preset, for example as a "cat food bowl" for a pet feeder or a "glass" for a faucet.

Device ATTRIBUTES

Devices with this trait may report the following attributes as part of the SYNC operation. To learn more about handling SYNC intents, see Intent fulfillment.

Attributes Type Description
supportedDispenseItems Array

Contains information on all the items that the device can dispense.

[item, ...] Object

Dispensable item.

item_name String

Required.

Internal name for the dispensed item. This can be non-user-friendly, and is shared across all languages.

item_name_synonyms Array

Required.

Synonyms names for the dispensed in each supported language.

[item, ...] Object

Synonyms names for the dispensed item in a given language.

synonyms Array

Required.

Synonym names for the dispensed item. The synomyms should include both singular and plural forms, if applicable. The first string in this list must be the plural form of the item in that language.

[item, ...] String

Synonym name

lang String

Required.

Language code (ISO 639-1). See supported languages.

supported_units Array

Required.

Set of units the device supports for that item.

[item, ...] String

Supported units.

Supported values:

CENTIMETERS
CUPS
DECILITERS
FLUID_OUNCES
GALLONS
GRAMS
KILOGRAMS
LITERS
MILLIGRAMS
MILLILITERS
MILLIMETERS
NO_UNITS
OUNCES
PINCH
PINTS
PORTION
POUNDS
QUARTS
TABLESPOONS
TEASPOONS
default_portion Object

Required.

Typical amount of the item that may be dispensed.

amount Integer

Required.

Dispensed amount.

unit String

Required.

Dispensed unit.

supportedDispensePresets Array

Presets supported by the device.

[item, ...] Object

Preset.

preset_name String

Required.

Internal name for the preset. This name can be non-user-friendly, and is shared across all languages.

preset_name_synonyms Array

Required.

Synonym names for the preset in each supported language.

[item, ...] Object

Synonym names for the preset in a given language.

synonyms Array

Required.

Synonym names for the preset. The synonyms should include both singular and plural forms, if applicable.

[item, ...] String

Synonym name

lang String

Required.

Language code (ISO 639-1). See supported languages.

Examples

Water dispenser that supports units for liquids with presets.

{
  "supportedDispenseItems": [
    {
      "item_name": "Water",
      "item_name_synonyms": [
        {
          "lang": "en",
          "synonyms": [
            "Water"
          ]
        }
      ],
      "supported_units": [
        "TEASPOONS",
        "TABLESPOONS",
        "FLUID_OUNCES",
        "CUPS",
        "PINTS",
        "QUARTS",
        "GALLONS",
        "MILLILITERS",
        "LITERS",
        "DECILITERS"
      ],
      "default_portion": {
        "amount": 2,
        "unit": "CUPS"
      }
    }
  ],
  "supportedDispensePresets": [
    {
      "preset_name": "cat_bowl",
      "preset_name_synonyms": [
        {
          "lang": "en",
          "synonyms": [
            "Cat water bowl",
            "Cat water dish",
            "Cat water cup"
          ]
        }
      ]
    },
    {
      "preset_name": "glass_1",
      "preset_name_synonyms": [
        {
          "lang": "en",
          "synonyms": [
            "Glass of water",
            "Glass"
          ]
        }
      ]
    }
  ]
}

Pet food dispenser without presets.

{
  "supportedDispenseItems": [
    {
      "item_name": "Treat",
      "item_name_synonyms": [
        {
          "lang": "en",
          "synonyms": [
            "Treats",
            "Dog treats",
            "Treat",
            "Dog treat"
          ]
        }
      ],
      "supported_units": [
        "NO_UNITS"
      ],
      "default_portion": {
        "amount": 1,
        "unit": "NO_UNITS"
      }
    }
  ]
}

Device STATES

Entities with this trait may report the following states as part of the QUERY operation. To learn more about handling QUERY intents, see Intent fulfillment.

States Type Description
dispenseItems Array

States of the items that the device can dispense.

[item, ...] Object

State of a given item.

itemName String

Name of the item from the item_name attribute.

amountRemaining Object

Amount of that item remaining in the device. If the device is currently dispensing, this reports the remaining amount or what the amount will be once the device finishes dispensing.

amount Number

Remaining amount

unit String

Unit for the amount from the supported_units attribute.

amountLastDispensed Object

Amount of that item that the device most recently dispensed. If the device is currently dispensing, this should report the amount it dispensed prior to the current dispensing amount.

amount Number

Remaining amount

unit String

Unit for the amount from the supported_units attribute.

isCurrentlyDispensing Boolean

Indicates if the device is currently dispensing this item.

Examples

How many dog treats are remaining in my dispenser?

{
  "dispenseItems": [
    {
      "itemName": "Dog treats",
      "amountRemaining": {
        "amount": 83,
        "unit": "NO_UNITS"
      },
      "amountLastDispensed": {
        "amount": 2,
        "unit": "NO_UNITS"
      },
      "isCurrentlyDispensing": false
    }
  ]
}

How much water is remaining in my water cooler?

{
  "dispenseItems": [
    {
      "itemName": "Water",
      "amountRemaining": {
        "amount": 6.2,
        "unit": "GALLONS"
      },
      "amountLastDispensed": {
        "amount": 1,
        "unit": "CUPS"
      },
      "isCurrentlyDispensing": false
    }
  ]
}

How much cat food did I give before?

{
  "dispenseItems": [
    {
      "itemName": "cat_food",
      "amountRemaining": {
        "amount": 16.5,
        "unit": "CUPS"
      },
      "amountLastDispensed": {
        "amount": 2.5,
        "unit": "CUPS"
      },
      "isCurrentlyDispensing": false
    }
  ]
}

Is the faucet still dispensing water?

{
  "dispenseItems": [
    {
      "itemName": "Water",
      "isCurrentlyDispensing": true
    }
  ]
}

amountRemaining and amountLastDispensed only need to be reported using one unit of measurement.

Multiple items can be provided within the dispenseItems array. Each item name must be unique and must correspond to an item in the supportedDispenseItems attribute.

Device COMMANDS

Devices with this trait may respond to the following commands as part of the EXECUTE operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

action.devices.commands.Dispense

Dispense items.

Parameters

The payload contains one of the following:

Dispense by amount.

Parameters Type Description
item String

Name of the item to dispense, from the item_name attribute.

amount Number

Required.

Amount to dispense.

unit String

Required.

Unit for the amount, from the supported_units attribute.

Dispense by preset.

Parameters Type Description
presetName String

Required.

Name of the preset to dispense, from the preset_name attribute.

Dispense without parameters.

Parameters Type Description

No properties

Examples

Give me 1 cup of water.

{
  "command": "action.devices.commands.Dispense",
  "params": {
    "amount": 1,
    "unit": "CUPS",
    "item": "Water"
  }
}

Fill the cat water bowl.

{
  "command": "action.devices.commands.Dispense",
  "params": {
    "presetName": "cat_bowl"
  }
}

Dispense water.

{
  "command": "action.devices.commands.Dispense",
  "params": {}
}

Device ERRORS

See the full list of errors and exceptions.
  • dispenseAmountRemainingExceeded: The user tried to dispense an item or amount from a device that does not have enough amount remaining.
  • dispenseAmountAboveLimit: The user tried to dispense an amount that is beyond the limits of what they can ask for in a single query. This is to prevent accidentally dispensing an excessive amount (for example, 500,000 cups of water).
  • dispenseAmountBelowLimit: The user tried to dispense an item or amount from the device the device that is below the minimum amount it can dispense.
  • dispenseFractionalAmountNotSupported: The user tried to dispense a fractional amount of an item that the device cannot split (for example, countable items like dog treats may not be divisible by the device).
  • genericDispenseNotSupported: The user tries to dispense from a device without specifying an item or preset, but the device does not support such functionality (for example, a default dispense action).
  • dispenseUnitNotSupported: The user tries to dispense from a device with a unit not supported for that case (for example, the item is not provided so supported_unit validation was skipped).
  • dispenseFractionalUnitNotSupported: The user tried to dispense a fractional amount of an item which can be split but not for the particular unit specified (for example, a faucet may be able to dispense 2.7 cups but not 2.7 mL).
  • deviceCurrentlyDispensing: The users tries to dispense an item but the device is already dispensing.
  • deviceClogged: The users tries to dispense an item but the device is clogged.
  • deviceBusy: The users tries to dispense an item but the device is busy (generic).

Device EXCEPTIONS

These exceptions can be reported as an exceptionCode in the states object of your response:

  • amountRemainingLow - The user dispenses an item or amount from the device which brings the amount remaining to a low level. You are responsible for defining what constitutes a "low" level.
  • userNeedsToWait - When the user has to wait before the requested item or amount can be successfully dispensed (for example, a faucet will dispense hot water but the user needs to wait for the water to heat up before it begins dispensing).