Schema del tratto di erogazione per la smart home

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

Questa caratteristica supporta anche l'erogazione di un preset, ad esempio una "ciotola per cibo per gatti" per un distributore di cibo per animali o un "bicchiere" per un rubinetto.

ATTRIBUTI dispositivo

I dispositivi con questa caratteristica potrebbero segnalare i seguenti attributi nell'ambito dell'operazione SYNC. Per saperne di più sulla gestione degli intent SYNC, consulta Completamento degli intent.

Esempi

Dispenser di acqua che supporta unità per liquidi con impostazioni predefinite.

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

Distributore di cibo per animali domestici senza impostazioni predefinite.

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

STATI del dispositivo

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

Esempi

Quanti premi per cani sono rimasti nel mio distributore?

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

Quanta acqua è rimasta nel mio refrigeratore?

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

Quanto cibo 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 utilizzando una sola unità di misura.

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

COMANDI del dispositivo

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

action.devices.commands.Dispense

Distribuire gli articoli.

Parametri

Il payload contiene uno dei seguenti elementi:

Eroga in base all'importo.

Eroga in base al preset.

Eroga senza parametri.

Esempi

Dammi una tazza d'acqua.

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

Riempi la ciotola dell'acqua del gatto.

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

Erogare acqua.

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

ERRORI del dispositivo

• dispenseAmountRemainingExceeded: L'utente ha tentato di erogare un articolo o un importo da un dispositivo con un importo residuo insufficiente.
• dispenseAmountAboveLimit: l'utente ha tentato di erogare un importo superiore ai limiti di ciò che può richiedere in una singola query. Questo serve a evitare l'erogazione accidentale di una quantità eccessiva (ad esempio, 500.000 tazze d'acqua).
• dispenseAmountBelowLimit: L'utente ha tentato di erogare un articolo o un importo dal dispositivo che è inferiore all'importo minimo che può erogare.
• dispenseFractionalAmountNotSupported: L'utente ha tentato di erogare una quantità frazionaria di un articolo che il dispositivo non può dividere (ad esempio, gli articoli numerabili come i dolcetti per cani potrebbero non essere divisibili dal dispositivo).
• genericDispenseNotSupported: L'utente tenta di erogare un prodotto da un dispositivo senza specificare un articolo o un preset, ma il dispositivo non supporta questa funzionalità (ad esempio, un'azione di erogazione predefinita).
• dispenseUnitNotSupported: L'utente tenta di erogare un'unità da un dispositivo non supportata per quel caso (ad esempio, l'articolo non viene fornito, quindi supported_unit validation è stato ignorato).
• dispenseFractionalUnitNotSupported: L'utente ha tentato di erogare una quantità frazionaria di un articolo che può essere suddiviso, ma non per l'unità specifica indicata (ad esempio, un rubinetto potrebbe erogare 2,7 tazze, ma non 2,7 ml).
• deviceCurrentlyDispensing: L'utente tenta di erogare un articolo, ma il dispositivo è già in fase di erogazione.
• deviceClogged: l'utente tenta di erogare un articolo, ma il dispositivo è intasato.
• deviceBusy: L'utente tenta di erogare un articolo, ma il dispositivo è occupato (generico).

Eccezioni per i dispositivi

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

• amountRemainingLow - L'utente eroga un articolo o un importo dal dispositivo che riduce l'importo rimanente a un livello basso. È tua responsabilità definire cosa costituisce un livello "basso".
• userNeedsToWait - Quando l'utente deve attendere prima che l'articolo o l'importo richiesto possa essere erogato correttamente (ad esempio, un rubinetto erogherà acqua calda, ma l'utente deve attendere che l'acqua si riscaldi prima che inizi a essere erogata).