Smart Home Dispense Trait Schema

action.devices.traits.Dispense: Dieses Attribut bezieht sich auf Geräte, die die Ausgabe einer bestimmten Menge von einem oder mehreren physischen Artikeln unterstützen.

Dieses Trait unterstützt auch die Ausgabe einer Voreinstellung, z. B. als „Katzenfutternapf“ für einen Futterspender oder als „Glas“ für einen Wasserhahn.

Geräteattribute

Geräte mit diesem Merkmal können die folgenden Attribute als Teil des SYNC-Vorgangs melden. Weitere Informationen zum Umgang mit SYNC-Intents finden Sie unter Intent-Ausführung.

Attribute	Typ	Beschreibung
supportedDispenseItems	Array	Enthält Informationen zu allen Artikeln, die das Gerät ausgeben kann.
[item, ...]	Objekt	Nicht erforderlicher Artikel.
item_name	String	Erforderlich. Interner Name für den ausgegebenen Artikel. Dies kann nicht nutzerfreundlich sein und wird in allen Sprachen verwendet.
item_name_synonyms	Array	Erforderlich. Synonyme für die Ausgabe in jeder unterstützten Sprache.
[item, ...]	Objekt	Synonyme für den ausgegeben Artikel in einer bestimmten Sprache.
synonyms	Array	Erforderlich. Synonyme Namen für den ausgegeben Artikel. Die Synonyme sollten gegebenenfalls sowohl die Singular- als auch die Pluralform enthalten. Der erste String in dieser Liste muss die Pluralform des Artikels in dieser Sprache sein.
[item, ...]	String	Synonym name
lang	String	Erforderlich. Sprachcode (ISO 639-1). Unterstützte Sprachen
supported_units	Array	Erforderlich. Satz der Einheiten, die das Gerät für diesen Artikel unterstützt.
[item, ...]	String	Unterstützte Einheiten. Unterstützte Werte: CENTIMETERS CUPS DECILITERS FLUID_OUNCES GALLONS GRAMS KILOGRAMS LITERS MILLIGRAMS MILLILITERS MILLIMETERS NO_UNITS OUNCES PINCH PINTS PORTION POUNDS QUARTS TABLESPOONS TEASPOONS
default_portion	Objekt	Erforderlich. Die übliche Menge des Artikels, die ausgegeben werden kann.
amount	Ganzzahl	Erforderlich. Ausgezahlter Betrag.
unit	String	Erforderlich. Ausgegebene Einheit.
supportedDispensePresets	Array	Vom Gerät unterstützte Voreinstellungen.
[item, ...]	Objekt	Voreinstellung.
preset_name	String	Erforderlich. Interner Name für die Voreinstellung. Dieser Name kann nicht nutzerfreundlich sein und wird für alle Sprachen verwendet.
preset_name_synonyms	Array	Erforderlich. Synonyme für die Voreinstellung in jeder unterstützten Sprache.
[item, ...]	Objekt	Synonymnamen für die Voreinstellung in einer bestimmten Sprache.
synonyms	Array	Erforderlich. Synonymnamen für die Voreinstellung. Die Synonyme sollten gegebenenfalls sowohl Singular- als auch Pluralformen enthalten.
[item, ...]	String	Synonym name
lang	String	Erforderlich. Sprachcode (ISO 639-1). Unterstützte Sprachen

Beispiele

Wasserspender, der Einheiten für Flüssigkeiten mit voreingestellten Einstellungen unterstützt

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

Futterautomat für Haustiere ohne Voreinstellungen

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

Gerät: STATES

Entitäten mit diesem Merkmal können im Rahmen der QUERY-Operation die folgenden Bundesstaaten melden. Weitere Informationen zum Umgang mit QUERY-Intents finden Sie unter Intent-Ausführung.

Bundesstaaten	Typ	Beschreibung
dispenseItems	Array	Status der Artikel, die das Gerät abgeben kann.
[item, ...]	Objekt	Status eines bestimmten Artikels.
itemName	String	Name des Artikels aus dem Attribut item_name.
amountRemaining	Objekt	Die Menge dieses Artikels, die auf dem Gerät verbleibt. Wenn das Gerät gerade etwas ausgibt, wird hier der verbleibende Betrag oder der Betrag angezeigt, der übrig bleibt, wenn die Ausgabe abgeschlossen ist.
amount	Number	Restbetrag
unit	String	Einheit für amount aus dem supported_units-Attribut.
amountLastDispensed	Objekt	Die Menge dieses Artikels, die das Gerät zuletzt ausgegeben hat. Wenn das Gerät gerade Spende durchführt, sollte dies die ausgegebene Menge vor der aktuellen Ausgabemenge melden.
amount	Number	Restbetrag
unit	String	Einheit für amount aus dem Attribut supported_units.
isCurrentlyDispensing	Boolesch	Gibt an, ob das Gerät diesen Artikel derzeit ausgibt.

