
Der Nest Learning ThermostatTM ist ein mit dem Internet verbundenes Gerät, das intuitiv und intuitiv funktioniert. Es lernt ständig über Nutzungsmuster in deinem Zuhause, um den Komfort zu optimieren und Energie zu sparen. Nutzer können ihre Heizung und Kühlung über jede Internetverbindung steuern.
Die Unterstützung dieser Funktionen erfordert ein ausgereiftes Steuerungssystem, das über einfache punktbasierte Programme hinausgeht. Nest bietet eine große Auswahl an Algorithmen (z. B. Early On, True Radiant und Airwave), die im Vergleich zu den meisten Thermostaten eine erheblich hohe Rechenleistung erfordern. Nest Thermostat hat die erforderliche Stromversorgung für diese erweiterten Funktionen.
Die Nest API wurde entwickelt, damit Produkte das HLK-System steuern können, ohne die Nest-Algorithmen zu unterbrechen oder unerwartetes Verhalten zu überraschen. Sie erhalten Zugriff auf die folgenden Daten für Nest Thermostat:
- Gebäudename und Gerät (wobei Name & Ort im Zuhause) ist
- Benutzerdefiniertes Thermostat-Label
- Onlinestatus und letzte Verbindungsinformationen
- Aktuelle und Zieltemperaturen
- Temperaturmodus
- Eco-Temperaturen
- Temperatur-Countdown
- Temperaturskala (Feste Temperatureinstellung)
- Temperatursperre und, falls gesperrt, die minimale/maximale Temperatur für die gesperrte Temperatur
- Timer für Lüfter und HLK-Modus
- Luftfeuchtigkeit
- Sunblocker
Thermostatberechtigungen
Wählen Sie für den Clientzugriff Leseberechtigung für den Thermostat aus, um Lesezugriff auf alle Daten der Thermostat API zu erhalten.
Wählen Sie für Ihren Client die Berechtigung Lese-/Schreibzugriff auf den Thermostat aus, um Lesezugriff auf alle Daten der Thermostat API und zusätzlichen Schreibzugriff auf bestimmte Werte zu erhalten. Mit dieser Berechtigungsstufe können Sie Folgendes aktualisieren:
- Zieltemperatur
- HLK-Modus
- Timer für Lüfter
Ab Version 5 des Thermostats können Sie auch Folgendes aktualisieren:
- Temperaturskala
- Thermostat-Label
Thermostat-IDs
Geräte
Nest-Geräte sind nach Typ als Array angeordnet. Mit ihnen können Geräte eindeutig über den Gerätepfad identifiziert werden. Die Thermostat-ID "peyiJNo..."
bedeutet also, dass du das Thermostat-Gerätemodell unter devices/thermostats/peyiJNo...
über die API laden kannst.
Wenn ein Gerät mit mehreren Produkten verbunden ist, wird jedem Entwickler eine andere ID für das Gerät angezeigt. Bei Geräten, auf denen mehrere Produkte vom selben Entwickler installiert wurden, sieht der Entwickler dieselbe ID.
Name
Es werden zwei Namensattribute angegeben. Das kürzere name
-Attribut wird in Benutzeroberflächenlabels angezeigt, während name_long
im langen Text verwendet wird.
name
In diesen Beispielen ist name
„Hallway"“ oder „Hallway (West)“.


name_long
In diesem Beispiel ist name_long
&Office (Erdgeschoss)&Quot;

Label


