Questo documento elenca gli errori e le eccezioni supportati ufficialmente per i dispositivi per la smart home. Utilizza gli errori e i codici di eccezione indicati nella risposta all'intent o nelle notifiche, se l'hai implementata, in modo che l'Assistente Google avvisi gli utenti finali di problemi relativi a un determinato comando o stato del dispositivo. Se la risposta contiene una formattazione errata o errorCode
, l'Assistente Google mostra agli utenti un messaggio di errore generico, ad esempio "Spiacenti, dispositivo non è al momento disponibile".
Errori
Devi restituire un codice di errore quando un problema causa il mancato completamento di una richiesta di esecuzione o di query. Ad esempio, se una serratura della porta è bloccata e non può essere chiusa o aperta, all'utente dovrebbe essere restituito un errore relativo a questo stato.
I codici di errore possono essere associati a livello di dispositivo o a livello globale. Ad esempio, se un utente ha molte luci di un provider e queste sono controllate da un hub, quando l'utente chiede di spegnere tutte le luci, il provider potrebbe restituire un errore a livello di dispositivo se una singola luce è offline o un errore a livello globale se l'intero hub è offline e non è possibile controllare nessuna luce. Se tutti i dispositivi sono offline, non c'è alcuna differenza tra l'utilizzo di errori a livello globale o a livello di dispositivo. Quando un dispositivo è offline, devi 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 casi di errore e casi di successo
Errori a livello globale
Lo snippet JSON riportato di seguito mostra come restituire errori a livello globale nella 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" } }
È in corso l'aggiornamento di un esempio di errore a livello globale inSoftwareUpdate
dovuto all'hub:
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "payload": { "errorCode": "inSoftwareUpdate", "status" : "ERROR" } }
Errori a livello di dispositivo
Risposta QUERY
Lo snippet JSON riportato di seguito mostra come restituire errori a livello di dispositivo nella risposta 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
Lo snippet JSON riportato di seguito mostra come restituire 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
Lo snippet JSON riportato di seguito 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
Lo snippet JSON riportato di seguito 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 il TTS associato sul dispositivo.
- abovemaximumLightEffectsDuration : superiore alla durata massima di 1 ora. Riprova.
- abovemaximumTimerDuration : Posso impostare <device(s)> solo per un massimo di <time period>
- actionNotAvailable : Mi dispiace, non posso farlo al momento.
- actionavailableWhenRunning : <device(s)> <is/are> attualmente in esecuzione, quindi non posso apportare alcuna modifica.
- alreadyArmed : <device(s)> <is/are> già abilitato.
- alreadyAtMax : <device(s)> <is/are> già impostato sulla temperatura massima.
- alreadyAtMin : <device(s)> <is/are> già impostato sulla temperatura minima.
- alreadyClosed : <device(s)> <is/are> already closed.
- alreadyDisarmed : <device(s)> <is/are> già disabilitato.
- Già inserito nel dock : <device(s)> <is/are> già inserito nel dock.
- alreadyInState : <device(s)> <is/are> è già in quello stato.
- già Bloccato : <dispositivo(i)> <è/sono> già bloccato.
- alreadyOff : <device(s)> <is/are> already off.
- alreadyOn : <device(s)> <is/are> already on.
- alreadyOpen : <device(s)> <is/are> already open.
- alreadyPausa : <device(s)> <is/are> già in pausa.
- alreadyStarted : <device(s)> <is/are> already started.
- alreadySSuggested : <device(s)> <is/are> già arrestati.
- alreadySbloccati : <device(s)> <is/are> già sbloccati.
- ambiguousZoneName : Spiacenti, impossibile identificare la zona di <device(s)> in quale zona ti riferisci. Assicurati che le zone abbiano nomi univoci e riprova.
- quantityAboveLimit : Più di quanto possa essere supportato da <device(s)>.
- appLaunch locale : Spiacenti, impossibile avviare <nome app> su <dispositivi>.
- armFailure : Impossibile abilitare <device(s)>.
- armLevelneeded : Non so con certezza su 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> <a full bag/full bag>. Svuota <it/them> e riprova.
- belowminimumLightEffectsDuration : meno della 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 : Spiacenti, non ho potuto annullare l'abilitazione di <device(s)>.
- cancelTooLate : Spiacenti, è troppo tardi per annullare. Usa <device(s)> o l'app.
- channelSwitchImpression : Spiacenti, impossibile passare al canale <nome del canale>. Riprova più tardi.
- caricabatterieProblema : Spiacenti, sembra che <device(s)> <has/have> <a caricabatterie issue/charger issues>.
- comandoInsertImpression : Impossibile elaborare comandi per <device(s)>.
- scaricabatteria : <device(s)> <has/have> <a scarico/batteria scarica>.
- gradiOutOfRange : I gradi richiesti sono fuori intervallo per <device(s)>.
- deviceAlertRequireAssistance : <device(s)> <has/have> un avviso attivo e <need(s)> la tua assistenza.
- deviceAtExtremeTemperature : <device(s)> <is/are> a <una temperatura/temperature estreme>.
- deviceBusy : Mi spiace, sembra che <device(s)> stia già facendo qualcosa in questo momento.
- deviceRicarica : Mi spiace, sembra che <device(s)> non possa farlo perché (ha_shared.Its theyre size=$item.devices.total_device_count) è in carica.
- deviceClogged : Spiacenti, sembra che <device(s)> sia intasato.
- deviceAttualmenteDispensing : <device(s)> sta già erogando qualcosa in questo momento.
- deviceDoorOpen : La porta è aperta su <device(s)>. Chiudila e riprova.
- deviceHandleClosed : La maniglia è chiusa su <device(s)>. Aprila e riprova.
- deviceJammingDetected : <device(s)> <è/sono> bloccati.
- deviceLidOpen : Il coperchio è aperto su <device(s)>. Chiudilo e riprova.
- deviceNeedsRepair : <device(s)> <need(s)> to be riveed. Contatta il tuo rivenditore di assistenza locale.
- deviceNotDocked : Mi dispiace, sembra che <device(s)> <non sia/non sia> inserito nel dock. Aggancia <it/them> e riprova.
- deviceNotFound : <device(s)> <is/are>non disponibile. Prova a riconfigurarli.
- deviceNotMounted : Mi spiace, sembra che <device(s)> non possa farlo perché <it/they> <is/are>non sono montati.
- deviceNotReady : <device(s)> <is/are>n ready.
- deviceStuck : <device(s)> <is/are> si è bloccato e ha bisogno del tuo aiuto.
- deviceTampered : <device(s)> <è/sono> stati manomessi.
- deviceThermalShutdown : Spiacenti, sembra che <device(s)> si sia spento a causa delle temperature estreme.
- directResponseSoloUnreachable : <device(s)> <non/non> supporta il controllo remoto.
- disarmFailure : Impossibile disabilitare <device(s)>.
- discreteOnlyOpenClose : Spiacenti, è possibile aprire o chiudere completamente i <device(s)>.
- dispenseAmountAboveLimit : <device(s)> non può erogare una quantità così grande.
- dispenseAmountBelowLimit : <device(s)> non può erogare una quantità così ridotta.
- dispenseAmountRemainingExceeded : <device(s)> non dispone di <dispense item> sufficiente per eseguire questa operazione.
- dispenseFractionalAmountNotSupported : <device(s)> non può erogare frazioni di <dispense item>.
- dispenseFractionalUnitNotSupported : <device(s)> non supporta frazioni dell'unità per <dispense item>.
- dispenseUnitNotSupported : <device(s)> non supporta quell'unità per <dispense item>.
- doorClosedTooLong : È passato un po' di tempo dall'ultima volta che la porta di <device(s)> è stata aperta. Apri la porta, assicurati che ci sia qualcosa all'interno e riprova.
- emergenzaRiscaldamento : <device(s)> <is/are> in modalità di riscaldamento di emergenza, pertanto <it/they> devono essere regolati manualmente.
- difettosa batteria : <device(s)> <ha/have> <una batteria difettosa/batterie difettose>.
- pianoNon raggiungibile : <device(s)> non può raggiungere quella stanza. Sposta <it/them> sul piano giusto e riprova.
- FunctionsNotSupported : In realtà, <device(s)> <non/non> supporta questa funzionalità.
- genericheDispenseNotSupported : Devo sapere cosa vuoi erogare. Riprova inserendo il nome dell'articolo.
- hardError : Mi dispiace, si è verificato un problema e non riesco a controllare il dispositivo per la casa.
- hardError : Mi dispiace, si è verificato un problema e non riesco a controllare il dispositivo per la casa.
- inAutoMode : <device(s)> <is/are> attualmente impostato sulla modalità automatica. Per cambiare la temperatura devi passare <it/loro > a un'altra modalità.
- inAwayMode : <device(s)> <is/are> attualmente impostato sulla modalità Fuori. Per controllare il termostato, dovrai passare manualmente alla modalità A casa utilizzando l'app Nest su telefono, tablet o computer.
- inDryMode : <device(s)> <is/are> attualmente impostato sulla modalità di deumidificazione. Per cambiare la temperatura devi passare <it/loro > a un'altra modalità.
- inEcoMode : <device(s)> <is/are> attualmente impostato sulla modalità eco. Per cambiare la temperatura devi passare <it/loro > a un'altra modalità.
- inFanOnlyMode : <device(s)> <is/are> attualmente è impostato sulla modalità di sola ventola. Per cambiare la temperatura devi passare <it/loro > a un'altra modalità.
- inCaldoOFreddo : <dispositivo(i)> <è/non è in modalità Caldo/Freddo.
- inHumidifierMode : <device(s)> <is/are> attualmente è impostato sulla modalità umidificatore. Per cambiare la temperatura devi passare <it/loro > a un'altra modalità.
- ModalitàOff : <device(s)> <is/are> attualmente spenti. Per cambiare la temperatura devi passare <it/them > a un'altra modalità.
- inPurifierMode : <device(s)> <is/are> attualmente impostato sulla modalità di purificazione. Per cambiare la temperatura devi passare <it/loro > a un'altra modalità.
- inSleepMode : <device(s)> <is/are> in modalità sonno. Riprova più tardi.
- inSoftwareUpdate : <device(s)> <is/are> attualmente in fase di aggiornamento software.
- lockFailure : Impossibile bloccare <device(s)>.
- lockState : <device(s)> <is/are> attualmente bloccati.
- lockToRange : La temperatura non rientra nell'intervallo bloccato su <device(s)>.
- Batteria in esaurimento : <device(s)> <ha/hanno> la batteria in esaurimento.
- maxSettingReached : <device(s)> <is/are> è già impostato sull'impostazione massima.
- maxSpeedReached : <device(s)> <is/are> è già impostato sulla velocità massima.
- minSettingReached : <device(s)> <is/are> è già impostato sull'impostazione più bassa.
- minSpeedReached : <device(s)> <is/are> è già impostato sulla velocità minima.
- monitoringServiceConnectionLost : <device(s)> <has/have> lost <its/their> connessione al servizio di monitoraggio.
- needAllegato : Spiacenti, sembra che <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)> water.
- networkProfileNotRecognized : Spiacenti, non riconosco "<profilo di rete>" su <device(s)>.
- networkSpeedTestInProgress : Sto già testando <network> <speed/speeds>>.
- noAvailableApp : Spiacenti, sembra che <app name> non sia disponibile.
- noAvailableChannel : Spiacenti, sembra che il canale <nome canale> non sia disponibile.
- noChannelSubscription : Spiacenti, al momento non hai effettuato l'iscrizione al canale <channel name>.
- noTimerExists : Mi spiace, sembra che non ci siano timer impostati su <device(s)>.
- notSupportato : Spiacenti, questa modalità non è disponibile per <device(s)>.
- ostruita : <device(s)> ha rilevato un'ostruzione.
- offline , deviceOffline : Spiacenti, sembra che <device(s)> <is/are>non sia disponibile al momento.
- onRequiresMode : Specifica la modalità che vuoi attivare.
- passphrase errata : Mi spiace, sembra che il PIN non sia corretto.
- percentOutOfRange : Mi dispiace, non posso impostare <device(s)> su <percent>.
- pinrisposta : (passphrase errata)
- rilevamento di pioggia : Non ho aperto <device(s)> perché è stata rilevata pioggia.
- rangeTooClose : Sono troppo vicini per un intervallo Caldo-Freddo per <device(s)>. Scegli temperature più lontane.
- relinkRequired : Spiacenti, sembra che si sia verificato un problema con il tuo account. Usa l'app Google Home o dell'assistente per ricollegare <dispositivi>.
-
remoteSetDisabled
:
- Parametro facoltativo
errorCodeReason
currentlyArmed
- Spiacenti, la sicurezza è già abilitata, devi usare <device(s)> o l'app per apportare modifiche.remoteUnlockNotAllowed
- Mi dispiace, non posso sbloccare <device(s)> da remoto.remoteControlOff
- Al momento questa azione è disattivata. Attiva il controllo remoto sui <dispositivi> e riprova.childSafetyModeActive
- L'azione è disattivata per <dispositivi> quando è attiva la modalità protezione bambini.
- Parametro facoltativo
- roomOnDifferentFloors : <device(s)> non può raggiungere quelle stanze perché si trovano su piani diversi.
- safetyShutOff : <device(s)> <is/are> in modalità di arresto di sicurezza, pertanto <it/they>> devono essere regolati manualmente.
- sceneCannotBeApplied : Spiacenti, non è possibile applicare <device(s)>.
- securityRestriction : <device(s)> <presenta/hanno> una limitazione di sicurezza.
- softwareUpdateNotAvailable : Spiacenti, non sono disponibili aggiornamenti software su <device(s)>.
- startRequiresTime : A tale scopo, devi dirmi per quanto tempo vuoi eseguire <device(s)>.
- stillCoolingDown : <device(s)> <is/are> si sta ancora raffreddando.
- stillWarmingUp : <device(s)> <is/are> è ancora in fase di preparazione.
- streamavailable : Spiacenti, sembra che lo stream non sia al momento disponibile su <device(s)>.
- streamUnplayable : Mi dispiace, non posso riprodurre lo stream da <device(s)> al momento.
- containerVuoto : <device(s)> <has/have> <an empty tank/emptys>. Riempi <it/them> e riprova.
- targetAlreadyReached : Mi dispiace, sembra che questa sia già la temperatura attuale.
- timerValueOutOfRange : Impossibile impostare <device(s)> per questo periodo di tempo.
- to manyfailtents : Spiacenti, sono presenti troppi tentativi non riusciti. Vai all'app del dispositivo per completare l'azione.
- transientError : Spiacenti, si è verificato un problema durante il controllo di <device(s)>. Riprova.
- off , deviceTurnedOff : <device(s)> <is/are> off now.
- allowToLocateDevice : Non ho potuto trovare <device(s)>.
- unknownFoodPreset : <device(s)> non supporta quel programma predefinito per alimenti.
- UnlockFailure : Impossibile sbloccare <device(s)>.
- unpausableState : al momento non è possibile mettere in pausa <device(s)>.
- userAnnullata : ok
- valueOutOfRange : Impossibile impostare <device(s)> su questa temperatura.
Eccezioni
Devi restituire un'eccezione quando si verifica un problema o un avviso associato a un comando. Il comando potrebbe avere esito positivo o negativo.
Se il comando ha avuto esito positivo (status = "SUCCESS"), segnala le eccezioni utilizzando il trait StatusReport
(per i dispositivi diversi dal target) o restituendo un 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. Allo stesso modo, quando la batteria di un dispositivo è in esaurimento, puoi comunque eseguire un comando, ma comunicandogli 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 che non blocca (SUCCESS) sul dispositivo di destinazione
Ecco un esempio per chiudere la serratura della porta:
Batteria della serratura della porta principale in esaurimento. Chiudo 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 che non blocca (SUCCESS) relativa a un altro dispositivo che utilizza StatusReport
Questo esempio riguarda l'abilitazione di un sistema di sicurezza: Ok, sto abilitando il sistema di sicurezza. Il finestrino anteriore è aperto.
{ "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 relativa a un altro dispositivo tramite 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 generano il TTS associato sul dispositivo.
- bagFull : <device(s)> <has/have> <a full bag/full bag>. Svuota <it/them> e riprova.
- binFull : <device(s)> <has/have> <a full bin/full bins>.
- carbonMonoxide Detected : È stato rilevato monossido di carbonio in <nome della casa>.
- deviceAtExtremeTemperature : <device(s)> <is/are> a <una temperatura/temperature estreme>.
- deviceJammingDetected : <device(s)> <è/sono> bloccati.
- deviceMoved : <device(s)> <è stato/sono stati spostati.
- deviceOpen : <device(s)> <is/are> open.
- deviceTampered : <device(s)> <è/sono> stati manomessi.
- deviceUnplugged : <device(s)> <is/are> scollegato.
- pianoNon raggiungibile : <device(s)> non può raggiungere quella stanza. Sposta <it/them> sul piano giusto e riprova.
- hardwareFailure : <device(s)> <ha/ha> un problema hardware.
- inSoftwareUpdate : <device(s)> <is/are> attualmente in fase di aggiornamento software.
- Bypassato : <device(s)> <is/are> attualmente ignorato.
- Batteria in esaurimento : <device(s)> <ha/hanno> la batteria in esaurimento.
- motionDetected : <device(s)> <detect(s)> motion.
- needPads : <device(s)> <need(s)> nuovi pad.
- needSoftwareUpdate : <device(s)> <need(s)> un aggiornamento software.
- needwater : <device(s)> <need(s)> water.
- networkJammingDetected : la connessione della rete di casa a <device(s)> non funziona correttamente.
- noIssuesReported : <device(s)> non ha segnalato problemi.
- roomOnDifferentFloors : <device(s)> non può raggiungere quelle stanze perché si trovano su piani diversi.
- runCycleFinished : Esecuzione di<device(s)> <has/have> terminata.
- securityRestriction : <device(s)> <presenta/hanno> una limitazione di sicurezza.
- Rilevato fumo : È stato rilevato fumo in <nome casa>.
- containerVuoto : <device(s)> <has/have> <an empty tank/emptys>. Riempi <it/them> e riprova.
- utilizzando CellularBackup : <device(s)> <is/are> usando il backup da rete mobile.
- waterLeakDetected : <device(s)> <detect(s)> una perdita d'acqua.