Schema delle caratteristiche di erogazione per la smart home

action.devices.traits.Dispense. Questa caratteristica appartiene ai dispositivi che supportano l'erogazione di una quantità specifica di uno o più articoli fisici.

Questa trait consente anche di erogare una preimpostazione, ad esempio come "ciotola per gatti" per un dispenser per animali domestici o un "bicchiere" per un rubinetto.

ATTRIBUTES del dispositivo

I dispositivi con questo trait potrebbero segnalare i seguenti attributi nell'ambito dell'operazione SYNC. Per scoprire di più sulla gestione degli intent SYNC, consulta fulfillment dell'intent.

Attributi Tipo Descrizione
supportedDispenseItems Matrice

Contiene informazioni su tutti gli articoli che il dispositivo può erogare.
[item, ...] Oggetto

Articolo dispensabile.
item_name String

Obbligatorio.

Nome interno dell'articolo erogato. Non è facile da usare e viene condiviso in tutte le lingue.
item_name_synonyms Matrice

Obbligatorio.

Sinonimi i nomi delle bevande in ogni lingua supportata.
[item, ...] Oggetto

Sinonimi i nomi dell'articolo erogato in una determinata lingua.
synonyms Matrice

Obbligatorio.

Nomi sinonimi dell'articolo erogato. I sinomimi devono includere sia la forma singolare che quella plurale, se possibile. La prima stringa di questo elenco deve essere la forma plurale dell'elemento in quella lingua.
[item, ...] String

Nome sinonimo
lang String

Obbligatorio.

Codice lingua (ISO 639-1). Consulta le lingue supportate.
supported_units Matrice

Obbligatorio.

Insieme di unità supportate dal dispositivo per l'elemento.
[item, ...] String

Unità supportate.

Valori supportati:

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

Obbligatorio.

Quantità tipica dell'articolo che potrebbe essere erogata.
amount Intero

Obbligatorio.

Importo erogato.
unit String

Obbligatorio.

Unità erogato.
supportedDispensePresets Matrice

Preimpostazioni supportate dal dispositivo.
[item, ...] Oggetto

Predefinito.
preset_name String

Obbligatorio.

Nome interno della preimpostazione. Questo nome non può essere intuitivo e viene condiviso in tutte le lingue.
preset_name_synonyms Matrice

Obbligatorio.

Nomi sinonimi della preimpostazione in ogni lingua supportata.
[item, ...] Oggetto

Nomi sinonimi della preimpostazione in una determinata lingua.
synonyms Matrice

Obbligatorio.

Nomi sinonimi della preimpostazione. I sinonimi devono includere sia la forma singolare che quella plurale, se possibile.
[item, ...] String

Nome sinonimo
lang String

Obbligatorio.

Codice lingua (ISO 639-1). Consulta le lingue supportate.

Esempi

Erogatore d'acqua che supporta unità per liquidi con valori preimpostati.

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

Dispenser di cibo per animali senza preimpostazioni.

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

Dispositivo STATES

Le entità con questo trait possono segnalare i seguenti stati nell'ambito dell'operazione QUERY. Per scoprire di più sulla gestione degli intent QUERY, consulta fulfillment dell'intent.

Stati Tipo Descrizione
dispenseItems Matrice

Stati degli articoli che il dispositivo può erogare.
[item, ...] Oggetto

Stato di un determinato articolo.
itemName String

Nome dell'articolo indicato nell'attributo item_name.
amountRemaining Oggetto

Quantità rimanente dell'elemento nel dispositivo. Se al momento il dispositivo sta erogando, viene indicato l'importo rimanente o quello che sarà una volta che il dispositivo avrà terminato l'erogazione.
amount Number

Importo rimanente
unit String

Unità di amount dall'attributo supported_units.
amountLastDispensed Oggetto

Quantità di quell'articolo erogato dal dispositivo più di recente. Se il dispositivo è in fase di erogazione, dovrebbe essere indicato l'importo erogato prima dell'importo erogato attuale.
amount Number

Importo rimanente
unit String

Unità di amount dall'attributo supported_units.
isCurrentlyDispensing Booleano

Indica se il dispositivo sta erogando questo articolo.

Esempi