Beispiele

Wie viele Hundeleckerli habe ich noch im Spender?

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

Wie viel Wasser ist noch in meinem Wasserkühler?

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

Wie viel Katzenfutter habe ich vorher gegeben?

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

Lässt sich die Armatur noch öffnen?

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

amountRemaining und amountLastDispensed müssen nur mit einer Maßeinheit erfasst werden.

Innerhalb des dispenseItems-Arrays können mehrere Elemente angegeben werden. Jeder Artikelname muss eindeutig sein und einem Artikel im Attribut supportedDispenseItems entsprechen.

BEFEHLE für Geräte

Geräte mit dieser Eigenschaft können im Rahmen des Vorgangs EXECUTE auf die folgenden Befehle reagieren. Weitere Informationen zum Umgang mit EXECUTE-Intents finden Sie unter Intent-Ausführung.

action.devices.commands.Dispense

Artikel ausgeben

Parameter

Die Nutzlast enthält Folgendes:

Ausgabe nach Betrag

Parameter	Typ	Beschreibung
item	String	Name des Artikels, der ausgegeben werden soll, aus dem Attribut item_name.
amount	Number	Erforderlich. Auszugebender Betrag.
unit	String	Erforderlich. Einheit für amount aus dem supported_units-Attribut.

Ausgeben nach Voreinstellung

Parameter	Typ	Beschreibung
presetName	String	Erforderlich. Name der Voreinstellung, die ausgegeben werden soll, aus dem Attribut preset_name.

Ohne Parameter ausgeben.

Parameter	Typ	Beschreibung
Keine Attribute

Beispiele

Geben Sie mir eine Tasse Wasser.

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

Füllen Sie die Wasserschüssel der Katze.

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

Wasser ausgeben.

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

GERÄTEFEHLER

Eine vollständige Liste der Fehler und Ausnahmen

• dispenseAmountRemainingExceeded: Der Nutzer hat versucht, einen Artikel oder eine bestimmte Menge von einem Gerät abzufüllen, in dem nicht genügend vorhanden ist.
• dispenseAmountAboveLimit: Der Nutzer hat versucht, einen Betrag auszugeben, der über die Grenzen der in einer einzelnen Abfrage verfügbaren Anfrage hinausgeht. So wird verhindert, dass versehentlich eine zu große Menge (z. B. 500.000 Tassen Wasser) ausgegeben wird.
• dispenseAmountBelowLimit: Der Nutzer hat versucht, einen Artikel oder eine Menge aus dem Gerät abzufüllen, die unter dem Mindestabgabebetrag liegt.
• dispenseFractionalAmountNotSupported: Der Nutzer hat versucht, eine Teilmenge eines Artikels abzugeben, die das Gerät nicht teilen kann. Zählbare Artikel wie Hundekekse sind beispielsweise möglicherweise nicht durch das Gerät teilbar.
• genericDispenseNotSupported: Der Nutzer versucht, etwas aus einem Gerät herauszugeben, ohne einen Artikel oder eine Voreinstellung anzugeben. Das Gerät unterstützt diese Funktion jedoch nicht (z. B. eine Standardausgabeaktion).
• dispenseUnitNotSupported: Der Nutzer versucht, über ein Gerät ein Produkt auszugeben, das für diesen Fall nicht unterstützt wird (z. B. ist der Artikel nicht verfügbar, sodass supported_unit validation übersprungen wurde).
• dispenseFractionalUnitNotSupported: Der Nutzer hat versucht, eine Bruchzahl eines Artikels auszugeben, die zwar aufgeteilt werden kann, aber nicht für die angegebene Einheit (z.B.kann ein Wasserhahn 2,7 Tassen, aber nicht 2,7 ml ausgeben).
• deviceCurrentlyDispensing: Der Nutzer versucht, ein Produkt abzuholen, aber das Gerät gibt bereits etwas aus.
• deviceClogged: Der Nutzer versucht, einen Artikel auszugeben, aber das Gerät ist verstopft.
• deviceBusy: Der Nutzer versucht, einen Artikel auszugeben, aber das Gerät ist beschäftigt (generisch).

AUSNAHMEN für Geräte

Diese Ausnahmen können als exceptionCode im states-Objekt Ihrer Antwort gemeldet werden:

• amountRemainingLow – Der Nutzer entnimmt dem Gerät einen Artikel oder eine bestimmte Menge, wodurch der verbleibende Bestand auf ein niedriges Niveau sinkt. Sie sind dafür verantwortlich, zu definieren, was als „niedrig“ gilt.
• userNeedsToWait: Wenn der Nutzer warten muss, bis der angeforderte Artikel oder die angeforderte Menge erfolgreich ausgegeben werden kann (z. B. gibt ein Wasserhahn Warmwasser aus, aber der Nutzer muss warten, bis das Wasser aufgeheizt ist, bevor er ausgegeben wird).