Schemat funkcji dozowania w inteligentnym domu

action.devices.traits.Dispense – ta cecha należy do urządzeń, które umożliwiają wydawanie określonej ilości co najmniej 1 przedmiotu fizycznego.

Ta cecha może też używać gotowych ustawień, np. „miska na karmę dla kota” do karmnika lub „szklanki” do kranu.

Urządzenie ATTRIBUTES

Urządzenia z tą cechą mogą zgłaszać poniższe atrybuty w ramach operacji SYNC. Więcej informacji o obsłudze intencji SYNC znajdziesz w artykule o realizacji intencji.

Atrybuty	Typ	Opis
supportedDispenseItems	Tablica	Zawiera informacje o wszystkich produktach, które urządzenie może wydać.
[item, ...]	Obiekt	Produkt do wydania.
item_name	String	Wymagane. Wewnętrzna nazwa wydawanego produktu. Tekst ten może nie być przyjazny dla użytkownika i jest dostępny we wszystkich językach.
item_name_synonyms	Tablica	Wymagane. Nazwy synonimów stosowanych w każdym obsługiwanym języku.
[item, ...]	Obiekt	Nazwy synonimów wydanego produktu w danym języku.
synonyms	Tablica	Wymagane. Nazwy synonimów wydanego produktu. synomymy powinny obejmować formy liczby pojedynczej i mnogiej, jeśli mają zastosowanie. Pierwszy ciąg na liście musi być liczbą mnogą elementu w danym języku.
[item, ...]	String	Nazwa synonimu
lang	String	Wymagane. Kod języka (ISO 639-1). Zobacz obsługiwane języki.
supported_units	Tablica	Wymagane. Zestaw jednostek obsługiwanych przez urządzenie dla danego elementu.
[item, ...]	String	Obsługiwane jednostki. Obsługiwane wartości: CENTIMETERS CUPS DECILITERS FLUID_OUNCES GALLONS GRAMS KILOGRAMS LITERS MILLIGRAMS MILLILITERS MILLIMETERS NO_UNITS OUNCES PINCH PINTS PORTION POUNDS QUARTS TABLESPOONS TEASPOONS
default_portion	Obiekt	Wymagane. Typowa ilość produktu, który może być wydany.
amount	Liczba całkowita	Wymagane. Kwota została wydana.
unit	String	Wymagane. Jednostka została wysłana.
supportedDispensePresets	Tablica	Gotowe ustawienia obsługiwane przez urządzenie.
[item, ...]	Obiekt	Gotowe ustawienia.
preset_name	String	Wymagane. Wewnętrzna nazwa gotowego ustawienia. Ta nazwa może być nieprzyjazna dla użytkownika i jest wspólna dla wszystkich języków.
preset_name_synonyms	Tablica	Wymagane. Nazwy synonimów gotowych ustawień w każdym obsługiwanym języku.
[item, ...]	Obiekt	Nazwy synonimów gotowych ustawień w danym języku.
synonyms	Tablica	Wymagane. Nazwy synonimów gotowych ustawień. Synonimy powinny obejmować formy liczby pojedynczej i mnogiej, jeśli mają zastosowanie.
[item, ...]	String	Nazwa synonimu
lang	String	Wymagane. Kod języka (ISO 639-1). Zobacz obsługiwane języki.

Przykłady

Dozownik wody, który obsługuje płyny za pomocą gotowych ustawień.

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

Dozownik karmy dla zwierząt bez gotowych ustawień.

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

Urządzenie STATES

Encje z tą cechą mogą zgłaszać poniższe stany w ramach operacji QUERY. Więcej informacji o obsłudze intencji QUERY znajdziesz w artykule o realizacji intencji.

Stany	Typ	Opis
dispenseItems	Tablica	Stany produktów, które urządzenie może wydać.
[item, ...]	Obiekt	Stan danego elementu.
itemName	String	Nazwa produktu z atrybutu item_name.
amountRemaining	Obiekt	Część tego elementu pozostała na urządzeniu. Jeśli urządzenie obecnie wydaje środki, wyświetla się w raporcie informacja o pozostałej kwocie lub kwocie, która wyświetli się po zakończeniu wydatkowania urządzenia.
amount	Number	Pozostała kwota
unit	String	Jednostka wartości amount z atrybutu supported_units.
amountLastDispensed	Obiekt	Kwota tego produktu ostatnio wydana przez urządzenie. Jeśli urządzenie aktualnie wydaje, powinna być widoczna informacja o wydanej ilości przed bieżącą.
amount	Number	Pozostała kwota
unit	String	Jednostka wartości amount z atrybutu supported_units.
isCurrentlyDispensing	Wartość logiczna	Wskazuje, czy urządzenie obecnie wydaje ten produkt.

