本文件列出官方支援的智慧住宅裝置錯誤和例外狀況。請在意圖回應或通知中使用這些指定的錯誤和例外狀況代碼 (如果您已實作此代碼),這樣 Google 助理就能通知使用者特定指令或裝置狀態相關問題。如果回應包含不正確的格式或 errorCode
,Google 助理會為使用者提供一般錯誤訊息,例如「很抱歉,目前尚無法使用 device」。
錯誤
如果問題導致執行或查詢要求失敗,您應傳回錯誤代碼。舉例來說,如果門鎖卡住,無法鎖定或解鎖,則應向使用者傳回有關這個狀態的錯誤訊息。
您可以將錯誤代碼附加至裝置層級或全域層級。舉例來說,如果使用者有多個來自某個供應商的燈具,且這些燈具是由一個供應商控制,當使用者要求關掉所有燈具時,供應器可能會在單燈離線時傳回裝置層級錯誤;如果整個中樞裝置離線且無法控制任何燈具,則可能會傳回全域層級錯誤。如果所有裝置都處於離線狀態,使用全域層級或裝置層級錯誤並無差異。在裝置離線時,即使傳回 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。
- aboveMaximumLightEffectsDuration : 超過了 1 小時的最長時間。請再試一次。
- 超過 maxTimerDuration : 我最多只能設定 <device(s)>,最長 <時間範圍>
- actionNotAvailable : 很抱歉,我目前無法執行這個動作。
- actionUnavailable 執行中 : <device(s)> <is/are> 目前正在執行,因此無法進行任何變更。
- alreadyArmed : <device(s)> <is/are> 已啟動。
- 已經在最大溫度 : <device(s)> <is/are> 已設為最高溫度。
- alreadyAtMin : <device(s)> <is/are> 已設為最低溫度。
- 已關閉 : <device(s)> <is/are> 已關閉。
- 已經解除 : <device(s)> <is/are> 已經解除。
- 已放上座架 : <device(s)> <is/are> 已插上座架。
- alreadyInState : <device(s)> <is/are> 先前已在這個狀態中。
- alreadyLocked : <device(s)> <is/are> 已鎖定。
- alreadyOff : <device(s)> <is/are> 已關閉。
- alreadyOn : <device(s)> <is/are> 已開啟。
- alreadyOpen : <device(s)> <is/are> 已開啟。
- 已暫停 : <device(s)> <is/are> 已暫停。
- 已開始 : <device(s)> <is/are> 已開始。
- 已經停止 : <device(s)> <is/are> 已停止。
- 已解鎖 : <device(s)> <is/are> 已解鎖。
- biguousZoneName : 很抱歉,<device(s)> 無法識別你指定的可用區。請確認各個可用區均有專屬名稱,然後再試一次。
- amountAboveLimit : 這超出了 <device(s)> 的功能。
- appLaunchFailed : 很抱歉,無法在 <device(s)> 上啟動 <應用程式名稱>。
- armFailure : 無法啟動 <device(s)>。
- armLevel 如需 : 我不確定要將 <device(s)> 設為哪個層級。請試著說出「將 <裝置> 設為 <低安全性>」或「將 <裝置> 設為「<高安全性>」
- authFailure : 我無法連線到「<device(s)>」。請查看應用程式,確認 <裝置/裝置> <is/are> 的設定完畢。
- packFull : <device(s)> <擁有/擁有> <滿袋/整袋> 。請將 <it/them>留空,然後再試一次。
- lowLightLightEffectsDuration : 這小於 5 分鐘的最短持續時間。請再試一次。
- 低於 MinimumTimerDuration : 暫時無法設定 <device(s)>,請再試一次。
- binFull :<device(s)> <has/have> <a full bin/full bins>。
- cancelArmingRestricted : 很抱歉,我無法取消啟動 <device(s)> 的轉換動作。
- cancelTooLate : 很抱歉,取消時間已過。請改用 <device(s)> 或應用程式。
- channelSwitchFailed : 很抱歉,無法切換至「<頻道名稱>」頻道,請稍後再試。
- 充電器問題 : 抱歉,看起來像是 <device(s)> <has/have> <a Charge issue/charger issues>。
- commandInsertFailed : 無法處理 <device(s)>的指令。
- deadBattery : <device(s)> <has/have> <a Batterys ird Battery/dead batteries>。
- degreeOutOfRange : 要求的角度超出 <device(s)> 的範圍。
- deviceAlert 需要協助 : <device(s)> <has/擁有> 未解除的快訊,因此 <need(s)>您的協助。
- deviceAtExtremeTemperature : <device(s)> <is/are> 度為 <極端溫度/極端溫度>。
- deviceBusy : 很抱歉,<device(s)> 似乎已在執行其他操作。
- deviceCharging : 很抱歉,<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> 卡住。
- deviceLidOpen : <device(s)> 的機蓋已開啟。請闔上裝置,然後再試一次。
- deviceNeedsRepair : <device(s)> <need(s)> 需要維修。請與您的當地服務經銷商聯絡。
- deviceNotDocked : 很抱歉,<device(s)> 似乎<is't/aren't 已放上座架。請將 <it/them>插入座架,然後再試一次。
- deviceNotFound : <device(s)> <is/are> 無法使用。建議你重新設定 <it/them>。
- deviceNotMounted : 很抱歉,「<device(s)>」似乎無法掛載,因為<it/這些> <is/are>尚未掛載。
- deviceNotReady : <device(s)> <is/are>尚未就緒。
- device 停滯 : <device(s)> <is/are> 停滯不前,需要你的協助。
- deviceTampered : <device(s)> <has/have> 遭竄改
- deviceThermalShutdown : 很抱歉,<device(s)> 因溫度極端而關機。
- directResponseOnlyUnconnected : <device(s)> <doesn't/don'>支援遠端控制系統。
- disarmFailure : <device(s)>無法解除。
- discreteOnlyOpenClose : 很抱歉,<device(s)> 只能完全開啟或關閉。
- dispenseAmountAboveLimit : <device(s)> 無法超量供應。
- dispenseAmountBelowLimit : <device(s)> 無法供應這麼小的量。
- DipenseAmountRemainingExceeded : <device(s)> 的 <dispense item> 不足,該怎麼辦?
- dispenseFractionalAmountNotSupported : <device(s)> 無法分配 <dispense item> 的小數。
- DipenseFractionalUnitNotSupported : <device(s)> 不支援以該單位為單位的 <dispense item>。
- dispenseUnitNotSupported :<device(s)>不支援該單位的 <dispense item>。
- gateClosedTooLong : <device(s)>的車門已經開啟一段時間。請打開車門並確認車內有東西,然後再試一次。
- EmergencyHeatOn : <device(s)> 處於緊急熱源模式,因此<it/這些> 必須手動調整。
- faultyBattery : <device(s)> <具有/有> <電池故障/電池故障>。
- FloUnConnected : <device(s)> 無法到達該房間。請將 <it/them>移至正確的樓層,然後再試一次。
- functionNotSupported : 實際上,<device(s)> <不支援/未> 支援該項功能。
- genericDispenseNotSupported : 我必須瞭解您要供應的類型。請使用商品名稱再試一次。
- HarError : 很抱歉,出了點小狀況,所以我無法控制你的住宅裝置。
- HarError : 很抱歉,出了點小狀況,所以我無法控制你的住宅裝置。
- inAutoMode : <device(s)> <is/are> 目前設為自動模式。如要調整溫度,必須將<it/them>切換為其他模式。
- inAwayMode : <device(s)> <is/are> 目前設為外出模式。如要控制溫度控制器,請使用手機、平板電腦或電腦上的 Nest 應用程式,手動將溫度控制器切換成在家模式。
- inDryMode : <device(s)> <is/are> 目前設為乾燥模式。如要調整溫度,必須將<it/them>切換為其他模式。
- inEcoMode : <device(s)> <is/are> 目前設為節能模式。如要調整溫度,必須將<it/them>切換為其他模式。
- inFanOnlyMode :<device(s)> <is/are>目前設為僅限風扇模式。如要調整溫度,必須將<it/them>切換為其他模式。
- inHeatOrCool : <device(s)> <is/are> 未處於熱/冷模式。
- inHumidifierMode : <device(s)> <is/are> 目前設為加濕器模式。如要調整溫度,必須將<it/them>切換為其他模式。
- inOffMode : <device(s)> <is/are> 目前處於關閉狀態。如要變更溫度,必須將 <it/them> 切換為其他模式。
- inPurifierMode : <device(s)> <is/are> 目前設為淨化模式。如要調整溫度,必須將<it/them>切換為其他模式。
- inSleepMode : 處於睡眠模式時,<device(s)> <is/are>。請稍後再試。
- inSoftwareUpdate : <device(s)> <is/are> 目前正在進行軟體更新。
- LockFailure : 無法鎖定 <device(s)>。
- lockState : <device(s)>目前鎖定中。
- lockToRange : 目前的溫度不在 <device(s)> 的鎖定範圍內。
- 低電量 : <device(s)> <擁有/擁有> 低電量。
- maxSettingReached : <device(s)>已將<is/are>設為最高的設定。
- maxSpeedReached : <device(s)>已設為最高速度。
- minSettingReached : <device(s)> <is/are> 已設為最低值。
- minSpeedReached : <device(s)> <is/are> 已經設為最低速度了。
- monitoringServiceConnection Loss : <device(s)> <has/have> 對監控服務的連線已中斷。
- 需要附件 : 很抱歉, <device(s)> 似乎缺少必要的附件。請更換後再試一次。
- needBin : 很抱歉,<device(s)> <is/are> 似乎缺少集點。請更換後再試一次。
- needPads : <device(s)> <need(s)> 新衛生棉。
- needSoftwareUpdate : <device(s)> <need(s)> 軟體更新。
- needWater : <device(s)> <need(s)>水。
- networkProfileNotReco 已識別 : 很抱歉,我在 <device(s)> 上無法辨識「<網路設定檔>」。
- networkSpeedTestInProgress :我已測試 <network> <speed/speeds>>。
- noAvailableApp : 很抱歉,<應用程式名稱> 似乎無法使用。
- noAvailableChannel : 抱歉,您似乎無法購買「<channel name>」頻道。
- noChannelSubscription : 很抱歉,你目前並未訂閱「<channel name>」頻道。
- noTimerExists : 很抱歉,<device(s)> 上似乎沒有任何設定任何計時器。
- 不支援 : 很抱歉,<device(s)> 不支援這個模式。
- 偵測到障礙物 :<device(s)>偵測到障礙物。
- 離線 , deviceOffline : 很抱歉,<device(s)> 目前無法使用。
- onRequiresMode :請指定你要開啟的模式。
- 通關密語不正確 : 很抱歉,PIN 碼似乎不正確。
- %OutOfRange : 很抱歉,我無法將 <device(s)> 設為 <percent>。
- PIN 碼不正確 :(passphrase 正確)
- rainDetected : 我沒有打開 <device(s)>,因為偵測到雨水。
- rangeTooClose : <device(s)> 的熱冷範圍範圍距離太近。請選擇較大的溫度。
- 重新連結必要 : 很抱歉,您的帳戶似乎發生問題。請透過 Google Home 或 Google 助理應用程式重新連結 <device(s)>。
-
RemoteSetDisabled
:
- 選用參數
errorCodeReason
currentlyArmed
- 很抱歉,安全機制已啟動,你必須使用「<device(s)>」或應用程式才能變更設定。remoteUnlockNotAllowed
- 很抱歉,我無法從遠端解鎖 <device(s)>。remoteControlOff
- 這個動作目前已停用。請在 <device(s)> 上啟用遙控器,然後再試一次。childSafetyModeActive
- 當兒童安全模式啟用時,<device(s)> 就無法執行這項操作。
- 選用參數
- roomOnDifferenceFloors <device(s)> 無法移動到這些房間,因為那些房間位於不同樓層。
- SafetyShutOff : 安全關機模式設為 <device(s)> <is/are>,因此你必須手動調整「<裝置>」<it/>。
- sceneCannotBeApplied : 很抱歉,無法套用 <device(s)>。
- securityRestriction : <device(s)> <具有/擁有>安全性限制。
- SoftwareUpdateNotAvailable : 很抱歉,<device(s)> 沒有可用的軟體更新。
- startRequiresTime : 不過,你必須先告訴我要執行「<device(s)>」的時間長度。
- tillCoolingDown : <device(s)> <is/are>仍在降溫。
- svearmingUp : <device(s)> <is/are>仍在準備中。
- streamUnavailable : 很抱歉,<device(s)> 目前無法串流播放。
- streamUnplayable : 很抱歉,我目前無法播放「<device(s)>」的串流內容。
- tankEmpty : <device(s)> <has/擁有> <空水槽/空水槽>。請填寫 <it/them>,然後再試一次。
- 目標已達成 : 抱歉,目前溫度已經是目前溫度。
- watchValueOutOfRange : <device(s)> 無法在該時間範圍內設定。
- Too ManyFailed Numbers (失敗) :很抱歉,嘗試失敗次數過多。請開啟裝置上的應用程式,完成這項操作。
- transientError : 很抱歉,控制 <device(s)> 時發生錯誤,請再試一次。
- Off , deviceTurnedOff : 目前已關閉<device(s)> <is/are>。
- 找不到「FindDevice」 : 我無法找到 <device(s)> 的位置。
- UnknownFoodPreset : <device(s)> 不支援這項食物預設設定。
- UnlockFailure : 無法解鎖 <device(s)>。
- unpausableState : 目前無法暫停<device(s)>。
- userCancelled : 確定
- valueOutOfRange : <device(s)> 無法設為這個溫度。
例外狀況
當指令發生問題或快訊時,您應傳回例外狀況。指令可能會成功或失敗。
如果指令執行成功 (status = "SUCCESS"),請使用 StatusReport
特徵 (針對目標以外的裝置) 回報例外狀況,或傳回適當的 exceptionCode
(適用於目標裝置)。
舉例來說,如果烘衣機 Lint 畫面滿格,使用者仍可啟動烘衣機,但您可能需要警告使用者此狀態。同樣地,如果裝置的電量較低,且使用的電量偏低,您還是可以執行指令,但應告知對方裝置電量過低。
如果指令因例外狀況而失敗,狀態應為「EXCEPTIONS」,且應使用 StatusReport
特徵回報例外狀況。
符合目標裝置的非封鎖例外狀況 (SUCCESS)
以下示範將門上鎖:
前門門鎖電量不足,正在鎖上前門
{ "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 取得其他裝置的非封鎖例外狀況 (SUCCESS)
以下示範如何啟動保全系統:Ok,正在啟動保全系統。前窗打開了。
{ "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。
- packFull : <device(s)> <擁有/擁有> <滿袋/整袋> 。請將 <it/them>留空,然後再試一次。
- binFull :<device(s)> <has/have> <a full bin/full bins>。
- carbonMonoxideDetected : 在 <house name> 偵測到一氧化碳。
- deviceAtExtremeTemperature : <device(s)> <is/are> 度為 <極端溫度/極端溫度>。
- deviceJammingDetected : <device(s)> <is/are> 卡住。
- deviceMoved : <device(s)> <was/were>已移動。
- deviceOpen : <device(s)> <is/are> 已開啟。
- deviceTampered : <device(s)> <has/have> 遭竄改
- deviceUnplugged : <device(s)> <is/are> 未接上電源。
- FloUnConnected : <device(s)> 無法到達該房間。請將 <it/them>移至正確的樓層,然後再試一次。
- HardwareFailure : <device(s)> <有/擁有>硬體問題。
- inSoftwareUpdate : <device(s)> <is/are> 目前正在進行軟體更新。
- 已略過 : 目前已略過<device(s)> <is/are>。
- 低電量 : <device(s)> <擁有/擁有> 低電量。
- MotionDetected : <device(s)> <detect(s)>動作。
- needPads : <device(s)> <need(s)> 新衛生棉。
- needSoftwareUpdate : <device(s)> <need(s)> 軟體更新。
- needWater : <device(s)> <need(s)>水。
- networkJammingDetected : 連至 <device(s)> 的家用網路連線無法正常運作。
- noIssuesReported : <device(s)> 未回報任何問題。
- roomOnDifferenceFloors <device(s)> 無法移動到這些房間,因為那些房間位於不同樓層。
- runCycleFinished : <device(s)> <搭載> 已執行完畢。
- securityRestriction : <device(s)> <具有/擁有>安全性限制。
- 煙霧偵測 : 系統在 <house name> 中偵測到煙霧。
- tankEmpty : <device(s)> <has/擁有> <空水槽/空水槽>。請填寫 <it/them>,然後再試一次。
- usingCellularBackup : <device(s)> <is/are> 正在使用行動備份功能。
- WaterLeakDetected : <device(s)> <detect(s)>漏水。