vitoconnect

Aus FHEMWiki
vitoconnect
Zweck / Funktion
Steuerung von Viessmann Heizungen
Allgemein
Typ Gerätemodul
Details
Dokumentation EN / DE
Thema
Support (Forum) Heizungssteuerung/Raumklima
Modulname 98_vitoconnect.pm
Ersteller stefanru (Forum /Wiki)
Wichtig: sofern vorhanden, gilt im Zweifel immer die (englische) Beschreibung in der commandref!


Vitoconnect ist die Schnittstelle zwischen Viessmann Gerät (Heizkessel, Wärmepumpe,...) und der App ViCare zum Bedienen von Viessmann Heizungsanlagen.

Mit dem FHEM Modul vitoconnect können die Daten, die über die Internetschnittstelle an den Herstellerserver gemeldet und von diesem über eine API zur Verfügung gestellt werden, in FHEM in Form von Readings angezeigt werden. Auch eine Steuerung der Heizung ist mit diesem Modul möglich.

Wen stört, dass die Daten in der Herstellercloud liegen, sei das Modul Vitotronic 200 (Viessmann Heizungssteuerung) empfohlen.

Die Idee zu dem Modul enstand aus dem Thread "Viessmann VitoConnect API". Es basiert auf dem PHP Modul von thetrueavatar.

Info green.pngAktuelle Entwicklung des Moduls

Das "offizielle" Modul im SVN war "verwaist", der Maintainer (mcp) nicht mehr aktiv:

  • Ursprüngliches Forenthema (86073): geschlossen; enthält "inoffizielle" Modulupdates von verschiedenen Autoren in verschiedenen Beiträgen
  • Neues Forenthema (Vitoconnect - Verbesserte Version), Benutzer stefanru  ; dieses Forenthema wird der neue "Entwicklungsthread" zum Modul.

Die neue Version des Moduls ist seit dem 29.01.2025 im SVN verfügbar.

Das neue Modul ist abwärtskompatibel, es wird aber empfohlen auf Raw Readings umzustellen (vitoconnect_raw_readings = 1), siehe Wiki.
Info green.pngDisclaimer zur Ursprungsversion des Moduls

Das Modul wurde nach bestem Wissen und Gewissen programmiert. Da Änderungen an der Heizung nur über die Viessmann API erfolgen, sollte die Nutzung risikoarm sein. Allerdings kann ich keine Garantie übernehmen, dass es nicht doch zu irgendwelchen unerwünschten Nebeneffekten kommt. Nutzung auf eigene Gefahr!

Diskussionen über Fehler, Verbesserungen usw. finden im Forum im Thread "Neues Modul: vitoconnect" statt.


Einrichtung

Vorbereitung

Zur Nutzung des Moduls muss vorhanden sein:

  • Eine aktuelle FHEM Installation
  • Internet-Schnittstelle Vitoconnect (Typ OPTO1 oder OPTO2) oder E3 One Base
  • Ein Viessmann ViCare Account, wie er im Rahmen der Nutzung der ViCare App erstellt wird.
  • Seit 15. Juli 2021 auch einen persönlichen API Key (=Client-ID), diesen gibts hier: https://developer.viessmann.com
  • Das Modul benötigt mindestens folgende Perl Libraries: Path::Tiny, JSON und DateTime. Diese können mit sudo apt install libtypes-path-tiny-perl libjson-perl libdatetime-perl oder via cpan. Sollten Libraries fehlen erhält man folgende Fehlermeldung "cannot load module vitoconnect". Dann bitte ins Logfile schauen, welche Lib fehlt.

Define des Devices

Dann kann das Gerät angelegt werden: define <name> vitoconnect <user> <password> <interval>

Z.B. : define vitoconnect vitoconnect user@mail.xx geheim 60

User und Passwort sind das gleiche wie in der ViCare App.

Da die Parameter, die beim Definieren des Devices angelegt werden im Klartext in der Detailansicht lesbar sind, kann man beim Definieren einfach ein falsches Passwort eingeben und das richtige später mit einem "set"-Kommando setzen. Also zum Beispiel:

define vitoconnect vitoconnect user@mail.xx fakePassword 60
set vitoconnect password correctPassword 60

Zusätzlich muss der apiKey gesetzt werden.

Dazu muss eine Client-ID unter https://developer.viessmann.com/ erstellt werden.

