🔌Schnittstellen

Wer von außen mit der Zentrale spricht – ioBroker, Home Assistant, Node-RED oder ein eigenes Skript – nutzt meist die XML-RPC-Schnittstelle der Schnittstellenprozesse. Das Besondere: Man fragt nicht ständig nach, sondern meldet sich einmal mit init() an und bekommt jede Änderung als Ereignis zugeschickt.

🚪Ports der Zentrale

Port	TLS	Interface / Dienst	Wofür
2001	42001	BidCos-RF	HomeMatic-Funk (klassisch, rfd)
2010	42010	HmIP-RF	Homematic IP (Funk und Wired)
2000	42000	BidCos-Wired	HomeMatic Wired (RS-485, nur mit Wired-LAN-Gateway)
9292	—	VirtualDevices	virtuelle Geräte/Gruppen (Pfad /groups)
8701	—	CUxD	CUxD-Addon (BIN-RPC)
8181	—	ReGaHss	Remote-HomeMatic-Skript (TclRega)

2001 und 2000 stehen in der eQ-3-XML-RPC-Spezifikation, 2010 im Homematic-IP-Addendum; 9292, 8701 und 8181 laut openHAB-Dokumentation; TLS-Ports laut ioBroker/Home-Assistant-Dokumentation. Welche Ports erreichbar sind, regelt die Firewall der Zentrale (siehe „Praxis“).

🪜XML-RPC Schritt für Schritt

Ein kompletter Ablauf gegen eine simulierte Zentrale mit Fensterkontakt und Schaltsteckdose – vom Anmelden über listDevices, getValue und setValue bis zum Ereignis und zum Abmelden.

Logikschicht 192.0.2.50 → Zentrale 192.0.2.10:2010init

1 · Anmelden mit init()

Die Logikschicht (z. B. ioBroker, Home Assistant) startet selbst einen XML-RPC-Server unter http://192.0.2.50:2011 und meldet ihn mit init(url, interface_id) an Port 2010 an. Ab jetzt schickt die Zentrale Ereignisse dorthin – kein Abfragen (Polling) nötig.

Schritt 1 / 9 · Tasten ← →

📤 Request (POST an 192.0.2.10:2010)228 Bytes (formatiert)

<?xml version="1.0"?>
<methodCall>
  <methodName>init</methodName>
  <params>
    <param>
      <value>http://192.0.2.50:2011</value>
    </param>
    <param>
      <value>demo-hmip</value>
    </param>
  </params>
</methodCall>

📥 ResponseWert: (leer / void)

<?xml version="1.0"?>
<methodResponse>
  <params>
    <param>
      <value></value>
    </param>
  </params>
</methodResponse>

Alles oben wird live von einem simulierten Schnittstellenprozess erzeugt und wieder dekodiert (eigene XML-RPC-Implementierung). Zur Lesbarkeit ist das XML eingerückt – laut Spezifikation verträgt der CCU-Server keine CRLF-Zeichen in Parameter-Tags und keine XML-Kommentare, echte Clients senden kompakt.

🧾Wichtige XML-RPC-Methoden

void init(String url, String interface_id)

Logikschicht an-/abmelden (leere interface_id = abmelden)

Array<DeviceDescription> listDevices()

alle Geräte und Kanäle

ValueType getValue(String address, String value_key)

einen Wert aus VALUES lesen

void setValue(String address, String value_key, ValueType value)

einen Wert in VALUES schreiben

Paramset getParamset(String address, String paramset_key)

MASTER, VALUES oder LINK (Partneradresse) lesen

void putParamset(String address, String paramset_key, Paramset set)

Parametersatz schreiben

ParamsetDescription getParamsetDescription(address, type)

Typen, Wertebereiche, OPERATIONS

void setInstallMode(Boolean on, …)

Anlernmodus

bool ping(String callerId)

erzeugt Ereignis PONG an CENTRAL – Verbindungstest

💡 Besondere Ereignisse

UNREACH (Kommunikationsstörung, aktueller Zustand), STICKY_UNREACH (es gab eine Störung – bleibt stehen),CONFIG_PENDING (Konfiguration noch nicht übertragen). Fehlercode −8 heißt: nicht genügend Duty Cycle.

✅ XML-RPC oder BIN-RPC?

BIN-RPC ist das kompaktere Binärformat derselben Methoden. Homematic IP und die virtuellen Geräte sprechen nur XML-RPC, das CUxD-Addon nur BIN-RPC.

🔄Integration: ioBroker, Home Assistant, Node-RED, MQTT

ioBroker: Nachrichtenfluss

1Adapter hm-rpc (je Interface eine Instanz: HmIP, BidCos-RF, Wired, CUxD) startet einen eigenen RPC-Server und meldet sich per init() an – Homematic IP und virtuelle Geräte nur per XML-RPC, CUxD per BIN-RPC.
2Die Zentrale pusht Ereignisse → ioBroker-Objekte wie hm-rpc.0.000A1BE9A00002.1.STATE werden aktualisiert.
3Adapter hm-rega liest über die ReGaHss Namen, Räume, Gewerke, Systemvariablen und Programme.
4Schreibt ein ioBroker-Skript einen Zustand, ruft hm-rpc setValue() auf.

🧰Weitere Schnittstellen

🖥️ JSON-RPC der WebUI

Die WebUI spricht selbst JSON-RPC mit /api/homematic.cgi. Erst anmelden, dann mit Session-ID Methoden aufrufen. Beispiel (erfundene Zugangsdaten):

POST https://192.0.2.10/api/homematic.cgi
{"method": "Session.login",
 "params": {"username": "Admin",
            "password": "beispiel-passwort"}}

{"method": "Interface.getValue",
 "params": {"_session_id_": "…",
            "interface": "HmIP-RF",
            "address": "000A1BE9A00001:1",
            "valueKey": "ACTUAL_TEMPERATURE"}}

📄 XML-API-Addon

Community-Addon mit einfachen CGI-Skripten unter /addons/xmlapi/: devicelist.cgi, statelist.cgi,statechange.cgi, sysvarlist.cgi, programlist.cgi, runprogram.cgi … Zugriff nur mit Token (sid, erzeugt über tokenregister.cgi).

https://192.0.2.10/addons/xmlapi/statechange.cgi
  ?sid=BEISPIEL-TOKEN&ise_id=12345&new_value=0.20

🧩 CUxD

Das Addon „CUxD“ erzeugt zusätzliche virtuelle Geräte (z. B. Zeitschaltuhren, Systembefehle, Fremdgeräte) und stellt sie wie ein weiteres Interface bereit – laut openHAB-Doku auf Port 8701 per BIN-RPC. In ReGa heißen die Datenpunkte dann CUxD.<Adresse>.<PARAMETER>.