====== Vitoconnect ======

++++ Version History...|

**Version 0.1.4**

  * **Added some values to SET**\\

heating.circuits.0.heating.curve\\  heating.circuits.1.heating.curve\\  heating.dhw.temperature.hysteresis\\  heating.circuits.0.operating.programs.comfort\\  heating.circuits.1.operating.programs.comfort

  * **Changed** heating.dhw.temperature to heating.dhw.temperature.main

**Version 0.1.2**

  * New Viessmann API integrated
  * Code partly reworked
  * [[https://loxwiki.atlassian.net/wiki/people/70121:a4903b1c-0127-4574-9b49-33290ff324a2?ref=confluence|Fabian Franzmann]]took over maintenance from [[https://loxwiki.atlassian.net/wiki/people/6166fc69198b4f0068f17eba?ref=confluence|Thomas Galland]](Vielen Dank für die Basis!)

**Version 0.0.8**

  * Added parameter "ventilation.schedule" for writing

**Version 0.0.6**

  * Added parameter heating.dhw.temperature.temp2 for writing

**Version 0.0.5**

  * Übernahme des CronJobs bei Update
  * Anzeige der WLAN Verbindungsqualität des Vitoconnect 100 Optolink Adapters

**Version 0.0.4**

  * Automatische Sicherung / Wiederherstellung der Config Datei bei Upgrade

**Version 0.0.3**

  * Es können nun auch Befehle an die Heizung gesendet werden.  

**Version 0.0.2**

  * Übermittlung des Gesamtstatus der Anlage und Zeitstempels der Datenübertragung\\

Neue Werte:\\  aggregatedstatus\\  timestamp

  * Automatische Updates wurden aktiviert
  * Bei den Fehlerwerten\\

heating.errors.active.entries und heating.errors.history wird wenn kein Fehler vorliegt von Viessmann ein leeres Array übermittelt.\\  Dies bereitet Probleme, da von MQTT nur Änderungen übertragen werden. Bei leeren Werten bleibt ein alter Fehler im Topic stehen.\\  Daher werden wenn alles ok vordefinierte Werte übertragen

**Version 0.0.1**

  * erste öffentliche Version\\

unterstützt das Lesen der übermittelten Daten.\\  Getestet mit Vitodens 200 / Vitoconnect 100

++++

----

===== Prämbel =====

  * Sollte Viessmann  die API ändern, kann es zu fehlenden Daten bzw. im schlimmsten Fall zu einem Ausfall des Plugins kommen
  * Es ist mein erstes Plugin für Loxberry. Von daher bitte um Nachsicht bei eventuellen Fehlern
  * das Plugin wurde mit Unterstützung folgender Quellen erstellt:
    * FHEM Plugin 98_vitoconnect.pm von andreas13 [[https://wiki.fhem.de/wiki/Vitoconnect]]
    * Viessmann-Api von TheTrueAvatar [[https://github.com/thetrueavatar/Viessmann-Api]]

===== Download =====

Das Plugin ist auf Github veröffentlicht und kann direkt von dort bezogen werden

[[https://github.com/eloka080677/loxberry_vitoconnect/archive/0.0.5.zip|S]]iehe Download Sektion im Header

[[https://github.com/challo2018/LoxBerry-Plugin-Vitoconnect]]

===== Funktion des Plugins =====

Nach Installation des Plugins ist eine Ersteinrichtung erforderlich um die Daten von Viessmann abrufen zu können bzw. die Daten per MQTT / HTML übermitteln zu können.

Für die Nutzung ist ein Viessmann Developer Portal Konto erforderlich. Im Plugin muss das dazugehörige Benutzerkonto (E-Mail Adresse), Kennwort sowie ein API-Key hinterlegt werden.

Aufgrund der Menge der übermittelten Daten wird eine Nutzung des MQTT Plugins von [[https://loxwiki.atlassian.net/wiki/people/6166fb1fc5388b0069f9351f?ref=confluence|Christian Fenzl]] empfohlen. 

Es sollte immer nur eine Übermittlungsart (MQTT oder HTML) aktiv sein.

Das Abholen der Daten kann entweder manuell über einen virtuellen Ausgang im Miniserver oder aber automatisiert per CRON Job erfolgen.

===== Konfigurationsoptionen (Registerkarte Settings) =====

{{plugins:vitoconnect:1279557624.png?900}}

Die Konfigurationsdatei am Loxberry wird erst nach dem ersten Aufrufen der Settings Seite und Abspeichern erstellt und abgespeichert (JSON Format)

==== Viessmann Online Anmeldedaten ====

  * Benutzeraccount für das [[https://developer.viessmann.com/|Viessmann Developer Portal]] erstellen.
  * API-Key anlegen:\\

{{plugins:vitoconnect:1277362191.png?500}}

  * **WICHTIG: "Google reCAPTCHA" Schutz deaktivieren da es aktuell keine Möglichkeit gibt das Captcha zu lösen**
  * Client ID kopieren und im Loxberry Plugin als "API-KEY" einfügen

==== Cron Job aktivieren ====

  * bei aktiviertem CronJob, kann das Aktualisierungsinterval angegeben werden:
    * 1 min
    * 5 min
    * 10 min
    * 15 min
    * 30 min 
    * 60min
  * Aktuell erlaubt Viessmann 1450 Anfragen in 24 Stunden.  Jeder get/set Data Zyklus enthält momentan 2 API-Zugriffe.

==== Datenübermittlung per MQTT ====

  * Wenn du das [[https://www.loxwiki.eu/display/LOXBERRY/MQTT+Gateway|MQTT Gateway Plugin ]][[https://www.loxwiki.eu/display/LOXBERRY/MQTT+Gateway| ]]installiert hast, sind keine weiteren Daten zwingend erforderlich und die Felder können leer gelassen werden
    * Base Topic:  vitoconnect (default, wenn Feld leergelassen wird)
    * Broker Hostname:Port: 127.0.0.1:1883(default, wenn Feld leergelassen wird)
    * Broker Username: wird automatisch aus dem MQTT Plugin ausgelassen (default)
    * Broker  Passwort: wird automatisch aus dem MQTT Plugin ausgelassen (default)
  * Die Angabe des Base Topics erfolgt ohne führendem und abschließendem Schrägstrich, z.B. ''%%vitoconnect%%''
  * Die Daten der Viessmann Installation können am Tab //Query links and data// angesehen werden.

**Wichtig:** Bevor das VitoConnect Plugin die Daten an das MQTT Plugin senden kann, muss unter den "Subscriptions" im MQTT Plugin das "Base Topic" des Vitoconnect Plugins hinterlegt werden.\\  Default Base Topic: vitoconnect => Subscription: vitoconnect /#.

{{plugins:vitoconnect:1244332395.png?250}}

Viessmann übermittelt einige Werte z.B. Zeiträume für Eco-/Normalbetrieb oder aber den aktuellen/vergangenen Fehlerstatus als Array zurück.

Damit dieses Array bei MQTT aufgelöst und die Daten als Einzelwerte übertragen werden, muss im MQTT Plugin in den Einstellungen zwingend der Haken "**//Expand JSON Data//**" aktiviert werden

{{plugins:vitoconnect:1244332400.png?600}}

==== Datenübermittlung HTTP ====

  * Den Miniserver anwählen.
  * Den Cache kannst du am Anfang zum Einrichten ausschalten (→ "No Cache"), du solltest ihn aber danach einschalten (→ "Cache").
  * Die Daten werden an virtuelle Eingänge (VI) bzw. virtuelle Texteingänge (VIT) gesendet. Diese VI's/VIT's musst du selbst anlegen. Wie diese heißen, findest du auf dem Tab //Query links and data//\\ // (Es werden nur die Daten übertragen, welche unter Installationsdaten Detail angezeigt werden)//

===== Daten (Registerkarte Query Links and data) =====

Anzeige des Links zum manuellen antriggern des Datenabholens (bei deaktivierten CronJob)

Anzeige der allgemeinen Installationsinformation:

{{plugins:vitoconnect:1244332262.png?800}}

Anzeige der detaillierten Installationsinformation: (Ausschnitt)

{{plugins:vitoconnect:1244332263.png?800}}

===== Einrichtung in der Loxone Config Software =====

siehe Download im Anhang.

==== Übertragung per MQTT: ====

Für die Einrichtung der virtuellen Eingänge für MQTT siehe: [[konfiguration:widget_help:widget_mqtt:mqtt_gateway:mqtt_schritt_fur_schritt_mqtt_loxone|MQTT - Schritt für Schritt: MQTT -> Loxone]]

Für jeden zu übertragenden Wert ist ein virtueller Eingang in LoxConfig anzulegen.\\  Abhängig davon welche Werte übertragen werden sollen, ist ein virtueller Eingang ( Boolean, Zahlen) oder ein virtueller Texteingang (String) nötig.\\  Werden Zahlen übertragen (Ganzzahlen oder Gleitkomma) so ist im virtuellen Eingang der Haken bei "Als Digitaleingang verwenden" zu entfernen

Der Name (Bezeichnung) des Eingangs ist der Name des MQTT Topic (Siehe MQTT Plugin → Incoming View)

Unter Beschreibung kann ein sprechender Name für die Darstellung in der App/Webseite vergeben werden

{{plugins:vitoconnect:1244332331.png?250}}

==== Beispiele für relevante Werte: ====

| MQTT Topic  | Beschreibung  |
| vitoconnect_aggregatedstatus  | Umschreibung für den Gesamtstatus  (WorksProperly = Alles in Ordnung)  |
| vitoconnect_aggregatedstatus_ok | Binärer Wert. Wenn 1, dann OK. 0 Sonst. |
| vitoconnect_timestamp  | Zeitpunkt der Datenübermittlung  |
| vitoconnect_timestamp_latestdata_lox | Loxone Epochtime (Sekunden seit 2009) des aktuellsten Timestamps in den Daten. Jedes Datum hat einen eigenen Timestamp, manche dieser Timestamps ändern sich häufiger als andere. So kann man erkennen, wenn die Daten insgesamt veraltet sind. |
| vitoconnect_heating_circuits_0_operating_modes_active_value  | aktueller Betriebsmodus\\ forcedNormal = Dauerbetrieb Normal\\ forcedReduces= Dauerbetrieb Reduzierte Temperatur / Eco\\ dhwAndHeating =Warmwasser und Heizung zeitgesteuert\\ dhw = Warmwasser zeitgesteuert\\ standby= aus |
| vitoconnect_heating_circuits_0_operating_modes_active_value_enum | aktueller Betriebsmodus, als integer basiertes enum (Status Bausteine arbeiten am besten mit Ints, UDP kann auch nur Int). Das gleiche pendant gibt es auch zum setzen der Werte.<code ->
1= standby
2= dhwAndHeating
3= dhw 
4= forcedNormal
5= forcedReduced
</code> |
| vitoconnect_heating_circuits_0_operating_programs_active_value  | Bei zeitgesteuerten Programmen wird hier der aktuelle Modus angezeigt\\ \\ normal = erhöhte Temperatur\\ reduced = reduzierte Temperatur\\ standby = Standby  |
| vitoconnect_heating_dhw_sensors_temperature_hotWaterStorage_value | aktuelle Temperatur im Pufferspeicher für Warmwasser  |
| vitoconnect_heating_dhw_temperature_main_value  | aktuelle Solltemperatur für Warmwasser  |
| vitoconnect_heating_burner_statistics_hours  | aktuelle Betriebsstunden  |
| vitoconnect_heating_burner_statistics_hours_starts  | aktuelle Brennerstarts  |

===== Setzen von Werten per HTTP Ausgangsbefehl: =====

das Setzen von Werten ist über einen HTTP Befehl möglich.

http:%%//%%<lbuser>:<lbpass>@loxberry:80/admin/plugins/Vitoconnect/vitoconnect.php?action=**setvalue**

das gewünschte Feature wird per option=YYY addressiert.

Der zu setzende Wert wird über value=XXX mitgegeben.

Um z.B. die Warmwassertemperatur auf 50 Grad zu setzen wäre der gesamte Befehl dann

http:%%//%%<lbuser>:<lbpass>@loxberry:80/admin/plugins/Vitoconnect/vitoconnect.php?action=**setvalue**&option**=heating.dhw.temperature.main**&value=50

In nachfolgender Tabelle werden die aktuell implementierten Set Befehle näher beschrieben

| Feature  | Description  | Value (Bitte auf korrekte Schreibweise achten, sonst geht es nicht !!!)  |
| heating.dhw.temperature.main  | Warmwassertemperatur  | min. 10\\ \\ max. 60  |
| heating.dhw.temperature.temp2  | Warmwassertemperatur 2  | min. 10\\ \\ max. 60  |
| heating.dhw.temperature.hysteresis  | WW-Hysterese  | min. 10\\ \\ max. 60  |
| heating.circuits.0.operating.modes.active  | Betriebsmodus Heizkreis 1  | forcedNormal\\ \\ forcedReduced\\ \\ dhwAndHeating\\ \\ dhw\\ \\ standby  |
| heating.circuits.1.operating.modes.active  | Betriebsmodus Heizkreis 2  | forcedNormal\\ \\ forcedReduced\\ \\ dhwAndHeating\\ \\ dhw\\ \\ standby  |
| heating.circuits.0.operating.modes.active.enum | Betriebsmodus Heizkreis 1 | <code ->
1=standby
2=dhwAndHeating
3=dhw
4=forcedNormal
5=forcedReduced
</code> |
| heating.circuits.1.operating.modes.active.enum | ,Betriebsmodus Heizkreis 2Int-Basiert | ::: |
| heating.circuits.0.operating.programs.normal | Temperatur Heizkreis 1 Normalbetrieb  | min. 3\\ \\ max. 37  |
| heating.circuits.1.operating.programs.normal | Temperatur Heizkreis 2 Normalbetrieb  | min. 3\\ \\ max. 37  |
| heating.circuits.0.operating.programs.reduced | Temperatur Heizkreis 1 Reduzierter Betrieb  | min. 3\\ \\ max. 37  |
| heating.circuits.1.operating.programs.reduced | Temperatur Heizkreis 2 Reduzierter Betrieb  | min. 3\\ \\ max. 37  |
| heating.circuits.0.operating.programs.comfort | Temperatur Heizkreis 1 Komfortbetrieb  | min. 3\\ \\ max. 37  |
| heating.circuits.1.operating.programs.comfort | Temperatur Heizkreis 2 Komfortbetrieb  | min. 3\\ \\ max. 37  |
| heating.dhw.oneTimeCharge  | Einmalige Aufladung des Warmwasserspeichers (soweit das Modell es unterstützt) | start\\ \\ stop  |
| ventilation.schedule  | Zeitplan Vitovent Lüftungsanlage  | Reduziert:\\ \\ {"mon":[{"start":"00:00","end":"24:00","mode":"reduced","position":0}],"tue":[{"start":"00:00","end":"24:00","mode":"reduced","position":0}],"wed":[{"start":"00:00","end":"24:00","mode":"reduced","position":0}],"thu":[{"start":"00:00","end":"24:00","mode":"reduced","position":0}],"fri":[{"start":"00:00","end":"24:00","mode":"reduced","position":0}],"sat":[{"start":"00:00","end":"24:00","mode":"reduced","position":0}],"sun":[{"start":"00:00","end":"24:00","mode":"reduced","position":0}]}\\ \\ Normal:\\ \\ {"mon":[{"start":"00:00","end":"24:00","mode":"standard","position":0}],"tue":[{"start":"00:00","end":"24:00","mode":"standard","position":0}],"wed":[{"start":"00:00","end":"24:00","mode":"standard","position":0}],"thu":[{"start":"00:00","end":"24:00","mode":"standard","position":0}],"fri":[{"start":"00:00","end":"24:00","mode":"standard","position":0}],"sat":[{"start":"00:00","end":"24:00","mode":"standard","position":0}],"sun":[{"start":"00:00","end":"24:00","mode":"standard","position":0}]}\\ \\ Intensiv:\\ \\ {"mon":[{"start":"00:00","end":"24:00","mode":"intensive","position":0}],"tue":[{"start":"00:00","end":"24:00","mode":"intensive","position":0}],"wed":[{"start":"00:00","end":"24:00","mode":"intensive","position":0}],"thu":[{"start":"00:00","end":"24:00","mode":"intensive","position":0}],"fri":[{"start":"00:00","end":"24:00","mode":"intensive","position":0}],"sat":[{"start":"00:00","end":"24:00","mode":"intensive","position":0}],"sun":[{"start":"00:00","end":"24:00","mode":"intensive","position":0}]}\\ \\ Aus:\\ \\ {"sun":[],"tue":[],"thu":[],"sat":[],"fri":[],"wed":[],"mon":[]} |
| heating.dhw.schedule  | Zeitplan Warmwasser  | Zeitplan:\\ \\ {"mon":[{"start":"05:50","end":"08:30","mode":"top","position":0},{"start":"17:00","end":"22:30","mode":"normal","position":1}],"tue":[{"start":"05:50","end":"08:30","mode":"top","position":0},{"start":"17:00","end":"22:30","mode":"normal","position":1}],"wed":[{"start":"05:50","end":"08:30","mode":"normal","position":0},{"start":"17:00","end":"22:30","mode":"normal","position":1}],"thu":[{"start":"05:50","end":"08:30","mode":"normal","position":0},{"start":"17:00","end":"22:30","mode":"normal","position":1}],"fri":[{"start":"05:50","end":"08:30","mode":"normal","position":0},{"start":"17:00","end":"22:30","mode":"normal","position":1}],"sat":[{"start":"07:30","end":"10:00","mode":"normal","position":0},{"start":"18:00","end":"23:30","mode":"normal","position":1}],"sun":[{"start":"08:00","end":"10:00","mode":"normal","position":0},{"start":"18:00","end":"23:30","mode":"normal","position":1}]}  |
| heating.dhw.pumps.circulation.schedule  | Zeitplan Warmwasser Zirkulationspumpe  | Zeitplan:\\ \\ {"mon":[{"start":"05:40","end":"09:00","mode":"5\/10-cycles","position":0},{"start":"17:00","end":"24:00","mode":"5\/10-cycles","position":1}],"tue":[{"start":"05:40","end":"09:00","mode":"5\/10-cycles","position":0},{"start":"17:00","end":"24:00","mode":"5\/10-cycles","position":1}],"wed":[{"start":"05:40","end":"09:00","mode":"5\/10-cycles","position":0},{"start":"17:00","end":"24:00","mode":"5\/10-cycles","position":1}],"thu":[{"start":"05:40","end":"09:00","mode":"5\/10-cycles","position":0},{"start":"17:00","end":"24:00","mode":"5\/10-cycles","position":1}],"fri":[{"start":"05:40","end":"09:00","mode":"5\/10-cycles","position":0},{"start":"17:00","end":"24:00","mode":"5\/10-cycles","position":1}],"sat":[{"start":"07:20","end":"10:00","mode":"5\/10-cycles","position":0},{"start":"19:00","end":"24:00","mode":"5\/10-cycles","position":1}],"sun":[{"start":"07:30","end":"10:00","mode":"5\/10-cycles","position":0},{"start":"19:00","end":"24:00","mode":"5\/10-cycles","position":1}]}\\ \\ An: \\ \\ {"mon":[{"start":"00:00","end":"24:00","mode":"on","position":0}],\\ "tue":[{"start":"00:00","end":"24:00","mode":"on","position":0}],\\ "wed":[{"start":"00:00","end":"24:00","mode":"on","position":0}],\\ "thu":[{"start":"00:00","end":"24:00","mode":"on","position":0}],\\ "fri":[{"start":"00:00","end":"24:00","mode":"on","position":0}],\\ "sat":[{"start":"00:00","end":"24:00","mode":"on","position":0}],\\ "sun":[{"start":"00:00","end":"24:00","mode":"on","position":0}]}\\ \\ Aus:\\ \\ {"sun":[],"tue":[],"thu":[],"sat":[],"fri":[],"wed":[],"mon":[]}  |

===== Beispieldatei für Input per MQTT und Ausgabe per HTTP Befehle =====

{{plugins:vitoconnect:1246069641.loxone|1246069641.loxone}}

===== Fragen stellen und Fehler melden =====

[[https://www.loxforum.com/forum/projektforen/loxberry/plugins/226290-loxberry-vitoconnect]]