Samsung SmartThings API - Auslesen der Wärmepumpe

[JohnB]

Die Wärmepumpe von Samsung wird über den Wi-Fi Adapter in das Umfeld der SmartThings aufgenommen. Damit kann sie über REST API ausgelesen werden.

REST ist hier beschrieben, leider nicht für Einsteiger

Representational State Transfer – Wikipedia

de.wikipedia.org

1) REST für Einsteiger
Hier geht es um Kommunikation zu einem Webserver. Diese läuft im einfachsten Fall als Frage (=Request) und Antwort (=Response). Die Frage kann Header und Queryparameter haben. Beiden können einen Body haben.

Der Request besteht aus
Zugriffsart: GET / POST / PUT / und weitere
Header : beinhaltet Passwort oder Token
URL : Webadresse (z.B. https://api.smartthings.com/v1/) und Kommando (z.b. devices)
Queryparameter werden hinter der URL angehängt
Body enthält eine Datei, idr. im JSON Format --> JavaScript Object Notation – Wikipedia

Die Response besteht aus
Responsecode (=HTTP Statuscode --> HTTP-Statuscode – Wikipedia)
Body, idr. eine Datei im JSON Format

API ist nur die Abkürzung für die Beschreibung der Befehle. Siehe Programmierschnittstelle – Wikipedia
Application Programming Interface

2) REST von SmartThings
Auf der Seite API | Developer Documentation | SmartThings hat Samsung die Kommandos beschrieben. Das dort gewählte Format ist üblich für eine API Beschreibung. D.h. so machen es alle wenn es gut werden soll.

Abschnitt "Devices" die möglichen Kommands mit den Zugriffsarten farbig hinterlegt

Zu jedem dieser Kommandos gibt es dann eine Beschreibung vom Request und vom Response. Hier die Beschreibung vom "List Devices"

Und hier die möglichen http Codes, teilweise mit Detailinfo (klick auf ">")

3) Beispiele in der Doku
Weiterhin gibt es zu jedem Kommando Beispiel für Request (Aufklappen für die Komplette URL)

und Beispiel für Response

Nächster Post: konkrete Beispiele

 

[JohnB]

Konkrete Beispiele für die API Nutzung mit Firefox

1 Einleitung
Jeder Aufruf einer Webseite kann wie ein GET einer REST Schnittstelle betrachtet werden. D.h. wenn z.B. in Firefox die Seite Heizungsforum aufgerufen wird, ist dies ein Request mit
- GET
- URL = "https://www.heizungsforum.de/"
- kein Header
- kein Queryparameter

Als Response kommt dann eine html Datei zurück und wird von Firefox so angezeigt

So weit - alles bekannt.

2 Erster API Aufruf
Nun will ich den API Aufruf vom Post #1 aufrufen. Das Beispiel wird so angezeigt (jetzt mit dem Detail ausgeklappt):

D.h. die Adresse https://api.smartthings.com/v1/devices in Firefox eingeben. Ergebnis ist beim ersten mal eine leere Seite. Grund: der Header wurde nicht mitgesendet.
Lösung: erst mal unter Samsung account anmelden und nochmals aufrufen. Dann wird der Header eine Zeitlang nicht benötigt.

Nochmals die Seite aufrufen, jetzt sollte Firefox diese JSON Antwort anzeiten (dies ist übrigends der Grund wieso ich diesen Browser nutze: die strukurierte Ausgabe)

Diese API Response (=Antwort) enthält alle Geräte, die Ihr über SamartThings angemeldet habt. Bei mir sind dies die Wärmepumpe und das Wi-Fi Kit.
Struktur der Antwort
Für's erste sind hier wichtig:
Liste "items" -> ein Eintrag für jedes SmartThings Gerät. Die Struktur innerhalb von jedem Listenelement ist gleich aufgebaut und beschreibt das Gerät.
Im items - Element
"deviceId" : eine Reihe von Buchstaben und Ziffern als eindeutige Id von dem Gerät. Beispielgerät in der Doku
deviceId": "6f5ea629-4c05-4a90-a244-cc129b0a80c3"
"label" : Beschreibung von dem Gerät. Ich habe die Geräte "Eco Heating System" und "Systemklimaanlage (Wi-Fi Kit)"

