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.

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.

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.

Dispense by preset.

Dispense without parameters.

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

• 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).