Thermostat

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

sdm.devices.types.THERMOSTAT

Eigenschaften

ReferenzJSON

Die folgenden Merkmale, Befehle oder Ereignisse sind mit dieser Gruppe verknüpft:

MerkmalBeschreibungBefehle
KonnektivitätDieses Attribut gehört zu jedem Gerät mit Verbindungsinformationen.
FanDiese Eigenschaft gilt für alle Geräte, bei denen der Lüfter vom System gesteuert werden kann.SetTimer
LuftfeuchtigkeitDieses Attribut gehört zu jedem Gerät mit einem Sensor zur Messung der Luftfeuchtigkeit.
InfoDieses Attribut gehört zu jedem Gerät und enthält gerätebezogene Informationen.
EinstellungenDiese Eigenschaft gehört zu jedem Gerät und enthält gerätebezogene Einstellungsinformationen.
TemperaturDiese Eigenschaft gehört zu jedem Gerät mit einem Temperatursensor.
ThermostatEcoDiese Eigenschaft gehört zu Gerätetypen vom Typ THERMOSTAT, die ECO-Modi unterstützen.SetMode
ThermostatHvacDiese Eigenschaft gehört zu Gerätetypen vom Typ THERMOSTAT, die Details zur HLK-Anlage melden können.
ThermostatModeDiese Eigenschaft gehört zu Gerätetypen vom Typ THERMOSTAT, die verschiedene Thermostatmodi unterstützen.SetMode
ThermostatTemperatureSetpointDiese Eigenschaft gehört zu Gerätetypen vom Typ THERMOSTAT, die die Einstellung der Zieltemperatur und des Temperaturbereichs unterstützen.SetHeat
SetCool
SetRange

Wenn ein Attribut in einer GET-Antwort nicht vorhanden ist, ist das Attribut oder die Funktion derzeit nicht für das Gerät verfügbar. Weitere Informationen finden Sie 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

Verwenden Sie den AttributTemperature , um die Umgebungstemperatur des Thermostats abzurufen. Die Umgebungstemperatur wird am Gerät gemessen.

Verwenden Sie das AttributLuftfeuchtigkeit , um die Luftfeuchtigkeit des Thermostats abzurufen. Die Umgebungsfeuchtigkeit wird am Gerät gemessen.

Temperaturskala

Der Google Nest Thermostat kann die Temperatur in Grad Celsius oder Fahrenheit anzeigen. Die Skala kann jedoch nicht über die SDM API festgelegt werden. Um die vom Nutzer aktuell festgelegte Temperaturskala zu ermitteln, verwenden Sie das AttributEinstellungen .

Modus ändern

Der Modus des Thermostats wird über zwei verschiedene Eigenschaften verwaltet: ThermostatMode und ThermostatEco.

Standardmodi

Verwenden Sie den Befehl SetMode der Eigenschaft „ThermostatMode“, um den Thermostatmodus in „HEAT“, „COOL“ oder „HEATCOOL“ zu ändern.

Mit diesem Befehl können Sie auch den Modus des Thermostats auf „Aus“ stellen. Der Eco-Modus kann damit nicht aktiviert werden.

So ändern Sie beispielsweise einen der Standardmodi des Thermostats:

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

{}

Eco-Modus

Wenn Sie den Eco-Modus aktivieren möchten, verwenden Sie den Befehl SetMode des Attributs „ThermostatEco“ und geben Sie „MANUAL_ECO“ als Modus an:

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

{}

Dieser Befehl wirkt sich je nach aktuellem Status oder Änderungen am Eco-Modus auf andere Eigenschaften aus:

  • Wenn der Eco-Modus deaktiviert ist, wird der Thermostatmodus standardmäßig auf den zuletzt aktiven Standardmodus (HEIZUNG, KÜHLUNG, HEIZUNG/KÜHLUNG oder AUS) zurückgesetzt.
  • Wenn der Eco-Modus „MANUAL_ECO“ ist:

Temperatursollwerte ändern

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

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

Wenn Sie beispielsweise den Befehl „SetHeat“ ausführen möchten, muss sich der Thermostat zuerst im Heizmodus befinden:

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

Für die Befehle zum Festlegen des Sollwerts kann nur Celsius als Parameter verwendet werden. Der Google Nest Thermostat kann die Temperatur jedoch in Celsius oder Fahrenheit anzeigen.