3 Zweiter API Aufruf
Mit diesen Infos können nun weitere Infos von den Geräten selbst aufgerufen werden. Hierfür ist der API Aufruf
https://api.smartthings.com/v1/devices/{deviceId}/status
zuständig. Der Teil "{deviceId}" ist ein Platzhalter für die deviceId aus dem ersten API Aufruf.
Siehe in der API Beschreibung unter API | Developer Documentation | SmartThings
Mit der deviceId aus dem Beispiel von oben wäre dies also die der Request:

https://api.smartthings.com/v1/devices/6f5ea629-4c05-4a90-a244-cc129b0a80c3/status

Response ist eine lange JSON Datei, die in Firefox schön struktuiert ausgegeben wird. Der Anfang sieht bei mir so aus

Interessantes hierin
components / main / temperatureMeasurement / temperature

Passt zur aktuellen Wert im BW

Entsprechend sind die Werte
components / INDOOR1 / temperatureMeasurement / temperature
components / INDOOR2 / temperatureMeasurement / temperature
die Werte von Zone1 und Zone2

Das Datum wird im Format ISO8601 angegeben (--> ISO 8601 – Wikipedia)
2024-02-26T20:14:35.491Z bedeutet also
2024-02-26 : 26. Febuar 2024
T : Trenner zwischen Datum und Uhrzeit
20:14:35.491 : 20 Uhr 14 Minuten 35 Sekunden 491 ms
Z : Zeitzone UTC (jetzt im Winter 1h vor unserer Zeit)

Ebenfalls interssant ist der Abschnitt
components / main / samsungce.ehsFsvSettings mit einigen FSV.


4 Unklare Daten
Die Temperatur vom Außenfühler kann ich leider nicht erkennen, evt. ist es hier gespeichert
components / main / samsungce.ehsCycleData / outdoor

                "outdoor": {
                    "timestamp": "2024-02-26T20:28:22.460Z",
                    "unit": "C",
                    "value": [
                        {   "data": "0019001973003D3D3F0200DF01B800020000",
                            "timestamp": "2024-02-26T20:17:21Z" },
                        {   "data": "001C001C77003D3C3F0200DF01B800020000",
                            "timestamp": "2024-02-26T20:22:21Z" },
                        {   "data": "0014001477003D3D3F0200DF018600020000",
                            "timestamp": "2024-02-26T20:27:21Z" }
                    ]
                }

Angaben zur Wärmeerzeugung könnten hier stehen, auch die kann ich nicht so entziffern
components / main / powerConsumptionReport

            "powerConsumptionReport": {
                "powerConsumption": {
                    "timestamp": "2024-02-26T20:37:26.349Z",
                    "value": {
                        "deltaEnergy": 529.0,
                        "end": "2024-02-26T20:37:26Z",
                        "energy": 1013546.0,
                        "energySaved": 0,
                        "persistedEnergy": 1013546.0,
                        "power": 0.092,
                        "powerEnergy": 0.65447846109271,
                        "start": "2024-02-26T20:11:26Z"
                    }
                }
            },

Habt Ihr Ideen zu den unklaren Daten?




Nächster Post: API Aufrufe mit Python. Hier gibt es nicht mehr die Anmeldung über die Seite my.samsung... sondern mit einem Header.

Der Header benötigt einen Token, der hier erzeugt werden kann:

Samsung account

account.smartthings.com

Cliffhanger !

 

[JohnB]