Przykłady

Ile psich przysmaków pozostało w dozowniku?

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

Ile wody zostało mi w chłodnicy wody?

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

Ile karmy dla kota podałem wcześniej?

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

Czy kran nadal wydaje wodę?

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

Wartości amountRemaining i amountLastDispensed trzeba raportować tylko za pomocą 1 jednostki miary.

Tablica dispenseItems może zawierać wiele elementów. Każda nazwa produktu musi być niepowtarzalna i musi odpowiadać elementowi w atrybucie supportedDispenseItems.

CommandS na urządzeniu

Urządzenia z tą cechą mogą reagować na podane niżej polecenia w ramach operacji EXECUTE. Więcej informacji o obsłudze intencji EXECUTE znajdziesz w artykule o realizacji intencji.

action.devices.commands.Dispense

Wydaj przedmioty.

Parametry

Ładunek zawiera jeden z tych elementów:

Wydaj według ilości.

Parametry	Typ	Opis
item	String	Nazwa produktu do wydania, pochodząca z atrybutu item_name.
amount	Number	Wymagane. Kwota do wydania.
unit	String	Wymagane. Jednostka atrybutu amount z atrybutu supported_units.

Wydaj według gotowego ustawienia.

Parametry	Typ	Opis
presetName	String	Wymagane. Nazwa gotowego ustawienia do wydania, pochodząca z atrybutu preset_name.

Wydaj bez parametrów.

Parametry	Typ	Opis
Brak właściwości

Przykłady

Daj mi 1 szklankę wody.

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

Napełnij miskę na wodę kota.

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

Wydaj wodę.

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

Urządzenie ERRORS

Zobacz pełną listę błędów i wyjątków.

• dispenseAmountRemainingExceeded: użytkownik próbował wydać produkt lub kwotę z urządzenia, na którym pozostała niewystarczająca ilość.
• dispenseAmountAboveLimit: użytkownik próbował wydać kwotę, która przekraczała dopuszczalne limity w jednym zapytaniu. Ma to zapobiec przypadkowemu wydaniu nadmiernej ilości wody (np. 500 tys. szklanek wody).
• dispenseAmountBelowLimit: użytkownik próbował wydać z urządzenia przedmiot lub kwotę, która jest poniżej minimalnej ilości, jaką można wydać.
• dispenseFractionalAmountNotSupported: użytkownik próbował wydać ułamkową część produktu, którego urządzenie nie może rozdzielić (np. liczba przedmiotów, takich jak psie przysmaki, nie może być podzielna przez urządzenie).
• genericDispenseNotSupported: użytkownik próbuje wydać środki z urządzenia bez określania elementu lub gotowego ustawienia, ale urządzenie nie obsługuje takiej funkcji (na przykład domyślnego działania wydania).
• dispenseUnitNotSupported: użytkownik próbuje wydać środki z urządzenia z jednostką, która nie jest w tym przypadku obsługiwana (na przykład produkt nie został dostarczony, więc element supported_unit validation został pominięty).
• dispenseFractionalUnitNotSupported: użytkownik próbował wydać ułamkową ilość produktu, który można podzielić, ale nie za określoną jednostkę (np. kran może wydać 2,7 filiżanki, ale nie 2,7 ml).
• deviceCurrentlyDispensing: użytkownik próbuje wydać produkt, ale urządzenie już je wydaje.
• deviceClogged: użytkownik próbuje wydać produkt, ale urządzenie się zapcha.
• deviceBusy: użytkownik próbuje wydać produkt, ale urządzenie jest zajęte (standardowe).

Urządzenie EXCEPTIONS

Te wyjątki można zgłosić jako exceptionCode w obiekcie states odpowiedzi:

• amountRemainingLow – użytkownik wydaje z urządzenia przedmiot lub kwotę, która obniża poziom pozostałej kwoty. To Ty odpowiadasz za określenie, co składa się na „niski” poziom.
• userNeedsToWait – gdy użytkownik musi poczekać, zanim będzie można wydać żądaną ilość lub przedmiot (np. kran będzie wydawać gorącą wodę, ale użytkownik musi poczekać, aż woda się nagrzeje, zanim będzie można ją wydobywać).