本文档列出了官方支持的智能家居设备错误和例外情况。请在 intent 响应或通知(如果您已实现)中使用这些指定的错误和异常代码,以便 Google 助理提醒最终用户注意与指定命令或设备状态相关的问题。如果响应中包含不正确的格式或 errorCode
,Google 助理会向用户显示一般错误消息,例如“抱歉,设备目前不可用”。
错误
当某个问题导致执行或查询请求失败时,您应该返回错误代码。例如,如果门锁卡住了,无法上锁或解锁,则应向用户返回有关此状态的错误。
您可以在设备级别或全局级别添加错误代码。例如,如果用户有多个来自一个提供商的灯,并且这些灯由 hub 控制,那么当用户要求关闭所有灯时,如果一个灯处于离线状态,该提供商可能会返回设备级错误,或者如果整个 hub 处于离线状态且无法控制任何灯,提供商可能会返回设备级错误。如果所有设备都处于离线状态,使用全局级错误和设备级错误之间没有区别。当设备离线时,即使您返回 deviceOffline
错误代码,也应在 reportState 中报告 {"online": false}
状态。
步骤简述:
- 全局级错误:响应中的所有设备都存在相同的错误
- 局部错误:响应包含错误和成功示例
全局级错误
以下 JSON 代码段展示了如何在 QUERY 或 EXECUTE 响应中返回全局级错误。
由于 hub 离线而导致的全局级错误 deviceOffline
示例:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "deviceOffline", "status" : "ERROR" } }
由 hub 更新导致的全局级错误 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" } } } }
EXECUTE 响应
以下 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。
- aboveMaxLightEffectsDuration : 这超过了 1 小时的最长持续时间。请重试。
- aboveMaxTimerDuration : 我最多只能为 <time period> 设置 <device(s)>
- actionNotAvailable : 抱歉,我目前似乎无法执行该操作。
- actionUnavailablewhileRunning : <device(s)> <is/are> 目前正在运行,因此我无法进行任何更改。
- alreadyArmed : <device(s)> <is/are> 已开启。
- alreadyAtMax : <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> 已锁定。
- 已关闭 : <device(s)> <is/are> 已关闭。
- 已开启 : <device(s)> <is/are> 已开启。
- alreadyOpen : <device(s)> <is/are> 已打开。
- 已暂停 : <device(s)> <is/are> 已暂停。
- 已开始 : <device(s)> <is/are> 已启动。
- 已停止 : <device(s)> <is/are> 已停止。
- alreadyUnlocked : <device(s)> <is/are> 已解锁。
- ambiguousZoneName : 抱歉,<device(s)> 无法识别您指的是哪个可用区。请确保您的区域具有唯一的名称,然后重试。
- amountAboveLimit : 这超过了 <device(s)> 所能支持的范围。
- appLaunchFailed : 很抱歉,未能在 <device(s)> 上启动 <app name>。
- armFailure : 无法开启 <device(s)>。
- armLevelNeeded : 我不确定要将 <device(s)> 设为哪个级别。请试着说“将 <设备> 设为<低安全性>”或“将 <设备> 设为<高安全性>”
- authFailure : 我似乎无法访问 <device(s)>。请尝试检查应用,确保您的 <device/devices> 已完整设置。
- bagFull : <device(s)> <has/have> <a full bag/full bags>。请清空 <it/them>并重试。
- belowMinimumLightEffectsDuration : 这小于最短时长 5 分钟。请重试。
- belowMinimumTimerDuration : 我无法在这么短的时间内设置 <device(s)>。请重试。
- binFull : <device(s)> <has/have> <afull bin/full bins>。
- cancelArmingRestricted : 抱歉,我无法取消开启 <device(s)> 的操作。
- cancelTooLate : 抱歉,已来不及取消。请改用 <device(s)> 或应用。
- channelSwitchFailed : 抱歉,未能切换到 <channel name>频道。请稍后重试。
- chargerIssue : 很抱歉,看起来是 <device(s)> <包含> <a charge issue/charger issues>。
- CommandInsertFailed : 无法处理 <device(s)> 的命令。
- deadBattery : <device(s)> <has/have> <a 已耗尽的电池/已耗尽的电池>。
- degreeOutOfRange : 请求的度数超出了 <device(s)> 的可测量范围。
- deviceAlertNeedsAssistance : <device(s)> <具有>一条有效提醒,<need(s)>您的协助。
- deviceAtExtremeTemperature : <device(s)> <is/are> <an extreme temperature/extreme temperatures>。
- deviceTrueView : 抱歉,<device(s)> 现在好像正在执行某项操作。
- deviceCharging : 抱歉,<device(s)> 似乎无法执行这项操作,因为 (ha_shared.ItsSomere 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)> <未/未>已插入基座。请停靠 <it/them> 并重试。
- deviceNotFound : <device(s)> <is/are> 不可用。您可能需要再次尝试设置 <it/them>。
- deviceNotMounted : 抱歉,<device(s)> 似乎无法执行该操作,因为 <it/them> <is/are>未装载。
- deviceNotReady : <device(s)> <is/are>n't ready.
- deviceStuck : <device(s)> <is/are> 卡住,需要你的帮助。
- deviceTampered : <device(s)> <已被篡改。
- deviceThermalShutdown : 抱歉,<device(s)> 似乎因极端温度而关机。
- directResponseOnlyUnreachable :<device(s)> <不支持远程控制。
- 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)> 上的门已打开已有一段时间。请打开门,确保门里已放好,然后重试。
- EmergencyHeatOn : <设备> <is/are>处于应急热源模式,所以必须手动调整<it/它们>。
- faultyBattery : <device(s)> <has/have> <a faulty battery/faulty Battery>.
- floorUnreachable : <device(s)> 无法进入该房间。请把 <it/them>移到正确的楼层,然后重试。
- functionNotSupported : 实际上,<device(s)> <不/不>支持该功能。
- generalDispenseNotSupported : 我需要知道您想分配什么内容。请使用商品名称重试。
- hardError : 抱歉,出了点问题,我无法控制你的家居设备。
- hardError : 抱歉,出了点问题,我无法控制你的家居设备。
- 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)> <未处于适温模式。
- 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)> <is/are> 目前已锁定。
- lockToRange : 该温度不在 <device(s)> 上的锁定范围内。
- lowBattery : <设备> <电量不足。
- maxSettingReached : <device(s)> <is/are> 已设置为最高设置。
- maxSpeedReached : <device(s)> <is/are> 已设为最高速度。
- minSettingReached : <device(s)> <is/are> 已设置为最低设置。
- minSpeedReached : <device(s)> <is/are> 已设置为最低速度。
- monitoringServiceConnectionLost : <device(s)> <has/has> 与监控服务的连接已断开。
- needAttachment : 抱歉,<device(s)> <is/are> 似乎缺少必需的附件。请更换电池,然后重试。
- needBin : 抱歉,<device(s)> 似乎缺少一个分箱。请更换电池,然后重试。
- needPads : <device(s)> <need(s)> 新垫。
- needSoftwareUpdate : <device(s)> <need(s)> 一项软件更新。
- needWater : <device(s)> <need(s)> water.
- networkProfileNotConfirmd : 抱歉,我在 <device(s)> 上无法识别“<network profile>”。
- networkSpeedTestInProgress : 我已经在测试 <network> <speed/speeds>>。
- noAvailableApp : 很抱歉,<app name> 似乎不可用。
- noAvailableChannel : 抱歉,<channel name>频道似乎无法播放。
- noChannelSubscription : 抱歉,您当前未订阅<channel name>频道。
- noTimerExists : 抱歉,<device(s)> 上似乎未设置任何计时器。
- notSupported : 抱歉,<device(s)>无法使用该模式。
- obstructionDetected : <device(s)> 检测到障碍物。
- 离线, deviceOffline : 抱歉,<device(s)> 现在似乎无法使用。
- onRequireMode : 请指定要开启的模式。
- 口令不正确 : 很抱歉,该 PIN 码似乎不正确。
- percentOutOfRange : 抱歉,无法将 <device(s)> 设置为 <percent>。
- pinIncorrect : (passphraseIncorrect)
- rainDetected : 我没有打开 <device(s)>,因为检测到雨。
- rangeTooClose : 对于 <设备> 的适温范围而言,它们太接近了。请将温差范围调大一些。
- 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/them>。
- sceneCannotBeApplied : 抱歉,无法应用 <device(s)>。
- securityRestriction : <device(s)> <具有>一项安全限制。
- SoftwareUpdateNotAvailable : 抱歉,<device(s)> 上没有可用软件更新。
- startRequireTime : 为此,你需要告诉我你希望运行 <device(s)> 多长时间。
- tillCoolingDown : <device(s)> <is/are> 仍在冷却。
- tillWarmingUp : <device(s)> <is/are>仍在预热。
- streamUnavailable : 抱歉,<device(s)> 上似乎无法播放此视频流。
- streamUnplayable : 抱歉,我目前无法播放来自 <device(s)> 的信息流。
- tankEmpty : <device(s)> <has/have> <an empty tank/Empty tanks>。请填充 <it/them> 并重试。
- targetAlreadyReached : 抱歉,当前温度好像已经到了。
- timeValueOutOfRange : 无法针对该时长设置 <device(s)>。
- Too ManyFailedAttempts : 抱歉,失败的尝试过多。请前往设备的应用中完成这项操作。
- transientError : 抱歉,控制 <device(s)> 时出了点问题。请重试。
- 已关闭 ,deviceTurnedOff : <设备> <当前>已关闭。
- cannotToLocateDevice : 我无法定位 <device(s)>。
- unknownFoodPreset : <device(s)> 不支持该食物预设。
- unlockFailure : 无法解锁 <device(s)>。
- unpausableState : 目前无法暂停 <device(s)>。
- userCancelled : ok
- valueOutOfRange : 无法将 <device(s)> 设置为该温度。
例外情况
当出现与命令相关的问题或提醒时,您应返回异常。命令可能会成功或失败。
如果命令成功(状态 = "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)
以下示例展示了如何开启安防系统:好的,开启安防系统。前窗开着。
{ "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>。请清空 <it/them>并重试。
- binFull : <device(s)> <has/have> <afull bin/full bins>。
- 检测到一氧化碳 : 在 <房屋名称>中检测到一氧化碳。
- deviceAtExtremeTemperature : <device(s)> <is/are> <an extreme temperature/extreme temperatures>。
- deviceJammingDetected : <device(s)> <is/are> 卡住了。
- deviceMoved : <device(s)> <之前已移动>。
- deviceOpen : <device(s)> <is/are> open.
- deviceTampered : <device(s)> <已被篡改。
- deviceUnplugged : <device(s)> <is/are> 已拔出。
- floorUnreachable : <device(s)> 无法进入该房间。请把 <it/them>移到正确的楼层,然后重试。
- hardwareFailure : <device(s)> <存在>硬件问题。
- inSoftwareUpdate : <device(s)> <is/are> 目前正在进行软件更新。
- isBypassed : <device(s)> <is/are> 目前已绕过。
- lowBattery : <设备> <电量不足。
- motionDetected : <device(s)> <detect(s)> 动作。
- needPads : <device(s)> <need(s)> 新垫。
- needSoftwareUpdate : <device(s)> <need(s)> 一项软件更新。
- needWater : <device(s)> <need(s)> water.
- networkJammingDetected : 与 <device(s)> 的家庭网络连接不正常。
- noIssuesReported : <device(s)> 未报告任何问题。
- roomOnDifferentFloors : <device(s)> 无法进入这些房间,因为它们位于不同的楼层。
- runCycleFinished : <device(s)> <has/have> 已完成运行。
- securityRestriction : <device(s)> <具有>一项安全限制。
- smokeDetected : 在 <房子名称>中检测到烟雾。
- tankEmpty : <device(s)> <has/have> <an empty tank/Empty tanks>。请填充 <it/them> 并重试。
- usingCellularBackup : <device(s)> <is/are> 使用备用移动网络。
- waterLeakDetected : <device(s)> <detect(s)> 漏水。