Ab Version 5 der Berechtigung können Sie über die API ein benutzerdefiniertes Thermostat-Label hinzufügen. In der Nest App wird das Label in Klammern nach dem Wo.-Namen angezeigt.
Ab Version 6 von Berechtigungen gibt es auch das Label „Thermostat“.
Wo?
where_id
- Eine eindeutige, von Nest generierte ID, die
name
darstellt where_id
ist schreibgeschützt und wird automatisch im Aufruf erstellt, um einen benutzerdefinierten Befehl zu erstellen, wobeiname
Weitere Informationen über die Namen von Nest Thermostaten, Nest Protect-Geräten und Nest Cams
where_name
Wenn du eine der Thermostatberechtigungen auswählst, kannst du über das Geräteobjekt (devices/thermostats
) auf das Gerät where_name
zugreifen.
Sonstige Metadaten
Sofern nicht anders angegeben, sind alle Datenwerte schreibgeschützt.
Datenwert | Beschreibung |
---|---|
locale |
Sprach- und Ländercode, der diesem Gerät zugewiesen ist |
software_version
|
Ein String, der die derzeit auf dem Gerät installierte Firmware darstellt |
structure_id
|
Ein String, der diese Struktur eindeutig darstellt. Dies ist die Struktur, mit der das Gerät gekoppelt ist. |
last_connection
|
Der Zeitstempel der letzten erfolgreichen Verbindung mit dem Nest-Dienst |
is_online
|
Onlinestatus Dies wird von Nest anhand der last_connection -Zeit und eines erwarteten gerätespezifischen Verbindungsfensters bestimmt. |
Thermostatfunktionen
Thermostatmodi
HLK-Systeme haben vier Aktivierungsstatus (heat
, cool
, heat-cool
, eco
) und einen Status (off
). Wir verwenden diese Status, um Komfort- und Energieeinsparungen über hvac_mode
- und Temperaturdatenwerte zu verwalten.
- Wenn der Modus „Heizen“ oder „Kühlen“ (
heat
,cool
) ausgewählt ist, passt der Thermostat das Zuhause an die Zieltemperatur an. - Wenn der Modus „Heizen • Kühlen“ (
heat-cool
) ausgewählt ist, wird die Temperatur in deinem Zuhause im bevorzugten Temperaturbereich gehalten. - Wenn Eco-Temperaturen (Eco) ausgewählt ist, wendet der Thermostat Algorithmen zum Energiesparen an. Dadurch wird das Zuhause gemütlich gehalten und der Energieverbrauch reduziert. Thermostate in diesem Modus zeigen ECO an.
Bei Gebäuden gibt es zwei unterschiedliche Zustände: „Zuhause“ und „Abwesend“. Wenn im Haus keine Bewegung erkannt wird, ändert sich das Gebäude von „Zuhause“ in „Abwesend“ und die Thermostate in deinem Zuhause aktivieren automatisch Eco-Temperaturen.
Zusammenspiel von hvac_mode
und Temperaturwerten
Abhängig vom Wert von hvac_mode
kann nur auf bestimmte Werte für Temperaturdaten in der API zugegriffen werden:
HLK-Modus | Auf Temperaturdaten, auf die Sie zugreifen können |
---|---|
heat oder cool |
target_temperature_f oder target_temperature_c |
heat-cool
|
target_temperature_low_f und
target_temperature_high_f oder target_temperature_low_c und
target_temperature_high_c |
eco
|
eco_temperature_low_f und
eco_temperature_high_f oder eco_temperature_low_c und
eco_temperature_high_c |
off |
keine |
In einigen Szenarien gelten spezielle Regeln zum Ändern von hvac_mode
:
Szenario | Kann hvac_mode geändert werden? |
---|---|
Temperatursperre ist aktiviert | Ja |
Notabschaltung ist aktiv | Nein |
Notheizung ist aktiviert | Nein |
Der Wert für can_cool oder can_heat ist false |
Nein |
Eco-Temperaturen
Mit Eco-Temperaturen kann der Nutzer Energie sparen, unabhängig davon, ob er zu Hause ist oder nicht.
Sie sollten hvac_mode
auf eco
umstellen, wenn Sie das Energiesparverhalten in Ihrem Produkt implementieren.
Eco-Temperaturendpunkte sind in der Nest API verfügbar, beginnend mit den Lese- und Schreibberechtigungen für Thermostat v6.
Zwischen Eco- und Nicht-Eco-Modi wechseln
Dein Gerät sollte die Zieltemperaturen nicht direkt im Eco-Modus verwalten. Wenn der Modus „Abwesend“ eingestellt ist, wird die Zieltemperatur nicht angezeigt, sondern intern basierend auf der Nutzerauswahl festgelegt. Wenn der Thermostat auf „AUS“ gestellt ist, werden keine Zieltemperaturen beobachtet.
Wenn du die Zieltemperaturen direkt ändern musst, führe dies in zwei separaten Aufrufen durch:
- Ändern Sie
hvac_mode
in einen anderen Wert außereco
- Entsprechende
target_temperature
-Datenwerte ändern
Ab Lese- und Lese-/Schreibberechtigungen für den Thermostat können Sie über die API auf previous_hvac_mode
zugreifen, um den Übergang zum HLK-Modus zu erleichtern.
previous_hvac_mode
wird verwendet, um die hvac_mode
des Geräts zu speichern, bevor sie zu „eco“ wechselt.
Wenn der Nest Thermostat beispielsweise Eco-Temperaturen (hvac_mode =
"eco"
) verwendet, previous_hvac_mode
verfügbar ist und Sie für Ihr Produkt target_temperature
einstellen möchten, müssen Sie zuerst Folgendes tun:
previous_hvac_mode
verdienenhvac_mode
auf den Wertprevious_hvac_mode
festlegen- bestätigen, dass
hvac_mode
nicht mehr auf &eco
Legen Sie anschließend die gewünschten Temperaturen fest.
Je nach hvac_mode
-Wert ändert sich previous_hvac_mode
so:
Wenn der Status hvac_mode ... |
Dann kann previous_hvac_mode ... |
---|---|
eco |
heat , cool , heat-cool oder off |
heat , cool , heat-cool oder off |
leer/leer |
Zieltemperatur
Die Zieltemperatur ist die wichtigste Eigenschaft für das HLK-System. Sie ist die gewünschte Temperatur, die der Nutzer normalerweise festlegt. Die meisten Aktionen und Entscheidungen basieren darauf. Über die API können „Works with Nest“-Produkte die Zieltemperatur als Teil eines größeren Prozesses schreiben.
Wenn das System eingeschaltet ist, ist immer eine Zieltemperatur eingestellt.
- Wenn der Modus „Heizen“ oder „Kühlen“ (
heat
,cool
) ausgewählt ist, wird eine einzelnetarget_temperature
festgelegt. - Wenn „Heizen • Kühlen“ (
heat-cool
) ausgewählt ist, werden zwei Werte fürtarget_temperature
festgelegt. Diese geben einen Zielbereich an, einen höheren für die Kühlung und einen niedrigeren für die Heizung. - Wenn der Eco-Modus ausgewählt wird (
eco
) ist der Zieltemperaturbereich intern festgelegt
Es gibt auch Sicherheitstemperaturen, die einen Rückschlag halten, um Gefrieren von Rohrn oder übermäßig hohe Temperaturen in Ihrem Zuhause zu verhindern.
Wenn der Thermostat ausgeschaltet ist, sind keine Zieltemperaturen eingestellt.
Temperatur-Countdown
Mit Temperatur-Countdown kannst du auf diese Datenwerte für das HLK-System zugreifen:
time_to_target
– Die Zeit in Minuten, die die Struktur benötigt wird, um die Zieltemperatur zu erreichen.time_to_target_training
- Trainingsstatus
- Der Thermostat lernt, wie das HLK-System reagiert, und passt die Schätzung für das Erreichen der Zieltemperatur an.
- Wenn sich der Thermostat in Bezug auf die geschätzte Zeit für das Erreichen der Zieltemperatur sicher ist, ändert sich der Status von
training
zuready
Umgebungstemperatur
Die Temperatur, die in der Nähe des Thermostats gemessen wird. Wert anzeigen, der der bevorzugten Temperaturskala des Nutzers entspricht.
Temperaturskala
Die Umgebungs- und Zieltemperaturvariablen sind nach Celsius oder Fahrenheit organisiert. Das Attribut temperature_scale
ist je nach Nutzerpräferenz entweder „F“ oder „C“. Diese Eigenschaft wird von jedem Thermostat festgelegt. Aus diesem Grund kann ein Nutzer in einer einzelnen Struktur zwei Thermostate haben, einen pro Temperaturskala. Berücksichtige die Nutzereinstellungen, wenn du Temperaturwerte anzeigen möchtest.
Ab Version 5 von Berechtigungen kannst du die Temperaturskala über die API ändern.
Die Felder „Ziel“ und „Umgebungstemperatur“ haben die Varianten _f
und _c
, um bei der Anzeige der Temperaturen eine konsistente Rundung zu ermöglichen.
Temperaturanzeige