Quanti snack per cani rimangono nel dispenser?

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

Quanta acqua rimane nel refrigeratore?

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

Quanto cibo per gatti ho dato in passato?

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

Il rubinetto continua a erogare acqua?

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

amountRemaining e amountLastDispensed devono essere creati nei report utilizzando un'unica unità di misura.

È possibile fornire più elementi all'interno dell'array dispenseItems. Il nome di ogni articolo deve essere univoco e deve corrispondere a un articolo nell'attributo supportedDispenseItems.

COMMANDS dispositivo

I dispositivi con questa caratteristica potrebbero rispondere ai seguenti comandi nell'ambito dell'operazione EXECUTE. Per scoprire di più sulla gestione degli intent EXECUTE, consulta fulfillment dell'intent.

action.devices.commands.Dispense

Eroga articoli.

Parametri

Il payload contiene uno dei seguenti valori:

Eroga in base all'importo.

Parametri Tipo Descrizione
item String

Nome dell'articolo da erogare, dall'attributo item_name.
amount Number

Obbligatorio.

Importo da erogare.
unit String

Obbligatorio.

Unità di amount, dall'attributo supported_units.

Eroga in base alle preimpostazioni.

Parametri Tipo Descrizione
presetName String

Obbligatorio.

Nome della preimpostazione da erogare, dall'attributo preset_name.

Eroga senza parametri.

Parametri Tipo Descrizione

Nessuna proprietà

Esempi

Dammi 1 tazza d'acqua.

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

Riempi la ciotola dell'acqua per il gatto.

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

Eroga acqua.

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

ERRORS dispositivo

Consulta l'elenco completo di errori ed eccezioni.
  • dispenseAmountRemainingExceeded: l'utente ha tentato di erogare un articolo o un importo da un dispositivo a cui non è rimasto sufficiente spazio.
  • dispenseAmountAboveLimit: l'utente ha cercato di erogare un importo che supera i limiti di quanto può richiedere in una singola query. per evitare di erogare involontariamente una quantità eccessiva (ad es. 500.000 tazze d'acqua).
  • dispenseAmountBelowLimit: l'utente ha tentato di erogare dal dispositivo un articolo o un importo inferiore al limite minimo che può erogare.
  • dispenseFractionalAmountNotSupported: l'utente ha tentato di erogare una parte frazionata di un articolo che il dispositivo non può suddividere (ad esempio, gli elementi conteggiabili come gli snack per cani potrebbero non essere divisibili per il dispositivo).
  • genericDispenseNotSupported: l'utente cerca di effettuare l'erogazione da un dispositivo senza specificare un articolo o una preimpostazione, ma il dispositivo non supporta questa funzionalità (ad esempio, un'azione di erogazione predefinita).
  • dispenseUnitNotSupported: l'utente cerca di effettuare l'erogazione da un dispositivo con un'unità non supportata per quel caso (ad esempio, l'articolo non è fornito, quindi supported_unit validation è stato ignorato).
  • dispenseFractionalUnitNotSupported: l'utente ha cercato di erogare una quantità frazionaria di un articolo che può essere suddivisa, ma non per l'unità specifica specificata (ad esempio, un rubinetto potrebbe essere in grado di erogare 2,7 tazze ma non 2,7 mL).
  • deviceCurrentlyDispensing: l'utente cerca di erogare un articolo, ma il dispositivo è già in fase di erogazione.
  • deviceClogged: l'utente cerca di erogare un articolo, ma il dispositivo è intasato.
  • deviceBusy: l'utente cerca di erogare un articolo, ma il dispositivo è occupato (generico).

Dispositivo EXCEPTIONS

Queste eccezioni possono essere segnalate come exceptionCode nell'oggetto states della risposta:

  • amountRemainingLow: l'utente eroga dal dispositivo un articolo o un importo per ridurre la quantità rimanente. Sei responsabile della definizione di ciò che costituisce un livello "basso".
  • userNeedsToWait: quando l'utente deve attendere prima di poter erogare correttamente l'articolo o la quantità richiesti (ad esempio, un rubinetto erogherà acqua calda, ma l'utente deve attendere che l'acqua si riscaldi prima che inizi a erogare).