Thermostat

Alle Google Nest Thermostat-Modelle werden von der Smart Device Management API (SDM) unterstützt. Diese Geräte geben den THERMOSTAT-Gerätetyp zurück:

sdm.devices.types.THERMOSTAT

Eigenschaften

Referenz

Die folgenden Merkmale, Befehle oder Ereignisse beziehen sich auf diese Gruppe:

EigenschaftBeschreibungBefehle
KonnektivitätDiese Eigenschaft gehört zu jedem Gerät, für das Verbindungsinformationen verfügbar sind.
FanDiese Eigenschaft gehört zu jedem Gerät, bei dem das System den Lüfter steuern kann.SetTimer
LuftfeuchtigkeitDiese Eigenschaft gehört zu jedem Gerät, das über einen Sensor zur Messung der Luftfeuchtigkeit verfügt.
InformationenDiese Trait gehört zu einem beliebigen Gerät, um gerätebezogene Informationen zu erhalten.
EinstellungenDiese Trait gehört zu einem beliebigen Gerät, um gerätebezogene Einstellungsinformationen abrufen zu können.
TemperaturDiese Eigenschaft gehört zu jedem Gerät, das über einen Sensor zur Temperaturmessung verfügt.
ThermostatEcoDiese Eigenschaft gehört zu den Gerätetypen von THERMOSTAT, die ECO-Modi unterstützen.SetMode
ThermostatHvacDiese Eigenschaft gehört zu den Gerätetypen von THERMOSTAT, die HLK-Details melden können.
ThermostatModeDiese Eigenschaft gehört zu den Gerätetypen von THERMOSTAT, die unterschiedliche Thermostatmodi unterstützen.SetMode
ThermostatTemperatureSetpointDiese Eigenschaft gehört zu den Gerätetypen von THERMOSTAT, die das Festlegen von Zieltemperaturen und Zieltemperaturen unterstützen.SetHeat
SetCool
SetRange

JSON

Wenn eine Eigenschaft in einer GET-Antwort fehlt, bedeutet dies, dass sie bzw. Funktion derzeit für das Gerät nicht verfügbar ist. Weitere Informationen findest du unter Gerätetypen.

{
  "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
    }
  }
}

Temperatur und Luftfeuchtigkeit

Wenn du die Umgebungstemperatur des Thermostats ablesen möchtest, verwende die EigenschaftTemperatur . Die Umgebungstemperatur wird am Gerät gemessen.

Die Luftfeuchtigkeit des Thermostats lässt sich mit der EigenschaftLuftfeuchtigkeit ermitteln. Die Luftfeuchtigkeit wird am Gerät gemessen.

Temperaturskala

Der Google Nest Thermostat kann die Temperatur in Grad Celsius oder Fahrenheit anzeigen, die Skalierung kann jedoch nicht von der SDM API eingestellt werden. Die aktuell vom Nutzer eingestellte Temperaturskala lässt sich über das MerkmalEinstellungen bestimmen.

Modus ändern

Der Modus des Thermostats wird von zwei verschiedenen Eigenschaften verwaltet: ThermostatMode und ThermostatEco.

Standardmodi

Verwenden Sie den Befehl SetMode der Trait „ThermostatMode“, um den Thermostatmodus auf HEIZEN, KÜHLEN oder HEIZKÜHLEN zu ändern.

Mit diesem Befehl kann auch der Modus des Thermostats deaktiviert werden. Er kann nicht verwendet werden, um den Eco-Modus zu aktivieren.

So ändern Sie beispielsweise einen der Standardmodi für den Thermostat:

Anfragen

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

Antwort

{}

Eco-Modus

Verwenden Sie zum Aktivieren des Eco-Modus MANUAL_ECO als Modus mit dem Befehl SetMode der ThermostatEco-Trait:

Anfragen

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

Antwort

{}

Dieser Befehl wirkt sich abhängig vom aktuellen Status des Eco-Modus oder von Änderungen am Eco-Modus auf andere Merkmale aus:

  • Wenn der Eco-Modus deaktiviert ist, wird standardmäßig der letzte aktive Standardmodus (HEITEN, KÜHLEN, HEIZKÜHLEN oder AUS) verwendet.
  • Wenn der Eco-Modus auf MANUAL_ECO gesetzt ist:

Temperatursollwerte ändern

Temperatursollwerte können nur geändert werden, wenn sich der Thermostat im Modus HEIZEN, KÜHLEN oder HEATCOOL befindet. Die zulässigen Sollwerte entsprechen dem aktuellen Modus des Thermostats. Temperatursollwerte können nicht geändert werden, wenn der Modus deaktiviert oder der Eco-Modus auf MANUAL_ECO eingestellt ist.

Der Thermostat muss sich in dem Modus befinden, der dem aufgerufenen Befehl entspricht, bevor die Temperatursollwerte geändert werden. Befehl und Feld(e) zum Ändern der Sollwerte variieren je nach Thermostatmodus.

Für den Befehl „SetHeat“ muss sich der Thermostat beispielsweise zuerst im Heizmodus befinden:

