智慧型住宅 OpenClose 特徵架構

action.devices.traits.OpenClose - 這項特徵屬於支援開關的裝置，在某些情況下，裝置可能支援部分開關，或朝多個方向開關。

裝置屬性

具有這項特徵的裝置可能會回報下列屬性，做為 SYNC 作業的一部分。如要進一步瞭解如何處理 SYNC 意圖，請參閱「意圖執行要求」。

屬性 類型 說明
discreteOnlyOpenClose 布林值

(預設值：false)

如果設為 true，表示裝置必須完全開啟或完全關閉 (即不支援 0% 到 100% 之間的值)。
openDirection 陣列

裝置可開啟或關閉的方向清單。如果裝置支援以多種方向開合，請加入這項屬性。
[item, ...] String

支援的方向。

支援的值：

UP
DOWN
LEFT
RIGHT
IN
OUT
commandOnlyOpenClose 布林值

(預設值：false)

指出裝置是否支援單向 (true) 或雙向 (false) 通訊。如果裝置無法回應這項特徵的 QUERY 意圖或 Report State，請將這個屬性設為 true。
queryOnlyOpenClose 布林值

(預設值：false)

指出裝置是否只能查詢狀態資訊，無法控制。只能回報開啟狀態的感應器應將這個欄位設為 true。

範例

簡單開啟/關閉裝置。

{
  "discreteOnlyOpenClose": true
}

由上而下和由下而上裝置。可雙向開啟。

{
  "openDirection": [
    "UP",
    "DOWN"
  ]
}

僅支援指令的裝置。

{
  "commandOnlyOpenClose": false
}

裝置狀態

具有這項特徵的實體可能會回報下列狀態，做為 QUERY 作業的一部分。如要進一步瞭解如何處理 QUERY 意圖，請參閱「意圖執行要求」。

酬載包含下列其中一項：

單一方向開合

州 類型 說明
openPercent Number

必要。

指出裝置開啟的百分比，其中 0 代表關閉，100 代表完全開啟。
targetOpenPercent Number

裝置因位置持續變更而將前往或正在前往的開啟百分比。

可朝多個方向開啟/關閉

州 類型 說明
openState 陣列

必要。

列出每個支援的開放方向的狀態。
[item, ...] 物件

指定開啟方向的目前狀態。
openPercent Number

必要。

指出裝置開啟的百分比，其中 0 代表關閉，100 代表完全開啟。
targetOpenPercent Number

裝置因位置持續變更而將前往或正在前往的開啟百分比。
openDirection String

必要。

裝置開啟的方向。

支援的值：

UP
DOWN
LEFT
RIGHT
IN
OUT

範例

簡單開啟/關閉裝置。

{
  "openPercent": 100
}

簡單的開合裝置目前正在開啟至新位置。

{
  "openPercent": 50,
  "targetOpenPercent": 100
}

向下開啟裝置 30%，向上開啟裝置 50%。

{
  "openState": [
    {
      "openPercent": 30,
      "openDirection": "DOWN"
    },
    {
      "openPercent": 50,
      "openDirection": "UP"
    }
  ]
}

將裝置向下開啟 30%，向上開啟 50%，目前向上開啟 80%。

{
  "openState": [
    {
      "openPercent": 30,
      "openDirection": "DOWN"
    },
    {
      "openPercent": 50,
      "targetOpenPercent": 80,
      "openDirection": "UP"
    }
  ]
}

裝置指令

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

action.devices.commands.OpenClose

設定裝置的開啟/關閉狀態。

參數

參數 類型 說明
openPercent Number

必要。

指出裝置開啟的百分比，其中 0 代表關閉，100 代表完全開啟。
openDirection String

開啟方向。只有在裝置支援多個方向 (如 openDirection 屬性所示)，且使用者指定方向時，才會顯示這個屬性。

支援的值：

UP
DOWN
LEFT
RIGHT
IN
OUT
followUpToken String

Google 提供的後續回應權杖。

範例

開啟裝置。

{
  "command": "action.devices.commands.OpenClose",
  "params": {
    "openPercent": 100,
    "followUpToken": "123"
  }
}

將裝置打開 50%。

{
  "command": "action.devices.commands.OpenClose",
  "params": {
    "openPercent": 50,
    "openDirection": "DOWN",
    "followUpToken": "456"
  }
}

設定裝置開啟/關閉狀態時發生錯誤。

支援的值：

lockedState
deviceJammingDetected

後續回覆

具有這項特徵的裝置可能會傳回下列後續回應酬載，做為 EXECUTE 作業的一部分。如要進一步瞭解如何導入後續回應，請參閱「智慧住宅動作的通知」。

酬載包含下列其中一項：

成功

欄位 類型 說明
followUpToken String

必要。

原始 EXECUTE 要求中提供的權杖。
status String

必要。

要求的結果。

支援的值：

SUCCESS
openPercent Number

必要。

指出裝置的開啟百分比，0 代表關閉，100 代表完全開啟。

失敗

欄位 類型 說明
followUpToken String

必要。

原始 EXECUTE 要求中提供的權杖。
status String

必要。

要求的結果。

支援的值：

FAILURE
errorCode String

必要。

這個值可以是這個特徵的任何錯誤代碼，例如 lockedState。

