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 tratti, comandi o eventi sono correlati a questo gruppo:

TrattoDescrizioneComandi
ConnettivitàQuesta caratteristica appartiene a qualsiasi dispositivo che disponga di informazioni sulla connettività.
VentolaQuesta caratteristica appartiene a qualsiasi dispositivo in grado di controllare la ventola.SetTimer
UmiditàQuesta caratteristica appartiene a qualsiasi dispositivo dotato di un sensore per misurare l'umidità.
InformazioniQuesto tratto appartiene a qualsiasi dispositivo per informazioni correlate al dispositivo.
ImpostazioniQuesto tratto appartiene a qualsiasi dispositivo per le informazioni sulle impostazioni relative al dispositivo.
TemperaturaQuesta caratteristica appartiene a qualsiasi dispositivo dotato di un sensore per misurare la temperatura.
ThermostatEcoQuesta caratteristica appartiene ai tipi di dispositivo TERMOSTATO che supportano le modalità ECO.SetMode
ThermostatHvacQuesto tratto appartiene ai tipi di dispositivi TERMOSTATO che possono segnalare i dettagli dell'impianto di climatizzazione.
ThermostatModeQuesto tratto appartiene ai tipi di dispositivi TERMOSTATO che supportano diverse modalità del termostato.SetMode
ThermostatTemperatureSetpointQuesta caratteristica appartiene ai tipi di dispositivi TERMOSTATO che supportano l'impostazione della temperatura target e dell'intervallo di temperatura.SetHeat
SetCool
SetRange

JSON

L'assenza di un tratto in una risposta GET indica che il tratto o la funzionalità non è attualmente disponibile per il dispositivo. Per ulteriori informazioni, consulta Tipi di dispositivi.

{
  "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 l'attributo Temperatura . La temperatura ambiente viene misurata sul dispositivo.

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

Scala di temperatura

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

Cambiare modalità

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

Modalità standard

Per impostare la modalità del termostato su HEAT, COOL o HEATCOOL, utilizza il comando SetMode del tratto ThermostatMode.

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

Ad esempio, per modificare 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, utilizza MANUAL_ECO come modalità con il comando SetMode del tratto 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 altre caratteristiche, in base allo stato attuale o alle modifiche alla modalità Eco:

  • Se la modalità Eco è disattivata, la modalità del termostato verrà impostata per impostazione predefinita sull'ultima modalità standard (CALDO, FREDDO, CALDO • FREDDO o SPENTO) attiva.
  • Se la modalità Eco è MANUAL_ECO:

Modificare i setpoint di temperatura

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

Prima di modificare i setpoint di temperatura, il termostato deve essere nella modalità corrispondente al comando chiamato. Il comando e i campi per modificare i set-point variano in base alla modalità del termostato.

Ad esempio, per eseguire il comando SetHeat, il termostato deve essere prima in modalità HEAT:

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

Tieni presente che i comandi di setpoint accettano solo 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 di temperatura quando il termostato è in modalità HEAT, 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

{}

Setpoint della modalità Eco

I setpoint heatCelsius e coolCelsius restituiti dalla caratteristica ThermostatEco sono impostati dall'utente e non possono essere modificati tramite l'API SDM.

Attivare o disattivare la ventola

Se il termostato supporta una ventola, utilizza il comando SetTimer del tratto Ventola per accenderla o spegnerla. Quando la accendi, puoi specificare la durata di funzionamento della ventola in secondi.

Ad esempio, per far funzionare 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 periodo di tempo predefinito di 15 minuti.

Controllare la connettività del dispositivo

Se il dispositivo non risponde ai comandi o non invia eventi oppure ricevi errori dall'API relativi al dispositivo, utilizza il tratto Connettività per controllare la connettività del dispositivo per uno stato OFFLINE. Controlla la connessione a internet del dispositivo e assicurati che il servizio Nest sia attivo.

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

Payload

{
  "eventId" : "31a9759c-21a6-47d7-acbc-8e854f1000a7",
  "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"
  ]
}

Reagire agli eventi del dispositivo

Qualsiasi modifica a un campo caratteristica genera un evento. Ad esempio, riceverai il seguente evento resourceUpdate se lo stato dell'impianto HVAC del termostato è cambiato in HEATING:

Payload

{
  "eventId" : "20388ec2-1a03-4eba-b2fc-aa30616108be",
  "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 tutte le caratteristiche associate a questo tipo di dispositivo. Attiva gli eventi se devi reagire in qualche modo nell'ambito di un'integrazione.

Tempi degli eventi

Tieni presente che un evento per una modifica dello stato dell'impianto HVAC potrebbe non essere inviato contemporaneamente agli eventi per una modifica della modalità del termostato.

Ad esempio, a volte si verifica un ritardo nell'avvio della modalità di riscaldamento o raffreddamento di un termostato per proteggere l'impianto HVAC. In questo scenario, la modifica della modalità del termostato potrebbe inizialmente inviare eventi solo per le modifiche delle caratteristiche ThermostatMode e ThermostatTemperatureSetpoint , mentre la modifica della caratteristica ThermostatHvac viene inviata in un secondo momento come evento separato una volta che l'impianto si accende. Se non ci fosse stato alcun ritardo nell'accensione dell'impianto di climatizzazione, tutti e tre gli eventi sarebbero stati inviati contemporaneamente.

Errori

Per questo dispositivo potrebbero essere restituiti i seguenti codici di errore:

Messaggio di errore RPC Risoluzione dei problemi
Il valore di raffreddamento deve essere maggiore del valore di riscaldamento. INVALID_ARGUMENT Assicurati che il campo heatCelsius sia inferiore al campo coolCelsius nel comando.
Il comando non è consentito nella modalità termostato attuale. FAILED_PRECONDITION Alcuni modelli di termostato non supportano la modifica della modalità Eco quando la modalità termostato è OFF, in base all'attributo ThermostatMode . Prima di modificare la modalità Eco, la modalità del termostato deve essere impostata su HEAT, COOL o HEATCOOL.
Ventola del termostato non disponibile. FAILED_PRECONDITION Il termostato non dispone della funzionalità di ventilazione. Le caratteristiche e i comandi relativi al ventilatore non possono essere utilizzati per questo dispositivo.
Il comando non è consentito quando il termostato è in modalità MANUAL_ECO. FAILED_PRECONDITION Il setpoint di temperatura non può essere impostato quando il termostato è in modalità Eco manuale.

Consulta i riferimenti ai codici di errore dell'API per l'elenco completo dei codici di errore dell'API.