Termostato

Tutti i modelli di Google Nest Thermostat sono supportati nell'API Smart Device Management (SDM). Questi dispositivi restituiscono il tipo di dispositivo TERMOSTATO:

sdm.devices.types.THERMOSTAT

Tratti

Riferimento

I seguenti trait, comandi o eventi sono correlati a questo gruppo:

TrattoDescrizioneComandi
ConnettivitàQuesto trait appartiene a qualsiasi dispositivo con informazioni sulla connettività.
FanQuesto tratto appartiene a qualsiasi dispositivo che ha la capacità di sistema di controllare la ventola.SetTimer
UmiditàQuesto tratto appartiene a qualsiasi dispositivo dotato di un sensore per misurare l'umidità.
InformazioniQuesto trait appartiene a qualsiasi dispositivo per le informazioni relative al dispositivo.
ImpostazioniQuesto trait appartiene a qualsiasi dispositivo per le informazioni sulle impostazioni relative al dispositivo.
TemperaturaQuesto tratto appartiene a qualsiasi dispositivo che dispone di un sensore per misurare la temperatura.
ThermostatEcoQuesto tratto appartiene ai tipi di dispositivi TERMOSTATO che supportano le modalità ECO.SetMode
ThermostatHvacQuesto trait appartiene ai tipi di dispositivi del TERMOSTATO che possono segnalare i dettagli dell'impianto.
ThermostatModeQuesto tratto appartiene ai tipi di dispositivi del TERMOSTATO che supportano diverse modalità del termostato.SetMode
ThermostatTemperatureSetpointQuesto tratto appartiene ai tipi di dispositivi TERMOSTATO che supportano l'impostazione della temperatura ottimale e dell'intervallo di temperatura.SetHeat
SetCool
SetRange

JSON

L'assenza di un trait in una risposta GET indica che il trait o la funzionalità non sono attualmente disponibili per il dispositivo. Per ulteriori informazioni, consulta Tipi di dispositivo.

{
  "type" : "sdm.devices.types.THERMOSTAT",
  "traits" : {
    "sdm.devices.traits.Connectivity" : {
      "status" : "ONLINE"
    },
    "sdm.devices.traits.Fan" : {
      "timerMode" : "ON",
      "timerTimeout" : "2019-05-10T03:22:54Z"
    },
    "sdm.devices.traits.Humidity" : {
      "ambientHumidityPercent" : 35.0
    },
    "sdm.devices.traits.Info" : {
      "customName" : "My device"
    },
    "sdm.devices.traits.Settings" : {
      "temperatureScale" : "CELSIUS"
    },
    "sdm.devices.traits.Temperature" : {
      "ambientTemperatureCelsius" : 23.0
    },
    "sdm.devices.traits.ThermostatEco" : {
      "availableModes" : ["MANUAL_ECO", "OFF"],
      "mode" : "MANUAL_ECO",
      "heatCelsius" : 20.0,
      "coolCelsius" : 22.0
    },
    "sdm.devices.traits.ThermostatHvac" : {
      "status" : "HEATING"
    },
    "sdm.devices.traits.ThermostatMode" : {
      "availableModes" : ["HEAT", "COOL", "HEATCOOL", "OFF"],
      "mode" : "COOL"
    },
    "sdm.devices.traits.ThermostatTemperatureSetpoint" : {
      "heatCelsius" : 20.0,
      "coolCelsius" : 22.0
    }
  }
}

Temperatura e umidità

Per leggere la temperatura ambiente del termostato, utilizza il trait Temperatura . La temperatura ambiente viene misurata sul dispositivo.

Per leggere l'umidità ambientale del termostato, utilizza il traitUmidità . L'umidità ambientale viene misurata sul dispositivo.

Scala di temperatura

Google Nest Thermostat può visualizzare la temperatura in gradi Celsius o Fahrenheit, ma la bilancia non può essere impostata dall'API SDM. Per determinare la scala di temperatura attualmente impostata dall'utente, utilizza il trait Impostazioni .

Cambia modalità

La modalità del termostato è gestita da due diverse caratteristiche: ThermostatMode e ThermostatEco.

Modalità standard

Per cambiare la modalità del termostato in Caldo, RAFFREDDAMENTO o RISCALDAMENTO, usa il comando SetMode del tratto ThermostatMode.

Questo comando può essere utilizzato anche per disattivare la modalità del termostato. Non può essere utilizzato per attivare la modalità Eco.

Ad esempio, per cambiare una delle modalità standard del termostato:

Richiesta

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatMode.SetMode",
  "params" : {
    "mode" : "HEAT"
  }
}

Risposta

{}

Modalità Eco

Per attivare la modalità Eco, usa MANUAL_ECO come modalità con il comando SetMode del trait ThermostatEco:

Richiesta

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatEco.SetMode",
  "params" : {
    "mode" : "MANUAL_ECO"
  }
}

Risposta

{}

Questo comando influisce su altri tratti, in base allo stato attuale della modalità Eco o alle sue modifiche:

  • Se la modalità Eco è disattivata, il termostato passerà all'ultima modalità standard (RISCALDAMENTO, RAFFREDDAMENTO, RISCALDAMENTO o Spento) che era attiva.
  • Se la modalità Eco è MANUAL_ECO:

Modificare i set-point di temperatura