Berücksichtige beim Anzeigen von Zieltemperaturinformationen diese drei abhängigen Werte: temperature_scale
, hvac_mode
und den away
-Status der Struktur.
Viele Datenwerte bestimmen zusammen, was auf dem Nest Thermostat-Display angezeigt wird und wie sich die Daten verhalten.
- Wenn
hvac_mode
aufheat-cool
gesetzt ist, zeigt der Nest Thermostat die niedrigen und hohen Sollwerte durch ein Aufzählungszeichen an (•), andernfalls zeigt der Nest Thermostat nur die Zieltemperatur an - Wenn
hvac_mode
aufoff
gesetzt ist, wird das Wort „AUS“ auf dem Nest Thermostat in der Sprache des Nutzers angezeigt - Wenn
hvac_mode
aufeco
gesetzt ist, wird das Wort „ECO“ auf dem Nest Thermostat in der bevorzugten Sprache des Nutzers angezeigt
Das Format der Anzeigetemperatur hängt auch von der ausgewählten Temperaturskala (F/C) ab.
Fahrenheit-Temperaturen werden als ganze Zahlen angezeigt:
- Zieltemperatur: 13 °C
- Umgebungstemperatur: 20 °C
Celsius-Temperaturen werden als ganze Zahl oder als Dezimalwert angezeigt, wobei die letzte Ziffer auf „.5&;“ gesetzt ist:
- Zieltemperatur: 12° C
- Umgebungstemperatur: 16,5 °C
Blatt
Wenn das Blattsymbol auf der Vorderseite des Thermostats angezeigt wird, ist der Thermostat auf eine energiesparende Temperatur eingestellt und has_leaf
= true
.

