סכימת מאפיינים של מכשיר בית חכם לחלוקת משקאות

‫action.devices.traits.Dispense - התכונה הזו שייכת למכשירים שתומכים בחלוקה של כמות מסוימת של פריט פיזי אחד או יותר.

התכונה הזו תומכת גם בחלוקה של הגדרה מראש, למשל כ "קערת אוכל לחתולים" במתקן אוטומטי להאכלת חיות מחמד או כ "" בברז.

מאפייני המכשיר

מכשירים עם המאפיין הזה עשויים לדווח על המאפיינים הבאים כחלק מהפעולה SYNC. SYNCמידע נוסף על טיפול בכוונות

דוגמאות

מתקן מים שתומך ביחידות למדידת נוזלים עם הגדרות קבועות מראש.

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

מכשיר לחלוקת מזון לחיות מחמד ללא הגדרות קבועות מראש.

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

מצבי המכשיר

יכול להיות שיירשמו לישויות עם המאפיין הזה המצבים הבאים כחלק מהפעולה QUERY. QUERYמידע נוסף על טיפול בכוונות

דוגמאות

כמה חטיפים לכלבים נשארו במתקן?

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

כמה מים נשארו במתקן המים?

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

כמה אוכל לחתולים נתתי קודם?

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

האם המים עדיין יוצאים מהברז?

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

amountRemaining ו-amountLastDispensed צריך לדווח רק באמצעות יחידת מידה אחת.

אפשר לספק כמה פריטים במערך dispenseItems. כל שם פריט חייב להיות ייחודי ולהתאים לפריט במאפיין supportedDispenseItems.

פקודות למכשיר

מכשירים עם המאפיין הזה עשויים להגיב לפקודות הבאות כחלק מהפעולה EXECUTE. EXECUTEמידע נוסף על טיפול בכוונות

action.devices.commands.Dispense

הוצאת פריטים.

פרמטרים

המטען הייעודי מכיל אחד מהערכים הבאים:

הנפקה לפי סכום.

הנפקה לפי הגדרות קבועות מראש.

הצגת מודעות ללא פרמטרים.

דוגמאות

תביא לי מים.

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

תמלא את קערת המים של החתול.

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

מזיגת מים

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

שגיאות במכשיר

• ‫dispenseAmountRemainingExceeded: המשתמש ניסה להוציא פריט או סכום ממכשיר שלא נשאר בו מספיק כסף.
• ‫dispenseAmountAboveLimit: המשתמש ניסה להקצות סכום שחורג מהמגבלות של מה שהוא יכול לבקש בשאילתה אחת. המטרה היא למנוע מצב שבו כמות מוגזמת של מים תצא בטעות (למשל 500,000 כוסות מים).
• ‫dispenseAmountBelowLimit: המשתמש ניסה להוציא פריט או סכום מהמכשיר, אבל הסכום היה נמוך מהסכום המינימלי שאפשר להוציא מהמכשיר.
• ‫dispenseFractionalAmountNotSupported: המשתמש ניסה להוציא כמות חלקית של פריט שהמכשיר לא יכול לפצל (לדוגמה, פריטים שאפשר לספור כמו חטיפים לכלבים לא ניתנים לחלוקה על ידי המכשיר).
• ‫genericDispenseNotSupported: המשתמש מנסה להוציא פריט ממכשיר בלי לציין פריט או הגדרה מראש, אבל המכשיר לא תומך בפונקציונליות כזו (לדוגמה, פעולת הוצאה שמוגדרת כברירת מחדל).
• ‫dispenseUnitNotSupported: המשתמש מנסה להשתמש במכשיר עם יחידה שלא נתמכת במקרה הזה (לדוגמה, הפריט לא מסופק ולכן המערכת דילגה על supported_unit validation).
• ‫dispenseFractionalUnitNotSupported: המשתמש ניסה להוציא כמות חלקית של פריט שאפשר לחלק, אבל לא ביחידה הספציפית שצוינה (לדוגמה, יכול להיות שאפשר להוציא 2.7 כוסות מברז, אבל לא 2.7 מ"ל).
• ‫deviceCurrentlyDispensing: המשתמש מנסה להוציא פריט אבל המכשיר כבר מוציא פריט.
• ‫deviceClogged: המשתמש מנסה להוציא פריט אבל המכשיר סתום.
• ‫deviceBusy: המשתמש מנסה להוציא פריט אבל המכשיר עסוק (כללי).

החרגות של מכשירים

אפשר לדווח על החריגים האלה כexceptionCode באובייקט states בתגובה:

• ‫amountRemainingLow – המשתמש מוציא פריט או סכום מהמכשיר, וכתוצאה מכך הכמות שנותרה יורדת לרמה נמוכה. באחריותכם להגדיר מה נחשב לרמה 'נמוכה'.
• ‫userNeedsToWait – כשהמשתמש צריך לחכות לפני שהפריט או הכמות המבוקשים מסופקים (לדוגמה, ברז שמספק מים חמים אבל המשתמש צריך לחכות עד שהמים יתחממו לפני שהם מתחילים לזרום).