Smart Home Dispense Trait Schema

action.devices.traits.Dispense: Dieses Merkmal gehört zu Geräten, die eine bestimmte Menge eines oder mehrerer physischer Artikel ausgeben können.

Dieser Trait unterstützt auch das Ausgeben eines Presets, z. B. als „Katzennapf“ für einen Futterautomaten oder als „Glas“ für einen Wasserhahn.

Geräteattribute

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

Beispiele

Wasserspender, der Einheiten für Flüssigkeiten mit Voreinstellungen 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ätestatus

Für Entitäten mit diesem Merkmal können im Rahmen des Vorgangs QUERY die folgenden Status gemeldet werden. Weitere Informationen zum Umgang mit QUERY-Intents finden Sie unter Intent-Fulfillment.

Beispiele

Wie viele Leckerlis sind noch in meinem 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
    }
  ]
}

Gibt der Wasserhahn weiterhin Wasser aus?

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

amountRemaining und amountLastDispensed müssen nur in einer Maßeinheit angegeben werden.

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

GERÄTEBEFEHLE

Geräte mit diesem Merkmal können im Rahmen des Vorgangs EXECUTE auf die folgenden Befehle reagieren. Weitere Informationen zum Umgang mit EXECUTE-Intents finden Sie unter Intent-Fulfillment.

action.devices.commands.Dispense

Artikel ausgeben

Parameter

Die Nutzlast enthält eines der folgenden Elemente:

Nach Menge ausgeben.

Ausgabe nach Voreinstellung.

Ausgabe ohne Parameter.

Beispiele

Gib mir eine Tasse Wasser.

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

Fülle die Wasserschüssel für die Katze.

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

Wasser ausgeben.

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

GERÄTEFEHLER

• dispenseAmountRemainingExceeded: Der Nutzer hat versucht, einen Artikel oder Betrag von einem Gerät abzurufen, auf dem nicht genügend Guthaben vorhanden ist.
• dispenseAmountAboveLimit: Der Nutzer hat versucht, eine Menge abzurufen, die die Grenzwerte für eine einzelne Anfrage überschreitet. So wird verhindert, dass versehentlich eine übermäßige Menge ausgegeben wird (z. B. 500.000 Tassen Wasser).
• dispenseAmountBelowLimit: Der Nutzer hat versucht, einen Artikel oder Betrag vom Gerät auszugeben, der unter dem Mindestbetrag liegt, den das Gerät ausgeben kann.
• dispenseFractionalAmountNotSupported: Der Nutzer hat versucht, eine Teilmenge eines Artikels auszugeben, die das Gerät nicht aufteilen kann. Zählbares wie Hundeleckerlis kann beispielsweise nicht vom Gerät geteilt werden.
• genericDispenseNotSupported: Der Nutzer versucht, ein Produkt über ein Gerät auszugeben, ohne ein Element oder eine Voreinstellung anzugeben. Das Gerät unterstützt diese Funktion jedoch nicht (z. B. eine standardmäßige Ausgabeaktion).
• dispenseUnitNotSupported: Der Nutzer versucht, ein Produkt über ein Gerät mit einer für diesen Fall nicht unterstützten Einheit auszugeben (z. B. wird der Artikel nicht bereitgestellt, sodass supported_unit validation übersprungen wurde).
• dispenseFractionalUnitNotSupported: Der Nutzer hat versucht, eine Teilmenge eines Artikels auszugeben, der 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 auszugeben, aber das Gerät gibt bereits ein Produkt aus.
• deviceClogged: Der Nutzer versucht, ein Produkt auszugeben, aber das Gerät ist verstopft.
• deviceBusy: Der Nutzer versucht, einen Artikel auszugeben, aber das Gerät ist beschäftigt (allgemein).

AUSNAHMEN für Geräte

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

• amountRemainingLow: Der Nutzer gibt einen Artikel oder Betrag über das Gerät aus, wodurch der verbleibende Betrag auf ein niedriges Niveau sinkt. Sie sind dafür verantwortlich, festzulegen, was ein „niedriges“ Niveau ausmacht.
• userNeedsToWait: Der Nutzer muss warten, bis der angeforderte Artikel oder die angeforderte Menge ausgegeben werden kann. Das kann z. B. der Fall sein, wenn ein Wasserhahn heißes Wasser ausgibt, der Nutzer aber warten muss, bis das Wasser heiß genug ist, bevor es ausgegeben wird.