-
Notifications
You must be signed in to change notification settings - Fork 26
032 Command Line Arguments
Es wird genau eine Kommunikations-Schnittstelle angegeben, über die Open3E Daten überträgt. Wird keines der beiden Argumente angegeben, so wirkt das Default CAN Kommunikation an can0.
Bei Benutzung eines CAN Adapters wird hier der Name des CAN Device angegeben, so wie er von ifconfig ausgegeben wird. Gewöhnlich ist das 'can0', so das Interface nicht vorher umbenannt wurde. Also z.B.
-c can0
Seit neuestem ist 'can0' als Default programmiert, man kann es also komplett weg lassen, wenn man den Interface-Kanal 'can0' verwendet.
Dieses Argument muss angegeben werden, wenn statt eines CAN Adapters eine Verbindung per Access Point Modus des E3 Gerätes hergestellt werden soll. In diesem Fall ist die entsprechende IP Adresse anzugeben, also bsw.
-d 192.168.12.34
Diese Option überschreibt die Angabe eines CAN Interfaces, wenn -d angegeben wurde, wird auf jeden Fall versucht, eine DoIP Verbindug herzustellen.
Mit diesem Argument zeigt man Open3E an, dass Datenpunkte ausgelesen werden sollen. Hierzu wird die Nummer des Datenpunktes - der Data Identifier (DID) hinter dem -r angegeben. Soll die BusIdentification des Führungsgerätes gelesen werden, schreibt man
-r 256
Es können mehrere zu lesende Datenpunkte mit Komma getrennt benannt werden. Möchte man ein paar DIDs auslesen, lautet die Angabe bsw.
-r 257,258,259,260
Soll von einem anderen als dem Führungsgerät (also von einer von der Default ECU Adresse abweichenden Adresse) gelesen werden, so muss diese Adresse per Punkt getrennt vorangestellt werden, bsw.
-r 0x68C.256 oder gleichbedeutend -r 1676.256
Mit diesem Argument wird Open3e angewiesen, einen Wert auf einen Datenpunkt zu schreiben. Bislang müssen hierbei hexadezimale Raw-Werte verwendet werden, es muss also gleichzeitig die Option -raw gesetzt sein. Soll der DomesticHotWaterTemperatureSetpoint (DID 396) auf 47°C geschrieben werden, lautet das Kommandozeilenargument hierfür
-raw -w 396=D601
Der DID 396 ist ein 16bit Integer Wert in 1/10°C (scale=10): 47,0°C -> 470 -> 0x01D6 Das Ganze ist dann auch noch lsb..msb, also muss der Wert D601 geschrieben werden.
Noch komplizierter wird es bei komplexen Datenpunkten, also bei DIDs, die mehr als nur einen Wert beinhalten. Hier muss zunächst der Wert ausgelesen werden, dann die zu ändernden Bytes angepasst und der geänderte Wert dann komplett geschrieben werden.
DID 2855, MixerOneCircuitFrostProtectionConfiguration, enthält zunächst ein Byte (wahrscheinlich ein Modus) und dahinter die Temperaturgrenze zur Pumpenansteuerung, die wieder wie oben aufgebaut ist, als 1/10°C 2-Byte Int Wert. Per Default steht die Grenze auf +3°C, man wird also wahrscheinlich 011E00 auslesen.
-9.0°C -> -90 -> 0xFFA6 -> A6FF lsb..msb
Das erste Byte wird unverändert übernommen, damit ergibt sich dann das Kommando zum Schreiben der Frostschutzgrenze auf -9°C
-raw -w 2855=01A6FF
Soll auf eine andere als die Default-ECU Adresse geschrieben werden, so muss diese durch Punkt getrennt dem DID vorangestellt werden:
-raw -w 0x6A1.927=02
Es kann immer nur ein Datenpunkt pro Aufruf geschrieben werden. Schreiben kann nicht zusammen mit einer anderen Funktion (Lesen, MQTT Listen) verwendet werden.
Bei vielen Datentypen ist inzwischen auch das Schreiben von 'Klarwerten' implementiert. Gegebenfalls man in die codecs.py schauen.
Wenn eine andere als die Default ECU Adresse angesprochen werden soll, so muss diese, wie oben bereits erwähnt, mittels eines Punktes getrennt dem DID vorangestellt werden. Hexadezimale und dezimale Schreibweise der ECU Adresse ist möglich
0x68C.256 oder gleichbedeutend 1676.256
Es kann auch eine Liste von DIDs von einer (non-default) ECU Adresse gelesen werden:
-r 0x68C.[257,259,261]
Die komplexen Adressierungen können auch kombiniert werden:
-r 256,257,396,0x68C.[257,259,261],1697.327
Mit diesem Argument wird bewirkt, dass die in der Read List (-r ...) aufgeführten Datenpunkte zyklisch gelesen und ausgegeben werden. Die Zykluszeit wird in Sekunden angegeben:
-r 268,269 -t 10
Die Ausgabe erfolgt gewöhnlich in dem Konsolenfenster. Wenn die MQTT Option gesetzt ist, werden die Daten zum MQTT Empfänger gesendet.
Das Setzen dieser Option bewirkt, dass alle Datenpunkte ausgelesen und ausgegeben werden. Hierbei wird anhand der zugrundeliegenden Datenpunktlisten vorgegangen. Diese sind entweder in der Konfigurationsdatei (gewöhnlich devices.json) benannt oder bei Verwendung der -dev Option wird die entsprechende Open3EdatapointsXyz.py benutzt, wobei 'Xyz' der Angabe hinter dem -dev entspricht.
Normalerweise, ohne einen der Optionen -raw oder -j, wird für jeden Sensor im DID ein Blatt im MQTT-Baum erzeugt. z.B.
open3e/688_376_MassFlowSensor/Actual = 16.0
open3e/688_376_MassFlowSensor/Minimum = 0.0
open3e/688_376_MassFlowSensor/Maximum = 153.1
open3e/688_376_MassFlowSensor/Average = 13.7
open3e/688_376_MassFlowSensor/Error = 0
Wenn das DID nur einen Sensor hat, also nicht komplex oder ein Liste ist, wird auch nur ein Blatt erzeugt. z.B.
open3e/680_627_CentralHeatingOneCircuitName = Heizkreis 1
Erzeugt nur ein Blatt mit dem hexadezimalen Inhalt des gesamten DIDs. z.B.
open3e/688_376_MassFlowSensor = 00000000fb05040000
Erzeugt nur ein Blatt mit dem JSON-formatierten Inhalt des gesamten DIDs. z.B.
open3e/688_376_MassFlowSensor = {"Actual": 16.5, "Minimum": 0, "Maximum": 153.1, "Average": 15.4, "Error": 0}
Erweitert die Ausgabe auf dem Terminal, verändert aber nicht den an den MQTT-Broker gesendeten Inhalt.
Die Angabe dieses Arguments bewirkt, dass die ausgelesenen Daten an einen MQTT Broker gesendet werden, so dass sie von dort aus bsw. in eine Hausautomatisierung weiterverteilt werden. Es wird durch Doppelpunkte getrennt die IP Adresse des Brokers, der Port für MQTT und der MQTT Topic angegeben. Der Topic ist frei definierbar.
-m 192.168.0.1:1883:open3e
Wenn beim MQTT Broker eine Benutzer/rechte/verwaltung aktiviert ist, wird mit diesem Argument Benutzername und Passwort für die Verbindung mit dem Broker angegeben
-muser ichuser:meinpasswrd
Mit dieser Option wird das Format spezifiziert, wie die Identifikation der Informationen für den MQTT Broker dargestellt wird.
-mfstr {ecuAddr:03X}_{device}_{didNumber:04d}_{didName}
bewirkt die Darstellung
- 680_0x680_0256_BusIdentification
Die Sachen hinter dem Doppelpunkt sind Python Formatierungsoptionen für Zahlen. 'X' für hexadezimal, 'd' für dezimale Ganzzahl, '0' für Auffüllen mit führenden Nullen, die Zahl dahinter für die Anzahl Ziffern.
Das 'device' kann in der devices.json auch umbenannt werden, in dem dort der hex Ausdruck vor dem Doppelpunkt und der geschweiften Klammer geändert wird. Wird bsw. "0x680": { geändert in "VitoCal": {, dann erscheint in der MQTT App
- 680_VitoCal_0256_BusIdentification
Es können natürlich auch Angaben ausgelassen werden, bsw.
-mfstr {device}_{didName}
ergibt die Ausgabe
- VitoCal_BusIdentification
Optional kann die MQTT Client-ID festgelegt werden, mit der sich Open3E beim MQTT-Broker anmeldet. Als Default verwendet Open3E die ID "Open3E_xxxxxx", wobei "xxxxxx" jeweils durch den aktuellen Linux Timestamp ersetzt wird. Dadurch ist es möglich, mehrere Open3E-Tasks parallel zu nutzen, denn jede Task meldet sich mit einer anderen Client-ID an.
-mcid Meine-Open3E-Client-ID
Diese Information bewirkt, dass open3e auf Kommandos lauscht, die ihm per MQTT Broker zukommengelassen werden. Damit kann man aus der MQTT App / Hausautomatisierung heraus die Viessmann Geräte auslesen und auch steuern (genauer gesagt Werte von Datenpunkten lesen und schreiben). Hinter dem --listen Argument wird der dafür abonierte Topic angegeben. Der Topic ist frei definierbar.
-l open3e/cmnd
Beispiele für entsprechende MQTT json Strings (Kommandos) finden sich im Readme von open3e.
Ein Viessmann One-Base (E3 Generation) System umfasst gewöhnlich mehrere ECUs. Die folgenden Parameter dienen dazu, Open3E Informationen zu dem System an die Hand zu geben.
Grundsätzlich ist es nicht notwendig, auch nur einen der folgenden Parameter anzugeben. In diesem Fall arbeitet Open3E mit dem kompletten Informationssatz aus Open3Edatapoints.py primär auf die Adresse der MCU (Main Control Unit - Führungsgerät) 0x680. In diesem Fall ist von einem --scanall abzusehen, weil im Zuge eins Solchen früher oder später versucht wird, einen Datenpunkt auszulesen, der bei der angesprochenen ECU nicht existiert. Gewöhnlich steigt Open3E dann mit der Fehlermeldung 'Conditions not correct - 22h' aus.
-dev vcal oder auch -dev _68a bewirkt, dass die Open3EdatapointsVcal.py oder die (von depictSystem erstellte) Open3Edatapoints_68a.py als Datenpunktliste (Overlay) benutzt wird.
-tx 68c bewirkt, dass die Default ECU Adresse statt der MCU Adresse 680h auf die Adresse 68Ch geändert wird.
cnfg devices.json bewirkt, dass die Informationen über die Struktur der Anlage der angegebenen Datei im json Format entnommen wird. cnfg dev ist Kurzform von cnfg devices.json, jede andere Datei muss explizit benannt werden und im entsprechenden json Format vorliegen. Bei Angabe der Option cnfg wird die Option -dev ignoriert.
Die Datei sieht bsw. so aus:
{
"0x680": {
"tx": "0x680",
"dpList": "Open3Edatapoints_680.py",
"prop": "HPMUMASTER"
},
"0x684": {
"tx": "0x684",
"dpList": "Open3Edatapoints_684.py",
"prop": "HMI"
},
"0x68c": {
"tx": "0x68c",
"dpList": "Open3Edatapoints_68c.py",
"prop": "VCMU"
},
"0x6c3": {
"tx": "0x6c3",
"dpList": "Open3Edatapoints_6c3.py",
"prop": "BACKENDGATEWAY"
},
"0x6c5": {
"tx": "0x6c5",
"dpList": "Open3Edatapoints_6c5.py",
"prop": "BACKENDGATEWAY"
},
"0x6cf": {
"tx": "0x6cf",
"dpList": "Open3Edatapoints_6cf.py",
"prop": "EHCU"
}
}
- mit "tx" wird die ECU Adresse angegeben
- mit "dpList" wird das zugehörige Datapoint-Overlay angegeben
- bei "prop" steht die mit der Bus Identification ausgelesene Property der ECU
Der 'Main Topic' ("0x680": { ...) ist per Default die Adresse der ECU. Er kann auch umbenannt werden bsw. in "VitoCal": { .... Dann taucht bei MQTT unter {device} 'VitoCal' auf, und bei komplexer Adressierung kann man dann auch -r VitoCal.256 benutzen.
Den Namen der dpList kann man auch sprechend gestalten, das muss dann aber in der json Datei wie mit der Overlay Liste gleichermassen geschehen.
Die Funktion der Kommandozeilen-Argumente zur Bestimmung der Kommunikations-Schnittstelle ist identisch mit der beim Open3EClient.
Durch das Setzen dieser Option wird das Schreiben der sowieso ausgelesenen Daten in die Dateien virtdata_6yz.txt aktiviert. Diese Dateien ermöglichen, die virtualE3 mit einem realen Datensatz (Snapshot) zu erfüllen. Dies ist zu unterschiedlichen Simulations- und weiteren Zwecken der Erkenntnisgewinnung nützlich.
Wer das Entwickeln von Open3E unterstützen möchte, setzt diesen Schalter und sendet den gesamten Datensatz, bestehend aus den Dateien devices.json, Open3Edatapoints_6**.py und virtdata_6**.txt sowie einer kurzen Beschreibung des Systems (verbaute Komponenten, Busverbindungen), an die Entwickler. Bitte schickt die Dateien an open3e/at/web.de
ACHTUNG: Ladet die Dateien, speziell die virtdata_*.txt NICHT irgendwo öffentlich zugänglich hoch, da die Dateien ggf. Angaben wie Seriennummern, SSIDs und weitere persönliche oder der DSGVO unterliegende Daten enthalten/können.
Das Setzen des Schalters erfolgt durch einfaches Aufführen in der Kommandozeile.
python3 Open3E_depictSystem.py -s
Wir, das Entwicklerteam, versichern die absolut vertrauliche Behandlung Euer Daten. Wer die Daten(inhalte) nicht teilen möchte, lässt die virtdata_6**.txt weg und schickt uns nur die devices.json und die Open3Edatapoints_6**.py. Danke! Phil