Smart Home 填滿特徵結構定義

action.devices.traits.Fill - 這個特性適用於支援填充的裝置,例如浴缸。

裝置屬性

具備這個特性的裝置可能會在 SYNC 作業中回報下列屬性。如要進一步瞭解如何處理 SYNC 意圖,請參閱「意圖執行要求」。

屬性 類型 說明
availableFillLevels 物件

說明裝入裝置的不同層級。

levels 陣列

必要。

層級名稱和特定語言的同義詞清單。

[item, ...] 物件

等級名稱和該語言專屬的同義詞。

level_name String

必要。

層級的內部名稱。這項設定可能不宜使用,並開放所有語言的使用者使用。

level_values 陣列

必要。

每種支援的語言的層級同義詞。

[item, ...] 物件

特定語言層級的同義詞。

level_synonym 陣列

必要。

層級的同義詞。這份清單中的第一個字串會做為該語言等級的標準名稱。

[item, ...] String

同義詞名稱。

lang String

必要。

語言代碼 (ISO 639-1)。查看支援的語言

ordered 布林

必要。

如果為 true,裝置就會處理以 levels 陣列表示的遞增或減號邏輯 (例如半層級) 的文法。

supportsFillPercent 布林

(預設值:false)。

如果為 true,請接受將等級調整為百分比的指令。

範例

具有基本填充或排水功能且不支援個別填滿等級的裝置。

{}

支援離散填充等級的裝置

{
  "availableFillLevels": {
    "levels": [
      {
        "level_name": "half_level",
        "level_values": [
          {
            "level_synonym": [
              "Half",
              "Half way",
              "One half"
            ],
            "lang": "en"
          }
        ]
      },
      {
        "level_name": "full_level",
        "level_values": [
          {
            "level_synonym": [
              "Full",
              "All the way",
              "Complete"
            ],
            "lang": "en"
          }
        ]
      }
    ],
    "ordered": true
  }
}

裝置狀態

具有這個特性的實體可能會在 QUERY 作業中回報下列狀態。如要進一步瞭解如何處理 QUERY 意圖,請參閱「意圖執行要求」。

狀態 類型 說明
isFilled 布林

必要。

如果裝置已填滿任何關卡,則為「是」。如果裝置已完全耗盡,則為「否」。

currentFillLevel String

如果已設定 availableFillLevels 屬性,則為必要欄位。指出在填入裝置時的 availableFillLevels 屬性中目前的 level_name

currentFillPercent Number

如果已設定 supportsFillPercent 屬性,則為必要欄位。指出目前的供應率百分比。

範例

浴缸是否已裝滿?

{
  "isFilled": true
}

浴缸是否已裝滿?。

{
  "isFilled": true,
  "currentFillLevel": "half_level"
}

裝置指令

具有這個特性的裝置可能會在 EXECUTE 作業中回應下列指令。如要進一步瞭解如何處理 EXECUTE 意圖,請參閱「意圖執行要求」。

action.devices.commands.Fill

填滿或清空裝置。

參數

參數 類型 說明
fill 布林

必要。

True 代表填充,值為 false 表示排水。

fillLevel String

指出 availableFillLevels 屬性中要設定的 level_name。如果未指定,會填入預設層級。

fillPercent Number

表示要求的等級百分比。

範例

為浴缸加水

{
  "command": "action.devices.commands.Fill",
  "params": {
    "fill": true
  }
}

為浴缸排水

{
  "command": "action.devices.commands.Fill",
  "params": {
    "fill": false
  }
}

將浴缸填滿一半

{
  "command": "action.devices.commands.Fill",
  "params": {
    "fill": true,
    "fillLevel": "half_level"
  }
}

將浴缸填充等級加 1 (規定 ordered 屬性必須為 true)。

{
  "command": "action.devices.commands.Fill",
  "params": {
    "fill": true,
    "fillLevel": "full_level"
  }
}

裝置錯誤

請參閱錯誤和例外狀況的完整清單。