Architektur¶
Das Add-on besteht aus zwei Teilen, die beide auf der CCU laufen: einer App im Browser (React) und einem Server in Go, der für die App mit der CCU spricht. Zwischen beiden liegt eine einzige WebSocket-Verbindung mit einem typisierten Protokoll.
Überblick¶
flowchart LR
subgraph Geräte["Handy, Tablet, PC"]
App["App (React, PWA)"]
end
subgraph CCU["CCU3 / OpenCCU"]
L["lighttpd<br/>:80 / :443"]
S["ccu-addon-mui-server<br/>Go, 127.0.0.1:8089"]
R["ReGa<br/>rega.exe"]
RF["rfd<br/>BidCos-RF :32001"]
IP["crRFD / HMIPServer<br/>HmIP-RF :32010"]
V["VirtualDevices<br/>:39292"]
W["WebUI<br/>JSON-RPC, CGIs"]
end
App -- "HTTPS: App-Dateien<br/>/addons/mui" --> L
App <-- "WebSocket /ws/mui" --> L
L <-- Proxy --> S
S -- "HM-Script" --> R
S -- "XML-RPC" --> RF
S -- "XML-RPC" --> IP
S -- "XML-RPC" --> V
S -- "Session.login,<br/>Backup, Firewall …" --> W
RF -- "Events an :9098" --> S
IP -- "Events an :9098" --> S
- lighttpd, der Webserver der CCU, liefert die App aus (
/addons/mui/…) und leitet/ws/muian den Go-Server weiter. Die Skripte und Styles (/addons/mui/assets/) liegen nur gzip-gepackt auf der CCU (scripts/compress-assets.mjs, 5,1 MB → 0,6 MB); lighttpd hat kein Kompressionsmodul, deshalb leitet es auch diesen Pfad an den Go-Server, der die Dateien unverändert mitContent-Encoding: gzipschickt (pkg/websocket/assets.go). Damit gelten für das Add-on dieselbe Adresse, dasselbe Zertifikat und dieselbe Firewall wie für die WebUI. - Der Go-Server lauscht nur auf
127.0.0.1, ist also von außen nicht direkt erreichbar. Er spricht mit den Diensten der CCU über deren eigene Schnittstellen und meldet sich bei den Funkdiensten für Events an. - Die App hält eine WebSocket-Verbindung, über die Anfragen, Antworten und Live-Events laufen.
Auf der CCU¶
Die Archive mui-<version>-arm-ccu3-raspi.tar.gz und mui-<version>-x86_64-pc.tar.gz enthalten die gebaute
App, das Server-Binary für ihre Architektur und vier Dateien, die die CCU für Add-ons erwartet:
| Datei | Aufgabe |
|---|---|
update_script |
wird von der WebUI bei der Installation ausgeführt: kopiert nach /usr/local/addons/mui, legt den Link /usr/local/etc/config/addons/www/mui an, installiert Startskript und lighttpd-Konfiguration |
rc.d/mui |
Startskript (start, stop, restart, info, uninstall); liest mui.conf, schreibt das Log, rotiert es ab 1 MB |
lighttpd.conf |
^/ws/mui → Proxy auf 127.0.0.1:8089 mit WebSocket-Upgrade (bzw. den WS_PORT aus mui.conf, den lighttpd-conf.sh beim Installieren einsetzt), ebenso /addons/mui/assets/ (die gzip-gepackten Skripte der App); unter /addons/mui/ jede unbekannte URL auf index.html (Routing der App). Läuft der Server nicht, laden die Skripte nicht, und ein kleines Skript in index.html zeigt „MUI lässt sich nicht laden“ statt einer weißen Seite |
lighttpd-conf.sh |
schreibt beim Installieren lighttpd.conf mit dem Port des Servers: dem Standard 8089 oder dem WS_PORT aus mui.conf, damit Weiterleitung und Server nach jedem Update zusammenpassen |
update-check.cgi |
meldet der WebUI die neueste Version auf GitHub |
status.cgi |
sagt dem Hinweis in index.html, ob der Server läuft, und wenn nicht, die Zeile, mit der er abgebrochen ist (JSON, ohne Anmeldung, siehe Sicherheit) |
Der Server ist ein statisches Go-Binary (CGO_ENABLED=0, -ldflags="-s -w", rund 10 MB), für ARMv7 (CCU3 und Raspberry Pi) und amd64 (OpenCCU auf x86), je in einem eigenen Archiv. Er braucht
keine Laufzeit und keine Bibliotheken der CCU und läuft daher unabhängig von der Firmware-Version (auf ARM). Welche Dateien er
anlegt, steht in der Installation.
Der Go-Server¶
go-server/
main.go Start: Konfiguration, Dienste verdrahten, Shutdown
pkg/websocket WebSocket-Server, Dispatcher für 153 Nachrichtentypen, Rechte, Audit-Aufrufe,
HTTP-Endpunkte für Backup, Upload und Logs
pkg/rega ReGa: 55 HM-Script-Vorlagen (embed), Ausführen, Parsen, Validieren
pkg/ccurpc XML-RPC-Client zu BidCos-RF, HmIP-RF, VirtualDevices; Cache für Beschreibungen
pkg/xmlrpc XML-RPC-Server für die Events der CCU, Anmeldung und Überwachung
pkg/subscriptions welche Verbindung welche Kanäle sieht
pkg/auth Anmeldung über die WebUI, HMAC-Tokens, Sitzungen, Sperre
pkg/audit Protokoll jeder Änderung (JSON Lines)
pkg/backup alles, was über die WebUI selbst läuft: Backup, Restore, Firmware, Add-ons,
Werkseinstellungen, Admin-Aufrufe per JSON-RPC, Heizgruppen über den HMServer
pkg/settings Dateien in /etc/config: Netzwerk, Firewall, Zertifikat, LAN-Gateways, rega.conf …
pkg/diagrams eigene Diagramme: Definitionen, Aufzeichnung, Abfrage
pkg/push Web Push (RFC 8291/8292) nur mit der Standardbibliothek
pkg/rules Benachrichtigungsregeln ohne Programm (Push)
pkg/devimages Gerätebilder der WebUI (DEVDB.tcl) mit markiertem Kanal
pkg/sysinfo Systeminformationen wie help.cgi: Hardware, Speicher, Last, Temperatur, Netzwerk
pkg/tiles Kachel-Layouts, Kachelart und Kachelname je Kanal (mui-tiles.json)
pkg/addons, logs, heatinggroups, config, logger, types
pkg/fakeccu eine nachgebaute CCU für Tests und Entwicklung
cmd/fakeccu startet die Fake-CCU mit einer Fixture
cmd/ccu-export liest eine echte CCU aus und schreibt eine Fixture
21.944 Zeilen Go, dazu 8.607 Zeilen Tests. Abhängigkeiten: gorilla/websocket, kolo/xmlrpc und für
ISO-8859-1 go-charset bzw. x/text, mehr nicht.
Startablauf (main.go): Konfiguration aus Umgebungsvariablen laden, ReGa-Client und WebSocket-Server
anlegen, Anmeldung (AUTH_MODE=ccu, ohne Schlüssel startet der Server nicht), Audit, Backup, XML-RPC-Client,
Einstellungen, Push und Diagramme einhängen, den Event-Server starten und bei BidCos-RF und HmIP-RF anmelden.
Beim Beenden meldet er sich wieder ab.
Zwei Plattformen¶
Aus demselben Code entstehen zwei Server: go build für CCU3 und OpenCCU, go build -tags lite für
openccu-lite, das keine ReGa und keine WebUI hat. Was sich
unterscheidet, liegt hinter Schnittstellen: das Hausmodell (Räume, Gewerke, Kanäle, Namen, Favoriten,
Servicemeldungen) hinter home.Source mit der ReGa (pkg/rega) bzw. occulites APIs (pkg/occulite), die
Heizgruppen hinter GroupService, die Anmeldung hinter dem Gate von openccu-lite. Was nur eine CCU hat,
verteilt dispatch_ccu.go, und die Dateien dafür bauen nur ins CCU-Paket. Auf openccu-lite kommen die
Events statt über einen Callback-Server über occulites Event-Stream, der Verpasstes nachholt, und die Werte
beim Start aus dessen Zustandsspeicher; die Funkdienste erreicht der Server über occulites lite-rpc, mit
der Sitzung des Nutzers, der etwas ändert. Die App ist für beide gleich; der Server sagt ihr bei der Anmeldung,
was es gibt.
Schnittstellen der CCU¶
Das Add-on verwendet ausschließlich die Schnittstellen, die auch die WebUI benutzt. Welche Funktion welche Schnittstelle nimmt, folgt den Quellen der WebUI in OpenCCU.
ReGa (HM-Script)¶
Die Logikschicht der CCU kennt Räume, Gewerke, Kanäle mit Namen, Systemvariablen, Programme, Favoriten,
Benutzer und das Systemprotokoll. Der Server schickt ihr HM-Script per POST /rega.exe:
- 55 Vorlagen in
pkg/rega/scripts/*.tcl(die Endung ist historisch, Inhalt ist HM-Script), ins Binary eingebettet. Platzhalter wie{{ADDRESS}}werden ersetzt. - Die Skripte geben tabulatorgetrennte Zeilen aus, das JSON baut Go. So muss im Skript nichts maskiert werden.
- Abbruch erkennen: Bei einem Laufzeitfehler bricht ReGa das Skript ab und antwortet trotzdem mit 200 und
dem, was bis dahin geschrieben war. Skripte, deren Ausgabe vollständig sein muss (schreibgeschützte Kanäle,
Systemprotokoll), laufen über
ExecuteComplete: Fehlt die angehängte Endmarke, ist das ein Fehler statt einer kurzen oder leeren Liste. - Keine Funktionen der WebUI-Seiten: Was die WebUI nur in ihren Seiten aufruft, etwa
web.webGetValueFromListinfunctions.fn::WriteDPText, meiden die Skripte; sie lesen solche Werte selbst (Enum-Texte perValueList().StrValueByIndex(";", n)). Das Systemprotokoll brach daran ab und erschien leer. - Ablehnen statt maskieren: HM-Script hat keine verlässlichen Escapes. Bezeichner müssen
^[a-zA-Z0-9_:.-]+$entsprechen, IDs sind Zahlen, Namen dürfen keine Anführungszeichen, Backslashes oder Zeilenumbrüche enthalten. Alles andere lehnt der Server ab, bevor ein Skript entsteht. - Werte schreiben läuft über ReGa (
State()), wie in der WebUI, auch an ein Gerät, das als nicht erreichbar gilt (bei HmIP-Batteriegeräten istUNREACHoft veraltet). Das Skript meldet den alten Wert fürs Audit-Log. - Eigene Daten wie das Kachel-Layout, die Kachelart und den Kachelnamen am Kanal legt das Add-on nicht in ReGa ab,
sondern in eigenen Dateien unter
/usr/local/etc/config(pkg/tiles,mui-tiles.json), atomar geschrieben. ReGa schreibt sein Objektmodell nur alle paar Minuten auf den Flash und beim Beenden gar nicht (rega.conf:CheckModifiedCycle,AutoSaveDOMOnExit=0); ein Neustart kurz nach dem Anordnen, etwa beim Installieren eines Add-ons über die WebUI der CCU3, verlor so das Layout. Die Dateien gehören trotzdem zur CCU, landen im Backup und gelten auf allen Geräten.
XML-RPC zu den Funkdiensten¶
| Dienst | Port auf der CCU (aus dem LAN) | wofür |
|---|---|---|
| BidCos-RF (rfd) | 32001 (2001) | Gerätebeschreibungen, Paramsets, Anlernen, Verknüpfungen, LAN-Gateways, Gerätetausch, Log-Level; Events |
| HmIP-RF (crRFD) | 32010 (2010) | dasselbe für HmIP und HmIP Wired, dazu Anlernen mit KEY/SGTIN und Firmware-Updates (installFirmware; BidCos: updateFirmware); Events |
| VirtualDevices | 39292 (9292) | Heizgruppen und virtuelle Geräte |
| BidCos-Wired (hs485d) | 32000 (2000) | wie BidCos-RF für HMW-Geräte am RS485-Bus, dazu die Gerätesuche; nur mit Wired-Gateway, dann trägt hs485dLoader es in InterfacesList.xml ein |
Die Ports 2001, 2010, 9292 und 8181 sind Weiterleitungen von lighttpd an die Dienste (webui_remoteapi.conf),
je nach Einstellung mit Authentifizierung. Auf der CCU spricht der Server die Dienste direkt an, wie ReGa
selbst: Die Ports liest er aus /etc/config/InterfacesList.xml, ReGa erreicht er auf 8183. Das spart den
Umweg und funktioniert unabhängig von lighttpd und der Authentifizierung der Fernzugriffs-Ports.
Gerätebeschreibungen und Paramset-Beschreibungen ändern sich nur mit der Firmware. Der Server cacht sie je
Schnittstelle, Gerätetyp, Kanaltyp, Firmware und Paramset und verwirft den Cache, wenn die CCU
updateDevice oder deleteDevices meldet. Beim Schreiben eines Paramsets prüft er jeden Wert gegen die
Beschreibung (bekannt, schreibbar, im Bereich) und wandelt JSON-Zahlen in den richtigen Typ.
Events¶
Der Server ist selbst ein XML-RPC-Server auf Port 9098 (nicht 9099 und beim WebSocket nicht 8088: dort lauscht der Mediola NEO Server, den OpenCCU mitbringt, libfirewall.tcl; wer beim Start zuerst kommt, bekommt die Ports, #224) und meldet sich mit init bei rfd und crRFD an, mit
Wired-Gateway auch bei hs485d.
Ab dann schickt die CCU jede Wertänderung als event (meist gebündelt in system.multicall).
- Kommt eine Minute lang nichts, schickt der Server
ping. Die Dienste antworten darauf mit einemPONG-Event. Bleibt es 15 Sekunden aus, hat der Dienst die Anmeldung vergessen (z. B. nach einem Neustart), und der Server meldet sich neu an. Eine verlorene Anmeldung fällt so nach gut einer Minute auf. Schlägt die Anmeldung fehl, versucht er es mit wachsendem Abstand (5 s bis 5 min) weiter. - Jedes Event geht an die Diagramm-Aufzeichnung und an alle Verbindungen, die den Kanal abonniert haben.
- Die Reihenfolge bleibt erhalten, weil der Handler synchron arbeitet.
JSON-RPC und Seiten der WebUI¶
Manche Funktionen bietet die CCU nur in der WebUI an. Dafür hält der Server eine WebUI-Sitzung des Benutzers:
- Anmeldung prüfen:
Session.loginund sofortSession.logout(die CCU erlaubt nur wenige Sitzungen). - Admin-Aufrufe über
/api/homematic.cgi: Sicherheitsstufe, SSH, Authentifizierung, HTTPS-Umleitung, Firewall, LAN-Gateways, Prüfung des Sicherheitsschlüssels, Neustart von lighttpd. - CGI-Seiten, genau wie die WebUI sie aufruft: Backup (
cp_security.cgi?action=create_backup), Restore, Werkseinstellungen, Sicherheitsschlüssel, CCU-Firmware (cp_maintenance.cgi), Add-ons (cp_software.cgi), Uploads überfileupload.ccc. - HMServer für Heizgruppen (
/pages/jpages/group/*) und Geräte-Firmware (/pages/jpages/system/DeviceFirmware/addFirmware,deleteFirmware), danachrefreshDeployedDeviceFirmwareListbei BidCos-RF und HmIP-RF. - CCU-Firmware direkt:
CCU.downloadFirmware(OpenCCU lädt das Release von GitHub nach/usr/local/tmp/firmwareUpdateFile), SHA256 gegen die.sha256des Releases wiecheckFirmwareUpdate.sh, danncp_maintenance.cgi?action=firmware_upload&directDownload=true. - eQ-3-Updateserver (
ccu3-update.homematic.com): Liste der neuesten Geräte-Firmware (/firmware/api/firmware/search/DEVICE) und Download, wiewebui.js(homematic.com).
Dateien und Befehle¶
Was die WebUI über eigene Tcl-Skripte erledigt, macht der Server direkt und auf dieselbe Weise: Uhr und
Zeitzone (date, hwclock, updateTZ.sh, time.conf, ntpclient), Netzwerk (netconfig), Syslog
(/etc/config/syslog, monit restart syslogd), Zertifikat (server.pem), Sitzungs-Timeout (rega.conf),
Neustart, Herunterfahren und abgesicherter Modus (nach SaveSystem in ReGa; für den abgesicherten Modus zusätzlich /etc/config/safemode wie safemode/enter.tcl), Zusatzsoftware über deren rc.d-Skripte.
Die App¶
| Framework | React 19 als API, zur Laufzeit TanStack Redact statt React; TypeScript strict |
| Routing | TanStack Router, dateibasiert, mit Code-Splitting je Route |
| Daten | TanStack Query: jede Anfrage über den WebSocket ist eine Query oder Mutation |
| Oberfläche | Tailwind CSS 4, shadcn/ui-Komponenten auf Radix, Icons zur Build-Zeit einkompiliert |
| Tabellen, Raster | TanStack Table, react-grid-layout |
| Diagramme | eigene SVG-Zeichnung, ohne Chart-Bibliothek |
| Übersetzungen | Paraglide JS, Deutsch und Englisch, typisierte Funktionen (m.KEY()) |
| PWA | vite-plugin-pwa (Workbox), Push über einen eigenen Service-Worker-Teil |
| Build | Vite; das Plugin von Redact lenkt die Importe von react und react-dom um |
28.817 Zeilen TypeScript ohne Tests und generierten Code.
src/
routes/ URLs (/, /room/:id, /trade/:id, /favorite/:id, /devices, /diagrams, /programs,
/program/:id, /sysvars, /history, /virtual-keys, /setup/…, /device/:interface/:address)
views/ Seiten: Dashboard, Räume, Favoriten, Diagramme, Programme, Einrichten (37 Dateien)
controls/ Kacheln je Kanaltyp, registry.ts, generische Kachel und Einstellungen,
Verknüpfungsvorlagen, Wochenprogramme
components/ Kopfzeile, Meldungen, Dialoge, Gesten; ui/ mit den shadcn-Komponenten
hooks/ useWebsocket (Verbindung, Anfragen, Events), channels (Events anwenden, sortieren)
queries/ alle Queries und Mutationen
contexts/ Theme, Effekte, Seitentitel, Hinweise
types/ protocol.ts (aus dem Schema generiert), types.ts
Datenfluss¶
flowchart TB
WS["useWebsocket<br/>eine Verbindung, request() mit requestId"] --> Q["TanStack Query Cache"]
E["Event der CCU"] --> WS
WS -- "applyEvent: nur der betroffene Kanal<br/>bekommt ein neues Objekt" --> Q
Q --> V["Views und Kacheln<br/>(React.memo)"]
V -- "useSetDataPoint: optimistisch,<br/>Rücknahme bei Fehler" --> WS
- Eine Verbindung:
useWebsocketöffnetws(s)://<host>/ws/mui, meldet sich mit dem gespeicherten Token an und verbindet sich bei Abbruch alle 3 Sekunden neu.request()vergibt einerequestIdund löst das Promise auf, wenn die Antwort mit derselben ID kommt (Timeout 20 s). Anfragen vor der Anmeldung werden gepuffert; Befehle wie Schalten werden nie gepuffert, damit ein Licht nicht Minuten später angeht. - Abos: Jede Ansicht abonniert die Adressen der Kanäle, die sie zeigt. Nach jedem Neuverbinden schickt die App das Abo erneut und lädt alle Daten neu.
- Events schreibt die App direkt in die gecachten Kanallisten. Nur der geänderte Kanal bekommt ein
neues Objekt, alle anderen Kacheln rendern nicht neu. Ändert sich ein Wartungswert (
UNREACH,LOW_BAT,CONFIG_PENDING…), lädt sie zusätzlich die Geräteprobleme neu; die Servicemeldungen schickt der Server. - Schalten ist optimistisch: Die Kachel zeigt den neuen Zustand sofort. Lehnt die CCU ab, nimmt die App ihn zurück, aber nur, wenn inzwischen kein Event einen neueren Wert gebracht hat.
- Systemvariablen melden keine Events. Der Server liest sie alle 5 s, einmal für alle Apps, die sie
zeigen, und schickt die Liste nur bei einer Änderung (
sysvars). Vorher fragte jede App selbst alle 10 s; ReGa arbeitet Skripte nacheinander ab, mit mehreren Tablets bremste das WebUI und Programme. - Alarme und Servicemeldungen führt ReGa, und ReGa schickt keine Events (die kommen per XML-RPC nur von
den Interface-Prozessen, für Datenpunkte der Geräte). Der Server liest sie ebenfalls einmal für alle Apps
und schickt sie bei einer Änderung (
alarmMessages,serviceMessages): Alarme alle 15 s, Servicemeldungen kurz nach einem Event eines Wartungswerts (UNREACH,LOW_BAT…) und sonst alle 5 Minuten. Der Push-Dienst nutzt dieselben Ergebnisse. - Geräteprobleme fragt die App alle 5 Minuten ab und nach einem Event eines Wartungswerts.
Kacheln¶
src/controls/registry.ts ordnet Kanaltypen Kacheln und Abschnitten zu, eine Kachel je Kanal oder eine je
Gerät (Taster, Energiezähler, Zutritt). Alles andere rendert GenericControl aus der Paramset-Beschreibung,
die der Server liefert. Einstellungen baut SettingsView ebenfalls aus der Beschreibung: settingKinds.ts
leitet aus Typ, Bereich, Einheit und Namen ab, ob ein Parameter Schalter, Segmente, Auswahl, Schieberegler,
Stepper, Dauer, Uhrzeit oder Monat wird, und fasst zusammengehörige Paare (*_VALUE/*_UNIT,
*_FACTOR/*_BASE) zu einem Feld zusammen. Das ist das Gegenstück zu den Easymodes der WebUI
(uiElements.tcl, options.tcl).
Die Verknüpfungsvorlagen stammen direkt aus den Easymodes der WebUI: scripts/import-link-profiles.mjs
liest www/config/easymodes/* aus OpenCCU-Base und schreibt linkProfiles.json. Die App lädt die Datei
erst, wenn jemand eine Verknüpfung öffnet.
Das Protokoll als Vertrag¶
protocol/schema.json beschreibt jede Anfrage, jede Antwort und jedes Event als JSON-Schema. Daraus
entstehen die TypeScript-Typen der App (bun run generate:protocol), sodass request('putParamset', …) die
passenden Felder verlangt und die passende Antwort liefert. Auf der Go-Seite prüft der Integrationstest
jede Nachricht, die der echte Server sendet, gegen das Schema. Ändert eine Seite das Protokoll, ohne das
Schema anzupassen, schlägt die CI fehl. Details in WebSocket-Protokoll.
Abläufe¶
Öffnen, anmelden, live sehen¶
sequenceDiagram
participant A as App
participant S as Go-Server
participant W as WebUI (JSON-RPC)
participant R as ReGa
participant F as rfd / crRFD
A->>S: auth {token}
S-->>A: auth_response {LOGIN_REQUIRED}
A->>S: login {username, password}
S->>W: Session.login, Session.logout
S->>R: UserLevel()
S-->>A: auth_response {token 365 d, adminToken 8 h}
A->>S: getRooms, getChannels {roomId}
S->>R: get_rooms, get_channels
S-->>A: Räume, Kanäle mit Werten
A->>S: subscribe {channels}
F->>S: event(ADDR:1, STATE, true)
S-->>A: {event: {channel, datapoint, value}}
Schalten¶
- Die Kachel zeigt den neuen Zustand und sendet
setDatapoint. - Der Server prüft die Rechte (Gäste dürfen nicht, Kanäle ohne bedienbar nur Administratoren), den Wert und den Bezeichner.
- ReGa setzt den Wert, wie in der WebUI auch bei einem als nicht erreichbar gemeldeten Gerät, und meldet den alten Wert.
- Audit-Eintrag, Antwort an die App. Bei Fehler (
FORBIDDEN,NOT_FOUND…) nimmt die App die Änderung zurück. - Das Gerät bestätigt, die CCU schickt das Event, alle anderen offenen Geräte sehen die Änderung.
Geräteeinstellungen speichern¶
- Die Geräteseite lädt Beschreibung und Werte des
MASTER-Paramsets je Kanal. - Speichern und übertragen sendet
putParamset. Der Server verlangt Administrator plus Admin-Token, prüft jeden Wert gegen die Beschreibung, liest die alten Werte fürs Audit-Log und schreibt per XML-RPC. - Die App beobachtet danach zwei Minuten lang
CONFIG_PENDINGam Wartungskanal: wird gesendet, wartet auf das Gerät, übertragen.
Anlernen¶
setInstallMode startet den Anlernmodus (HmIP optional mit KEY/SGTIN als Whitelist). Die App fragt die
Restzeit jede Sekunde und den Posteingang alle 3 Sekunden ab. Übernehmen läuft über ReGa
(accept_device). Löschen geht per XML-RPC deleteDevice.
Backup¶
createBackupmit Passwort: Der Server meldet sich bei der WebUI an und ruftcp_security.cgi?action=create_backupauf, wie der Knopf in der WebUI.- Die Datei landet im RAM der CCU (
/tmp), die App bekommt eine einmalige URL/ws/mui/backup/<id>. - Der Browser lädt sie herunter; danach oder nach 5 Minuten wird sie gelöscht.
Wiederherstellen, CCU-Firmware und Add-ons laufen genauso über einmalige Upload-URLs und die Seiten der WebUI.
Entscheidungen¶
Warum ein eigener Server und nicht direkt die WebUI-API? Der Browser kann weder XML-RPC-Events empfangen noch ReGa sicher ansprechen. Ein kleiner Server auf der CCU kann beides, prüft Rechte und Werte an einer Stelle und verteilt Events an alle Geräte.
Warum Go? Das erste Add-on lief auf Node.js und brachte dafür eine Laufzeit von 71 MB mit, abhängig von der GLIBC der Firmware. Go erzeugt ein einziges statisches Binary ohne Abhängigkeiten (rund 8,6 MB), das unabhängig von den Bibliotheken der Firmware läuft. Für das, was der Server tut (viele kleine Netzwerkaufrufe, nebenläufige Verbindungen), ist Go wie gemacht.
Warum WebSocket? Eine Verbindung für Anfragen und Events, ohne Polling, mit wenig Overhead pro Nachricht.
Anfragen bekommen eine requestId, Events kommen ohne.
Warum nach den OpenCCU-Quellen? Die WebUI ist die Referenz dafür, wie die CCU richtig bedient wird:
welche Datenpunkte, welche Reihenfolge, welche Skripte. Jede Funktion des Add-ons ist dort nachgeschlagen,
und der Code nennt die Quelldatei (z. B. „wie in der WebUI door_opener.fn“). So verhält sich das Add-on wie
die WebUI, und Änderungen der CCU lassen sich nachvollziehen.
Warum zwei Tokens? Ein Wandtablet soll dauerhaft angemeldet bleiben, aber wer es in der Hand hat, soll nicht die Firewall abschalten können. Deshalb gilt das normale Token ein Jahr und erlaubt nur, was der Benutzer auch in der WebUI darf; Einstellungen brauchen ein Admin-Token, das 8 Stunden gilt.
Warum eine Fake-CCU? Fast jede Funktion ändert etwas an der Zentrale. Die Fake-CCU bildet ReGa, XML-RPC, die WebUI und den HMServer nach, sodass alle Abläufe End-to-End getestet werden können, ohne eine echte Zentrale anzufassen (siehe Tests).
Warum eigene Diagramme? Die Diagramme der WebUI zeichnen nur feste Werttypen auf und brauchen eine microSD-Karte. Der Server bekommt ohnehin jedes Event; er fasst sie zu Minuten- und Stundenwerten zusammen und schreibt alle 5 Minuten auf den Speicher der CCU.
Warum TanStack Redact statt React? Die App lädt auf Handys und über das WLAN der CCU; jedes KB zählt
beim ersten Öffnen. Redact ist eine Laufzeit mit der API von
React 19: Der Code importiert weiter aus react, das Vite-Plugin (vite.config.mts) lenkt die Importe beim
Bauen um, auch in den Unit-Tests (vitest.config.mts). Das spart beim Start rund 43 KB gzip (190 → 146 KB
JavaScript, das die Seite sofort lädt). Redact rendert synchron, ohne Time-Slicing; die App nutzt weder
useTransition noch useDeferredValue. Eine Eigenheit: SVG-Attribute in camelCase setzt Redact nur bei
clip…, fill… und stroke… als clip-path, fill-opacity usw.; textAnchor, stopColor, stopOpacity,
vectorEffect, paintOrder und Ähnliche kämen unverändert im DOM an und wirkten nicht. Solche Werte stehen
deshalb im style (style={{ textAnchor: 'end' }}), was mit React wie mit Redact gilt. Zurück zu React geht
es, indem man redact() aus vite.config.mts nimmt.
Warum es schnell ist¶
- Push statt Polling: Die WebUI ruft in jedem offenen Tab alle 3 Sekunden ein ReGa-Skript über alle angezeigten Kanäle auf. Beim Add-on meldet die CCU Änderungen von selbst, und der Server verteilt sie nur an die Verbindungen, die den Kanal anzeigen. ReGa wird für Gerätewerte nur beim Öffnen einer Ansicht gefragt.
- Keine Seiten vom Server: Die WebUI lässt ReGa jede Seite als HTML erzeugen. Die App wechselt Seiten im Browser und holt nur Daten.
- Wenig zu laden, und nur einmal: 17 Dateien mit 355 KB (gzip-gepackt, 1,1 MB entpackt) bis zum fertigen Dashboard statt 40 Dateien mit 3,1 MB, die die lighttpd der CCU ungepackt schickt. Danach kommt die App aus dem Cache des Service Workers. Große Teile wie die Verknüpfungsvorlagen und die Seiten von Einrichten lädt sie erst bei Bedarf.
- Ein kleiner Server: Das Go-Binary hat 10 MB und braucht rund 15 MB RAM (14 MB mit allen CCU-Verbindungen, 16 MB mit 10 offenen Apps, gegen die Fake-CCU gemessen). Ein leerer HTTP-Server unter Node.js 22 braucht allein 46 MB, die Laufzeit 118 MB auf dem Speicher.
- Caches, wo die CCU es erlaubt: Gerätebeschreibungen ändern sich nur mit der Firmware und werden im Server gehalten. Auf der App-Seite hält TanStack Query die Daten, sodass ein Zurück sofort da ist.
- Gezieltes Rendern: Ein Event ändert genau ein Objekt im Cache; alle anderen Kacheln bleiben, wie sie sind.
Codeumfang¶
| Zeilen | |
|---|---|
| Go-Server | 21.944 |
| Go-Tests | 8.607 |
| App (TypeScript, ohne Tests und generierten Code) | 28.817 |
| Unit-Tests der App | 2.073 |
| End-to-End-Tests | 4.496 |
| Protokoll-Schema | 12.790 |
| HM-Script-Vorlagen | 1.475 |