В этом документе перечислены официально поддерживаемые ошибки и исключения для устройств умного дома. Пожалуйста, используйте эти коды ошибок и исключений в ответе о намерениях или в уведомлениях , если вы их реализовали, чтобы Google Assistant предупреждал конечных пользователей о проблемах, связанных с данной командой или состоянием устройства. Если ответ содержит неправильное форматирование или errorCode
, Google Assistant выдает пользователям стандартное сообщение об ошибке, например: «Извините, устройство сейчас недоступно».
Ошибки
Вы должны вернуть код ошибки, когда проблема приводит к сбою запроса на выполнение или запрос. Например, если дверной замок заедает и не может быть заперт или отперт, пользователю должна быть возвращена ошибка об этом состоянии.
Коды ошибок могут быть прикреплены на уровне устройства или на глобальном уровне. Например, если у пользователя есть много источников света от одного провайдера и они контролируются концентратором, когда пользователь просит выключить все их источники света, провайдер может вернуть ошибку на уровне устройства, если один источник света отключен, или глобальный -уровня ошибка, если весь их хаб отключен и никакие источники света не могут управляться. Если все устройства отключены, нет никакой разницы между использованием ошибок глобального уровня или уровня устройства. Когда устройство находится в автономном режиме, вы должны сообщать о состоянии {"online": false}
в reportState , даже если вы возвращаете код ошибки deviceOffline
.
В итоге:
- Ошибка глобального уровня: все устройства в ответе имеют одинаковую ошибку
- Ошибка локального уровня: смешанный ответ с ошибками и успешными случаями
Ошибки глобального уровня
В следующем фрагменте кода 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" } }
Ошибки на уровне устройства
ЗАПРОС ответ
В следующем фрагменте 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 на устройстве.
- вышеMaximumLightEffectsDuration : это больше, чем максимальная продолжительность в 1 час. Пожалуйста, попробуйте еще раз.
- вышеMaximumTimerDuration : я могу установить <устройства> только до <периода времени>
- actionNotAvailable : Извините, я не могу сделать это прямо сейчас.
- actionUnavailableWhileRunning : <устройство(а)> <является/являются> запущенными в данный момент, поэтому я не могу внести какие-либо изменения.
- уже Armed : <устройство(а)> <есть/являются> уже поставлено на охрану.
- ужеAtMax : <устройство(а)> <есть/являются> уже настроены на максимальную температуру.
- ужеAtMin : <устройство(а)> <есть/являются> уже настроены на минимальную температуру.
- уже закрыто : <устройство(а)> <является/являются> уже закрытыми.
- уже Disarmed : <устройство(а)> <есть/являются> уже снято с охраны.
- уже пристыкован : <устройство(а)> <есть/есть> уже пристыковано.
- ужеInState : <устройство(а)> <находится/находятся> уже в этом состоянии.
- уже заблокировано : <устройство(а)> <заблокировано/являются> уже заблокированными.
- ужеOff : <устройство(а)> <есть/являются> уже выключено.
- уже On : <устройство(а)> <есть/являются> уже включено.
- ужеOpen : <устройство(а)> <является/являются> уже открытыми.
- ужеPaused : <устройство(а)> <есть/являются> уже приостановлено.
- ужеStarted : <устройство(а)> <есть/являются> уже запущенными.
- ужеStopped : <устройства> <есть/есть> уже остановлены.
- уже разблокировано : <устройства> <есть/являются> уже разблокированными.
- ambiguousZoneName : извините, <device(s)> не может определить, какую зону вы имеете в виду. Убедитесь, что ваши зоны имеют уникальные имена, и повторите попытку.
- amountAboveLimit : Это больше, чем может поддерживать <device(s)>.
- appLaunchFailed : извините, не удалось запустить <имя приложения> на <устройствах>.
- armFailure : <устройство(а)> не может быть поставлено на охрану.
- armLevelNeeded : я не уверен, какой уровень установить для <device(s)>. Попробуйте сказать «Установите для <устройства> <низкий уровень безопасности>» или «Установите для <устройства> <высокий уровень безопасности>».
- authFailure : я не могу подключиться к <устройствам>. Попробуйте проверить приложение, чтобы убедиться, что ваше <device/devices> <is/are> полностью настроено.
- bagFull : <устройство(а)> <имеет/есть> <полная сумка/полные сумки>. Пожалуйста, очистите <it/them> и повторите попытку.
- нижеMinimumLightEffectsDuration : меньше минимальной продолжительности в 5 минут. Пожалуйста, попробуйте еще раз.
- нижеMinimumTimerDuration : я не могу установить <устройства> на такое короткое время. Пожалуйста, попробуйте еще раз.
- binFull : <устройство(а)> <имеет/есть> <полная корзина/полные корзины>.
- cancelArmingRestricted : Извините, мне не удалось отменить постановку <устройства> на охрану.
- cancelTooLate : Извините, уже слишком поздно для отмены. Вместо этого используйте <устройства> или приложение.
- channelSwitchFailed : Извините, не удалось переключиться на канал <название канала>. Пожалуйста, повторите попытку позже.
- chargeIssue : Извините, это выглядит как <устройство(а)> <имеет/есть> <проблема с зарядным устройством/проблемы с зарядным устройством>.
- commandInsertFailed : невозможно обработать команды для <устройства>.
- deadBattery : <устройство(а)> <имеет/есть> <разряженная батарея/разряженные батареи>.
- DegreeOutOfRange : запрошенные градусы выходят за пределы допустимого диапазона для <устройства(ов)>.
- deviceAlertNeedsAssistance : <устройство(а)> <имеет/имеет> активное оповещение и <нуждается(а)> в вашей помощи.
- deviceAtExtremeTemperature : <устройство(а)> <находится/находятся> при <экстремальной температуре/экстремальных температурах>.
- deviceBusy : Извините, похоже, что <device(s)> уже что-то делает прямо сейчас.
- deviceCharging : Извините, похоже, что <device(s)> не может этого сделать, потому что (ha_shared.Its Theyre size=$item.devices.total_device_count) заряжается.
- deviceClogged : Извините, похоже <устройство(а)> засорено.
- deviceCurrentlyDispensing : <device(s)> уже что-то раздает прямо сейчас.
- deviceDoorOpen : Дверь открыта на <устройстве(ах)>. Пожалуйста, закройте его и повторите попытку.
- deviceHandleClosed : дескриптор закрыт на <устройствах>. Пожалуйста, откройте его и повторите попытку.
- deviceJammingDetected : <устройство(я)> <заблокировано/являются>.
- deviceLidOpen : крышка открыта на <устройстве(ах)>. Пожалуйста, закройте его и повторите попытку.
- deviceNeedsRepair : <устройство(я)> <требуется(и)> для ремонта. Обратитесь к местному дилеру по обслуживанию.
- deviceNotDocked : Извините, похоже, что <устройство(а)> <не/не> пристыковано. Пожалуйста, закрепите <это/их> и повторите попытку.
- deviceNotFound : <устройство(а)> <является/являются> недоступными. Возможно, вы захотите снова настроить <это/их>.
- deviceNotMounted : извините, похоже, что <устройства> не могут этого сделать, потому что <оно/они> не смонтированы.
- deviceNotReady : <устройство(а)> <есть/не>не готовы.
- deviceStuck : <устройство(а)> <застряло/застряли> и нуждается в вашей помощи.
- deviceTampered : <устройство(а)> <было/было> подделано.
- deviceThermalShutdown : Извините, похоже, <устройства> отключены из-за экстремальных температур.
- directResponseOnlyUnreachable : <устройство(а)> <не поддерживает/не поддерживает удаленное управление.
- disarmFailure : <устройства> не могут быть сняты с охраны.
- discOnlyOpenClose : Извините, <устройство(а)> можно только полностью открыть или закрыть.
- дозироватьAmountAboveLimit : <устройство(а)> не может выдать такое большое количество.
- disposeAmountBelowLimit : <устройство(а)> не может дозировать такое небольшое количество.
- dispensAmountRemainingExceeded : <device(s)> не имеет достаточного количества <dispense item> для этого.
- dispenseFractionalAmountNotSupported : <устройство(а)> не может распределять части <раздаточного предмета>.
- dispenseFractionalUnitNotSupported : <устройство(а)> не поддерживает доли этой единицы для <элемента раздачи>.
- дозироватьUnitNotSupported : <устройство(а)> не поддерживает эту единицу для <раздаточный элемент>.
- doorClosedTooLong : Прошло некоторое время с тех пор, как дверь на <устройстве(ах)> была открыта. Пожалуйста, откройте дверь, убедитесь, что внутри что-то есть, и попробуйте еще раз.
- EmergencyHeatOn : <устройство(а)> <находится/находятся> в режиме аварийного обогрева, поэтому <это/они> придется настраивать вручную.
- faultyBattery : <устройство(а)> <имеет/имеет> <неисправная батарея/неисправные батареи>.
- floorUnreachable : <устройства> не могут подключиться к этой комнате. Пожалуйста, переместите <это/их> на нужный этаж и повторите попытку.
- functionNotSupported : На самом деле, <устройства> <не/не> поддерживают эту функциональность.
- genericDispenseNotSupported : мне нужно знать, что вы хотите раздать. Пожалуйста, попробуйте еще раз с названием элемента.
- hardError : Извините, что-то пошло не так, и я не могу управлять вашим домашним устройством.
- hardError : Извините, что-то пошло не так, и я не могу управлять вашим домашним устройством.
- inAutoMode : <устройство(а)> <является/являются> в данный момент настроено на автоматический режим. Чтобы изменить температуру, вам нужно переключить <это/их> в другой режим.
- inAwayMode : <устройство(а)> <находится/находятся> в данный момент установлено в режим отсутствия. Чтобы управлять термостатом, вам нужно вручную переключить его в домашний режим с помощью приложения Nest на телефоне, планшете или компьютере.
- inDryMode : <устройство(а)> <есть/являются> в настоящее время настроены на сухой режим. Чтобы изменить температуру, вам нужно переключить <это/их> в другой режим.
- inEcoMode : <устройство(а)> <находится/являются> в данный момент настроено на экономичный режим. Чтобы изменить температуру, вам нужно переключить <это/их> в другой режим.
- inFanOnlyMode : <device(s)> <is/are> в настоящее время настроены на режим только вентилятора. Чтобы изменить температуру, вам нужно переключить <это/их> в другой режим.
- inHeatOrCool : <устройство(а)> <находится/не>не в режиме обогрева/охлаждения.
- inHumidifierMode : <устройство(а)> <является/являются> в данный момент настроено на режим увлажнителя. Чтобы изменить температуру, вам нужно переключить <это/их> в другой режим.
- inOffMode : <устройство(а)> <в настоящее время выключено. Чтобы изменить температуру, вам нужно переключить <это/их> в другой режим.
- inPurifierMode : <устройство(а)> <есть/являются> в настоящее время настроены на режим очистки. Чтобы изменить температуру, вам нужно переключить <это/их> в другой режим.
- inSleepMode : <устройство(а)> <находится/находятся> в спящем режиме. Пожалуйста, повторите попытку позже.
- inSoftwareUpdate : <устройство(а)> <находится/находятся> в настоящее время в обновлении программного обеспечения.
- lockFailure : <устройства> не могут быть заблокированы.
- LockedState : <устройство(а)> <заблокировано/являются> в данный момент заблокированными.
- LockedToRange : эта температура находится за пределами заблокированного диапазона на <устройствах>.
- lowBattery : <устройство(а)> <имеет/имеет> низкий заряд батареи.
- maxSettingReached : <устройство(а)> <является/являются> уже установлены на максимальное значение.
- maxSpeedReached : <устройство(а)> <является/являются> уже настроено на максимальную скорость.
- minSettingReached : <устройство(а)> <является/являются> уже настроено на самое низкое значение.
- minSpeedReached : <устройства> <есть/есть> уже установлены на минимальную скорость.
- MonitoringServiceConnectionLost : <устройства> <имели/имели> потеряли <свое/их> соединение со службой мониторинга.
- needAttachment : Извините, похоже, что <device(s)> <is/are> отсутствует необходимое вложение. Пожалуйста, замените его и повторите попытку.
- needBin : Извините, похоже, <device(s)> <is/are> не хватает корзины. Пожалуйста, замените его и повторите попытку.
- needPads : <устройство(я)> <необходимость(и)> новые планшеты.
- needSoftwareUpdate : <устройство(я)> <требуется(я)> обновление программного обеспечения.
- needWater : <устройство(я)> <потребность(я)> вода.
- networkProfileNotRecognized : извините, я не узнаю «<сетевой профиль>» на <устройствах>.
- networkSpeedTestInProgress : я уже тестирую <сеть> <скорость/скорость>>.
- noAvailableApp : Извините, похоже <имя приложения> недоступно.
- noAvailableChannel : Извините, похоже, что канал <название канала> недоступен.
- noChannelSubscription : К сожалению, в данный момент вы не подписаны на канал <название канала>.
- noTimerExists : Извините, похоже, что на <устройстве(ах)> не установлены таймеры.
- notSupported : К сожалению, этот режим недоступен для <устройства>.
- obstructionDetected : <устройство(а)> обнаружило препятствие.
- offline , deviceOffline : Извините, похоже, <устройство(а)> <is/are> сейчас недоступно.
- onRequiresMode : укажите, какой режим вы хотите включить.
- passphraseIncorrect : Извините, похоже, этот PIN-код неверен.
- процентOutOfRange : извините, я не могу установить для <устройства> значение <процент>.
- pinIncorrect : (пароль неправильный)
- rainDetected : я не открывал <устройства>, потому что был обнаружен дождь.
- rangeTooClose : они слишком близки для диапазона Heat-Cool для <device(s)>. Выберите температуры, которые находятся дальше друг от друга.
- relinkRequired : извините, похоже, что-то пошло не так с вашей учетной записью. Воспользуйтесь приложением Google Home или Assistant, чтобы повторно связать <устройства>.
- удаленный сетдисаблед :
- Необязательный параметр
errorCodeReason
-
currentlyArmed
. Извините, поскольку система безопасности уже включена, для внесения изменений необходимо использовать <устройство(а)> или приложение. -
remoteUnlockNotAllowed
— Извините, я не могу удаленно разблокировать <устройства>. -
remoteControlOff
— это действие в настоящее время отключено. Включите удаленное управление на <устройствах> и повторите попытку. -
childSafetyModeActive
— это действие отключено для <устройства>, пока активен детский режим безопасности.
- Необязательный параметр
- roomOnDifferentFloors : <устройства> не могут получить доступ к этим комнатам, поскольку они находятся на разных этажах.
- SafetyShutOff : <устройство(а)> <находится/находятся> в режиме безопасного отключения, поэтому <это/они> придется настраивать вручную.
- sceneCannotBeApplied : извините, <устройства> не могут быть применены.
- securityRestriction : <устройство(а)> <имеет/имеет> ограничение безопасности.
- softwareUpdateNotAvailable : К сожалению, на <устройствах> нет доступных обновлений программного обеспечения.
- startRequiresTime : для этого вам нужно сообщить мне, как долго вы хотите запускать <устройство(а)>.
- StillCoolingDown : <устройство(а)> <есть/есть> все еще остывает.
- StillWarmingUp : <устройства> <есть/есть> все еще прогреваются.
- streamUnavailable : извините, похоже, что поток в настоящее время недоступен с <устройства>.
- streamUnplayable : извините, в данный момент я не могу воспроизвести поток с <устройства>.
- tankEmpty : <устройство(а)> <имеет/есть> <пустой бак/пустые баки>. Пожалуйста, заполните <it/them> и повторите попытку.
- targetAlreadyReached : Извините, похоже, это уже текущая температура.
- timerValueOutOfRange : <устройство(а)> не может быть установлено на этот период времени.
- tooManyFailedAttempts : Извините, слишком много неудачных попыток. Пожалуйста, перейдите в приложение вашего устройства, чтобы выполнить это действие.
- transientError : Извините, что-то пошло не так при управлении <устройствами>. Пожалуйста, попробуйте еще раз.
- TurnOff , deviceTurnedOff : <устройство(а)> <является/являются> выключенными в данный момент.
- failedToLocateDevice : мне не удалось найти <устройство(а)>.
- unknownFoodPreset : <устройство(я)> не поддерживает этот пресет еды.
- unlockFailure : <устройства> не могут быть разблокированы.
- unpausableState : <устройства> не могут быть приостановлены прямо сейчас.
- пользовательОтменено : хорошо
- valueOutOfRange : <устройство(а)> не может быть установлено на эту температуру.
Исключения
Вы должны вернуть исключение, когда есть проблема или предупреждение, связанное с командой. Команда может быть успешной или неудачной.
Если команда выполнена успешно (status = "SUCCESS"), сообщайте об исключениях, используя трейт StatusReport
(для устройств, отличных от целевого), или возвращая соответствующий exceptionCode
(для целевого устройства).
Например, если экран сушилки заполнен, пользователь все еще может запустить свою сушилку, но вы можете предупредить его об этом состоянии. Точно так же, когда у устройства разряжена батарея, которая не разряжена, вы все равно можете выполнить команду, но должны сообщить им, что батарея устройства разряжена.
Если команда завершается сбоем из-за исключений, статус должен быть «ИСКЛЮЧЕНИЯ», и об исключениях следует сообщать с помощью признака 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" } }] } }
Неблокирующее исключение (SUCCESS) о другом устройстве с использованием 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 : <устройство(а)> <имеет/есть> <полная сумка/полные сумки>. Пожалуйста, очистите <it/them> и повторите попытку.
- binFull : <устройство(а)> <имеет/есть> <полная корзина/полные корзины>.
- carbonMonoxidDetected : в <название дома> обнаружен угарный газ.
- deviceAtExtremeTemperature : <устройство(а)> <находится/находятся> при <экстремальной температуре/экстремальных температурах>.
- deviceJammingDetected : <устройство(я)> <заблокировано/являются>.
- deviceMoved : <устройство(а)> <было/было> перемещено.
- deviceOpen : <устройство(а)> <является/являются> открытыми.
- deviceTampered : <устройство(а)> <было/было> подделано.
- deviceUnplugged : <устройство(а)> <является/являются> отключенными.
- floorUnreachable : <устройства> не могут подключиться к этой комнате. Пожалуйста, переместите <это/их> на нужный этаж и повторите попытку.
- hardwareFailure : <устройство(а)> <имеет/имеют> аппаратную проблему.
- inSoftwareUpdate : <устройство(а)> <находится/находятся> в настоящее время в обновлении программного обеспечения.
- isBypassed : <устройство(а)> <является/являются> в данный момент обойденными.
- lowBattery : <устройство(а)> <имеет/имеет> низкий заряд батареи.
- motionDetected : <устройство(я)> <обнаружение(я)> движения.
- needPads : <устройство(я)> <необходимость(и)> новые планшеты.
- needSoftwareUpdate : <устройство(я)> <требуется(я)> обновление программного обеспечения.
- needWater : <устройство(я)> <потребность(я)> вода.
- networkJammingDetected : подключение домашней сети к <устройствам> не работает должным образом.
- noIssuesReported : <устройство(я)> не сообщило о проблемах.
- roomOnDifferentFloors : <устройства> не могут получить доступ к этим комнатам, поскольку они находятся на разных этажах.
- runCycleFinished : <устройство(а)> <имеет/имеет> завершено выполнение.
- securityRestriction : <устройство(а)> <имеет/имеет> ограничение безопасности.
- smokeDetected : В <название дома> обнаружен дым.
- tankEmpty : <устройство(а)> <имеет/есть> <пустой бак/пустые баки>. Пожалуйста, заполните <it/them> и повторите попытку.
- usingCellularBackup : <device(s)> <is/are>, использующие резервное копирование по сотовой сети.
- waterLeakDetected : <device(s)> <detect(s)> утечка воды.
В этом документе перечислены официально поддерживаемые ошибки и исключения для устройств умного дома. Пожалуйста, используйте эти коды ошибок и исключений в ответе о намерениях или в уведомлениях , если вы их реализовали, чтобы Google Assistant предупреждал конечных пользователей о проблемах, связанных с данной командой или состоянием устройства. Если ответ содержит неправильное форматирование или errorCode
, Google Assistant выдает пользователям стандартное сообщение об ошибке, например: «Извините, устройство сейчас недоступно».
Ошибки
Вы должны вернуть код ошибки, когда проблема приводит к сбою запроса на выполнение или запрос. Например, если дверной замок заедает и не может быть заперт или отперт, пользователю должна быть возвращена ошибка об этом состоянии.
Коды ошибок могут быть прикреплены на уровне устройства или на глобальном уровне. Например, если у пользователя есть много источников света от одного провайдера и они контролируются концентратором, когда пользователь просит выключить все их источники света, провайдер может вернуть ошибку на уровне устройства, если один источник света отключен, или глобальный -уровня ошибка, если весь их хаб отключен и никакие источники света не могут управляться. Если все устройства отключены, нет никакой разницы между использованием ошибок глобального уровня или уровня устройства. Когда устройство находится в автономном режиме, вы должны сообщать о состоянии {"online": false}
в reportState , даже если вы возвращаете код ошибки deviceOffline
.
В итоге:
- Ошибка глобального уровня: все устройства в ответе имеют одинаковую ошибку
- Ошибка локального уровня: смешанный ответ с ошибками и успешными случаями
Ошибки глобального уровня
В следующем фрагменте кода 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" } }
Ошибки на уровне устройства
ЗАПРОС ответ
В следующем фрагменте 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 на устройстве.
- вышеMaximumLightEffectsDuration : это больше, чем максимальная продолжительность в 1 час. Пожалуйста, попробуйте еще раз.
- вышеMaximumTimerDuration : я могу установить <устройства> только до <периода времени>
- actionNotAvailable : Извините, я не могу сделать это прямо сейчас.
- actionUnavailableWhileRunning : <устройство(а)> <является/являются> запущенными в данный момент, поэтому я не могу внести какие-либо изменения.
- уже Armed : <устройство(а)> <есть/являются> уже поставлено на охрану.
- ужеAtMax : <устройство(а)> <есть/являются> уже настроены на максимальную температуру.
- ужеAtMin : <устройство(а)> <есть/являются> уже настроены на минимальную температуру.
- уже закрыто : <устройство(а)> <является/являются> уже закрытыми.
- alreadyDisarmed : <device(s)> <is/are> already disarmed.
- alreadyDocked : <device(s)> <is/are> already docked.
- alreadyInState : <device(s)> <is/are> already in that state.
- alreadyLocked : <device(s)> <is/are> already locked.
- alreadyOff : <device(s)> <is/are> already off.
- alreadyOn : <device(s)> <is/are> already on.
- alreadyOpen : <device(s)> <is/are> already open.
- alreadyPaused : <device(s)> <is/are> already paused.
- alreadyStarted : <device(s)> <is/are> already started.
- alreadyStopped : <device(s)> <is/are> already stopped.
- alreadyUnlocked : <device(s)> <is/are> already unlocked.
- ambiguousZoneName : Sorry, <device(s)> can't identify which zone you mean. Please make sure your zones have unique names and try again.
- amountAboveLimit : That's more than what <device(s)> can support.
- appLaunchFailed : Sorry, failed to launch <app name> on <device(s)>.
- armFailure : <device(s)> couldn't be armed.
- armLevelNeeded : I'm not sure which level to set <device(s)> to. Try saying "Set <device(s)> to <low security>" or "Set <device(s)> to <high security>"
- authFailure : I can't seem to reach <device(s)>. Try checking the app to make sure your <device/devices> <is/are> fully set up.
- bagFull : <device(s)> <has/have> <a full bag/full bags>. Please empty <it/them> and try again.
- belowMinimumLightEffectsDuration : That's less than the minimum duration of 5 minutes. Please try again.
- belowMinimumTimerDuration : I can't set <device(s)> for such a short time. Please try again.
- binFull : <device(s)> <has/have> <a full bin/full bins>.
- cancelArmingRestricted : Sorry, I couldn't cancel arming <device(s)>.
- cancelTooLate : Sorry, it's too late to cancel. Use <device(s)> or the app instead.
- channelSwitchFailed : Sorry, failed to switch to channel <channel name>. Please try again later.
- chargerIssue : Sorry, it looks like <device(s)> <has/have> <a charger issue/charger issues>.
- commandInsertFailed : Unable to process commands for <device(s)>.
- deadBattery : <device(s)> <has/have> <a dead battery/dead batteries>.
- degreesOutOfRange : The requested degrees are out of range for <device(s)>.
- deviceAlertNeedsAssistance : <device(s)> <has/have> an active alert and <need(s)> your assistance.
- deviceAtExtremeTemperature : <device(s)> <is/are> at <an extreme temperature/extreme temperatures>.
- deviceBusy : Sorry, it looks like <device(s)> is already doing something right now.
- deviceCharging : Sorry, it looks like <device(s)> can't do that because (ha_shared.ItsTheyre size=$item.devices.total_device_count) charging.
- deviceClogged : Sorry, it looks like <device(s)> is clogged.
- deviceCurrentlyDispensing : <device(s)> is already dispensing something right now.
- deviceDoorOpen : The door is open on <device(s)>. Please close it and try again.
- deviceHandleClosed : The handle is closed on <device(s)>. Please open it and try again.
- deviceJammingDetected : <device(s)> <is/are> jammed.
- deviceLidOpen : The lid is open on <device(s)>. Please close it and try again.
- deviceNeedsRepair : <device(s)> <need(s)> to be repaired. Please contact your local service dealer.
- deviceNotDocked : Sorry, it looks like <device(s)> <isn't/aren't> docked. Please dock <it/them> and try again.
- deviceNotFound : <device(s)> <is/are>n't available. You might want to try setting <it/them> up again.
- deviceNotMounted : Sorry, it looks like <device(s)> can't do that because <it/they> <is/are>n't mounted.
- deviceNotReady : <device(s)> <is/are>n't ready.
- deviceStuck : <device(s)> <is/are> stuck and needs your help.
- deviceTampered : <device(s)> <has/have> been tampered with.
- deviceThermalShutdown : Sorry, it looks like <device(s)> shut down due to extreme temperatures.
- directResponseOnlyUnreachable : <device(s)> <doesn't/don't> support remote control.
- disarmFailure : <device(s)> couldn't be disarmed.
- discreteOnlyOpenClose : Sorry, <device(s)> can only be opened or closed all the way.
- dispenseAmountAboveLimit : <device(s)> can't dispense such a large amount.
- dispenseAmountBelowLimit : <device(s)> can't dispense such a small amount.
- dispenseAmountRemainingExceeded : <device(s)> doesn't have enough <dispense item> to do that.
- dispenseFractionalAmountNotSupported : <device(s)> can't dispense fractions of <dispense item>.
- dispenseFractionalUnitNotSupported : <device(s)> doesn't support fractions of that unit for <dispense item>.
- dispenseUnitNotSupported : <device(s)> doesn't support that unit for <dispense item>.
- doorClosedTooLong : It's been a while since the door on <device(s)> has been opened. Please open the door, make sure there's something inside, and try again.
- emergencyHeatOn : <device(s)> <is/are> in Emergency Heat Mode, so <it/they>'ll have to be adjusted by hand.
- faultyBattery : <device(s)> <has/have> <a faulty battery/faulty batteries>.
- floorUnreachable : <device(s)> can't reach that room. Please move <it/them> to the right floor and try again.
- functionNotSupported : Actually, <device(s)> <doesn't/don't> support that functionality.
- genericDispenseNotSupported : I need to know what you would like to dispense. Please try again with the name of the item.
- hardError : Sorry, something went wrong and I'm unable to control your home device.
- hardError : Sorry, something went wrong and I'm unable to control your home device.
- inAutoMode : <device(s)> <is/are> currently set to auto mode. To change the temperature, you'll need to switch <it/them> to a different mode.
- inAwayMode : <device(s)> <is/are> currently set to away mode. To control your thermostat, you'll need to manually switch it to home mode using the Nest app on a phone, tablet, or computer.
- inDryMode : <device(s)> <is/are> currently set to dry mode. To change the temperature, you'll need to switch <it/them> to a different mode.
- inEcoMode : <device(s)> <is/are> currently set to eco mode. To change the temperature, you'll need to switch <it/them> to a different mode.
- inFanOnlyMode : <device(s)> <is/are> currently set to fan-only mode. To change the temperature, you'll need to switch <it/them> to a different mode.
- inHeatOrCool : <device(s)> <is/are>n't in heat/cool mode.
- inHumidifierMode : <device(s)> <is/are> currently set to humidifier mode. To change the temperature, you'll need to switch <it/them> to a different mode.
- inOffMode : <device(s)> <is/are> currently off. To change the temperature, you'll need to switch <it/them> to a different mode.
- inPurifierMode : <device(s)> <is/are> currently set to purifier mode. To change the temperature, you'll need to switch <it/them> to a different mode.
- inSleepMode : <device(s)> <is/are> in sleep mode. Please try again later.
- inSoftwareUpdate : <device(s)> <is/are> currently in a software update.
- lockFailure : <device(s)> couldn't be locked.
- lockedState : <device(s)> <is/are> currently locked.
- lockedToRange : That temperature is outside the locked range on <device(s)>.
- lowBattery : <device(s)> <has/have> low battery.
- maxSettingReached : <device(s)> <is/are> already set to the highest setting.
- maxSpeedReached : <device(s)> <is/are> already set to the maximum speed.
- minSettingReached : <device(s)> <is/are> already set to the lowest setting.
- minSpeedReached : <device(s)> <is/are> already set to the minimum speed.
- monitoringServiceConnectionLost : <device(s)> <has/have> lost <its/their> connection to the monitoring service.
- needsAttachment : Sorry, it looks like <device(s)> <is/are> missing a required attachment. Please replace it and try again.
- needsBin : Sorry, it looks like <device(s)> <is/are> missing a bin. Please replace it and try again.
- needsPads : <device(s)> <need(s)> new pads.
- needsSoftwareUpdate : <device(s)> <need(s)> a software update.
- needsWater : <device(s)> <need(s)> water.
- networkProfileNotRecognized : Sorry, I don't recognize "<network profile>" on <device(s)>.
- networkSpeedTestInProgress : I'm already testing the <network> <speed/speeds>>.
- noAvailableApp : Sorry, it looks like <app name> isn't available.
- noAvailableChannel : Sorry, it looks like channel <channel name> isn't available.
- noChannelSubscription : Sorry, you aren't subscribed to channel <channel name> at the moment.
- noTimerExists : Sorry, it looks like there aren't any timers set on <device(s)>.
- notSupported : Sorry, that mode isn't available for <device(s)>.
- obstructionDetected : <device(s)> detected an obstruction.
- offline , deviceOffline : Sorry, it looks like <device(s)> <is/are>n't available right now.
- onRequiresMode : Please specify which mode you want to turn on.
- passphraseIncorrect : Sorry, it looks like that PIN is incorrect.
- percentOutOfRange : Sorry, I can't set <device(s)> to <percent>.
- pinIncorrect : (passphraseIncorrect)
- rainDetected : I didn't open <device(s)> because rain was detected.
- rangeTooClose : Those are too close for a Heat-Cool range for <device(s)>. Choose temperatures that are farther apart.
- relinkRequired : Sorry, it looks like something went wrong with your account. Please use your Google Home or Assistant App to re-link <device(s)>.
- remoteSetDisabled :
- Optional parameter
errorCodeReason
-
currentlyArmed
- Sorry, since security is already armed, you need to use <device(s)> or the app to make any changes. -
remoteUnlockNotAllowed
- Sorry, I can't unlock <device(s)> remotely. -
remoteControlOff
- That action is currently disabled. Please enable remote control on <device(s)> and try again. -
childSafetyModeActive
- That action is disabled for <device(s)> while child safety mode is active.
- Optional parameter
- roomsOnDifferentFloors : <device(s)> can't reach those rooms because they're on different floors.
- safetyShutOff : <device(s)> <is/are> in Safety Shut-Off Mode, so <it/they>'ll have to be adjusted by hand.
- sceneCannotBeApplied : Sorry, <device(s)> can't be applied.
- securityRestriction : <device(s)> <has/have> a security restriction.
- softwareUpdateNotAvailable : Sorry, there's no software update available on <device(s)>.
- startRequiresTime : To do that, you'll need to tell me how long you'd like to run <device(s)>.
- stillCoolingDown : <device(s)> <is/are> still cooling down.
- stillWarmingUp : <device(s)> <is/are> still warming up.
- streamUnavailable : Sorry, it looks like the stream is currently unavailable from <device(s)>.
- streamUnplayable : Sorry, I can't play the stream from <device(s)> at the moment.
- tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
- targetAlreadyReached : Sorry, it looks like that's already the current temperature.
- timerValueOutOfRange : <device(s)> can't be set for that amount of time.
- tooManyFailedAttempts : Sorry, too many failed attempts. Please go to your device's app to complete that action.
- transientError : Sorry, something went wrong controlling <device(s)>. Please try again.
- turnedOff , deviceTurnedOff : <device(s)> <is/are> off right now.
- unableToLocateDevice : I wasn't able to locate <device(s)>.
- unknownFoodPreset : <device(s)> doesn't support that food preset.
- unlockFailure : <device(s)> couldn't be unlocked.
- unpausableState : <device(s)> can't be paused right now.
- userCancelled : ok
- valueOutOfRange : <device(s)> can't be set to that temperature.
Exceptions
You should return an exception when there is an issue or alert associated with a command. The command could succeed or fail.
If the command was successful (status = "SUCCESS"), report exceptions using the StatusReport
trait (for devices other than the target), or by returning an appropriate exceptionCode
(for the target device).
For example, if the dryer lint screen is full the user can still start their dryer, but you may want to warn them about this state. Similarly, when a device has a low battery that is not empty, you can still execute a command but should let them know that the device battery is low.
If the command fails due to exceptions, the status should be "EXCEPTIONS", and the exceptions should be reported using the StatusReport
trait.
Non-blocking exception (SUCCESS) about target device
This example is for locking the door:
The front door lock has low battery. Locking the front door.
{ "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" } }] } }
Non-blocking exception (SUCCESS) about another device using StatusReport
This example is for arming a security system: Ok, arming the security system. The front window is open.
{ "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" }] } }] } }
Blocking exception about another device using 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" } ] } } } }
Exception list
The following exceptions will produce the associated TTS on the device.
- bagFull : <device(s)> <has/have> <a full bag/full bags>. Please empty <it/them> and try again.
- binFull : <device(s)> <has/have> <a full bin/full bins>.
- carbonMonoxideDetected : Carbon monoxide has been detected in <house name>.
- deviceAtExtremeTemperature : <device(s)> <is/are> at <an extreme temperature/extreme temperatures>.
- deviceJammingDetected : <device(s)> <is/are> jammed.
- deviceMoved : <device(s)> <was/were> moved.
- deviceOpen : <device(s)> <is/are> open.
- deviceTampered : <device(s)> <has/have> been tampered with.
- deviceUnplugged : <device(s)> <is/are> unplugged.
- floorUnreachable : <device(s)> can't reach that room. Please move <it/them> to the right floor and try again.
- hardwareFailure : <device(s)> <has/have> a hardware problem.
- inSoftwareUpdate : <device(s)> <is/are> currently in a software update.
- isBypassed : <device(s)> <is/are> currently bypassed.
- lowBattery : <device(s)> <has/have> low battery.
- motionDetected : <device(s)> <detect(s)> motion.
- needsPads : <device(s)> <need(s)> new pads.
- needsSoftwareUpdate : <device(s)> <need(s)> a software update.
- needsWater : <device(s)> <need(s)> water.
- networkJammingDetected : the home network connection to <device(s)> isn't working properly.
- noIssuesReported : <device(s)> reported no issues.
- roomsOnDifferentFloors : <device(s)> can't reach those rooms because they're on different floors.
- runCycleFinished : <device(s)> <has/have> finished running.
- securityRestriction : <device(s)> <has/have> a security restriction.
- smokeDetected : Smoke has been detected in <house name>.
- tankEmpty : <device(s)> <has/have> <an empty tank/empty tanks>. Please fill <it/them> and try again.
- usingCellularBackup : <device(s)> <is/are> using cellular backup.
- waterLeakDetected : <device(s)> <detect(s)> a water leak.