Skip to content

Latest commit

 

History

History
332 lines (240 loc) · 13.2 KB

README.md

File metadata and controls

332 lines (240 loc) · 13.2 KB
Raw

IPSymconBuderusKM200

IPS-Version Code License

Dokumentation

Inhaltsverzeichnis

  1. Funktionsumfang
  2. Voraussetzungen
  3. Installation
  4. Funktionsreferenz
  5. Konfiguration
  6. Anhang
  7. Versions-Historie

1. Funktionsumfang

Das Modul dient zu Anbindung einer Buderus-Heizung mit einem KM200-Kommunikationsmodul. Es können alle Datenpunkte abgerufen und die beschreibbaren Datenpunkte geändert werden.

Diese Modul basiert auf den Arbeiten von Slash, siehe auch Buderus Logamatic Web KM200 und Buderus Logamatic Web KM200 Reloaded.

2. Voraussetzungen

  • IP-Symcon ab Version 6.0
  • Buderus mit KM200
    Nach Prüfung durch danam33 funktioniert das Modul auch mit Heizungen von Junkers mit dem Modul Junkers MB Lan funktionsfähig (siehe hier).

3. Installation

IP-Symcon

Die Konsole von IP-Symcon öffnen. Im Objektbaum unter Kerninstanzen die Instanz Modules durch einen doppelten Mausklick öffnen.

In der Modules Instanz rechts oben auf den Button Hinzufügen drücken.

In dem sich öffnenden Fenster folgende URL hinzufügen:

https://github.com/demel42/IPSymconBuderusKM200.git

und mit OK bestätigen.

Anschließend erscheint ein Eintrag für das Modul in der Liste der Instanz Modules

In IP-Symcon nun Instanz hinzufügen (CTRL+1) auswählen unter der Kategorie, unter der man die Instanz hinzufügen will, und Hersteller Buderus und als Gerät KM200 auswählen.

Einrichtung der Instanz

Nach Eingabe von Host und Key in der Konfigurationsmaske kann man mit die Funktion Zugriff prüfen verwenden, um ein paar Basisdaten abzurufen.

Leider gibt es sehr viele Datenpunkte, deren Existenz bzw. deren Befüllung von der individuellen Konfiguration abhängen. Daher macht es Sinn, als erstes Datenpunkt-Tabelle auszulösen. Hiermit werden alle verfügbaren Datenpunkte ermittelt und im csv-Format als Medienobjekt unterhalb der Instanz gespeichert.
Das dauert etwas, weil einige Hundert Abfragen gemacht werden. Diese Tabelle sollte man sich in einer geeigneten Programm öffnen und ansehen.
Folgende Datenpunkte meine ich identifiziert zu haben: siehe hier, Ergänzungen sind ausdrücklich erwünscht.

In dem Konfigurationsformular im Bereich Felder kann man nun die Datenpunkte eingeben, die man haben möchte und zu dem Datenpunkt den gewünschten Variablentyp.
Hierbei liefern die o.g. Tabellen Informationen

  1. welcher Datentyp von KM200 geliefert wird
  2. welcher Variablentyp im IPS möglicherweise der sinnvollste ist.

Eine gewisse Konvertierung der Werte wird automatisch durchgeführt, so wird z.B. /gateway/DateTime automatisch in ein Timestamp umgewandelt, wenn der Variablentyp Integer ist; ist es String wird der Wert unverändert übernommen. Eine Umsetzung wird ebenfalls bei allen Variablen gemacht, bei denen in der Spalte Wertemenge eine Wertemenge angegeben ist und der Variablentyp Integer (bzw. Boolean). Siehe hierzu auch die vordefinierten Datentypen. Sind weitergehenden Konvertierungen des Datentyps erwünscht, kann man optional ein Script einbinden (siehe unten).

Die Variablen sind so benannt wie der Datenpunkt, es müsste also sinnvollerweise die Bezeichnung und der Datentyp angepasst werden.

Wichtig: wenn man einen Datenpunkt wieder aus der Liste æntfernt, wird die dazugehörige Variable gelöscht!

4. Funktionsreferenz

BuderusKEM200_UpdateData(int $InstanzID)

ruft die Daten vom KEM200 ab; für jeden Datenpunkt muss ein separater HTTP-Call durchgeführt werden. Der Abruf wird automatisch zyklisch durch die Instanz durchgeführt im Abstand wie in der Konfiguration angegeben.

BuderusKEM200_DatapointSheet(int $InstanzID)

erzeugt das Medien-Objekt Datenpunkt-Tabelle.

BuderusKEM200_GetData(int $InstanzID, string $datapoint)

ruft die Daten eines einzelnen Datenpunktes ab und liefert ein JSON-kodiester Objekt zurück.

BuderusKEM200_SetBooleanData(int $InstanzID, string $datapoint, string $Content)

BuderusKEM200_SetIntegerData(int $InstanzID, string $datapoint, string $Content)

BuderusKEM200_SetStringData(int $InstanzID, string $datapoint, string $Content)

BuderusKEM200_SetFloatData(int $InstanzID, string $datapoint, string $Content)