Temperatursperre
Nutzer können einen Nest Thermostat sperren, sodass er nur innerhalb eines begrenzten Temperaturbereichs angepasst werden kann. Ab Version 5 der Berechtigungsstufe könnt ihr anhand der Option is_locked
erkennen, ob die Temperatursperre aktiviert ist. Ist dies der Fall, könnt ihr über die API Werte für die minimale/maximale Temperatursperre abrufen:
Sperrtemperaturen müssen als Paare in Form von Höchst- und Minimalwerten angegeben werden. Sie dürfen nur geschrieben werden, wenn is_locked
= true
.
Luftfeuchtigkeit
Die Luftfeuchtigkeit in Prozent (%), gemessen auf dem Gerät, auf 5 % gerundet.
Sunblocker
Die Sunblocker-Technologie passt die Temperatur des Nest Thermostats automatisch an, um Hitzespitzen auszugleichen, die durch direkte Sonneneinstrahlung auf dem Gerät auftreten.
Anhand dieser Datenwerte sehen Sie, ob Sunblocker aktiviert und/oder die Temperatur aktiv korrigiert wurde.
sunlight_correction_enabled
- Boolescher Wert, gibt
true
zurück, wenn Sunblocker aktiviert ist
- Boolescher Wert, gibt
sunlight_correction_active
– boolescher Wert; gibttrue
zurück, wenn Sunblocker aktiviert ist. Das bedeutet, dass sich der Thermostat bei direkter Sonneneinstrahlung befindet.
Lüfter
Viele HLK-Systeme haben Ventilatoren. Das bedeutet, dass der Lüfter nicht unabhängig gesteuert werden kann. Für integrierte Lüfter gibt es keinen Modus „Aus“, da der Lüfter laufen muss, wenn die Heizung oder Kühlung eingeschaltet ist.
Wenn das HLK-System kompatibel ist, kann der Lüfter explizit über die API aktiviert werden, um die Insassen zu erleichtern, ohne das gesamte HLK-System einzubeziehen.
Wenn der Lüfter unabhängig steuerbar ist, wird has_fan
auf true
gesetzt und die folgenden Datenwerte können mit den Lese-/Schreibberechtigungen des Thermostats festgelegt werden:
fan_timer_active
– Boolescher Wert, gibttrue
zurück, wenn der Lüfter-Timer für eine vorprogrammierte Dauer aktiv ist.fan_timer_duration
: Dauer in Minuten, die der Lüfter festgelegt ist
Wenn Sie diesen Wert zusammen verwenden, können Sie den Lüfter-Timer für einen bestimmten Zeitraum einschalten. Sie können auch den Wert fan_timer_timeout
verwenden, um den Zeitstempel für die Ausführung des Lüfters festzulegen.
Beachten Sie, dass Sie fan_timer_duration
jederzeit ändern können. Sie ist unabhängig von hvac_mode
oder dem Status der Belegung (strukturiert).
Beispiele für erfolgreiche oder fehlgeschlagenen Antworten:
- 200 OK
- 400 Fehlerhafte Anfrage
Wenn der Befehl zum Einschalten des Lüfters nicht das erwartete Ergebnis liefert, kann das daran liegen, dass der Lüfter bereits entweder vom Nutzer oder nach einem Zeitplan oder aufgrund eines Heiz-/Kühl-Heizsystems von HLK läuft.
Ratenbegrenzung
Wir wenden Ratenbegrenzungen an, um übermäßige Aufrufe von Geräten zu schützen, die die System- oder Akkuleistung beeinträchtigen können. Unter normalen Bedingungen laden Nest-Geräte den Akku aus den Niederspannungsleitungen des Heiz- und Kühlsystems. Wenn aber innerhalb kurzer Zeit übermäßig viele Anrufe getätigt und der Akkustand niedrig ist, deaktiviert der Nest Thermostat die WLAN-Funktion, um Energie zu sparen.
In der Praxis heißt das, dass die Anzahl der Aufrufe eines Geräts innerhalb eines bestimmten Zeitraums begrenzt ist. Wird dieses Limit überschritten, erhalten Sie eine Fehlermeldung und eine Meldung, dass Sie das Limit überschritten haben.
Weitere Informationen findest du unter Datenbegrenzungen.
Energieeinschränkungen
In einigen Fällen kann der Thermostat nicht ausreichend mit Strom versorgt werden, um eine Änderungsanfrage zu bearbeiten. Du erhältst dann eine Fehlermeldung und eine Nachricht, dass das Gerät die Anfrage zu diesem Zeitpunkt nicht ausführen kann. Warten Sie in diesem Fall noch etwas Zeit, um den Akku zu laden, bevor Sie es noch einmal versuchen.
Hier erfahren Sie mehr über den Akkustand von Nest Learning Thermostaten.
Fehlermeldungen
In einigen Bundesstaaten sind bestimmte Funktionen nicht verfügbar. Diese Regeln sollen Energie sparen und Komfort und Sicherheit gewährleisten.
Informationen zu den API-Aufruffehlern und deren Behebung finden Sie unter Fehlermeldungen.
WLAN-/Verbindungsproblem
Wenn ein Gerät offline ist, sind keine Änderungen zulässig. Sie können den Onlinestatus des Geräts im Datenmodell und auf der entsprechenden UI anzeigen.