Termostato

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

sdm.devices.types.THERMOSTAT

Tratti

Riferimento

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

TrattoDescrizioneComandi
ConnettivitàQuesto tratto appartiene a qualsiasi dispositivo con informazioni sulla connettività.
FanQuesta caratteristica appartiene a qualsiasi dispositivo che ha la capacità del sistema di controllare la ventola.SetTimer
UmiditàQuesta caratteristica appartiene a qualsiasi dispositivo dotato di un sensore per misurare l'umidità.
InformazioniQuesto attributo appartiene a qualsiasi dispositivo per informazioni correlate al dispositivo.
ImpostazioniQuesto attributo appartiene a qualsiasi dispositivo per informazioni sulle impostazioni relative al dispositivo.
TemperaturaQuesta caratteristica appartiene a qualsiasi dispositivo dotato di un sensore per misurare la temperatura.
ThermostatEcoQuesto attributo appartiene ai tipi di dispositivi THERMOSTAT che supportano le modalità ECO.SetMode
ThermostatHvacQuesto attributo appartiene ai tipi di dispositivi THERMOSTAT che possono segnalare i dettagli dell'impianto di climatizzazione.
ThermostatModeQuesto attributo appartiene ai tipi di dispositivi THERMOSTAT che supportano diverse modalità di termostato.SetMode
ThermostatTemperatureSetpointQuesto attributo appartiene ai tipi di dispositivi THERMOSTAT che supportano l'impostazione della temperatura ottimale 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 è al momento 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 il tratto 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ò mostrare 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 .

Modificare la modalità

La modalità del termostato è gestita da due tratti diversi: ThermostatMode e ThermostatEco.

Modalità standard

Per impostare la modalità del termostato su CALDO, FREDDO o CALDOFREDDO, 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 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 o alle modifiche della modalità Eco:

  • Se la modalità Eco è OFF, per impostazione predefinita la modalità del termostato sarà l'ultima modalità standard (CALDO, FREDDO, CALDOFREDDO o OFF) 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 CALDO/FREDDO e i set-point consentiti corrispondono alla modalità corrente del termostato. I setpoint della temperatura non possono essere modificati quando la modalità è OFF o quando la modalità Eco è impostata su MANUAL_ECO.

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

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

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

Tieni presente che i comandi del set-point accettano come parametro solo gradi Celsius, 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à CALDO, utilizza il comando SetHeat del trait 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 dal tratto ThermostatEco sono impostati dall'utente e non possono essere modificati tramite l'API SDM.

Accendere o spegnere il ventilatore

Se il termostato supporta una ventola, utilizza il comando SetTimer dell'attributo Fan per attivarla o disattivarla. Quando la attivi, puoi specificare la durata in secondi della ventola.

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, il ventilatore funzionerà per una durata predefinita di 15 minuti.

Controlla la connettività del dispositivo

Se il dispositivo non risponde ai comandi o non invia eventi oppure ricevi errori dall'API relativi al dispositivo, utilizza la caratteristicaConnettività per verificare se la connettività del dispositivo è 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 della risorsa che indica che il dispositivo è offline:

Payload

{
  "eventId" : "66cc2182-9529-41f4-a8c9-4f5413c40bfd",
  "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"
  ]
}

Rispondere agli eventi del dispositivo

Qualsiasi modifica a un campo del tratto genera un evento. Ad esempio, riceverai il seguente evento resourceUpdate se lo stato dell'impianto di climatizzazione del termostato è impostato su RISCALDAMENTO:

Payload

{
  "eventId" : "5cbd3f60-055f-4ed7-b92d-9ae3cfa3e1ff",
  "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 tratti associati 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 di climatizzazione 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 di climatizzazione. In questo scenario, la modifica della modalità del termostato potrebbe inizialmente inviare solo eventi per le modifiche ai tratti ThermostatMode e ThermostatTemperatureSetpoint , mentre la modifica del tratto ThermostatHvac verrà inviata in un secondo momento come evento distinto quando l'impianto si accende effettivamente. Se non ci fosse stato alcun ritardo nell'accensione dell'impianto di climatizzazione, tutti e tre gli eventi sarebbero stati inviati contemporaneamente.

Errori

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

Messaggio di errore RPC Risoluzione dei problemi
Il valore freddo deve essere maggiore del valore caldo. INVALID_ARGUMENT Assicurati che il campo heatCelsius sia inferiore al campo coolCelsius nel comando.
Comando non consentito nella modalità attuale del termostato. FAILED_PRECONDITION Alcuni modelli di termostato non supportano la modifica della modalità Eco quando la modalità del termostato è OFF, in base al tratto ThermostatMode . La modalità del termostato deve essere impostata su CALDO, FREDDO o CALDO/FREDDO prima di modificare la modalità Eco.
Ventola del termostato non disponibile. FAILED_PRECONDITION Il termostato non ha la funzionalità di ventilazione. I comandi e le caratteristiche 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 temperatura non può essere impostato quando il termostato è in modalità Eco manuale.

Consulta il riferimento ai codici di errore dell'API per un elenco completo dei codici di errore dell'API.