setzt ein Datenobjekt auf den übergebenen Wert. Die Objekte, die beschreibbar sind, sind in der o.g. Tabelle der Datenpunkte gekennzeichet.

5. Konfiguration

Variablen

Eigenschaft Typ Standardwert Beschreibung
Instanz deaktivieren boolean false Instanz temporär deaktivieren
Host string KM200-Server
Port integer 80 HTTP-Port
Gateway-Passwort string Passwort des Gateway [1]
privates Passwort string Passwort der Heizung [2]
Felder Tabelle zur Angabe der auszulesenden Datenpunkte
Werte konvertieren
Aktualisiere Status ... integer 60 Aktualisierungsintervall, Angabe in Sekunden

[1]: das Gateway-Passwort (KM200) ist auf dem Gehäuse aufgedruckt. Angabe mit oder ohne -
[2]: das private Internet-Passwort wird in der Buderus-App konfiguriert und kann bei Bedarf in der Bedieneinheit (zB RC301) zurückgesetzt werden. Es hat nichts mit dem Passwort der Bosch-ID zu tun, das zur Anmeldung in der App benötigt wird.

  • Felder:
    Liste der zu übernehmenden Datenpunkte und Angabe des Datentyps der Variable. Variablen, die aus dieser Liste gelöscht werden, werden gelöscht. Der Ident dieser erzeugten Variablen ist wie folgt aufgebaut: DP + Bezeichung des Datenpunkts, die / sind ersetzt durch _.

Anmerkung: der Datenpunkt /notifications wird automatisch abgerufen und in einer Variablen vom Typ ~HTMLBox abgelegt.

  • Werte konvertieren:
    mit diesen Scripten kann man Werte zu konvertieren

Ein passendes Code-Fragment für ein Script (siehe auch docs/convert_script.php):

<?php

$datapoint = $_IPS['datapoint'];
$value = $_IPS['value'];

$ret = '';
if ($datapoint == '/heatSources/workingTime/totalSystem') {
    $m = $value;
    if ($m > 60) {
        $h = floor($m / 60);
        $m = $m % 60;
        $ret .= sprintf('%dh', $h);
    }
    if ($m > 0) {
        $ret .= sprintf('%dm', $m);
    }
}

echo $ret;

Wandelt die Betriebszeit (in Minuten) in einer Darstellung als dm, Variable dann als String.

Schaltflächen

Bezeichnung Beschreibung
Zugriff prüfen Zugriff auf prüfen
Aktualisiere Status aktuellen Status holen
Datenpunkt-Tabelle Tabelle der verfügbafren Datenpunkte erzeugen
  • Datenpunkt-Tabelle:
    liest alle Datenpunkte der Heizung ein und legt diese csv-Datei als Medien-Objekt unterhalb der Instanz ab.

Variablenprofile

  • Boolean
    BuderusKM200.OnOff [Off|On], BuderusKM200.Status [Inactive|Active], BuderusKM200.Charge [Stop|Start]

  • Integer
    BuderusKM200.min, BuderusKM200.HealthStatus [Error|Maintenance|Ok], BuderusKM200.Hc_OperationMode [automatic|manual], BuderusKM200.Dwh_OperationMode [Off|High|HC-Program|Own program]

  • Float
    BuderusKM200.bar, BuderusKM200.Celsius, BuderusKM200.kW, BuderusKM200.kWh, BuderusKM200.l_min, BuderusKM200.Pascal, BuderusKM200.Percent, BuderusKM200.Wh

6. Anhang

GUIDs

  • Modul: {6AE8F5B3-93AC-428E-9EDB-B37D46B708F1}
  • Instanzen:
    • BuderusKM200: {3A2FE2B9-EB88-4B14-B144-2A3839A761CA}