I set-point di temperatura possono essere modificati solo quando il termostato è in modalità CALDO, FREDDO o HEATCOOL e i set-point consentiti corrispondono alla modalità corrente del termostato. I set-point di temperatura non possono essere modificati quando la modalità è disattivata o quando la modalità Eco è impostata su MANUAL_ECO.

Il termostato deve trovarsi nella modalità corrispondente al comando che viene chiamato prima di modificare i set-point di temperatura. Il comando e i campi per modificare i set-point variano a seconda della modalità del termostato.

Ad esempio, per inviare il comando SetHeat, il termostato deve essere prima in modalità Caldo:

Modalità Comando Campo/i
RISCALDAMENTO SetHeat heatCelsius
FREDDO SetCool coolCelsius
RISCALDAMENTO SetRange heatCelsius, coolCelsius

Tieni presente che i comandi del set-point utilizzano solo i gradi Celsius come parametro, anche se Google Nest Thermostat può visualizzare la temperatura in gradi Celsius o Fahrenheit.

Ad esempio, per modificare il set-point della temperatura quando il termostato è in modalità RISCALDAMENTO, utilizza il comando SetHeat del tratto ThermostatTemperatureSetpoint:

Richiesta

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatTemperatureSetpoint.SetHeat",
  "params" : {
    "heatCelsius" : 22.0
  }
}

Risposta

{}

Set-point modalità Eco

I set-point heatCelsius e coolCelsius restituiti dal trait ThermostatEco sono impostati dall'utente e non possono essere modificati tramite l'API SDM.

Accendere o spegnere la ventola

Se il termostato supporta una ventola, usa il comando SetTimer della trait della ventola per attivarla o disattivarla. Quando accendi la ventola, puoi specificare il periodo di tempo in secondi durante il quale vuoi che la ventola rimanga in funzione.

Ad esempio, per accendere la ventola per un'ora:

Richiesta

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.Fan.SetTimer",
  "params" : {
    "timerMode" : "ON",
    "duration" : "3600s"
  }
}

Risposta

{}

Se il campo duration viene omesso, la ventola funzionerà per un tempo predefinito di 15 minuti.

Controllare la connettività del dispositivo

Se il dispositivo non risponde ai comandi o non invia eventi oppure se ricevi errori dall'API relativi al dispositivo, usa la funzionalità Connettività per verificare se la connettività del dispositivo è in stato OFFLINE. Controlla la connessione del dispositivo a Internet e assicurati che il servizio Nest sia attivo.

Se gli eventi sono abilitati, dovresti anche aver ricevuto un evento risorsa che indica che il dispositivo è offline:

Payload

{
  "eventId" : "cf0ad502-481d-402c-b4e5-7b618bf62b7f",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.Connectivity" : {
        "status" : "OFFLINE"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Reazione agli eventi del dispositivo

Qualsiasi modifica al campo di un trait genera un evento. Ad esempio, ricevi il seguente evento resourceUpdate se lo stato di climatizzazione del termostato diventa RISCALDAMENTO:

Payload

{
  "eventId" : "b8ff1058-f4f2-466a-b040-5c875fa922d2",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.ThermostatHvac" : {
        "status" : "HEATING"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Gli eventi vengono attivati per tutti i trait associati a questo tipo di dispositivo. Abilita gli eventi se devi reagire in qualche modo agli eventi nell'ambito di un'integrazione.

Tempistiche degli eventi

Tieni presente che un evento relativo a un cambiamento dello stato della climatizzazione potrebbe non essere inviato contemporaneamente agli eventi relativi a un cambio di modalità del termostato.

Ad esempio, a volte si verifica un ritardo nell'avvio della modalità Riscaldamento o Raffreddamento di un termostato per proteggere l'impianto di climatizzazione. In questo scenario, la modifica della modalità del termostato potrebbe comportare inizialmente l'invio di eventi solo per ThermostatMode e ThermostatTemperatureSetpoint , mentre il ThermostatHvac{/19/}si attiva effettivamente come un evento separato come passaggio successivo.}{20 Se non si verifica alcun ritardo nell'accensione dell'impianto di climatizzazione, tutti e tre gli eventi vengono inviati contemporaneamente.

Errori

In relazione a questo dispositivo, potrebbero essere restituiti i seguenti codici di errore:

Messaggio di errore RPC Risolvere i problemi
Il valore del raffreddamento deve essere maggiore del valore del calore. INVALID_ARGUMENT Assicurati che il campo heatCelsius sia inferiore al campo coolCelsius nel comando.
Comando non consentito nell'attuale modalità termostato. FAILED_PRECONDITION Alcuni modelli di termostato non supportano la modifica della modalità Eco quando la modalità del termostato è disattivata, a seconda del trait ThermostatMode . Prima di cambiare la modalità Eco, è necessario impostare la modalità del termostato in Caldo, Freddo o Caldo.
Ventola del termostato non disponibile. FAILED_PRECONDITION Il termostato non dispone di una funzionalità di ventola. I comandi e i tratti relativi ai fan non possono essere utilizzati per questo dispositivo.
Comando non consentito quando il termostato è in modalità MANUAL_ECO. FAILED_PRECONDITION Il set-point della temperatura non può essere impostato quando il termostato è in modalità Eco manuale.

Consulta la pagina Riferimento sui codici di errore delle API per l'elenco completo dei codici di errore delle API.