Nach dem Erstellen eines Kontos muss ein neuer Client mit folgenden Einstellungen angelegt werden:

  • Google reCAPTCHA deaktiviert
  • Redirect URI = http://localhost:4200/
  • Nun die Client-ID kopieren und am FHEM Device setzen:
  • set vitoconnect apiKey <Client-ID>

Sollte die Anlage mehrere Viessmann Geräte oder mehrere Gateways mit mehreren Geräten oder mehrere Standorte mit mehreren Gateways und mehreren Geräten besitzen, wird es eine Meldung im Status des FHEM Devices geben. Bitte mit

set vitoconnect selectDevice <Devices>

das Device auswählen, das FHEM abfragen soll.

Sollen mehrere Devices abgefragt werden, bitte mehrere FHEM vitoconnect Devices anlegen. Hier bitte das API Limit von oben beachten.

Zur nachträgliches Änderung des Intervalls kann das DEF aufgerufen und dort die Parameter korrigiert werden (z.B. von 60 Sek. auf 180 Sek.) - dies gilt natürlich ebenso für nachträgliches Ändern des Usernamens oder Passwortes.

Betrieb

Der Zugriff auf die API von Viessmann ist aktuell auf 1450 pro Tag in der gratis Version beschränkt, daraus ergibt sich ein Maximum von ca. einer Abfrage pro Minute. Die Anzahl der Zugriffe ist im Entwicklerportal einsehbar: https://developer.viessmann.com/de/clients/history

Readings

Mapping

Im neuen Modul kann man per Attribut auswählen, wie die Readings dargestellt werden sollen. Es gibt drei Möglichkeiten:

  1. Raw Readings: Die Readings werden im API-Format abgelegt.
  2. Altes SVN Mapping: Die Readings werden wie im alten Modul auf Namen gemappt.
  3. "Roger Mapping": Die Readings werden wie in den Zwischenversionen von Roger in diesem Forenbeitrag gemappt.

Die Mappings sind passend zur aktuellen API. Ein Mapping lässt jedoch immer Raum für falsche Namen oder ein falsches Mapping, sollte Viessmann einen Namen in der API ändern.

Das Mapping der Readings hat auch einen Einfluss beim Setzen von Werten der Anlage. Das heißt, sie müssen korrekt zurückgemappt werden.

Deshalb empfehle ich, die Möglichkeit 1 zu nutzen. Bei Raw Readings findet kein Mapping statt; es werden die originalen API-Namen von Viessmann verwendet. Man kann mit diesen Namen auch im Viessmann-Forum anfragen oder sogar bei anderen SmartHome-Plattformen. Sollte sich ein Wert der Viessmann API ändern, wird er bei Raw Readings direkt als neues Reading auftauchen. Auch beim Setzen von Werten der Anlage können direkt diese Raw Readings verwendet werden.

Aus Kompatibilitätsgründen verwendet das Modul jedoch standardmäßig das SVN Mapping.

Um dies zu ändern, gibt es folgende Attribute am Modul:

  • vitoconnect_mapping_roger
  • vitoconnect_raw_readings

Setzt man keines der Attribute, wird das SVN Mapping verwendet. Setzt man eines der beiden Attribute auf 1, wird dieses Mapping verwendet.

Wie oben erklärt, empfehle ich die Einstellung vitoconnect_raw_readings = 1.

Weiter unten die Beschreibung des SVN Mappings. Zum Roger Mapping gibt es keine Aufstellung, es ähnelt aber stark dem SVN Mapping.

Raw Readings müssen nicht erklärt werden; die Beschreibung der Datenpunkte kann hier bei Viessmann gefunden werden: http://documentation.viessmann.com/static/iot/data-points.

altes SVN Mapping


Settings

Set Befehle

Allgemein

Name Datentyp/
Wertebereich
Beschreibung
update löst ein Update der Reading zwischen manuell aus
clearReadings clear all readings immeadiatlely
password <passwd> String store password in key store
logResponseOnce dumps the json response of Viessmann server to entities.json, gw.json, actions.json in FHEM log directory
apiKey <clientID> String set the viessmann clientID, see define device
selectDevice in case of more then one viessmann devic, select the device to be used

Benutzung der Set-Befehle auf eigenes Risiko!

Die set Befehle stehen je nach Mapping und Anlagen Konfiguration zur Verfügung.

Bei vitoconnect_raw_readings haben die set Befehle die selben Namen wie die Readings und sind somit selbst erklärend oder über die Viessmann Doku nachzuschauen: http://documentation.viessmann.com/static/iot/data-points.

Bei SVN oder Roger Mapping sind die Namen gemappt.

Liste einiger SVN set Befehl