Wenn Sie beispielsweise den Temperatursollwert ändern möchten, wenn sich der Thermostat im Modus „HEIZEN“ befindet, verwenden Sie den Befehl SetHeat der Eigenschaft „ThermostatTemperatureSetpoint“:

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

{}

Sollwerte für den Eco-Modus

Die vom Attribut „ThermostatEco“ 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, können Sie ihn mit dem Befehl SetTimer der Eigenschaft „Fan“ ein- oder ausschalten. Beim Einschalten können Sie die Dauer in Sekunden angeben, für die der Lüfter laufen soll.

So legen Sie beispielsweise fest, dass der Lüfter eine Stunde lang laufen soll:

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

{}

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

Geräteverbindung prüfen

Wenn das Gerät nicht auf Befehle reagiert oder keine Ereignisse sendet oder du Fehler von der API erhältst, die sich auf das Gerät beziehen, verwende das AttributConnectivity , um zu prüfen, ob die Verbindung des Geräts den Status „OFFLINE“ hat. Prüfen Sie die Internetverbindung des Geräts und ob der Nest-Dienst aktiv ist.

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

Nutzlast
{
  "eventId" : "7bfa9f08-b07a-4839-bf2f-3c64b2b40660",
  "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

Jede Änderung an einem Merkmalsfeld generiert ein Ereignis. Wenn sich der HLK-Status des Thermostats beispielsweise in „HEIZUNG“ ändert, erhalten Sie das folgende resourceUpdate-Ereignis:

Nutzlast
{
  "eventId" : "bb46ea3e-e674-4d45-a5da-1eb163bc2b3e",
  "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 Merkmale ausgelöst, die mit diesem Gerätetyp verknüpft sind. Aktivieren Sie Ereignisse, wenn Sie in einer Integration auf sie reagieren müssen.

Zeitangaben für Ereignisse

Beachten Sie, dass ein Ereignis für eine Änderung des HLK-Status möglicherweise nicht gleichzeitig mit Ereignissen für eine Änderung des Thermostatmodus gesendet wird.

Manchmal gibt es beispielsweise eine Verzögerung beim Starten des Heiz- oder Kühlmodus eines Thermostats, um das HLK-System zu schützen. In diesem Szenario werden beim Ändern des Thermostatmodus möglicherweise nur anfänglich Ereignisse für die Änderungen der Eigenschaften ThermostatMode und ThermostatTemperatureSetpoint gesendet. Die Änderung der Eigenschaft ThermostatHvac wird später als separates Ereignis gesendet, sobald das System tatsächlich eingeschaltet wird. Wenn das HLK-System ohne Verzögerung eingeschaltet wird, werden alle drei Ereignisse gleichzeitig gesendet.

Fehler

Für dieses Gerät können die folgenden Fehlercodes zurückgegeben werden:

Fehlermeldung RPC Fehlerbehebung
Der Wert für „Kühlen“ muss größer als der Wert für „Heizen“ sein. INVALID_ARGUMENT Das Feld heatCelsius muss im Befehl kleiner als das Feld coolCelsius sein.
Befehl ist im aktuellen Thermostatmodus nicht zulässig. FAILED_PRECONDITION Einige Thermostatmodelle unterstützen gemäß der Eigenschaft ThermostatMode nicht das Ändern des Eco-Modus, wenn der Thermostatmodus deaktiviert ist. Der Thermostatmodus muss auf „HEIZEN“, „KÜHLEN“ oder „HEIZEN/KÜHLEN“ gestellt sein, bevor der Eco-Modus geändert werden kann.
Lüfter des Thermostats nicht verfügbar. FAILED_PRECONDITION Der Thermostat hat keine Lüfterfunktion. Fanbezogene Eigenschaften und Befehle können für dieses Gerät nicht verwendet werden.
Befehl nicht zulässig, wenn sich der Thermostat im Modus „MANUAL_ECO“ befindet. FAILED_PRECONDITION Der Temperatursollwert kann nicht festgelegt werden, wenn sich der Thermostat im manuellen Eco-Modus befindet.

Eine vollständige Liste der API-Fehlercodes findest du in der API-Fehlercode-Referenz.