viessmann
Das Viessmann-Plugin ermöglicht die Verbindung zu einer Viessmann-Heizung über einen IR-Adapter (z.B. Optolink oder Nachbauten, wie im OpenV-Wiki beschrieben) und das Lesen und Schreiben von Parametern der Heizung. Derzeit sind das P300- und das KW-Protokoll unterstützt. Weitere Gerätetypen, die diese Protokolle unterstützen, können einfach hinzugefügt werden. Für weitere Protokolle (z.B. GWG) wird zusätzliche Entwicklungsarbeit notwendig sein.
Details zu den betroffenen Geräten und Protokollen finden sich im OpenV Wiki
Dieses Plugin nutzt eine separate Datei commands.py, in der die Definitionen für Protokolle, Gerätetypen und Befehlssätze enthalten sind. Neue Geräte können hinzugefügt werden, indem die entsprechenden Informationen in der commands.py ergänzt werden.
Das Plugin unterstützt die serielle Kommunikation mit dem Lesekopf (ggf. über einen USB-Seriell-Adapter).
Zur Identifizierung des Heizungstyps kann das Plugin auch im Standalone-Modus betrieben werden (s.u.)
Changelog
1.2.2
Funktion zum manuellen Schreiben von Werten hinzugefügt
1.2.0
Komplette Überarbeitung von Code und Webinterface (AJAX)
Code refaktorisiert und besser strukturiert
Funktion zum Lesen mehrerer Werte gleichzeitig im KW-Protokoll
Verbesserte Fehler- und Locking-Behandlung
Funktionen zum manuellen Auslesen von konfigurierten und unbekannten Adressen, z.B. zum Testen von Adressen
Webinterface mit der Möglichkeit, Adressen manuell auszulesen
1.1.0
Unterstützung für das KW-Protokoll
1.0.0
Erste Version
Anforderungen
Das Plugin benötigt die pyserial-Bibliothek und einen seriellen IR-Adapter.
Unterstützte Geräte
Jede Viessmann-Heizung mit Optolink-Anschluss wird grundsätzlich unterstützt.
Derzeit sind Gerätekonfigurationen (Befehlssätze) für die folgenden Type verfügbar:
V200KO1B
V200HO1C
V200KW2
V200WO1C
Weitere Gerätetypen können problemlos hinzugefügt werden, wenn die entsprechenden Befehlsadressen bekannt sind.
Konfiguration
Diese Plugin Parameter und die Informationen zur Item-spezifischen Konfiguration des Plugins sind unter Plugin ‚viessmann‘ Konfiguration beschrieben.
plugin.yaml
viessmann:
protocol: P300
plugin_name: viessmann
heating_type: V200KO1B
serialport: /dev/ttyUSB_optolink
items.yaml
Die Verknüfpung von SmartHomeNG-Items und Heizungsparametern ist vollständig flexibel und konfigurierbar. Mit den Item-Attributen kann das Verhalten des Plugins festgelegt werden.
Die folgenden Attribute werden unterstützt:
viess_read
Der Wert des angegebenen Parameters wird gelesen und dem Item zugewiesen.
item:
viess_read: Raumtemperatur_Soll_Normalbetrieb_A1M1
viess_send
Der angegebene Parameter wird bei Änderungen an diesem Item an die Heizung gesendet.
item:
viess_send: Raumtemperatur_Soll_Normalbetrieb_A1M1
Sofern das Item sowohl zum Lesen als auch zum Schreiben eines Parameters konfiguriert wird, kann die vereinfachte Konfiguration mit true erfolgen:
item:
viess_read: Raumtemperatur_Soll_Normalbetrieb_A1M1
viess_send: true
viess_read_afterwrite
Wenn dieses Attribut mit einer Dauer in Sekunden angegeben ist, wird nach eine Schreibvorgang die angegebene Anzahl an Sekunden gewartet und ein erneuter Lesevorgang ausgelöst.
Damit dieses Attribut verwendet werden kann, muss das Item sowohl die Attribute viess_read als auch viess_send enthalten.
item:
viess_read: Raumtemperatur_Soll_Normalbetrieb_A1M1
viess_send: true
viess_read_afterwrite: 1 # seconds
viess_read_cycle
Mit einer Angabe in Sekunden wird ein periodisches Lesen angefordert. viess_read muss zusätzlich konfiguriert sein.
item:
viess_read: Raumtemperatur_Soll_Normalbetrieb_A1M1
viess_read_cycle: 3600 # every hour
viess_init
Wenn dieses Attribut vorhanden und auf true gesetzt ist, wird das Item nach dem Start von SmartHomeNG einmalig gelesen.
viess_read muss zusätzlich konfiguriert sein.
item:
viess_read: Raumtemperatur_Soll_Normalbetrieb_A1M1
viess_init: true
viess_trigger
Enthält eine Liste von Parametern. Wenn dieses Item aktualisiert wird, wird ein Lesevorgang für jeden Eintrag in der Liste angestoßen. viess_send muss zusätzlich konfiguriert sein.
Zwischen dem Schreibvorgang und den folgenden Lesevorgängen ist standardmäßig eine Verzögerung von 5 Sekunden eingestellt. Diese kann mit viess_trigger_afterwrite verändert werden.
Beispiel: wenn der Betriebsmodus geändert wird, können neue Sollwerte für Raum- und Wassertemperaturen gelesen werden.
item:
viess_send: Betriebsart_A1M1
viess_trigger:
- Raumtemperatur_Soll
- Wassertemperatur_Soll
viess_trigger_afterwrite
Wenn ein viess_trigger konfiguriert ist, kann mit diesem Attribut die Verzögerung zwischen Schreib- und Lesevorgang verändert werden.
Standardmäßig beträgt diese Verzögerung 5 Sekunden.
item:
viess_send: Betriebsart_A1M1
viess_trigger:
- Raumtemperatur_Soll
- Wassertemperatur_Soll
viess_trigger_afterwrite: 10 # seconds
viess_update
Das Zuweisen von true an ein Item mit diesem Attribut löst den Lesevorgang aller konfigurierter Items mit viess_read aus.
Der in der Itemkonfiguration angegebene Wert wird nicht ausgewertet.
item:
viess_update: 'egal'
viess_timer
Das Item mit diesem Attribut übergibt als Attributwert den Namen einer Anwendung, z.B. Heizkreis_A1M1, und das Plugin gibt ein UZSU-formatiertes dict mit allen zugehörigen Timern der Heizung zurück Beim Schreiben wird das UZSU-dict in die einzelnen Tagestimer aufgeteilt und an die Heizung gesendet.
item:
viess_timer: 'Heizkreis_A1M1'
viess_ba_list
Das Item mit diesem Attribut erhält einmalig beim Start des Plugins die Liste der für den konfigurierten Heizungstyp gültigen Betriebsarten.
Diese kann z.B. in SmartVISU wie folgt eingebunden werden:
item:
viess_ba_list: 'egal'
{{ basic.select('heizen_ba_item', 'heizung.betriebsart', 'menu', '', '', '', '', '', 'heizung.ba_list') }}
Dies erzeugt eine („Menü“-) Auswahlliste, aus der die Betriebsart ausgewählt werden kann, die dann vom Plugin an die Heizung übergeben wird.
Beispiel
Here you can find a configuration sample using the commands for V200KO1B:
viessmann:
viessmann_update:
name: Update aller Items mit 'viess_read'
type: bool
visu_acl: rw
viess_update: 1
enforce_updates: true
autotimer: 1 = false = latest
allgemein:
aussentemp:
name: Aussentemperatur
type: num
viess_read: Aussentemperatur
viess_read_cycle: 300
viess_init: true
database: true
aussentemp_gedaempft:
name: Aussentemperatur
type: num
viess_read: Aussentemperatur_TP
viess_read_cycle: 300
viess_init: true
database: true
kessel:
kesseltemperatur_ist:
name: Kesseltemperatur_Ist
type: num
viess_read: Kesseltemperatur
viess_read_cycle: 180
viess_init: true
database: init
kesseltemperatur_soll:
name: Kesselsolltemperatur_Soll
type: num
viess_read: Kesselsolltemperatur
viess_read_cycle: 180
viess_init: true
abgastemperatur:
name: Abgastemperatur
type: num
viess_read: Abgastemperatur
viess_read_cycle: 180
viess_init: true
database: init
heizkreis_a1m1:
betriebsart:
betriebsart_aktuell:
name: Aktuelle_Betriebsart_A1M1
type: str
viess_read: Aktuelle_Betriebsart_A1M1
viess_read_cycle: 3600
viess_init: true
betriebsart:
name: Betriebsart_A1M1
type: num
viess_read: Betriebsart_A1M1
viess_send: true
viess_read_afterwrite: 5
viess_init: true
cache: true
enforce_updates: true
viess_trigger:
- Aktuelle_Betriebsart_A1M1
struct: viessmann.betriebsart
visu_acl: rw
sparbetrieb:
name: Sparbetrieb_A1M1
type: bool
viess_read: Sparbetrieb_A1M1
viess_send: true
viess_read_afterwrite: 5
viess_trigger:
- Betriebsart_A1M1
- Aktuelle_Betriebsart_A1M1
viess_init: true
visu_acl: rw
schaltzeiten:
montag:
name: Timer_A1M1_Mo
type: list
viess_read: Timer_A1M1_Mo
viess_send: true
viess_read_afterwrite: 5
viess_init: true
struct: viessmann.timer
visu_acl: rw
dienstag:
name: Timer_A1M1_Di
type: list
viess_read: Timer_A1M1_Di
viess_send: true
viess_read_afterwrite: 5
viess_init: true
struct: viessmann.timer
visu_acl: rw
ferienprogramm:
status:
name: Ferienprogramm_A1M1
type: num
viess_read: Ferienprogramm_A1M1
viess_read_cycle: 3600
viess_init: true
starttag:
name: Ferien_Abreisetag_A1M1
type: str
viess_read: Ferien_Abreisetag_A1M1
viess_send: true
viess_read_afterwrite: 5
viess_init: true
visu_acl: rw
eval: value[:10]
endtag:
name: Ferien_Rückreisetag_A1M1
type: str
viess_read: Ferien_Rückreisetag_A1M1
viess_send: true
viess_read_afterwrite: 5
viess_init: true
visu_acl: rw
Funktionen
update_all_read_items()
Diese Funktion stößt den Lesevorgang aller konfigurierten Items mit viess_read-Attribut an.
read_addr(addr)
Diese Funktion löst das Lesen des Parameters mit der übergebenen Adresse addr aus. Die Adresse muss als vierstellige Hex-Zahl im String-Format übergeben werden. Es können nur Adressen ausgelesen werden, die im Befehlssatz für den aktiven Heizungstyp enthalten sind. Unabhängig von der Itemkonfiguration werden durch read_addr() keine Werte an Items zugewiesen.
Der Rückgabewert ist das Ergebnis des Lesevorgangs oder None, wenn ein Fehler aufgetreten ist.
read_temp_addr(addr, length, unit)
Diese Funktion versucht, den Parameter an der Adresse addr zu lesen und einen Wert von length Bytes in die Einheit unit zu konvertieren. Die Adresse muss als vierstellige Hex-Zahl im String-Format übergeben werden, im Gegensatz zu read_addr() aber nicht im Befehlssatz definiert sein. length ist auf Werte zwischen 1 und 8 (Bytes) beschränkt. unit muss im aktuellen Befehlssatz definiert sein.
Der Rückgabewert ist das Ergebnis des Lesevorgangs oder None, wenn ein Fehler aufgetreten ist.
write_addr(addr, value)
Diese Funktion versucht, den Wert value an die angegebene Adresse zu schreiben. Die Adresse muss als vierstellige Hex-Zahl im String-Format übergeben werden. Es können nur Adressen beschrieben werden, die im Befehlssatz für den aktiven Heizungstyp enthalten sind. Durch write_addr werden Itemwerte nicht direkt geändert; wenn die geschriebenen Werte von der Heizung wieder ausgelesen werden (z.B. durch zyklisches Lesen), werden die geänderten Werte in die entsprechenden Items übernommen.
Warnung
Das Schreiben von beliebigen Werten oder Werten, deren Bedeutung nicht klar ist, kann im Heizungsgerät möglicherweise unerwartete Folgen haben. Auch eine Beschädigung der Heizung ist nicht auszuschließen.
Hinweis
Wenn eine der Plugin-Funktionen in einer Logik verwendet werden sollen, kann dies in der folgenden Form erfolgen:
result = sh.plugins.return_plugin('viessmann').read_temp_addr('00f8', 2, 'DT')
Web Interface
Im Web-Interface gibt es neben den allgemeinen Statusinformationen zum Plugin zwei Seiten.
Auf einer Seite werden die Items aufgelistet, die Plugin-Attributen konfiguriert haben. Damit kann eine schnelle Übersicht über die Konfiguration und die aktuellen Werte geboten werden.
Auf der zweiten Seite werden alle im aktuellen Befehlssatz enthaltenen Parameter aufgelistet. Dabei besteht für jeden Wert einzeln die Möglichkeit, einen Lesevorgang auszulösen. Die Rückgabewerte werden in die jeweilige Tabellenzeile eingetragen. Dieser entspricht der Funktion read_addr(), d.h. es werden keine Item-Werte aktualisiert.
Weiterhin kann in der Zeile für den Parameter „_Custom“ eine freie Adresse angegeben werden, die analog zur Funktion read_temp_addr() einen Lesevorgang auf beliebigen Adressen erlaubt. Auch hier wird der Rückgabewert in die jeweilige Tabellenzeile eingetragen. Damit wird ermöglicht, ohne großen Aufwand Datenpunkte und deren Konfiguration (Einheit und Datenlänge) zu testen.
Standalone-Modus
Wenn der Heizungstyp nicht bekannt ist, kann das Plugin im Standalone-Modus (also ohne SmartHomeNG zu starten) genutzt werden. Es versucht dann, mit der Heizung zu kommunizieren und den Gerätetyp zu identizifieren.
Dazu muss das Plugin im Plugin-Ordner direkt aufgerufen werden:
./__init__.py <serieller Port> [-v]
Der serielle Port ist dabei die Gerätedatei bzw. der entsprechende Port, an dem der Lesekopf angeschlossen ist, z.B. /dev/ttyUSB0. Dieses Argument ist verpflichtend.
Das optionale zweite Argument -v weist das Plugin an, zusätzliche Debug-Ausgaben zu erzeugen. Solange keine Probleme beim Aufruf auftreten, ist das nicht erforderlich.
Sollte die Datei sich nicht starten lassen, muss ggf. der Dateimodus angepasst werden. Mit chmod u+x __init__.py kann die z.B. unter Linux erfolgen.