範例

打開車庫門。(follow-up response for success case)

{
  "OpenClose": {
    "priority": 0,
    "followUpResponse": {
      "openPercent": 100,
      "status": "SUCCESS",
      "followUpToken": "1234"
    }
  }
}

打開車庫門。(後續回應，適用於失敗案例)

{
  "OpenClose": {
    "priority": 0,
    "followUpResponse": {
      "errorCode": "lockedState",
      "status": "FAILURE",
      "followUpToken": "1234"
    }
  }
}

action.devices.commands.OpenCloseRelative

根據目前的狀態調整裝置的開啟/關閉狀態。只有在 discreteOnlyOpenClose 設為 false 時，才能使用這項指令。

這項指令需要下列屬性： 
{
  "discreteOnlyOpenClose": false
}

參數

參數 類型 說明
openRelativePercent Number

必要。

變更開啟/關閉狀態的確切百分比。模糊的相對指令會轉換為確切的百分比參數 (例如「將百葉窗打開一點」與「將百葉窗打開 5%」)。
openDirection String

開啟方向。只有在裝置支援多個方向 (如 openDirection 屬性所示)，且使用者指定方向時，才會顯示這個屬性。

支援的值：

UP
DOWN
LEFT
RIGHT
IN
OUT

範例

將裝置稍微打開

{
  "command": "action.devices.commands.OpenCloseRelative",
  "params": {
    "openRelativePercent": 5
  }
}

將裝置再關上 10%

{
  "command": "action.devices.commands.OpenCloseRelative",
  "params": {
    "openRelativePercent": -10
  }
}

將裝置向下開啟 50% 以上。

{
  "command": "action.devices.commands.OpenCloseRelative",
  "params": {
    "openRelativePercent": 50,
    "openDirection": "DOWN"
  }
}

設定裝置開啟/關閉狀態時發生錯誤。

支援的值：

lockedState
deviceJammingDetected

語音指令範例

de-DE

  • Bitte öffne die Jalousien auf 30%
  • Fensterläden um 25 % schliessen
  • Ist die Jalousie zu?
  • Mach den Rollladen zu
  • Mach die Rollos auf
  • schließe die Rollläden ein bisschen mehr
  • Öffne die Jalousien um 25%

en-US

  • Are the blinds in the kitchen open
  • Close the blinds 25% in my room
  • Close the door more
  • Just close the front door
  • open the blinds in my room
  • open the blinds to 25%
  • open the door by 25%

es-ES

  • abre la ventana del salón
  • cerrar persianas del dormitorio un 20%
  • cierra la cortina del salón
  • cierra mucho más la ventana
  • está abierta la puerta
  • quiero que subas la persiana al 25%
  • sube un 20% las persianas

fr-FR

  • baisse les stores de 10%
  • est-ce que la porte d'entrée est ouverte
  • ferme les stores
  • ferme un peu les stores
  • ouvre les stores
  • ouvre les stores de la chambre de 25%
  • ouvre les stores à 25%

hi-IN

  • कृपया 25% पर्दे को खुला रखो
  • क्या मैंने सामने वाला दरवाजा खुला छोड दिया?
  • पर्दे को 25% बंद करोगे
  • पर्दे खोलो
  • ब्लाइंड 25% खुले पर सेट कर दीजिए
  • ब्लाइंड को थोड़ा और बंद कर दिजिए
  • ब्लाइंड बंद करें

it-IT

  • abbassa un po' di più le tapparelle
  • apri la serranda
  • apri la tapparella al 30%
  • apri le serrande del 30%
  • chiudi le serrande
  • chiudi le tende del 25%
  • è aperta la porta d'ingresso

ja-JP

  • 25% に ブラインド を開けて
  • 25% ブラインド を閉めてください
  • 25% ブラインド 開けて
  • ブラインド 閉めて
  • ブラインド 開けて
  • 少し ブラインド を閉じて
  • 玄関のドア は開いてますか

ko-KR

  • 문 살짝만 닫아 줘
  • 블라인드 25% 열어 줘
  • 블라인드 25% 까지 열어 줘
  • 블라인드 30프로 닫아
  • 블라인드 닫아 줘
  • 블라인드 열어 줘
  • 안방 문 열렸어

nl-NL

  • doe de gordijnen 25% open
  • doe de jaloezieën voor 25% dicht
  • doe het raam ietsje meer dicht
  • is de voordeur open
  • open de gordijnen
  • sluit het gordijn
  • zet de luxaflex voor 50% open

pt-BR

  • Abrir janela 50%
  • As cortinas estão abertas?
  • Fecha a persiana toda
  • Fechar a janela 10%
  • a cortina do quarto está aberta?
  • abra a persiana até 30%
  • abre as cortinas
  • abre as cortinas a 50%
  • abrir as cortinas
  • abrir as cortinas na sala em 30%
  • fecha a persiana por favor
  • fecha um bocado a janela
  • fechar as cortinas em 25%
  • fechar um pouco mais as cortinas

sv-SE

  • Dra upp persiennerna
  • Dra upp persiennerna till 25%
  • stäng persiennen i mitt rum 25%
  • stäng persiennerna
  • är ytterdörren öppen?
  • öppna persiennerna med 25%

裝置錯誤

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