[Erfahrungsbericht] [V4.8 IP4] Miele@Home mit Miele 3rd Party API

[AndererStefan]

Im „HTTP-API Server und Ressourcen Manager“ ist ein Eintrag für jeden Serivce. Dort ist neben dem Mülleimer-Icon ein Blatt-Icon mit einem Pfeil, damit startet man den Export.

[MoseP]

Ich habe das Profilt für den OAUTH-Callback exportiert:

TWS HTTP-API Export - OAuth Callback.json

Dieser muss als HTTP-Sever im Timberwolf eingerichtet werden. Dann kann mittels Aufruf im Browser der Miele-Autentifizierungsworkflow gestartet werden, um den ersten Autorisierungscode zu bekommen.

Code: Alles auswählen

https://auth.domestic.miele-iot.com/partner/realms/mcs/protocol/openid-connect/auth?client_id=<YOUR-CLIENT-ID>&response_type=code&redirect_uri=<YOUR-TWS-BASE-URL>&scope=mcs_thirdparty_read%20mcs_thirdparty_write%20mcs_thirdparty_media%20openid&state=>YOUR-RANDOM-STRING>

Entsprechend die <YOUR-...> an die eigenen Daten anpassen.

[MoseP]

Als Client habe ich zwei Subsysteme eingerichtet. Einmal ein "Miele OAuth2", der Token-Erzeugung und -Refresh übernimmt. Und ein "Miele Cloud API", in der die eigentliche Gerätesteuerung stattfindet.

TWS HTTP-API Export - Miele OAuth2.json

Mit "Miele OAuth2" wird folgender Ablauf möglich:
Schritt A: Authorization URL manuell im Browser öffnen (siehe vorangegangener Post)
Schritt B: Mit den Miele-Login-Daten im Browser anmelden und die Geräte für den Zugriff bestätigen.
Schritt C: Access Token und Refresh Token erzeugen.
Schritt D: Regelmässig mit Refresh Token ein neues Paar Access Token + Refresh Token holen.

Hier Schritt C:

Die Logik-Engines sind KONKATENIERE mit dem jeweiligen Begriff als Input und einem Trigger.
Logik 78 und 112 braucht es nicht, hiermit wollte ich den Refresh mit der empfangenen Gültigkeit selbst triggern. Aber das ist unnötig kompliziert, denn das Intervall ist immer 60 Minuten, deshalb habe ich es stattdessen oben als Auslöser-Intervall "hard coded" eingestellt.

Für das Access-Token musste ich etwas basteln. Es muss das Wort "Bearer " (mit Leerzeichen) vor das empfangene Token geschrieben werden, damit es verwendet werden kann. Aber aufgrund der Länge des Tokens von rund 1000 Bytes geht das nicht mit dem Standard-Konkateniere aus dem Katalog, sondern ich musste eine Custom-Logik bauen, die eine entsprechend grosse Variable erstellt:

Code: Alles auswählen

{
  "_Meta": { // Optional
    "Description": "Schreibt 'Bearer ' vor das Token",
    "Author": "André P.",
    "Version": "1.00"
  },
  "Level": [
    ["$Bearer", "string", "Bearer "],
    ["$Token", "string", "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx100xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx200xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx300xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx400xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx500xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx600xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx700xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx800xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx900xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx1000xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx1100"],
    ["$Result", "string", "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx100xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx200xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx300xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx400xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx500xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx600xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx700xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx800xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx900xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx1000xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx1100"]
  ],
  "Module": [
    ["Concat", ["$Bearer", "$Token"], "$Result"]
  ],
  "Input": [
    ["AccessToken", "Access Token (1099 Bytes)", "$Token", "c"]
  ],
  "Output": [
    ["BearerToken", "Bearer Token fuer Authorization-Header", "$Result", "a"]
  ]
}

Die Funktion D Token Refresh sieht so aus:

Hier könnte man noch vereinfachen und den Ausgang "Refresh Token Refresh" direkt auf den Eingang "Refresh Token" verknüpfen, statt über die Logik zwischenzuspeichern.

So ist die automatische Erneuerung des Tokens gesichert, und die Steuerung kann in einem eigenen Subsystem sauber getrennt dargestellt und genutzt werden. Über das Subsystem "Miele Cloud API" schreibe ich im nächsten Post.

Viel Spass beim Nachbauen.

[AndererStefan]

Danke das hast du schön beschrieben!
Für die Gardena Cloud habe ich so ähnlich gemacht - funktioniert super, selbst nach Offline-Phase im Winter.

VG Stefan

[chtonian]

