Esquema de traço de dispensação de casa inteligente

action.devices.traits.Dispense: essa característica pertence a dispositivos que oferecem suporte à dispensação de uma quantidade especificada de um ou mais itens físicos.

Essa característica também permite dispensar uma predefinição, por exemplo, uma "tigela de ração para gatos" para um comedouro de animais de estimação ou um "copo" para uma torneira.

ATRIBUTOS do dispositivo

Dispositivos com essa característica podem informar os seguintes atributos como parte da operação SYNC. Para saber mais sobre como processar intents SYNC, consulte Lógica de fulfillment de intents.

Exemplos

Dispensador de água compatível com unidades para líquidos com predefinições.

{
  "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"
          ]
        }
      ]
    }
  ]
}

Dispensador de comida para animais de estimação sem predefinições.

{
  "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"
      }
    }
  ]
}

ESTADOS DO DISPOSITIVO

As entidades com essa característica podem informar os seguintes estados como parte da operação QUERY. Para saber mais sobre como processar intents QUERY, consulte Lógica de fulfillment de intents.

Exemplos

Quantos petiscos para cachorro ainda tenho no dispenser?

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

Quanto de água ainda tem no meu bebedouro?

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

Quanto de ração eu dei antes?

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

A torneira ainda está liberando água?

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

amountRemaining e amountLastDispensed só precisam ser informados usando uma unidade de medida.

Vários itens podem ser fornecidos na matriz dispenseItems. Cada nome de item precisa ser exclusivo e corresponder a um item no atributo supportedDispenseItems.

COMANDOS do dispositivo

Dispositivos com essa característica podem responder aos seguintes comandos como parte da operação EXECUTE. Para saber mais sobre como processar intents EXECUTE, consulte Lógica de fulfillment de intents.

action.devices.commands.Dispense

Dispensar itens.

Parâmetros

O payload contém uma das seguintes opções:

Dispensar por valor.

Dispensar por predefinição.

Dispensar sem parâmetros.

Exemplos

Me dê uma xícara de água.

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

Encha o pratinho de água do gato.

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

Sirva água.

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

ERROS do dispositivo

• dispenseAmountRemainingExceeded: o usuário tentou dispensar um item ou valor de um dispositivo que não tem saldo suficiente.
• dispenseAmountAboveLimit: o usuário tentou dispensar um valor que está além dos limites do que pode ser solicitado em uma única consulta. Isso evita a dispensação acidental de uma quantidade excessiva (por exemplo, 500.000 copos de água).
• dispenseAmountBelowLimit: o usuário tentou dispensar um item ou valor do dispositivo que está abaixo do valor mínimo que ele pode dispensar.
• dispenseFractionalAmountNotSupported: o usuário tentou dispensar uma quantidade fracionada de um item que o dispositivo não pode dividir. Por exemplo, itens contáveis, como petiscos para cachorro, podem não ser divisíveis pelo dispositivo.
• genericDispenseNotSupported: o usuário tenta dispensar um item de um dispositivo sem especificar um item ou uma predefinição, mas o dispositivo não é compatível com essa funcionalidade (por exemplo, uma ação de dispensar padrão).
• dispenseUnitNotSupported: o usuário tenta dispensar de um dispositivo com uma unidade não compatível com esse caso (por exemplo, o item não é fornecido, então supported_unit validation foi ignorado).
• dispenseFractionalUnitNotSupported: o usuário tentou dispensar uma quantidade fracionada de um item que pode ser dividido, mas não para a unidade especificada (por exemplo, uma torneira pode dispensar 2,7 xícaras, mas não 2,7 ml).
• deviceCurrentlyDispensing: o usuário tenta dispensar um item, mas o dispositivo já está dispensando.
• deviceClogged: o usuário tenta dispensar um item, mas o dispositivo está entupido.
• deviceBusy: o usuário tenta dispensar um item, mas o dispositivo está ocupado (genérico).

EXCEÇÕES DE DISPOSITIVOS

Essas exceções podem ser informadas como um exceptionCode no objeto states da sua resposta:

• amountRemainingLow: o usuário dispensa um item ou uma quantidade do dispositivo, o que reduz o valor restante a um nível baixo. Você é responsável por definir o que constitui um nível "baixo".
• userNeedsToWait: quando o usuário precisa esperar antes que o item ou a quantidade solicitada possa ser dispensada (por exemplo, uma torneira vai dispensar água quente, mas o usuário precisa esperar que a água esquente antes de começar a dispensar).