本文件列出智慧住宅裝置正式支援的錯誤和例外狀況。請在意圖回應或通知中使用這些指定的錯誤和例外狀況代碼 (如果您已實作),讓 Google 助理提醒使用者與特定指令或裝置狀態相關的問題。如果回應包含格式不正確或 errorCode
,Google 助理會向使用者顯示一般錯誤訊息,例如「很抱歉,裝置目前無法使用」。
錯誤
如果問題導致執行或查詢要求失敗,您應傳回錯誤代碼。舉例來說,如果門鎖卡住而無法上鎖或解鎖,則應傳回使用者這個狀態的相關錯誤。
錯誤代碼可附加在裝置層級或全域層級。舉例來說,如果使用者有多個由某個供應商提供的燈具,並由中樞控管,當使用者要求關閉所有燈具時,供應商可能會在單一燈具離線時傳回裝置層級錯誤,或是在整個中樞離線且無法控制任何燈具時,傳回全域層級錯誤。如果所有裝置都處於離線狀態,則使用全域層級或裝置層級錯誤沒有差別。裝置離線時,即使傳回 deviceOffline
錯誤代碼,也應在 reportState 中回報 {"online": false}
狀態。
摘要說明:
- 全域層級錯誤:回應中的所有裝置含有相同錯誤
- 局部錯誤:混合回應包含錯誤和成功案例
全域層級錯誤
下列 JSON 程式碼片段說明如何在 QUERY 或 EXECUTE 回應中傳回全域層級錯誤。
因中樞而造成的全域層級錯誤 deviceOffline
示例如下:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "deviceOffline", "status" : "ERROR" } }
中樞更新造成的全域層級錯誤 inSoftwareUpdate
範例如下:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "inSoftwareUpdate", "status" : "ERROR" } }
裝置層級錯誤
QUERY 回應
下列 JSON 程式碼片段顯示如何在 QUERY 回應中傳回裝置層級錯誤。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": { "device-id-1": { "errorCode": "deviceOffline", "status" : "ERROR" }, "device-id-2": { "errorCode": "deviceOffline", "status" : "ERROR" } } } }
執行回應
下列 JSON 程式碼片段顯示如何在 EXECUTE 回應中傳回裝置層級錯誤。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [ { "ids": [ "device-id-1" ], "status": "ERROR", "errorCode": "deviceOffline" }, { "ids": [ "device-id-2" ], "status": "SUCCESS", "states": { "on": true, "online": true } } ] } }
含有錯誤的通知
主動通知
下列 JSON 程式碼片段說明如何透過主動通知回報裝置層級錯誤。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id-1", "eventId": "unique-event-id-1", "payload": { "devices": { "notifications": { "device-id-1": { "RunCycle": { "priority": 0, "status": "FAILURE", "errorCode": "deviceDoorOpen" } } } } } }
後續回應
下列 JSON 程式碼片段說明如何在後續回應中回報裝置層級錯誤。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "agentUserId": "agent-user-id-1", "eventId": "unique-event-id-1", "payload": { "devices": { "notifications": { "device-id-1": { "LockUnlock": { "priority": 0, "followUpResponse": { "status": "FAILURE", "errorCode": "deviceJammingDetected", "followUpToken": "PLACEHOLDER" } } } } } } }
錯誤清單
下列錯誤會在裝置上產生相關聯的 TTS。
- above maxLightEffectsDuration : 超過 1 小時的長度上限。請再試一次。
- above maxTimerDuration : 我只能設定 <device(s)>,最長可達 <時間範圍>
- action 無法使用 : 很抱歉,我目前無法執行這個動作。
- actionUnavailable 卓越 : <device(s)> <is/are> 目前正在執行中,所以我無法進行任何變更。
- 已經啟用 : <device(s)> <is/are> 已經啟動。
- 已最高溫度 : <device(s)> <is/are> 已經設為最高溫度。
- hasAtMin : <device(s)> <is/are> 已設為最低溫度。
- 已關閉 : <device(s)> <is/are> 已關閉。
- 已解除 : <device(s)> <is/are> 已解除。
- 已插入座架 : <device(s)> <is/are> 已插入座架。
- wasInState : <device(s)> <is/are> 已處於該狀態。
- 已鎖定 : <device(s)> <is/are> 已鎖定。
- 已經關閉 : <device(s)> <is/are> 已關閉。
- 已經開啟 : <device(s)> <is/are> 已經開啟。
- 已開啟 : <device(s)> <is/are> 已開啟。
- 已暫停 : <device(s)> <is/are> 已暫停。
- 已經啟動 : <device(s)> <is/are> 已啟動。
- 已經停止 : <device(s)> <is/are> 已停止。
- 已解鎖 : <device(s)> <is/are> 已解鎖。
- ambiguousZoneName : 很抱歉,「<device(s)>」無法辨識正確的可用區。請確認各個區域皆有專屬名稱,然後再試一次。
- AmountAboveLimit : 這超出 <device(s)> 支援的上限。
- appLaunchFailed :很抱歉,無法在 <device(s)> 上啟動「<應用程式名稱>」。
- arm 失敗 : <device(s)> 無法啟動。
- armLevelNeeded : 我不確定要將 <device(s)> 設為哪個層級,請試著說出「將 <裝置> 設為 <低安全性>」或「將 <裝置> 設為 <高安全性>」
- auth 失敗 : 我無法連線到 <device(s)>,請查看應用程式,確認你的 <裝置/裝置> <is/are> 已設定完畢。
- bagFull : <device(s)> <has/have> <a full bag/full bags>。請 <它/裝置>清空並重試。
- belowMinimumLightEffectsDuration : 低於最短 5 分鐘。請再試一次。
- belowMinimumTimerDuration : 我無法設定 <device(s)>的短時間,請再試一次。
- binFull : <device(s)> <has/have> <a full bin/full bins>。
- cancelArmingRestricted : 很抱歉,我無法取消啟動 <device(s)>。
- cancelTooLate : 很抱歉,取消期限已過,請改用 <device(s)> 或 app。
- channelSwitchFailed : 很抱歉,無法切換至「<頻道名稱>」頻道,請稍後再試。
- 充電器問題 : 抱歉,似乎是 <device(s)> <has/have> <充電器問題/充電器問題>。
- commandInsertFailed :無法處理 <device(s)> 的指令。
- deadBattery : <device(s)> <has/have> <a dead Battery/dead Battery>。
- degreeOutOfRange :要求的度數超出 <device(s)> 的範圍。
- deviceAlert 需要輔助 : <device(s)> <has/have> 可執行警報, <need(s)> 為你提供協助。
- device AtExtremeTemperature : <device(s)> <is/are> 同時 <is/are> 在 <極端溫度/極端溫度> 的情況下。
- deviceBusy : 很抱歉,<device(s)> 目前正在執行其他操作。
- 裝置充電 : 很抱歉,<device(s)> 似乎正在充電,因為 (ha_shared.Its 他們 re size=$item.devices.total_device_count) 充電中。
- deviceClogged : 很抱歉,<device(s)> 似乎卡住。
- deviceCurrentlyDispensing : <device(s)> 目前在供應東西。
- deviceDoorOpen : 這個門在 <device(s)> 上已開啟,請關緊後再試一次。
- deviceHandleClosed : 這個帳號代碼已在 <device(s)> 上關閉,請開啟帳號並再試一次。
- deviceJammingDetected : <device(s)> <is/are> jammed.
- deviceLidOpen : 機蓋在 <device(s)> 上已開啟。請關上,然後再試一次。
- device 需要維修 : <device(s)> <need(s)>進行維修。請聯絡當地服務經銷商。
- device Not Docked : 很抱歉,看起來 <device(s)> <isn't/aren't> 已插入座架。請將 <it/them> 插入座架,然後再試一次。
- deviceNotFound : <device(s)> <is/are>無法使用。建議您重新設定 <it/them>。
- device 未掛接 : 很抱歉,<device(s)> 似乎尚未掛載 <it/they> <is/are>並未安裝,因此無法執行這個動作。
- deviceNotReady : <device(s)> <is/are>尚未準備就緒。
- device 停滯 : <device(s)> <is/are>無法解決,需要你的協助。
- deviceTampered : <device(s)> <has/have> 遭到竄改。
- deviceThermalShutdown :很抱歉,<device(s)>似乎因極端溫度而關閉。
- directResponseOnlyUnavailable : <device(s)> <it't/don't> 支援遠端控制。
- disarmFailure : 無法解除 <device(s)>。
- discreteOnlyOpenClose : 很抱歉,「<device(s)>」只能完全開啟或關閉。
- dispenseAmountAboveLimit : <device(s)> 無法分配這麼多的額度。
- dispenseAmountBelowLimit : <device(s)> 無法分配這麼少的量。
- dispenseAmountRemainingExceeded : <device(s)> 的 <dispense item> 不足,無法執行這項操作。
- dispenseFractionalAmountNotSupported : <device(s)>無法分配 <dispense item> 的分數。
- dispenseFractionalUnitNotSupported : <device(s)> 不支援 <dispense item> 該單位的分數。
- dispenseUnitNotSupported : <device(s)> 不支援 <dispense item> 的該單位。
- doorClosedTooLong : 自 <device(s)> 上的門前已有一段時間未開啟,請打開門,確認裡面有東西,然後再試一次。
- 緊急熱源 : <device(s)> <is/are> 處於緊急熱源模式,因此<裝置/結果>必須手動調整。
- 電池有問題 : <device(s)> <has/have> <有電池故障/有問題>。
- 無法連上樓層 : <device(s)> 無法連線至該房間。請將 <it/m> 移至正確的樓層,然後再試一次。
- functionNotSupported : 事實上,<device(s)> <not'/don't> 支援該功能。
- genericDispenseNotSupported : 我必須知道你想供應什麼。請使用商品名稱再試一次。
- hardError : 很抱歉,發生錯誤,我現在無法控制你的住宅裝置。
- hardError : 很抱歉,發生錯誤,我現在無法控制你的住宅裝置。
- inAutoMode : <device(s)> <is/are>目前設為自動模式。如要變更溫度,請將 <裝置> 切換至其他模式。
- inAwayMode : <device(s)> <is/are>目前設為外出模式。如要控制溫度控制器,請使用手機、平板電腦或電腦上的 Nest 應用程式,手動將溫度控制器切換成在家模式。
- inDryMode : <device(s)> <is/are>目前設為乾燥模式。如要變更溫度,請將 <裝置> 切換至其他模式。
- inEcoMode : <device(s)> <is/are>目前設為節能模式。如要變更溫度,請將 <裝置> 切換至其他模式。
- inFanOnlyMode : <device(s)> <is/are> 目前設為送風模式。如要變更溫度,請將 <裝置> 切換至其他模式。
- inHeatOrCool : <device(s)> <is/are>未處於暖氣/冷氣模式。
- inHumidifierMode : <device(s)> <is/are>目前設為加濕器模式。如要變更溫度,請將 <裝置> 切換至其他模式。
- inOffMode : <device(s)> <is/are>目前關閉中。如要變更溫度,你必須將 <it/m> 切換至其他模式。
- inPurifierMode : <device(s)> <is/are>目前設為淨化模式。如要變更溫度,請將 <裝置> 切換至其他模式。
- inSleepMode : <device(s)> <is/are>處於睡眠模式。請稍後再試。
- inSoftwareUpdate : <device(s)> <is/are>目前正在進行軟體更新。
- Lock 失敗 : 無法鎖定 <device(s)>。
- LockState : <device(s)> <is/are>目前鎖定。
- lockToRange : 這個溫度不在 <device(s)> 的鎖定範圍內。
- 低電量 : <device(s)> <has/have> 低電量。
- maxSettingReached : <device(s)> <is/are> 已設為最高設定。
- maxSpeedReached : <device(s)> <is/are> 已設為最高速度。
- minSettingReached : <device(s)> <is/are> 已設為最低設定。
- minSpeedReached : <device(s)> <is/are> 已設為最低速度。
- monitoringServiceConnection Loss : <device(s)> <has/have>中斷 <its/their>連線與監控服務連線。
- needAttachment : 很抱歉,<device(s)> <is/are> 似乎缺少必要的附件。請更換後再試一次
- needBin : 很抱歉,看起來 <device(s)> <is/are> 缺少特徵分塊。請更換後再試一次
- needPads : <device(s)> <need(s)> new pads.
- needSoftwareUpdate : <device(s)> <need(s)> a Software Update。
- 需要水 : <device(s)> <need(s)> Water。
- networkProfile 無法辨識 : 很抱歉,我無法辨識 <裝置> 上的「<網路設定檔>」。
- networkSpeedTestInProgress : 我正在測試 <network> <speed/speeds>>。
- noAvailableApp : 很抱歉,「<應用程式名稱>」似乎無法使用。
- noAvailableChannel : 很抱歉,「<頻道名稱>」似乎無法使用。
- no 頻道訂閱 : 很抱歉,你目前並未訂閱「<頻道名稱>」頻道。
- 沒有計時器 : 很抱歉,<device(s)>上似乎沒有設定任何計時器。
- 不支援 : 很抱歉,<device(s)>不支援這個模式。
- 偵測到障礙物 : <device(s)> 偵測到障礙物。
- 離線 、裝置離線 : 很抱歉,目前似乎 <device(s)> <is/are> 目前無法使用。
- onRequiresMode : 請指定要開啟的模式。
- 通關密語不正確 : 很抱歉,PIN 碼似乎不正確。
- %OutOfRange : 很抱歉,我無法將 <device(s)> 設為 <percent>。
- PIN 碼不正確 : (passphrasebug)
- rainDetected : 我沒有開啟 <device(s)>,因為偵測到雨水。
- RangeTooClose : 與 <device(s)> 的熱、冷氣範圍太小,請選擇距離較遠的溫度。
- relinkRequired : 很抱歉,您的帳戶似乎有問題。請透過 Google Home 或 Google 助理應用程式重新連結 <device(s)>。
-
remoteSetDisabled
:
- 選用參數
errorCodeReason
currentlyArmed
- 很抱歉,安全性已啟動,因此你必須使用 <device(s)> 或應用程式才能進行變更。remoteUnlockNotAllowed
- 很抱歉,我無法從遠端解鎖「<device(s)>」。remoteControlOff
- 這個動作目前已停用。請在 <device(s)> 上啟用遙控器,然後再試一次。childSafetyModeActive
- 啟用兒童安全模式時,<device(s)>就無法執行這項操作。
- 選用參數
- roomOnDifferentFloors : <device(s)>無法移動到這些房間,因為這些裝置位於不同樓層。
- safetyShutOff : <device(s)> <is/are> 處於安全關閉模式,因此 <it/Account> 必須手動調整。
- sceneCannotBelied : 很抱歉,無法套用 <device(s)>。
- security 限制 : <device(s)> <has/have>安全性限制。
- SoftwareUpdateNotAvailable : 很抱歉,<device(s)> 無法提供軟體更新。
- startRequiresTime : 首先,請告訴我要執行 <device(s)> 的時間長度。
- 仍然等待冷卻 : <device(s)> <is/are> 仍在冷卻中。
- 仍然 WarmingUp : <device(s)> <is/are>仍在準備中。
- streamUnavailable : 很抱歉,<device(s)>目前沒有串流播放內容。
- 串流播放無法播放 : 很抱歉,我目前無法透過 <device(s)> 播放串流。
- tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>。請填入 <it/them>,然後再試一次。
- targetReadyed : 很抱歉,這似乎已經是目前的溫度。
- timeValueOutOfRange : <device(s)> 無法設定這個時間長度。
- Too ManyFailedtrys :很抱歉,嘗試失敗次數過多。請前往裝置的應用程式完成這項操作。
- transientError : 很抱歉,控制 <device(s)> 時發生錯誤,請再試一次。
- 關閉,deviceedOff : <device(s)> <is/are>目前已關閉。
- notToLocateDevice :我找不到「<device(s)>」。
- UnknownFoodPreset : <device(s)> 不支援這項食物預設設定。
- 解鎖失敗 : 無法解鎖 <device(s)>。
- unpausableState : 目前無法暫停 <device(s)>。
- userCancelled :ok
- valueOutOfRange : <device(s)> 無法設為該溫度。
例外狀況
您應在指令出現問題或快訊時傳回例外狀況。指令可能會成功或失敗。
如果指令成功 (狀態 = 「SUCCESS」),請使用 StatusReport
特徵 (適用於目標以外的裝置) 或傳回適當的 exceptionCode
(針對目標裝置) 回報例外狀況。
舉例來說,如果乾衣機 Lint 螢幕已滿,使用者仍可啟動烘衣機,但建議您警告使用者這個狀態。同樣地,即使裝置電量過低,並非空白,您還是可以執行指令,但應告知裝置電量過低。
如果指令因例外狀況而失敗,狀態應為「EXCEPTIONS」,且應使用 StatusReport
特徵回報例外狀況。
與目標裝置相關的非封鎖例外狀況 (成功)
以鎖門為例:
前門門電池電力不足,正在鎖上前門
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["device-id-1"], "status": "SUCCESS", "states": { "on": true, "online": true, "isLocked": true, "isJammed": false, "exceptionCode": "lowBattery" } }] } }
透過 StatusReport 處理其他裝置的非封鎖例外狀況 (成功)
本例是啟動保全系統:好,啟動保全系統。前窗戶已開啟。
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "commands": [{ "ids": ["device-id-1"], "status": "SUCCESS", "states": { "on": true, "online": true, "isArmed": true, "currentArmLevel": "L2", "currentStatusReport": [{ "blocking": false, "deviceTarget": "sensor_id1", "priority": 0, "statusCode": "deviceOpen" }] } }] } }
使用 StatusReport 封鎖另一部裝置的例外狀況
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": { "device-id-1": { "on": true, "online": true, "status": "EXCEPTIONS", "currentStatusReport": [{ "blocking": true, "deviceTarget": "device-id-1", "priority": 0, "statusCode": "lowBattery" }, { "blocking": true, "deviceTarget": "front_window_id", "priority": 1, "statusCode": "deviceOpen" }, { "blocking": true, "deviceTarget": "back_window_id", "priority": 1, "statusCode": "deviceOpen" } ] } } } }
例外清單
以下例外狀況會在裝置上產生相關聯的 TTS。
- bagFull : <device(s)> <has/have> <a full bag/full bags>。請 <它/裝置>清空並重試。
- binFull : <device(s)> <has/have> <a full bin/full bins>。
- 碳 MonoideDetected : 系統在 <住家名稱>中偵測到一氧化碳。
- device AtExtremeTemperature : <device(s)> <is/are> 同時 <is/are> 在 <極端溫度/極端溫度> 的情況下。
- deviceJammingDetected : <device(s)> <is/are> jammed.
- device 已移動 : <device(s)> <was/were>搬遷。
- deviceOpen : <device(s)> <is/are> 已開啟。
- deviceTampered : <device(s)> <has/have> 遭到竄改。
- deviceUnplugged : <device(s)> <is/are> 未接上電源。
- 無法連上樓層 : <device(s)> 無法連線至該房間。請將 <it/m> 移至正確的樓層,然後再試一次。
- Hardware Failed : <device(s)> <has/have>硬體發生問題。
- inSoftwareUpdate : <device(s)> <is/are>目前正在進行軟體更新。
- 已略過 :<device(s)> <is/are>目前已略過。
- 低電量 : <device(s)> <has/have> 低電量。
- 動作偵測 : <device(s)> <detect(s)> 動作。
- needPads : <device(s)> <need(s)> new pads.
- needSoftwareUpdate : <device(s)> <need(s)> a Software Update。
- 需要水 : <device(s)> <need(s)> Water。
- networkJammingDetected : 與 <device(s)> 之間的家用網路連線無法正常運作。
- noIssuesReported : <device(s)> 回報沒有任何問題。
- roomOnDifferentFloors : <device(s)>無法移動到這些房間,因為這些裝置位於不同樓層。
- runCycleFinished : <device(s)> <has/have>結束跑步。
- security 限制 : <device(s)> <has/have>安全性限制。
- smokeDetected : 系統在 <house name> 中偵測到煙霧。
- tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>。請填入 <it/them>,然後再試一次。
- 使用 CellularBackup : <device(s)> <is/are>正在使用行動備份功能。
- WaterLeakDetected : <device(s)> <detect(s)> 漏水。