Schéma du trait de distribution pour la maison connectée

action.devices.traits.Dispense : ce trait appartient aux appareils qui permettent de distribuer une quantité spécifiée d'un ou de plusieurs articles physiques.

Cette caractéristique permet également de distribuer une quantité prédéfinie, par exemple une "gamelle pour chat" pour un distributeur de nourriture pour animaux ou un "verre" pour un robinet.

ATTRIBUTS de l'appareil

Les appareils dotés de ce trait peuvent signaler les attributs suivants dans le cadre de l'opération SYNC. Pour en savoir plus sur la gestion des intents SYNC, consultez Fulfillment d'intent.

Exemples

Distributeur d'eau compatible avec les unités pour les liquides avec des préréglages.

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

Distributeur de nourriture pour animaux sans préréglages.

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

ÉTATS des appareils

Les entités dotées de ce trait peuvent signaler les états suivants dans le cadre de l'opération QUERY. Pour en savoir plus sur la gestion des intents QUERY, consultez Fulfillment d'intent.

Exemples

Combien de friandises pour chiens reste-t-il dans mon distributeur ?

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

Combien d'eau reste-t-il dans ma fontaine à eau ?

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

Quelle quantité de nourriture pour chat ai-je donnée avant ?

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

Le robinet continue-t-il de verser de l'eau ?

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

amountRemaining et amountLastDispensed ne doivent être signalés qu'avec une seule unité de mesure.

Vous pouvez fournir plusieurs éléments dans le tableau dispenseItems. Chaque nom d'article doit être unique et correspondre à un article de l'attribut supportedDispenseItems.

COMMANDES de l'appareil

Les appareils dotés de ce trait peuvent répondre aux commandes suivantes dans le cadre de l'opération EXECUTE. Pour en savoir plus sur la gestion des intents EXECUTE, consultez Fulfillment d'intent.

action.devices.commands.Dispense

Distribuer des articles.

Paramètres

La charge utile contient l'un des éléments suivants :

Distribuer par montant.

Distribuer selon un préréglage.

Distribution sans paramètres.

Exemples

Donne-moi une tasse d'eau.

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

Remplis le bol d'eau du chat.

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

Distribue de l'eau.

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

ERREURS liées à l'appareil

• dispenseAmountRemainingExceeded : l'utilisateur a essayé de distribuer un article ou un montant à partir d'un appareil dont le solde est insuffisant.
• dispenseAmountAboveLimit : l'utilisateur a essayé de distribuer une quantité qui dépasse les limites de ce qu'il peut demander dans une seule requête. Cela permet d'éviter de distribuer accidentellement une quantité excessive (par exemple, 500 000 tasses d'eau).
• dispenseAmountBelowLimit : l'utilisateur a essayé de distribuer un article ou un montant inférieur au montant minimal que l'appareil peut distribuer.
• dispenseFractionalAmountNotSupported : l'utilisateur a essayé de distribuer une quantité fractionnaire d'un article que l'appareil ne peut pas diviser (par exemple, les articles dénombrables comme les friandises pour chiens ne peuvent pas être divisés par l'appareil).
• genericDispenseNotSupported : l'utilisateur essaie de distribuer un article à partir d'un appareil sans spécifier d'article ni de préréglage, mais l'appareil ne prend pas en charge cette fonctionnalité (par exemple, une action de distribution par défaut).
• dispenseUnitNotSupported : l'utilisateur tente de distribuer un article à partir d'un appareil dont l'unité n'est pas compatible avec ce cas (par exemple, l'article n'est pas fourni, donc supported_unit validation a été ignoré).
• dispenseFractionalUnitNotSupported : l'utilisateur a essayé de distribuer une quantité fractionnée d'un élément qui peut être divisé, mais pas pour l'unité spécifiée (par exemple, un robinet peut distribuer 2,7 tasses, mais pas 2,7 ml).
• deviceCurrentlyDispensing : l'utilisateur essaie de distribuer un article, mais l'appareil est déjà en train de le faire.
• deviceClogged : l'utilisateur essaie de distribuer un article, mais l'appareil est bouché.
• deviceBusy : l'utilisateur essaie de distribuer un article, mais l'appareil est occupé (générique).

EXCEPTIONS concernant les appareils

Ces exceptions peuvent être signalées en tant que exceptionCode dans l'objet states de votre réponse :

• amountRemainingLow : l'utilisateur distribue un article ou une quantité à partir de l'appareil, ce qui réduit la quantité restante à un niveau bas. Il vous appartient de définir ce qui constitue un niveau "bas".
• userNeedsToWait : lorsque l'utilisateur doit attendre avant que l'article ou le montant demandé puisse être distribué (par exemple, un robinet distribue de l'eau chaude, mais l'utilisateur doit attendre que l'eau chauffe avant qu'elle ne commence à couler).