Modus Befehl Feld(er)
HEIZUNG SetHeat heatCelsius
KÜHLEN SetCool coolCelsius
HEIZKÜHLEN SetRange heatCelsius, coolCelsius

Beachte, dass für die Sollwertbefehle nur Grad Celsius als Parameter verwendet wird. Der Google Nest Thermostat kann die Temperatur aber auch in Grad Celsius oder Fahrenheit anzeigen.

Wenn Sie beispielsweise den Temperatursollwert ändern möchten, wenn sich der Thermostat im HEI-Modus befindet, verwenden Sie den Befehl SetHeat des Merkmals ThermostatTemperatureSetpoint:

Anfragen

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

Antwort

{}

Sollwerte für den Eco-Modus

Die vom ThermostatEco-Trait zurückgegebenen Sollwerte heatCelsius und coolCelsius werden vom Nutzer festgelegt und können nicht über die SDM API geändert werden.

Lüfter ein- oder ausschalten

Wenn der Thermostat einen Lüfter unterstützt, kannst du ihn mit dem Befehl SetTimer der Eigenschaft „Lüfter“ ein- oder ausschalten. Beim Einschalten kannst du angeben, wie lange der Lüfter laufen soll (in Sekunden).

So können Sie beispielsweise den Lüfter eine Stunde lang laufen lassen:

Anfragen

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

Antwort

{}

Wenn das Feld duration weggelassen wird, läuft der Lüfter standardmäßig 15 Minuten.

Geräteverbindung prüfen

Wenn das Gerät nicht auf Befehle reagiert oder Ereignisse sendet oder von der API Fehler in Verbindung mit dem Gerät angezeigt wird, verwenden Sie die EigenschaftKonnektivität , um die Verbindung des Geräts auf einen OFFLINE-Status zu prüfen. Prüfe, ob das Gerät mit dem Internet verbunden ist und ob der Nest-Dienst aktiv ist.

Wenn Ereignisse aktiviert sind, sollten Sie auch ein Ressourcenereignis erhalten haben, das anzeigt, dass das Gerät offline ist:

Nutzlast

{
  "eventId" : "c15a80a2-eea2-459a-a1ef-6a1e358392b6",
  "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"
  ]
}

Auf Geräteereignisse reagieren

Bei jeder Änderung an einem Trait-Feld wird ein Ereignis ausgelöst. Sie erhalten beispielsweise das folgende resourceUpdate-Ereignis, wenn sich der HLK-Status des Thermostats in HEIZUNG ändert:

Nutzlast

{
  "eventId" : "4b4e3e0a-d671-46fa-97fe-3c3be2b70baf",
  "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"
  ]
}

Ereignisse werden für alle Traits ausgelöst, die diesem Gerätetyp zugeordnet sind. Aktivieren Sie Ereignisse, wenn Sie im Rahmen einer Integration irgendwie darauf reagieren müssen.

Zeitpunkt von Ereignissen

Ein Ereignis bei einer Änderung des HLK-Status kann nicht gleichzeitig mit Ereignissen für eine Änderung des Thermostatmodus gesendet werden.

Beispielsweise kann es manchmal zu einer Verzögerung beim Starten des Heiz- oder Kühlmodus eines Thermostats kommen, um das HLK-System zu schützen. In diesem Szenario werden beim Ändern des Thermostatmodus anfangs nur Ereignisse für ThermostatMode und ThermostatTemperatureSetpoint Trait-Änderungen gesendet, wobei das separate Merkmalsänderungsereignis ThermostatHvac zu einem späteren Zeitpunkt aktiviert wird. Wenn es keine Verzögerung beim Einschalten des HLK-Systems gab, werden alle drei Ereignisse gleichzeitig gesendet.

Fehler

Folgende Fehlercodes können im Zusammenhang mit diesem Gerät zurückgegeben werden:

Fehlermeldung RPC Fehlerbehebung
Kühlwert muss größer als Heizwert sein. INVALID_ARGUMENT Achten Sie darauf, dass das Feld heatCelsius kleiner als das Feld coolCelsius im Befehl ist.
Der Befehl ist im aktuellen Thermostatmodus nicht zulässig. FAILED_PRECONDITION Bei einigen Thermostatmodellen wird es gemäß der Eigenschaft ThermostatMode nicht unterstützt, den Eco-Modus zu ändern, wenn der Thermostatmodus ausgeschaltet ist. Der Thermostatmodus muss vor dem Umschalten auf den Eco-Modus auf HEIZEN, KÜHLEN oder HEIZENKÜHLEN umgestellt werden.
Thermostat-Lüfter nicht verfügbar. FAILED_PRECONDITION Der Thermostat hat keine Lüfterfunktion. Funktionen und Befehle für Fans können für dieses Gerät nicht verwendet werden.
Der Befehl ist nicht zulässig, wenn sich der Thermostat im Modus „MANUAL_ECO“ befindet. FAILED_PRECONDITION Der Temperatursollwert kann nicht eingestellt werden, wenn sich der Thermostat im manuellen Eco-Modus befindet.

Eine vollständige Liste der API-Fehlercodes finden Sie in der API-Fehlercode-Referenz.