本文档列出了智能家居设备正式支持的错误和异常。请在 intent 响应中或通知(如果实现了该功能)中使用这些给定的错误和异常代码,以便 Google 助理提醒最终用户注意与给定命令或设备状态相关的问题。如果响应包含不正确的格式或 errorCode
,Google 助理会为用户提供一条通用错误消息,例如“抱歉,设备目前无法使用”。
错误
当某个问题导致执行或查询请求失败时,您应该返回错误代码。例如,如果门锁卡住而无法锁定或解锁,则应向用户返回关于此状态的错误。
错误代码可在设备级别或全局级别添加。例如,如果用户有许多来自一个提供方的灯,并且它们由 hub 控制,则当用户要求关闭所有灯时,提供程序可以在单个灯处于离线状态时返回设备级错误,或者在整个 hub 处于离线状态并且无法控制任何灯时返回全局级错误。如果所有设备都处于离线状态,则使用全局级错误或设备级错误没有任何区别。当设备离线时,您应返回 reportState 中的 {"online": false}
状态,即使返回 deviceOffline
错误代码也是如此。
总结:
- 全局级错误:响应中的所有设备都有相同的错误
- 本地级错误:混合响应与错误和成功案例
全局级错误
以下 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。
- AboveMaximumLightEffectsDuration : 超出 1 小时的最长时长。请重试。
- AboveMaximumTimeoutDuration : 我只能设置 <device(s)>,最长不超过 <time time>
- actionNotAvailable : 抱歉,我现在好像无法这样做。
- actionUnavailable 娜 Running : <device(s)> <is/are> 目前正在运行,所以我不能进行任何更改。
- 已启用 Armed : <device(s)> <is/are> 已开启。
- atAtMax : <device(s)> <is/are> 已经设为最高温度。
- atAtMin : <device(s)> <is/are> 已设为最低温度。
- 已关闭 : <device(s)> <is/are> has already close.
- 已关闭警报 : <device(s)> <is/are> 已关闭警报。
- 已插入基座 : <device(s)> <is/are> 已插入基座。
- alreadyInState : <device(s)> <is/are> 已处于该状态。
- 已锁定 : <device(s)> <is/are> 已锁定。
- 已开启 : <device(s)> <is/are> 已关闭。
- 已开启 : <device(s)> <is/are> 已开启。
- 已打开 : <device(s)> <is/are>已开启。
- AlreadyPaused : <device(s)> <is/are> already paused.
- 已经开始 : <device(s)> <is/are> 已经开始。
- 已停止 : <device(s)> <is/are>已停止。
- 已解锁 : <device(s)> <is/are> 已经解锁。
- ambiguousZoneName : 抱歉,<device(s)> 无法识别您要找的可用区。请确保您的可用区具有唯一名称,然后重试。
- amountAboveLimit :这超出了 <device(s)> 支持的范围。
- appLaunchFailed : 抱歉,无法在“<device(s)>”上启动 <app name>。
- armFailure : <device(s)> 无法开启。
- armLevelNeeded : 我不确定将<device(s)> 设置为哪个级别。试着说“将 <设备(s)> 设为<低安全性>”或“将 <设备(s)> 设置为<高安全性>”
- authFailure : 我似乎无法访问 <device(s)>。请尝试检查应用,确保您的 <device/devices> 已完全设置。
- bagFull : <device(s)> <has/has> <a full bag/full bags>. please empty <it/them> and try again.
- minimumMinimumLightEffectsDuration : 这少于 5 分钟的最短时长。请重试。
- minimumMinimum 计时器时长 : 我无法设置这么短的时间<device(s)>。请重试。
- binFull : <device(s)> <has/has> <a full bin/full bins>.
- cancelArmingRestricted : 抱歉,我无法取消开启<device(s)>。
- CancelTooLate : 抱歉,为时已晚,无法取消。请改用 <device(s)> 或应用。
- channelSwitchFailed : 抱歉,未能切换到 <channel name>。请稍后再试。
- 充电器问题 : 抱歉,好像有 <device(s)> <has/has> <a 充电器问题/充电器问题>。
- CommandInsertFailed : 无法处理 <device(s)> 的命令。
- DeadBattery : <device(s)> <has/has> <dadBattery/dad Batterys>。
- degreesOutOfRange : 请求的角度超出 <device(s)> 的范围。
- DeviceAlertNeedsAssistance : <device(s)> <has/has> 已启用的警报和 <need(s)> 您的帮助。
- deviceAtExtremeTemperature : <设备
- deviceBusy : 抱歉,<device(s)> 似乎已在执行某些操作。
- deviceCharging : 抱歉,<device(s)> 似乎无法执行这项操作,因为 (ha_shared.ItsItre size=$item.devices.total_device_count) 正在充电。
- deviceClogged : 抱歉,<device(s)> 似乎是卡住的。
- deviceCurrentlyDispensing : <device(s)> 目前正在进行分配。
- deviceDoorOpen : 门在 <device>上打开。请关好门,然后重试。
- deviceHandleClosed : 手柄已在 <device(s)> 上关闭。请打开它并重试。
- deviceJammingDetected :<device(s)> <is/are> 卡住。
- deviceLidOpen : 盖子在 <device(s)> 上打开。请关上盖子,然后重试。
- deviceNeedsRepair :待修复的 <device(s)> <need(s)>。请联系你的当地服务经销商。
- deviceNotDocked : 抱歉,似乎 <device(s)> <isn't/arentt> 已插入基座。请将 <it/them> 停靠,然后重试。
- deviceNotFound :<device(s)> <is/are> 不可用。您可能需要重新设置 <it/them>。
- deviceNotMounted : 抱歉,<device(s)> 似乎无法执行该操作,因为 <it/它们> <is/are>未装载。
- deviceNotReady : <device(s)> <is/are>n.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 :在紧急供暖模式下,<device(s)> <is/are>,因此必须手动调整<it/它们>。
- faultyBattery : <device(s)> <has/has> <a ult 电池/电池故障>。
- floorUnreachable : <device(s)> 无法进入该房间。请将 <it/them> 移到正确的楼层,然后重试。
- functionNotSupported : 实际上,<device(s)> <不/不{2}支持该功能。
- generalDispenseNotSupported : 我需要知道您要分发的内容。请使用商品名称重试。
- 硬性错误 : 抱歉,出了点问题,我无法控制你的家居设备。
- 硬性错误 : 抱歉,出了点问题,我无法控制你的家居设备。
- 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>n’t in hot/cool mode.
- 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)> 无法锁定。
- 锁定状态 : <设备(s)> <is/are> 目前锁定。
- LockToRange : 该温度不在 <device(s)> 的锁定范围内。
- lowBattery : <device(s)> <has/has> 电池电量低。
- 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> 与监控服务断开了 <it/her> 连接。
- need 附件 : 抱歉,<device(s)> <is/are> 缺少必需的附件。请先更换它,然后重试。
- needBin : 抱歉,似乎 <device(s)> <is/are> 缺少箱。请先更换它,然后重试。
- needPads : <device(s)> <need(s)> new pad。
- needSoftwareUpdate : <device(s)> <need(s)> 软件更新。
- needWater : <device(s)> <need(s)> water.
- networkProfileNotRecognized : 抱歉,我无法识别<device(s)>上的“<network profile>”。
- networkSpeedTestInProgress : 我已经在测试 <network> <speed/speeds>>。
- noAvailableApp : 抱歉,<app name> 似乎不可用。
- noAvailableChannel : 抱歉,似乎 <channel name> 不可用。
- noChannelSubscription : 抱歉,您目前没有订阅<channel name>。
- noTimingExists : 抱歉,似乎 <device(s)> 上没有设置任何计时器。
- 不支持 : 抱歉,<device(s)> 无法使用该模式。
- obstructionDetected : <device(s)> 检测到障碍物。
- 离线 ,设备离线 : 抱歉,目前似乎无法使用 <device(s)> <is/are>。
- onRequiresMode : 请指定要开启的模式。
- passwordsIncorrect : 抱歉,PIN 码似乎不正确。
- percentageOutOfRange : 抱歉,无法将 <device(s)> 设置为 <percent>。
- PIN 不正确 : (passphraseIncorrect)
- rainDetected : 我没有打开 <device(s)>,因为系统检测到雨。
- rangeTooClose : 对于 <device(s)> 来说,这些温度过高并无法实现适温范围。请选择相距较远的温度。
- relinkRequired : 抱歉,您的帐号似乎出现问题。请使用 Google Home 或 Google 助理应用重新关联 <设备>。
-
remoteSetDisabled
:
- 可选参数
errorCodeReason
currentlyArmed
- 抱歉,由于安防系统已开启,您需要使用 <设备>或应用进行更改。remoteUnlockNotAllowed
- 抱歉,我没法远程解锁<device>。remoteControlOff
- 该操作目前处于停用状态。请在 <device(s)> 上启用遥控器,然后重试。childSafetyModeActive
- 当儿童安全模式处于活动状态时,<device(s)> 会停用该操作。
- 可选参数
- roomOnDifferenceFloors : <device(s)> 无法访问这些房间,因为它们位于不同的楼层。
- safetyShutOff : <device(s)> <is/are> 处于安全关机模式,因此<it/它们>必须手动调整。
- sceneCannotBeApply : 抱歉,无法应用 <device(s)>。
- securityRestriction : <device(s)> <has/has> 安全限制。
- SoftwareUpdateNotAvailable : 抱歉,<device(s)> 上没有软件更新。
- startRequiresTime : 为此,您需要告诉我您想要运行 <device(s)> 多长时间。
- tillCoolingDown :<device(s)> <is/are> 仍在冷却。
- tillWarmingUp :<device(s)> <is/are> 仍在预热。
- streamUnavailable : 抱歉,目前好像无法通过 <device(s)> 获取数据流。
- streamUnplayable : 抱歉,我目前无法播放来自 <device(s)> 的视频流。
- tankEmpty : <device(s)> <has/has> <an empty 坦克/空水箱>。请填写 <it/them> 并重试。
- targetAlreadyReached : 抱歉,这似乎是当前温度。
- timeValueOutOfRange :无法在 该时间段内设置 <device(s)>。
- tooManyFailedFaileds : 抱歉,尝试失败的次数过多。请转到设备的应用中完成这项操作。
- transientError : 抱歉,控制 <device(s)> 时出错。请重试。
- turnOff , deviceTurnedOff : <device(s)> <is/are> 现已关闭。
- unableToLocateDevice : 我找不到 <device(s)>。
- unFoodPreset : <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/has> <a full bag/full bags>. please empty <it/them> and try again.
- binFull : <device(s)> <has/has> <a full bin/full bins>.
- carbonMonoxideDetected : 在 <house name>中检测到一氧化碳。
- deviceAtExtremeTemperature : <设备
- deviceJammingDetected :<device(s)> <is/are> 卡住。
- deviceMoved : <device(s)> <was/were> 已移动。
- deviceOpen : <device(s)> <is/are> open.
- deviceTampered : <device(s)> <已经/被篡改。
- deviceUnplugged : <device(s)> <is/are> 已拔出。
- floorUnreachable : <device(s)> 无法进入该房间。请将 <it/them> 移到正确的楼层,然后重试。
- hardwareFailure : <device(s)> <has/has> 硬件问题。
- inSoftwareUpdate : <device(s)> <is/are> 目前正在进行软件更新。
- isBypassed : <device(s)> <is/are> 目前绕过。
- lowBattery : <device(s)> <has/has> 电池电量低。
- motionDetected : <device(s)> <detect(s)> motion。
- needPads : <device(s)> <need(s)> new pad。
- needSoftwareUpdate : <device(s)> <need(s)> 软件更新。
- needWater : <device(s)> <need(s)> water.
- networkJammingDetected : 到 <device(s)> 的家庭网络连接无法正常工作。
- noIssuesReported : <device(s)> 未报告任何问题。
- roomOnDifferenceFloors : <device(s)> 无法访问这些房间,因为它们位于不同的楼层。
- runCycleFinished : <device(s)> <has/has> finished running.
- securityRestriction : <device(s)> <has/has> 安全限制。
- smokeDetected : 在 <house name>中检测到烟雾。
- tankEmpty : <device(s)> <has/has> <an empty 坦克/空水箱>。请填写 <it/them> 并重试。
- UsingCellularBackup : <device(s)> <is/are> 使用移动网络备份。
- waterLeakDetected : <device(s)> <detect(s)> 漏水。