Schema delle funzionalità di domotica smart

action.devices.traits.Dispense: questo tratto appartiene ai dispositivi che supportano l'erogazione di una o più quantità specifiche di uno o più articoli fisici.

Questa caratteristica supporta anche l'erogazione di una preimpostazione, ad esempio come "ciotola per gatti" per un alimentatore per animali domestici o come "vetro" per un rubinetto.

ATTRIBUTE dispositivo

I dispositivi con questo trattino potrebbero segnalare i seguenti attributi come parte dell'operazione SYNC. Per saperne di più sulla gestione degli intent SYNC, consulta la sezione fulfillment di intent.

Attributi Tipo Descrizione
supportedDispenseItems Array

Contiene informazioni su tutti gli elementi che il dispositivo può erogare.

[item, ...] Oggetto

Articolo dispensabile.

item_name String

Obbligatorio.

Nome interno dell'articolo erogatore. Questa opzione può essere ottimizzata per gli utenti e viene condivisa in tutte le lingue.

item_name_synonyms Array

Obbligatorio.

Sinonimi di nomi assegnati in ogni lingua supportata.

[item, ...] Oggetto

Sinonimi di nomi di articoli distribuiti in una determinata lingua.

synonyms Array

Obbligatorio.

Nomi dei sinonimi dell'articolo erogatore. Le sinomi devono includere forme singolari e plurali, se applicabili. 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). Scopri le lingue supportate.

supported_units Array

Obbligatorio.

Set 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 erogato.

amount Intero

Obbligatorio.

Importo erogato.

unit String

Obbligatorio.

Unità di erogazione.

supportedDispensePresets Array

Preimpostazioni supportate dal dispositivo.

[item, ...] Oggetto

Preimpostato.

preset_name String

Obbligatorio.

Nome interno della preimpostazione. Questo nome non è facile da usare e viene condiviso in tutte le lingue.

preset_name_synonyms Array

Obbligatorio.

Nomi dei sinonimi per la preimpostazione in ogni lingua supportata.

[item, ...] Oggetto

Nomi di sinonimi per la preimpostazione in una determinata lingua.

synonyms Array

Obbligatorio.

Nomi di sinonimi per la preimpostazione. I sinonimi devono includere forme singolari e plurali, se applicabili.

[item, ...] String

Nome sinonimo

lang String

Obbligatorio.

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

Esempi

Erogatore di acqua che supporta le unità per i liquidi con preimpostazioni.

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

STATO dispositivo

Le entità con questa caratteristica possono segnalare i seguenti stati nell'ambito dell'operazione QUERY, Per saperne di più sulla gestione degli intent QUERY, consulta la sezione fulfillment di intent.

Stati Tipo Descrizione
dispenseItems Array

Stati degli articoli che il dispositivo può erogare.

[item, ...] Oggetto

Lo stato di un determinato articolo.

itemName String

Nome dell'articolo dall'attributo item_name.

amountRemaining Oggetto

Importo rimanente dell'articolo nel dispositivo. Se il dispositivo sta erogando un prodotto, viene registrato l'importo rimanente o l'importo che verrà erogato al termine dell'erogazione.

amount Number

Importo rimanente

unit String

Unità di misura per amount dall'attributo supported_units.

amountLastDispensed Oggetto

Quantità dell'articolo erogato il dispositivo più di recente. Se il dispositivo sta erogando prodotti, è necessario segnalare l'importo erogato prima di quello attuale.

amount Number

Importo rimanente

unit String

Unità di misura per amount dall'attributo supported_units.

isCurrentlyDispensing Booleano

Indica se il dispositivo sta erogando questo articolo.

Esempi

Quanti croccantini 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 mio refrigeratore?

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

Quanti alimenti per gatti ho dato prima?

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

Il rubinetto eroga ancora acqua?

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

amountRemaining e amountLastDispensed devono essere segnalati solo utilizzando un'unità di misura.

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

COMANDI dispositivo

I dispositivi con questo trattino potrebbero rispondere ai seguenti comandi nell'ambito dell'operazione EXECUTE. Per saperne di più sulla gestione degli intent EXECUTE, consulta la sezione fulfillment di intent.

action.devices.commands.Dispense

Erogazione di 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 misura per amount, dall'attributo supported_units.

Eroga per preimpostazione.

Parametri Tipo Descrizione
presetName String

Obbligatorio.

Nome della preimpostazione da erogare dall'attributo preset_name.

Dosatore 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 del gatto.

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

Erogazione di acqua.

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

ERRORI del dispositivo

Consulta l'elenco completo degli errori e delle eccezioni.
  • dispenseAmountRemainingExceeded: l'utente ha tentato di erogare un elemento o un importo da un dispositivo che non dispone di importo sufficiente.
  • dispenseAmountAboveLimit: l'utente ha tentato di erogare un'importo superiore ai limiti di ciò che può chiedere in una singola query. Questo per evitare di erogare accidentalmente una quantità eccessiva (ad esempio, 500.000 tazze d'acqua).
  • dispenseAmountBelowLimit: l'utente ha tentato di erogare dal dispositivo un importo o un importo inferiore all'importo minimo che può erogare.
  • dispenseFractionalAmountNotSupported: l'utente ha tentato di erogare una quantità frazionata di un elemento che il dispositivo non può dividere (ad esempio, gli elementi conteggiabili come i cibo per cani potrebbero non essere divisibili per il dispositivo).
  • genericDispenseNotSupported: l'utente cerca di erogare un dispositivo da un dispositivo senza specificare un elemento o un preset, ma il dispositivo non supporta questa funzionalità (ad esempio, un'azione di erogazione predefinita).
  • dispenseUnitNotSupported: l'utente cerca di erogare da un dispositivo con un'unità non supportata per il caso (ad esempio, l'articolo non è fornito, pertanto supported_unit validation è stato ignorato).
  • dispenseFractionalUnitNotSupported: l'utente ha tentato di erogare una quantità frazionata di un articolo che può essere suddiviso, ma non per l'unità specificata (ad esempio, un rubinetto potrebbe essere in grado di erogare 2,7 tazze ma non 2,7 ml).
  • deviceCurrentlyDispensing: l'utente tenta di erogare un articolo, ma il dispositivo lo sta già facendo.
  • deviceClogged: l'utente tenta di erogare un articolo, ma il dispositivo è intasato.
  • deviceBusy: l'utente cerca di erogare un articolo, ma il dispositivo è occupato (generico).

ECCEZIONI DEL Dispositivo

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

  • amountRemainingLow: l'utente eroga un dispositivo o un importo dal dispositivo e, in questo modo, porta la quantità rimanente a un livello basso. 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 l'importo richiesto (ad esempio, un rubinetto eroga acqua calda, ma l'utente deve attendere che l'acqua si riscaldi prima che inizi l'erogazione).