Questo documento elenca gli errori e le eccezioni ufficialmente supportati per i dispositivi
per la smart home. Utilizza questi codici di errore ed eccezioni nella risposta di intent o nelle notifiche, se li hai implementati, in modo che l'Assistente Google avvisi gli utenti finali in caso di problemi relativi a un determinato comando o stato del dispositivo. Se la risposta contiene una formattazione errata o errorCode
, l'Assistente Google visualizza agli utenti un messaggio di errore generico, ad esempio: "Spiacenti, dispositivo non è disponibile al momento".
Errori
Dovresti restituire un codice di errore quando un problema causa la mancata riuscita di una richiesta di esecuzione o di una query. Ad esempio, se una serratura è bloccata e non può essere chiusa o aperta, l'utente deve restituire un errore relativo a questo stato.
I codici di errore possono essere allegati a livello di dispositivo o a livello globale. Ad esempio,
se un utente ha molte luci di un fornitore e questo è controllato da un hub, quando
l'utente chiede di spegnere tutte le luci, il fornitore potrebbe restituire un
errore a livello di dispositivo se una singola luce è offline oppure un errore a livello globale se
l'intero hub è offline e non è possibile controllare le luci. Se tutti i dispositivi sono offline, non esiste alcuna differenza tra l'utilizzo di errori a livello globale o di dispositivo. Quando un dispositivo è offline, dovresti segnalare lo stato {"online": false}
in
reportState anche se restituisci il
codice di errore deviceOffline
.
In sintesi:
- Errore a livello globale: tutti i dispositivi nella risposta hanno lo stesso errore
- Errore a livello locale: risposta mista con errori e casi di successo
Errori a livello globale
Il seguente snippet JSON mostra come restituire errori a livello globale in una risposta QUERY o EXECUTE.
Un esempio di errore a livello globale deviceOffline
dovuto all'hub è offline:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "deviceOffline", "status" : "ERROR" } }
Un esempio di errore a livello globale inSoftwareUpdate
dovuto all'hub viene
aggiornato:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "inSoftwareUpdate", "status" : "ERROR" } }
Errori a livello di dispositivo
Risposta di QUERY
Il seguente snippet JSON mostra come restituire errori a livello di dispositivo nella risposta di QUERY.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "devices": { "device-id-1": { "errorCode": "deviceOffline", "status" : "ERROR" }, "device-id-2": { "errorCode": "deviceOffline", "status" : "ERROR" } } } }
ESEGUI risposta
Il seguente snippet JSON mostra come restituire gli errori a livello di dispositivo nella risposta 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 } } ] } }
Notifiche con errori
Notifica proattiva
Il seguente snippet JSON mostra come segnalare gli errori a livello di dispositivo in una notifica proattiva.
{ "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" } } } } } }
Risposta di follow-up
Il seguente snippet JSON mostra come segnalare errori a livello di dispositivo in una risposta di follow-up.
{ "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" } } } } } } }
Elenco di errori
I seguenti errori produrranno la sintesi vocale associata sul dispositivo.
- aboveMaxLightEffectsDuration : Supera la durata massima di 1 ora. Riprova.
- aboveMaxTimerDuration : Posso impostare <device(s)> solo per un massimo di <time period>
- actionNotAvailable : Mi dispiace, non riesco a farlo al momento.
- actionUnavailableWhenRunning : <device(s)> <è/sono> attualmente in esecuzione, quindi non posso apportare modifiche.
- già abilitato : <device(s)> <is/are> è già abilitato.
- giàAtMax : <device(s)> <is/are> è già impostato sulla temperatura massima.
- giàAtMin : <device(s)> <is/are> è già impostato sulla temperatura minima.
- già chiusi : <device(s)> <è/sono> già chiusi.
- già disarmato : <device(s)> <è/sono> già disabilitato.
- già agganciato alla base : <device(s)> <è/sono> già agganciato alla base.
- giàInState : <device(s)> <is/are> è già in quello stato.
- già bloccata : <device(s)> <is/are> è già bloccato.
- giàOff : <device(s)> <è/sono> già spenti.
- giàOn : <device(s)> <è/sono> già accesi.
- già aperti : <device(s)> <è/are> già aperti.
- già in pausa : <device(s)> <is/are> è già in pausa.
- già avviato : <device(s)> <is/are> è già avviato.
- già arrestato : <device(s)> <is/are> è già arrestato.
- già sbloccato : <device(s)> <is/are> è già sbloccato.
- ambiguousZoneName : Spiacenti, <device(s)> non riesce a identificare la zona interessata. Assicurati che le zone abbiano nomi univoci e riprova.
- amountAboveLimit : È più di quanto può supportare <device(s)>.
- appLaunchFailed : Spiacenti, non è stato possibile avviare <app name> su <device(s)>.
- armFailure : Impossibile abilitare <device(s)>.
- armLevelNeeded : Non so a quale livello impostare <device(s)>. Prova a dire "Imposta <dispositivi> su <sicurezza bassa>" o "Imposta <dispositivi> su <sicurezza alta>"
- authFailure : Non riesco a raggiungere <device(s)>. Prova a controllare l'app per assicurarti che <device/devices> <is/are> sia completamente configurato.
- bagFull : <device(s)> <has/have> <un bagaglio pieno/borse piene>. Svuota <it/them> e riprova.
- belowminimumLightEffectsDuration : È inferiore alla durata minima di 5 minuti. Riprova.
- belowminimumTimerDuration : Non riesco a impostare <device(s)> per un periodo di tempo così breve. Riprova.
- binFull : <device(s)> <has/have> <a full bin/full bins>.
- cancelArmingRestricted : Mi dispiace, non è stato possibile annullare l'abilitazione di <device(s)>.
- cancelTooLate : Spiacenti, è troppo tardi per annullare. Usa invece <device(s)> o l'app.
- channelSwitchFailed : Spiacenti, impossibile passare al canale <channel name>. Riprova più tardi.
- problema al caricabatterie : Spiacenti, sembra che <device(s)> <ha/hanno> <un problema con il caricabatterie/un problema con il caricabatterie>.
- commandInsertFailed : Impossibile elaborare i comandi per <device(s)>.
- Batteria scarica : <device(s)> <ha/hanno> <una batteria scarica/batterie scariche>.
- gradiOutOfRange : I gradi richiesti sono fuori intervallo per <device(s)>.
- deviceAlertAlertanceance : <device(s)> <ha/hanno> un avviso attivo e <need(s)> la tua assistenza.
- deviceAtExtremeTemperature : <device(s)> <è/sono> a <una temperatura estrema/temperature estreme>.
- deviceBusy : Spiacenti, sembra che <device(s)> stia già facendo qualcosa in questo momento.
- deviceCharging : Mi dispiace, sembra che <device(s)> non possa farlo perché è in carica (ha_shared.ItsYesre size=$item.devices.total_device_count).
- deviceClogged : Spiacenti, sembra che <device(s)> sia intasato.
- deviceCurrentDispensing : <device(s)> sta già erogando qualcosa.
- deviceDoorOpen : La porta è aperta su <device(s)>. Chiudila e riprova.
- deviceHandleClosed : L'handle è chiuso su <device(s)>. Aprilo e riprova.
- deviceJammingDetected : <device(s)> <è/are> ha rilevato un jamming.
- deviceLidOpen : Il coperchio è aperto su <device(s)>. Chiudilo e riprova.
- deviceRichiedeRepair : <device(s)> <need(s)> da riparare. Contatta il tuo rivenditore di assistenza locale.
- deviceNotDocked : Spiacenti, sembra che <device(s)> <isn't/aren't> sia agganciato alla base. Aggancia <it/them> alla base e riprova.
- deviceNotFound : <device(s)> <è/are>non disponibile. Potresti provare a configurare di nuovo <it/them>.
- deviceNotMounted : Spiacenti, sembra che <device(s)> non possa farlo perché <it/they> <is/are>non è montato.
- deviceNotReady : <device(s)> <is/are>non è pronto.
- deviceStuck : <device(s)> <è/sono> bloccato e ha bisogno del tuo aiuto.
- dispositivo manomesso : <device(s)> <ha/sono> stati manomessi.
- deviceThermalShutdown : Spiacenti, sembra che <device(s)> si sia arrestato a causa di temperature estreme.
- directResponseOnlyUnreachable : <device(s)> <non supporta/non supporta il controllo remoto.
- disarmFailure : Impossibile disabilitare <device(s)>.
- discreteOnlyOpenClose : Spiacenti, <device(s)> può essere solo aperto o chiuso completamente.
- dispenseAmountAboveLimit : <device(s)> non può erogare una quantità così elevata.
- dispenseAmount belowLimit : <device(s)> non può erogare una quantità così ridotta.
- dispenseAmountottingExceeded : <device(s)> non dispone di <dispense item> sufficiente per farlo.
- dispenseFractionalAmountNotSupported : <device(s)> non può distribuire frazioni di <dispense item>.
- dispenseFractionalUnitNotSupported : <device(s)> non supporta frazioni di quell'unità per <dispense item>.
- dispenseUnitNotSupported : <device(s)> non supporta tale unità per <dispense item>.
- doorClosedTooLong : È passato un po' di tempo dall'apertura della porta di <device(s)>. Apri la porta, assicurati che ci sia qualcosa all'interno e riprova.
- emergenzeHeatOn : <device(s)> <è/sono> in modalità di riscaldamento di emergenza, quindi <it/they> dovranno essere regolati manualmente.
- Batteria difettosa : <device(s)> <ha/hanno> <una batteria difettosa/batterie difettose>.
- floorUnreachable : <device(s)> non può raggiungere quella stanza. Sposta <it/them> al piano giusto e riprova.
- functionNotSupported : In realtà, <device(s)> <non/non> supporta questa funzionalità.
- generalDispenseNotSupported : Devo sapere cosa vuoi distribuire. Riprova indicando il nome dell'elemento.
- hardError : Mi dispiace, si è verificato un problema e non riesco a controllare il tuo dispositivo per la casa.
- hardError : Mi dispiace, si è verificato un problema e non riesco a controllare il tuo dispositivo per la casa.
- inAutoMode : <device(s)> <è/sono> attualmente impostato sulla modalità automatica. Per cambiare la temperatura, devi passare <it/them > a un'altra modalità.
- inAwayMode : <device(s)> <è/sono> attualmente impostati sulla modalità Assenza. Per controllare il termostato, devi passare manualmente alla modalità A casa utilizzando l'app Nest su smartphone, tablet o computer.
- inDryMode : <device(s)> <è/sono> attualmente impostato sulla modalità di deumidificazione. Per cambiare la temperatura, devi passare <it/them > a un'altra modalità.
- inEcoMode : <device(s)> <is/are> è attualmente impostato sulla modalità Eco. Per cambiare la temperatura, devi passare <it/them > a un'altra modalità.
- inFanOnlyMode : <device(s)> <is/are> è attualmente impostato sulla modalità di sola ventola. Per cambiare la temperatura, devi passare <it/them > a un'altra modalità.
- inHeatOrCool : <device(s)> <è/sono>non in modalità Caldo • Freddo.
- inHumidifierMode : <device(s)> <is/are> è attualmente impostato sulla modalità umidificatore. Per cambiare la temperatura, devi passare <it/them > a un'altra modalità.
- inOffMode : <device(s)> <è/sono> attualmente spenti. Per cambiare la temperatura devi passare <it/them > a un'altra modalità.
- inPurifierMode : <device(s)> <è/sono> attualmente impostati sulla modalità di purificazione. Per cambiare la temperatura, devi passare <it/them > a un'altra modalità.
- inSleepMode : <device(s)> <è/sono> in modalità di sospensione. Riprova più tardi.
- inSoftwareUpdate : <device(s)> <è/sono> attualmente in fase di aggiornamento software.
- LockFailure : Impossibile bloccare <device(s)>.
- lockState : <device(s)> <è/are> attualmente bloccato.
- restrictedToRange : La temperatura è al di fuori dell'intervallo bloccato su <device(s)>.
- Batteria bassa : <device(s)> <ha/have>> batteria in esaurimento.
- maxSettingReached : <device(s)> <is/are> è già impostato sull'impostazione più alta.
- maxSpeedReached : <device(s)> <is/are> è già impostato alla velocità massima.
- minSettingReached : <device(s)> <is/are> è già impostato sul valore più basso.
- minSpeedReached : <device(s)> <is/are> è già impostato alla velocità minima.
- MonitoringServiceConnectionLost : <device(s)> <ha/hanno> perso <its/their> la connessione al servizio di monitoraggio.
- needAttachment : Spiacenti, sembra che in <device(s)> <is/are> manchi un allegato obbligatorio. Sostituiscila e riprova.
- needBin : Spiacenti, sembra che <device(s)> <is/are> manchi un contenitore. Sostituiscila e riprova.
- needPads : <device(s)> <need(s)> nuovi pad.
- needSoftwareUpdate : <device(s)> <need(s)> un aggiornamento software.
- needWater : <device(s)> <need(s)> acqua.
- networkProfileNotIdentifid : Spiacenti, non riconosco "<profilo di rete>" su <dispositivi>.
- networkSpeedTestInProgress : Sto già testando <network> <speed/speeds>>.
- noAvailableApp : Spiacenti, sembra che <app name> non sia disponibile.
- noAvailableChannel : Spiacenti, sembra che il canale <channel name> non è disponibile.
- noChannelSubscription : Spiacenti, non hai effettuato l'iscrizione al canale <channel name> al momento.
- noTimerExists : Spiacenti, sembra che non ci siano timer impostati su <device(s)>.
- notSupported : Spiacenti, questa modalità non è disponibile per <device(s)>.
- ostruzione rilevata : <device(s)> ha rilevato un'ostruzione.
- offline , deviceOffline : Spiacenti, sembra che <device(s)> <is/are>non sia disponibile al momento.
- onRequestsMode : Specifica la modalità che vuoi attivare.
- Passphrase errata : Spiacenti, sembra che il PIN non sia corretto.
- percentOutOfRange : Mi dispiace, non posso impostare <device(s)> su <percent>.
- pinerrato : (passphrase verificata)
- pioggia rilevata : Non ho aperto <device(s)> perché è stata rilevata pioggia.
- Intervallo troppo vicino : Questi valori sono troppo vicini per un intervallo Caldo-Freddo per <device(s)>. Scegli temperature più distanziate.
- relinkRequired : Spiacenti, sembra che si sia verificato un problema con il tuo account. Usa l'app Google Home o dell'assistente per ricollegare <device(s)>.
-
remoteSetDisabled
:
- Parametro facoltativo
errorCodeReason
currentlyArmed
- Spiacenti, la sicurezza è già abilitata, devi utilizzare <device(s)> o l'app per apportare le modifiche.remoteUnlockNotAllowed
- Mi dispiace, non posso sbloccare <device(s)> da remoto.remoteControlOff
- Questa azione è attualmente disattivata. Attiva il controllo remoto su <device(s)> e riprova.childSafetyModeActive
- Questa azione è disattivata per <device(s)> mentre è attiva la modalità di protezione bambini.
- Parametro facoltativo
- roomOnDiversiFloors : <device(s)> non può raggiungere queste stanze perché si trovano su piani diversi.
- safetyShutOff : <device(s)> <è/sono> in modalità di arresto di sicurezza, quindi <it/they> dovrà essere regolato a mano.
- sceneCannotBeApplied : Spiacenti, impossibile applicare <device(s)>.
- securityRestriction : <device(s)> <ha/have> una limitazione di sicurezza.
- softwareUpdateNotAvailable : Spiacenti, non ci sono aggiornamenti software disponibili su <device(s)>.
- startRequestsTime : Per farlo, devi dirmi per quanto tempo vuoi eseguire <device(s)>.
- ancoraRaffreddamento : <device(s)> <è/sono ancora in fase di raffreddamento.
- ancora in fase di riscaldamento : <device(s)> <è/si sta ancora riscaldando.
- streamUnavailable : Spiacenti, sembra che lo stream non sia al momento disponibile da <device(s)>.
- streamUnplayable : Mi dispiace, al momento non posso riprodurre lo stream da <device(s)>.
- tankEmpty : <device(s)> <has/have> <un serbatoio vuoto/serbatoi vuoti>. Riempi <it/them> e riprova.
- targetAlreadyReached : Spiacenti, sembra che quella sia già la temperatura attuale.
- timerValueOutOfRange : Non è possibile impostare <device(s)> per questo periodo di tempo.
- too ManyFailed eventualmente : Spiacenti, sono stati effettuati troppi tentativi non riusciti. Vai all'app del dispositivo per completare l'azione.
- transitorientError : Spiacenti, si è verificato un problema durante il controllo di <device(s)>. Riprova.
- spento , deviceTurnedOff : <device(s)> <è/sono> spenti al momento.
- cannotToLocateDevice : Non ho potuto individuare <device(s)>.
- sconosciutoFoodPreset : <device(s)> non supporta quella preimpostazione per alimenti.
- UnlockFailure : Impossibile sbloccare <device(s)>.
- unpausableState : al momento non è possibile mettere in pausa <device(s)>.
- userAnnullato : ok
- valueOutOfRange : Impossibile impostare <device(s)> su quella temperatura.
Eccezioni
Dovresti restituire un'eccezione quando esiste un problema o un avviso associato a un comando. Il comando potrebbe avere esito positivo o negativo.
Se il comando ha avuto esito positivo (stato = "SUCCESS"), segnala eccezioni
utilizzando il trait StatusReport
(per dispositivi diversi da quello di destinazione)
o restituendo un valore exceptionCode
appropriato (per il dispositivo di destinazione).
Ad esempio, se la schermata di pelucchi dell'asciugatrice è piena, l'utente può comunque avviare l'asciugatrice, ma potresti volerlo avvisare di questo stato. Analogamente, quando la batteria di un dispositivo è in esaurimento e non è scarica, puoi comunque eseguire un comando, ma devi comunicare al cliente che la batteria del dispositivo è in esaurimento.
Se il comando non riesce a causa di eccezioni, lo stato dovrebbe essere "EXCEPTIONS"
e le eccezioni devono essere segnalate utilizzando il trait StatusReport
.
Eccezione non bloccante (SUCCESS) per il dispositivo di destinazione
Questo esempio riguarda la chiusura della porta:
La batteria della serratura della porta principale è in esaurimento. Chiudo a chiave la porta d'ingresso.
{ "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" } }] } }
Eccezione non blocco (SUCCESS) relativa a un altro dispositivo che utilizza StatusReport
Questo esempio si riferisce all'abilitazione di un sistema di sicurezza: Ok, abilita il sistema di sicurezza. La finestra anteriore è aperta.
{ "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" }] } }] } }
Blocco dell'eccezione per un altro dispositivo che utilizza 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" } ] } } } }
Elenco delle eccezioni
Le seguenti eccezioni produrranno la sintesi vocale associata sul dispositivo.
- bagFull : <device(s)> <has/have> <un bagaglio pieno/borse piene>. Svuota <it/them> e riprova.
- binFull : <device(s)> <has/have> <a full bin/full bins>.
- carbonMonoxideDetected : È stato rilevato monossido di carbonio in <house name>.
- deviceAtExtremeTemperature : <device(s)> <è/sono> a <una temperatura estrema/temperature estreme>.
- deviceJammingDetected : <device(s)> <è/are> ha rilevato un jamming.
- dispositivo spostato : <device(s)> <è/sono stati> spostati.
- dispositivo aperto : <device(s)> <è/sono> aperti.
- dispositivo manomesso : <device(s)> <ha/sono> stati manomessi.
- dispositivo scollegato : <device(s)> <è/sono> scollegati.
- floorUnreachable : <device(s)> non può raggiungere quella stanza. Sposta <it/them> al piano giusto e riprova.
- Guasto hardware : <device(s)> <ha/have> un problema hardware.
- inSoftwareUpdate : <device(s)> <è/sono> attualmente in fase di aggiornamento software.
- Bypassato : <device(s)> <è/sono> attualmente bypassato.
- Batteria bassa : <device(s)> <ha/have>> batteria in esaurimento.
- movimento rilevato : <device(s)> <detect(s)> movimento.
- needPads : <device(s)> <need(s)> nuovi pad.
- needSoftwareUpdate : <device(s)> <need(s)> un aggiornamento software.
- needWater : <device(s)> <need(s)> acqua.
- networkJammingDetected : la connessione della rete di casa a <device(s)> non funziona correttamente.
- noIssuesReported : <device(s)> non ha segnalato problemi.
- roomOnDiversiFloors : <device(s)> non può raggiungere queste stanze perché si trovano su piani diversi.
- runCycleFinished : <device(s)> <has/have> terminato.
- securityRestriction : <device(s)> <ha/have> una limitazione di sicurezza.
- fumo rilevato : È stato rilevato fumo in <nome della casa>.
- tankEmpty : <device(s)> <has/have> <un serbatoio vuoto/serbatoi vuoti>. Riempi <it/them> e riprova.
- conCellularBackup : <device(s)> <is/are> sta utilizzando il backup da rete mobile.
- waterLeakDetected : <device(s)> <detect(s)> una perdita d'acqua.