7. Versions-Historie

  • 1.24 @ 17:51

    • Fix: Zugriff auf Medien-Objekte waren z.T. noch per Name

  • 1.23 @ 06.02.2024 09:46

    • Verbesserung: Angleichung interner Bibliotheken anlässlich IPS 7
    • update submodule CommonStubs

  • 1.22 @ 03.11.2023 11:06

    • Neu: Ermittlung von Speicherbedarf und Laufzeit (aktuell und für 31 Tage) und Anzeige im Panel "Information"
    • update submodule CommonStubs

  • 1.21 @ 06.07.2023 09:41

    • Fix: Absicherung für Geräte ohne Solarthermie
    • Fix: Zusatzpause von 250ms nach jedem Datenabruf
    • Fix: Übersetzung vervollständigt
    • Vorbereitung auf IPS 7 / PHP 8.2
    • update submodule CommonStubs
      • Absicherung bei Zugriff auf Objekte und Inhalte

  • 1.20 @ 27.11.2022 16:57

    • Fix: README bzgl. der Passwörter angepasst
    • Neu: Absicherung gegen konkurrierende Zugriffe auf den KM200
    • Neu: Abruf von Archivdaten (bestimmte Energiedaten, die auf dem KM200 gespeichert werden)
    • update submodule CommonStubs

  • 1.19 @ 19.10.2022 10:09

    • Fix: README
    • update submodule CommonStubs

  • 1.18.2 @ 12.10.2022 09:38

    • zusätzliche Debug-Meldung beim Datenabruf
    • update submodule CommonStubs

  • 1.18.1 @ 07.10.2022 13:59

    • update submodule CommonStubs Fix: Update-Prüfung wieder funktionsfähig

  • 1.18 @ 07.08.2022 19:30

    • Verbesserung: bessere Absicherung der Nicht-Erreichbarkeit der Heizung
    • Verbesserung: Datenpunkte in eigenem Panel
    • update submodule CommonStubs

  • 1.17 @ 07.07.2022 11:47

    • einige Funktionen (GetFormElements, GetFormActions) waren fehlerhafterweise "protected" und nicht "private"
    • interne Funktionen sind nun private und ggfs nur noch via IPS_RequestAction() erreichbar
    • Fix: Angabe der Kompatibilität auf 6.2 korrigiert
    • Verbesserung: IPS-Status wird nur noch gesetzt, wenn er sich ändert
    • update submodule CommonStubs Fix: Ausgabe des nächsten Timer-Zeitpunkts

  • 1.16.4 @ 17.05.2022 15:38

    • update submodule CommonStubs Fix: Absicherung gegen fehlende Objekte

  • 1.16.3 @ 10.05.2022 15:06

    • update submodule CommonStubs
    • SetLocation() -> GetConfiguratorLocation()
    • weitere Absicherung ungültiger ID's

  • 1.16.2 @ 30.04.2022 10:15

    • Überlagerung von Translate und Aufteilung von locale.json in 3 translation.json (Modul, libs und CommonStubs)

  • 1.16.1 @ 26.04.2022 12:32

    • Korrektur: self::$IS_DEACTIVATED wieder IS_INACTIVE
    • IPS-Version ist nun minimal 6.0

  • 1.16 @ 21.04.2022 08:52

    • Implememtierung einer Update-Logik
    • diverse interne Änderungen

  • 1.15 @ 16.04.2022 11:49

    • potentieller Namenskonflikt behoben (trait CommonStubs)
    • Aktualisierung von submodule CommonStubs

  • 1.14 @ 11.04.2022 17:30

    • Anpassungen an IPS 6.2 (Prüfung auf ungültige ID's)
    • Anzeige der Referenzen der Instanz incl. Statusvariablen und Instanz-Timer
    • common.php -> libs/CommonStubs

  • 1.13 @ 14.07.2021 18:34

    • PHP_CS_FIXER_IGNORE_ENV=1 in github/workflows/style.yml eingefügt
    • Schalter "Instanz ist deaktiviert" umbenannt in "Instanz deaktivieren"

  • 1.12 @ 18.12.2020 14:57

    • LICENSE.md hinzugefügt
    • lokale Funktionen aus common.php in locale.php verlagert
    • Traits des Moduls haben nun Postfix "Lib"
    • GetConfigurationForm() überarbeitet
    • define's durch statische Klassen-Variablen ersetzt

  • 1.11 @ 13.05.2020 20:35

    • mehr Debug zur Funktion 'SetData()'
    • Datentyp-spezifische Funktionen: 'SetBooleanData', 'SetIntegerData', 'SetStringData', 'SetFloatData'

  • 1.10 @ 06.01.2020 11:17

    • Nutzung von RegisterReference() für im Modul genutze Objekte (Scripte, Kategorien etc)
    • SetTimerInterval() erst nach KR_READY

  • 1.9 @ 02.01.2020 13:28

    • Fix wegen Umstellung auf strict_types=1
    • Schreibfehler korrigiert

  • 1.8 @ 30.12.2019 10:56

    • Anpassungen an IPS 5.3
      • Formular-Elemente: 'label' in 'caption' geändert

  • 1.7 @ 09.12.2019 16:46

    • mehr Ausgabe zu der Funktion 'DatapoitSheet' (Tabelle der Datenpunkte)

  • 1.6 @ 29.10.2019 10:21

    • Datenpunkt 'notifications' gegen fehlende Felder abgesichert

  • 1.5 @ 13.10.2019 13:18

    • Anpassungen an IPS 5.2
      • IPS_SetVariableProfileValues(), IPS_SetVariableProfileDigits() nur bei INTEGER, FLOAT
      • Dokumentation-URL in module.json
    • Umstellung auf strict_types=1
    • Umstellung von StyleCI auf php-cs-fixer

  • 1.4 @ 09.08.2019 14:32

    • Schreibfehler korrigiert

  • 1.3 @ 16.06.2019 18:34

    • leeres Ergebnis eines HTTP-Request abfangen

  • 1.2 @ 03.05.2019 14:14

    • Dateiname der Mediadatei "Buderus KM200 Datenpunkte" ist nun eindeutig
    • Abfrage des Status nun über GetStatus() mit Emulation für IPS < 5.1

  • 1.1 @ 02.05.2019 11:56

    • Bugfix: Auswertung des HTTP-Port

  • 1.0 @ 28.03.2019 19:07

    • Initiale Version