Schaffe heute nichts mehr, zu lange gearbeitet. Vorgriff auf's nächste Thema: automatische Abfrage der WP über die API. Zu allen Werten der Responses gibt es einen Zeitstempel. Auf der persönlichen Webseite sieht das dann so aus:

All diese Werte gibt's auch in der API Abfrage. Die automatische Abfrage mache ich alle 60 Sekunden und bekomme diese Zeitstempel

Timestamp: Uhrzeit von meinem Rechner
Indoor1_timestamp: Zeitstempel in der JSON Antwort

D.h. die Abfrage alle 60 Sekunden ist viel häufiger als es SmartThings hergibt.

 

[JohnB]

Die Python Abfrage

Die Liste aller in SmartThings angemeldeten Geräte wird so abgefragt und in eine Liste mit dem Namen "DeviceList" eingetragen

    APIurl = f"https://api.smartthings.com/v1/"
    headers = {'Authorization' : 'Bearer xxxxxxxx-xxxx-xxxxx-xxxx-xxxxxxxxxx'}
    DeviceList = []
    def __init__(self):
        dataHTTPResponse = requests.get(self.APIurl + "devices", timeout=5, headers=self.headers)
        if dataHTTPResponse.status_code==200:
            dataJson = json.loads(dataHTTPResponse.text)
        else:
                print(dataHTTPResponse.status_code)
                dataJson=json.loads("{}")
        if len(dataJson) != "":
            for x in range(len(dataJson["items"])):
                self.DeviceList.append([dataJson["items"][x]["label"],dataJson["items"][x]["deviceId"]])

Einige Erkärungen
- requests.get : der API Aufruf mit den entsprechenden Parametern wie in den Beiträgen oben beschrieben
- status_code 200 : nur dann kann die Antwort ausgewertet werden
- dataJson : hier ist die fertig geparste JSON Antwort drin (Parser =json.loads)
- DeviceList.append : legt ein neues Element in der Liste an
- dataJson["items"][x]["label"] und dataJson["items"][x]["deviceId"] sind die Zugriffe auf Label und Id der Geräte

Um das Ganze noch stabiler zu machen sollten eventuelle Fehler noch mit try-except abgefangen werden. Dies habe ich hier nicht gezeigt.


Um nun an den Status selbst dran zu kommen reichen diese Zeilen um an das gewünschte Gerät ran zu kommen

    def GetStatusByName(self,name):
        for i in range(len(self.DeviceList)):
            if self.DeviceList[i][0]==name:
                dataHTTPResponse = requests.get(self.APIurl + "devices/" + self.DeviceList[i][1] + "/status", timeout=5, headers=self.headers)
                break
        return json.loads(dataHTTPResponse.text)

for i in range(len(self.DeviceList)) Schleife über alle gefundenen Geräte
if self.DeviceList[0]==name Hier die Suche nach dem Gerät
requests.get(self.APIurl + "devices/" + self.DeviceList[1] + "/status" der API Aufruf wie im Beispiel oben


So hole ich mir also den Status meiner WP ab und daraus die für mich interessanten Daten

                        x = SmartThings.GetStatusByName('Eco Heating System')
                        t1 = x['components']['INDOOR1']['temperatureMeasurement']['temperature']['value']
                        t1ts = x['components']['INDOOR1']['temperatureMeasurement']['temperature']['timestamp']
                        t2 = x['components']['INDOOR2']['temperatureMeasurement']['temperature']['value']
                        t2ts = x['components']['INDOOR2']['temperatureMeasurement']['temperature']['timestamp']
                        main_temperature = x['components']['main']['temperatureMeasurement']['temperature']['value']
                        main_ts = x['components']['main']['temperatureMeasurement']['temperature']['timestamp']

x = SmartThings.GetStatus API Aufruf von dem Gerät mit dem label "Eco Heating System", JSON Struktur wird in x abgelegt
alle weiteren Zeilen : hier werden die Werte aus der JSON Struktur heraus geholt