Für solche komplexen Vorgänge würde ich im übrigen eine kleine node middleware via chatgpt/claude empfehlen, die den gesamten oauth path handelt. Wichtig ist dass das refresh token regelmäßig genutzt wird, dann braucht man auch keine user auth zwischen hängen. Einfach einen Docker container mit dem Node (API) Script via portainer laufen lassen und den timberwolf via API direkt auf die exposete API von node container schicken, dann braucht ihr euch um solche komplexitäten keine gedanken mehr machen.

[AndererStefan]

Ja und nein.
Die Komplexität ist in dem Fall die zusätzliche Middelware (immerhin im Container und auch auf dem TWS). Dadurch ergeben sich Schnittstellen und Abhängigkeiten. Ein weiterer Dienst mit dem sich mit dem man sich bei Einrichtung und Wartung auseinandersetzen muss. Weiß man in 5 Jahren noch, was wie wo und warum?

Ich bevorzuge daher den „Baukasten“ den der TWS nativ bietet um andere Geräte anzubinden. Ich finde das insgesamt übersichtlicher und einheitlicher, auch wenn man mal zwei, drei Logiken erstellen muss.

VG
Stefan

[Sun1453]

Da stimme ich Stefan zu, extra Wartung und Dokumentation.

[chtonian]

So wie jeder mag, ich bin ein fan von microservices und keiner monolithischen Gigastruktur. Gerade die "Probleme" mit JSON Response Parser vs Request Parser im Timberwolf oder andere "Kinderkrankheiten" machen in meinen augen einen gemischten Ansatz sinnvoll. Natürlich habt ihr recht, dass man nach 3 Jahren sicherlich nicht mehr genau weiss wieso man was gemacht hat, aber das gleiche kann man auch über 30 Logiken im Timberwolf sagen, die man das letzte mal vor 3 Jahren angefasst hat.

[MoseP]

Einfach einen Docker container mit dem Node (API) Script via portainer laufen lassen und den timberwolf via API direkt auf die exposete API von node container schicken, dann braucht ihr euch um solche komplexitäten keine gedanken mehr machen.

Unser Verständnis von einfach unterscheidet sich sehr. "So wie jeder mag", hast Du richtig gesagt.
Ich sehe hier keine Komplexität, für die ein zusätzliches System (Middleweare) den Aufwand und die zusätzliche Pflege eines microservice wert wäre. Schritt A, B und C sind nur ein einziges Mal erforderlich. Mag sein, das mein Aufwand dafür etwas hoch war, aber alle Nutzer hier können ja jetzt mein Subsystem einfach importieren und benutzen - noch einfacher, als wenn jeder zusätzlich etwas mit generativer KI erstellen muss (vom Risiko, Logindaten mit generativen Modellen zu teilen, mal abgesehn).

Ich habe mir zusätzlich in der Visu-Seite in der Detailansicht meines Miele-Buttons unter "Erweiterte Steuerung" meine Login-URL (Schritt A) als Schaltfläche angelegt, falls doch mal was mit dem Refresh nicht geklappt haben sollte.
Und auf dem Smartphone öffnet der zweite Button die Miele-App über die URL "miele://"

[MoseP]

Hier das zweite Subsystem "Miele Cloud API", mit dem die Geräte ausgelesen und gesteuert werden können.
Die verfügbaren Funktionen sind modellspezifisch. Alte Modelle wie meine können nur gestartet und gestoppt werden, zum Teil sogar nur, wenn sie in den Zeitvorwahlmodus gesetzt werden. Und natürlich auch nur die Geräte und nur für die Funktionen, die man im Schritt A/B im Miele-Dialog aktiviert.

TWS HTTP-API Export - Miele Cloud API.json

Ich habe die Funktionen entsprechend der Miele-Dokumentation erstellt.


Die Autorisierung erfolgt über Logik 111, die das Wort Bearer vor das Token schreibt (Code siehe oben).
In den Funktionen, die ich nur einmal oder höchst selten brauche, habe ich als Trigger das Feld "Language" definert und daran eine Logik 75 gehängt, die ich manuell im Doktormodus auslöse.

Bei vielen der Get-Funktionen habe ich die Device-ID als Trigger genommen. Sie wird von meiner Visu beim Auswählen eines Geräts in der Detailansicht übergeben (siehe Screenshot oben).

Die Get-Status-Funktionen habe ich für meine drei Geräte einzeln eingerichtet und triggere diese automatisch alle 60 Sekunden. Das reicht mir für eine Meldung, ob meine Wäsche aufgehängt werden will.


Viel Spass beim Nachbauen und verbessern.

Grüsse
André