Entwicklung¶
Hier findest du alles, was du brauchst, um am Add-on zu arbeiten: die lokale Umgebung, die wichtigsten Befehle, den Aufbau des Repositorys und die üblichen Handgriffe, etwa für eine neue Nachricht, eine neue Kachel oder einen neuen Text.
Voraussetzungen¶
- Bun 1.4 oder neuer: installiert die Pakete und führt die Skripte aus, auch den Testrunner von
Playwright (
bun --bun playwright test); welche Version die CI nimmt, steht inpackage.jsonunterpackageManager - Go 1.27 oder neuer (für den Server, die Fake-CCU und die Stack-Tests)
- für die E2E-Tests einmal
bun run test:e2e:install, das installiert Chromium für Playwright
Drei Arten zu entwickeln¶
Ohne CCU: gegen die Fake-CCU¶
Das startet die Fake-CCU (mit fixtures/demo-ccu.json), den Go-Server und Vite zusammen, mit Buns
bun run --parallel (die Ausgabe jedes Skripts steht hinter seinem Namen). Strg+C beendet alle, Strg+Z
hält alle an und fg setzt sie fort; beendet sich eines, stoppt Bun die anderen. Bun schickt dabei
SIGINT nur an den Prozess des Skripts, deshalb besteht jeder Schritt aus einem einzigen Befehl: Die
Go-Programme baut ein prestart:*-Skript mit go build, das Skript selbst startet sie mit exec.
go run ginge nicht, es ignoriert SIGINT und reicht es nicht weiter. Bun leitet die Ausgabe durch eine
Pipe, die Skripte setzen deshalb FORCE_COLOR=1, wenn sie in einem Terminal laufen, damit die Farben
bleiben. Die Tastenkürzel von Vite (h, o, r, …) gibt es nur, wenn du bun run start:fe allein
startest. Die App läuft
dann auf http://localhost:4200, du meldest dich mit Admin / secret an (oder mit Gast / gast).
Hier kannst du alles gefahrlos ausprobieren, sogar die Werkseinstellungen. Willst du sehen, wie die App
reagiert, wenn ein Gerät einen Wert meldet, geht das so:
curl -X POST http://127.0.0.1:18080/fake/set \
-d '{"interface":"HmIP-RF","address":"0008DA8A9F1234:1","datapoint":"STATE","value":true}'
Gegen die eigene CCU¶
cp go-server/.env.example go-server/.env
# in go-server/.env: CCU_HOST, CCU_USER/CCU_PASS (falls die CCU Authentifizierung verlangt)
# und CALLBACK_HOST = IP dieses Rechners
bun run dev
Der Go-Server läuft dann auf deinem Rechner und spricht über das Netz mit deiner CCU. Damit Events ankommen, muss die CCU deinen Rechner auf Port 9098 erreichen können. Wenn du den Server mit Strg+C beendest, meldet er sich bei der CCU wieder ab.
Nur die App, gegen das installierte Add-on¶
Vite leitet /ws/mui an die CCU weiter, deren Adresse steht in vite.config.mts unter
proxyTargets.ccu3. Das ist praktisch, wenn du nur an der Oberfläche arbeitest.
Befehle¶
| Befehl | Wirkung |
|---|---|
bun run dev:fake |
Fake-CCU + Server + App |
bun run dev |
Server + App gegen die CCU aus go-server/.env |
bun run start:fe:ccu3 |
nur App, Proxy auf die CCU |
bun run build |
App bauen, Typen prüfen, Server für ARMv7 und amd64 bauen, mui-<version>-arm-ccu3-raspi.tar.gz und mui-<version>-x86_64-pc.tar.gz packen |
bun run generate:protocol |
src/types/protocol.ts aus protocol/schema.json erzeugen |
bun run export:ccu |
eine echte CCU nur lesend auslesen und als Fixture speichern |
bun run test |
Unit-Tests (Vitest) |
bun run typecheck |
TypeScript prüfen |
bun run lint |
Formatierung und Lint-Regeln prüfen (Biome, Regeln in biome.json) |
bun run lint:fix |
Formatieren und behebbare Lint-Befunde beheben |
bun run test:go |
Go-Tests |
bun run test:e2e |
Playwright mit Mock-WebSocket |
bun run test:stack |
Playwright gegen Go-Server + Fake-CCU |
bun run test:visual |
Screenshot-Vergleich (:update erneuert die Bilder; in der CI im Playwright-Image) |
bun run docs:screenshots |
die Bilder in docs/ neu aufnehmen (Mock und Fake-CCU) |
bun run docs:tiles |
die bewegten Bilder der Kacheln (docs/kacheln/) neu aufnehmen, braucht ffmpeg |
Mehr zu den Tests findest du unter Tests.
Aufbau des Repositorys¶
src/ App (React, TypeScript); Aufbau in architektur.md
messages/ Texte der App, de.json und en.json
protocol/schema.json Vertrag zwischen App und Server
go-server/ Server, Fake-CCU, CCU-Export
fixtures/ Daten für Fake-CCU und Tests
e2e/, e2e-stack/ Playwright-Tests
addon_installer/ Dateien, die ins Add-on-Archiv kommen (Startskript, lighttpd, update_script)
scripts/ import-link-profiles.mjs (Verknüpfungsvorlagen aus OpenCCU-Base),
import-parameter-labels.mjs (Namen der Parameter aus OpenCCU-Base),
import-service-texts.mjs (Texte der Servicemeldungen aus OpenCCU-Base)
docs/ diese Dokumentation
Konventionen¶
- Nach den OpenCCU-Quellen bauen. Bevor du eine Funktion baust, die die CCU betrifft, schau nach, wie
die WebUI sie umsetzt. Die CCU hat viele Eigenheiten, und ihre Quellen sind die verlässlichste Referenz:
OpenCCU mit den gepatchten Dateien der WebUI unter
buildroot-external/package/openccu-base/rootfs-patches/*/rootfs/www/, und OpenCCU-Base mit der ganzen WebUI (www/webui/webui.js,www/config/easymodes/**,www/rega/esp/controls/*.fn). Am einfachsten klonst du sie flach:git clone --depth 1 https://github.com/OpenCCU/OpenCCU-Base. Dort findest du Datenpunkte, Wertelisten, ReGa-Skripte und XML-RPC-Aufrufe. - Die Quelle nennen. Wenn eine Quelle ein Detail entscheidet, schreib sie in den Kommentar oder die
Commit-Nachricht, zum Beispiel „wie in der WebUI
door_opener.fn“. So kann später jeder nachvollziehen, warum etwas so ist. - Formatierung und Lint-Regeln setzt Biome durch (
biome.json), die CI prüft beides, auch Warnungen. Lass vor dem Commitbun run lint:fixlaufen; die Erweiterungbiomejs.biomefür VS Code formatiert beim Speichern. Schlägt eine Regel an, obwohl der Code stimmt, nimm die Stelle mit// biome-ignore <regel>: <Grund>aus, statt die Regel abzuschalten. - SVG-Präsentationsattribute wie
textAnchor,stopColorodervectorEffectgehören in denstyle(style={{ stopColor: color }}): Die Laufzeit TanStack Redact setzt in camelCase nurclip…,fill…undstroke…richtig (siehe Architektur). Echte SVG-Attribute wieviewBoxoderstdDeviationbleiben, wie sie sind. - Texte der Oberfläche gibt es auf Deutsch und Englisch. Halte sie kurz und vermeide Fachjargon, wo es geht.
- Ein Feature, ein Pull Request. Kleine PRs lassen sich leichter prüfen. Gemergt wird, wenn die CI grün ist.
- Keine Geheimnisse ins Repository, also keine privaten Schlüssel und keine Passwörter. Die Testzertifikate erzeugen die Tests selbst, während sie laufen.
Eine neue Nachricht¶
- Schema: Leg in
protocol/schema.jsonunterpropertieseinen Eintrag"meinTyp": {"$ref": "#/definitions/MeinTypCall"}an. Unterdefinitionskommen dazuMeinTypCallmitrequestundresponsesowie die DefinitionenMeinTypRequestundMeinTypResponse. Nimm die Antwort außerdem inServerMessageauf. Alle Objekte bekommen"additionalProperties": false. - Typen erzeugen:
bun run generate:protocol. - Server: Trag den Typ in
go-server/pkg/websocket/dispatch.goim Dispatcherdispatchein (was nur eine CCU hat, indispatch_ccu.go), bei reinen Lesezugriffen auch inparallelReads. Den Handler schreibst du in die Datei seiner Domäne, etwadevices.go,links.go,pairing.go,logic.go(Programme und Systemvariablen) oderfavorites.go;websocket.goselbst enthält nur den Server und die Verbindungen,client.godie einzelne Verbindung. Für Einstellungen gibt esconfigure(...)inconfigure.go: Es prüft die Rechte, führt die Aktion aus, schreibt ins Audit-Log und antwortet. Für das Bedienen gibt esoperate(...)mit denselben Schritten: Gäste dürfen nicht. Handler mit eigenen Prüfungen zwischen Recht und Aktion (Datenpunkte, Favoriten, Layouts) nehmencanOperateselbst. Räume, Gewerke, Kanäle, Namen, Favoriten und Servicemeldungen liest und ändert der Handler übers.home(die Schnittstellehome.Sourceingo-server/pkg/home), nicht direkt über die ReGa: Auf der CCU steckt die ReGa dahinter, auf openccu-lite dessen APIs. Nur was es ausschließlich auf der CCU gibt, etwa Programme oder Systemvariablen, rufts.regaClientdirekt, und zwar nur in Dateien mit//go:build !lite. Eine Datei, die beide Builds nutzen, ruft dafür eine kleine Funktion ausrega_ccu.go. Ihr Gegenstück für openccu-lite steht inrega_lite.go. - Fake-CCU: Braucht die Aktion etwas Neues von der CCU, etwa ein Skript, eine XML-RPC-Methode oder eine
CGI-Seite, bildest du es in
go-server/pkg/fakeccunach. Neue ReGa-Vorlagen erkennt die Fake-CCU von selbst an ihrem Text, du ergänzt nur die Antwort in der TabellescriptHandlers(scripthandlers.go). XML-RPC-Methoden stehen inrpcMethods(rpcmethods.go). - App: Schreib in
src/queries/index.tseine Query oder Mutation, dierequest('meinTyp', …)aufruft. Die Typen kommen aus dem Schema. - Tests: Ein Go-Integrationstest prüft die Antwort automatisch gegen das Schema. Er gehört in die
passende
go-server/stack_*_test.gound fragt mitcall(t, conn, message{…})ausstack_helpers_test.go. Ist es eine sichtbare Funktion, gehört noch ein Stack-Test ine2e-stack/stack.spec.tsdazu.
Eine Kachel für ein neues Gerät¶
- Schlag den Kanaltyp und seine Datenpunkte nach: in der Gerätebeschreibung in OpenCCU-Base
(
opt/HMServer/HMIPServer.jar→de/eq3/cbcs/devicedescription/…für HmIP,firmware/rftypes/*.xmlfür BidCos) und wie die WebUI das Gerät bedient (www/rega/esp/controls/*.fn). - Bau die Kachel unter
src/controls/. Werte setzt du mituseSetDataPoint, gemeinsame Bausteine findest du insrc/components/Tile.tsxundGestures.tsx. - Trag den Kanaltyp in
src/controls/registry.tsein, mit Abschnitt undper: 'channel'oder'device'. - Nimm einen Kanal mit den echten Datenpunkten in den Mock (
e2e/helpers/websocketMock.ts) auf und schreib einen Test ine2e/frontend-mocked-websocket.spec.ts. Sieht etwas neu aus, erneuere auch die Screenshots.
Echte Daten bekommst du über einen Export deiner eigenen CCU:
Der Export ändert nichts an deiner CCU, er liest nur: Räume, Gewerke, Kanäle mit ihren Werten,
Gerätebeschreibungen und Paramsets. Mit -anonymize werden die Namen von Räumen, Gewerken und Geräten
ersetzt, damit du die Datei teilen kannst. Passwörter lassen sich nicht exportieren, die Fixture bekommt
deshalb Admin / secret. Mit go run ./cmd/fakeccu -fixture … (in go-server/) läuft deine eigene CCU
dann als Fake.
Texte und Übersetzungen¶
Die Texte stehen in messages/de.json und messages/en.json. Beide Dateien haben dieselben Schlüssel, der
Test src/i18n/messages.test.ts passt darauf auf. Paraglide JS macht daraus typisierte Funktionen:
import { m } from '../paraglide/messages';
<span>{m.WINDOWS_OPEN()}</span>
<span>{m.MOTION_MINUTES_AGO({ minutes: 3 })}</span>
Vite übersetzt die Texte beim Start und bei jeder Änderung selbst. Brauchst du es einmal von Hand:
bunx paraglide-js compile --project ./project.inlang --outdir ./src/paraglide \
--emit-ts-declarations --strategy preferredLanguage baseLocale
Geschweifte Klammern in Texten sind Platzhalter, nimm {name} also nur für Variablen. Die Sprache richtet
sich nach dem Browser, sonst ist es Englisch.
Verknüpfungsvorlagen aktualisieren¶
Die Profile der Direktverknüpfungen stammen aus den Easymodes der WebUI:
Das Skript liest www/config/easymodes/<Empfänger>/<Sender>.tcl samt Übersetzungen und schreibt daraus
src/controls/links/linkProfiles.json.
Die importierten Daten (Verknüpfungsprofile, Parameternamen, Texte der Servicemeldungen) stehen wie ihre Quelle, die WebUI, unter der Apache-Lizenz 2.0, nicht unter der AGPL. THIRD_PARTY_LICENSES.md nennt sie und liegt dem Add-on bei; ein neues Import-Skript gehört dort mit in die Liste.
Umgebungsvariablen¶
Der Server liest seine Einstellungen aus Umgebungsvariablen (go-server/pkg/config/config.go). Auf der CCU
kommen sie aus /usr/local/etc/config/mui.conf, lokal aus go-server/.env.
| Variable | Standard | Bedeutung |
|---|---|---|
CCU_HOST |
localhost |
Adresse der CCU |
CCU_USER, CCU_PASS |
– | Basic Auth für ReGa und XML-RPC, falls die CCU sie verlangt (nur aus dem LAN; auf der CCU nicht nötig) |
CALLBACK_HOST |
127.0.0.1 |
Adresse, unter der die CCU den Event-Server erreicht |
RPC_SERVER_PORT |
9098 |
Port des Event-Servers |
WS_PORT, WS_BIND_HOST |
8089, 127.0.0.1 |
WebSocket-Server; auf der CCU übernimmt update_script einen WS_PORT aus mui.conf in die Weiterleitung von lighttpd |
REGA_PORT |
8183 bei localhost, sonst 8181 |
ReGa |
SYSVAR_INTERVAL |
5 |
Sekunden zwischen zwei Abfragen der Systemvariablen, solange eine App sie zeigt |
RPC_PORT, HMIP_PORT, VIRTUAL_DEVICES_PORT |
bei localhost aus /etc/config/InterfacesList.xml (sonst 32001, 32010, 39292), aus dem LAN 2001, 2010, 9292 |
Funkdienste |
WIRED_PORT |
bei localhost aus InterfacesList.xml (nur mit Wired-Gateway), sonst 0 (aus) |
BidCos-Wired (hs485d); aus dem LAN von Hand setzen, meist 2000 |
CCU_WEBUI_URL |
http://<CCU_HOST> |
WebUI für JSON-RPC und CGI-Seiten |
AUTH_MODE |
ccu |
none schaltet die Anmeldung ab |
AUTH_KEY_FILE, SESSIONS_FILE, AUDIT_LOG_FILE, PUSH_FILE, DIAGRAMS_FILE, RULES_FILE, TILES_FILE |
unter /usr/local/etc/config |
Dateien des Add-ons |
DIAGRAMS_DIR |
/usr/local/mui-diagrams |
Diagrammwerte |
DATA_DIR |
– | ein Verzeichnis für alle Dateien des Add-ons und die Diagrammwerte; auf openccu-lite /usr/local/etc/config/addons/mui, weil das Add-on dort nur in eigene Verzeichnisse schreiben darf. Einzeln gesetzte Pfade gehen vor |
BACKUP_DIR |
/usr/local/tmp/mui-backups auf der CCU, sonst $TMPDIR/mui-backups |
Backups bis zum Download, Uploads |
CCU_CONFIG_DIR, CCU_STATUS_DIR |
/etc/config, /var/status |
Konfiguration der CCU |
ADDONS_DIR, SYSLOG_CONFIG, LOG_DIR, TIME_CONF_FILE, NTP_CLIENT_FILE, TZ_FILE, GROUPS_FILE |
Pfade der CCU | Zusatzsoftware, Logs, Uhr, Heizgruppen |
DEVICE_FIRMWARE_SERVER |
https://ccu3-update.homematic.com |
eQ-3-Updateserver für Geräte-Firmware |
CCU_WWW_DIR |
/www |
Dateien der WebUI (Gerätebilder, Texte der Servicemeldungen) |
APP_DIR |
/usr/local/addons/mui |
die installierte App; assets/ liefert der Server gzip-gepackt aus |
USERFS_DIR, FIRMWARE_DOWNLOAD_FILE |
/usr/local, /usr/local/tmp/firmwareUpdateFile |
Freier Speicher und Ziel des CCU-Firmware-Downloads |
FIRMWARE_UPLOAD_DIR, FIRMWARE_STAGED_LINK |
/usr/local/tmp, /usr/local/.firmwareUpdate |
Hochgeladene CCU-Updates und der Link, über den die WebUI das geprüfte Update bereitstellt |
CCU_FIRMWARE_RELEASES |
https://github.com/openccu/openccu/releases/download |
Releases mit SHA256-Dateien |
ADDON_RELEASE_URL, ADDON_UPDATE_DIR |
GitHub-API der neuesten Release, /usr/local/tmp |
Update des Add-ons ohne Neustart der CCU: woher die neue Version kommt und wo sie ausgepackt wird |
OCCULITE_URL, OCCULITE_TOKEN_FILE |
http://127.0.0.1, /run/occulite/addon-tokens/mui.api |
nur openccu-lite: occulited und das API-Token des Add-ons |
LITE_FORCE |
– | nur openccu-lite: startet das Lite-Binary auch ohne openccu-lite, etwa gegen die Fake-CCU mit -lite |
PUSH_SUBJECT |
GitHub-URL | Kontakt in Push-Anfragen |
DEBUG |
false |
ausführliches Log |
Wie man alle Pfade für eine Testumgebung umbiegt, siehst du an den Stack-Tests in
playwright.stack.config.ts.
openccu-lite¶
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, steht in Dateien mit Build-Tag:
main_ccu.goundmain_lite.goverbinden die Plattform,pkg/websocket/dispatch_ccu.goverteilt, was nur eine CCU hat (Programme, Systemvariablen, Alarme, Benutzer, die Systemeinstellungen der WebUI). Die Handler-Dateien dafür tragen//go:build !lite, Felder des Servers, die nur die CCU braucht, stehen inccuState(pkg/websocket/state_ccu.go), auchregaClient: Der Lite-Build kennt ihn nicht, ein Aufruf aus einer gemeinsamen Datei bricht dort das Übersetzen. Die CI prüft beide Builds mitstaticcheck; fehlt einer CCU-Datei das Tag, meldet es ihren Code im Lite-Build als ungenutzt. Das Hausmodell (Räume, Gewerke, Kanäle, Namen) liegt hinterhome.Source: auf der CCUpkg/rega, auf openccu-litepkg/occulite. - Werte und Events: Auf openccu-lite meldet sich der Server nicht per
initals Callback-Server an. Er liest beim Start den Zustandsspeicher (/api/rpc/v1/state) und folgt ab dort dem Event-Stream (/api/rpc/v1/events), der nach einer Unterbrechung das Verpasste nachholt; meldet erresync, liest der Server den Zustandsspeicher neu. Die Funkdienste erreicht er über occuliteslite-rpc(ccurpc.NewProxy, XML-RPC unter/api/rpc/v1/xmlrpc/<Interface>), nicht über ihre lokalen Ports. Was ein Nutzer auslöst, geht mit dessen Sitzung (Client.WithToken,Home.ForSession), alles andere mit dem Token des Add-ons. - Eigene Daten: Kachel-Layouts, die Kachelwahl und die Kachelnamen je Kanal liegen wie auf der CCU in
mui-tiles.json(pkg/tiles), auf openccu-lite im Datenverzeichnis. Der Modus von Eingangskanälen und die Favoritenlisten liegen dort inmui-lite.json, weil es keine ReGa für sie gibt. Räume, Gewerke und Namen ändert der Server in occulites Metadaten-Speicher; Räume heißen dort Pfade (room/eg/wohnzimmer), KanäleHmIP-RF.<Adresse>, und die App bekommt daraus feste Zahlen-IDs (occulite.ID). - Geräteverwaltung: Anlernen, Paramsets und Direktverknüpfungen laufen wie auf der CCU über XML-RPC,
hier durch
lite-rpc. Einen Posteingang hat openccu-lite nicht: Neu sind dort die Geräte ohne Eintrag im Metadaten-Speicher, Übernehmen legt ihn mit dem Namen<Typ> <Adresse>an. Heizgruppen gehen über occulites/api/system/v1/groups(occulite.Groups), Gerätefirmware lädt und verteilt occulite selbst. - Servicemeldungen und Gesundheit: Die Servicemeldungen sammelt occulited selbst
(
/api/system/v1/service-messages); eine Sticky-Meldung bestätigt der Server, indem er sie am Gerät zurücksetzt. Geräteprobleme und Geräte-Gesundheit kommen aus den Werten der Wartungskanäle. Alarme gibt es ohne ReGa nicht; Push-Benachrichtigungen und Regeln laufen unverändert. - Hinweise statt Lücken: Statt der Programme zeigt die App auf openccu-lite, wo Automationen dort laufen
(Node-RED unter
/addons/red/, die Zusatzsoftware, Direktverknüpfungen), und unter System Links auf occulites eigene Seiten (src/views/setup/LiteHints.tsx). In occulites Rahmen übernimmt sie dessen Hell/Dunkel und Sprache (?theme=,?lang=,postMessageopenccu-lite:theme). - Anmeldung: Auf openccu-lite meldet occulites Gate vor
/addons/die Sitzung im HeaderX-Occulite-Session, auch am WebSocket-Upgrade. Deshalb verbindet sich die App installiert mit/addons/mui/ws. - Die App ist für beide gleich. Bei der Anmeldung schickt der Server
platformundcapabilitiesmit, danach blendet sie aus, was es nicht gibt. - Paket:
make build-litebaut die Server für aarch64 und x86_64,bun run buildpackt darausmui-<version>-aarch64-lite.tar.gzundmui-<version>-x86_64-lite.tar.gzmitopenccu-lite.json. Das Add-on läuft dort als eigener Benutzer und schreibt nur nach/usr/local/etc/config/addons/mui(DATA_DIR);addon_installer/rc.d/mui-liteundaddon_installer/lite/sind die Teile dafür. - Testen:
go test -tags lite ./...startet den Lite-Server gegen die Fake-CCU im Lite-Modus (fakeccu.CCU.Lite): keine ReGa, dafür occulites APIs aus der Fixture. Von Hand geht das mitgo run ./cmd/fakeccu -lite, das die Umgebung für den Server ausgibt.
Release¶
Ein Release beginnt mit einem Tag vX.Y.Z, nach demselben Schema wie in den anderen Projekten
(firsttris/workflows). Den Tag kannst du auf zwei Wegen anlegen:
- ohne Checkout: unter Actions → Bump version → patch, minor oder major (
bump.yml). Das erhöht die Version inpackage.json, committet sie alsRelease vX.Y.Zaufmain, setzt den Tag und startetrelease.ymldarauf. - lokal: mit
bun run release:patch(oder:minor,:major). Commit und Tag werden dann perpostversiongepusht.
release.yml lässt anschließend Build, Go- und Playwright-Tests laufen und legt die Release mit den
Archiven mui-<version>-arm-ccu3-raspi.tar.gz und mui-<version>-x86_64-pc.tar.gz an. Die Tests entfallen,
wenn die CI auf main sie für denselben Code schon bestanden hat: Der Release-Commit von Bump version
ändert nur die Version. Die Notizen erzeugt
GitHub aus den Pull Requests seit der letzten Version. Lokal baut bun run build dieselben Archive, und
jeder Build in der CI hängt sie als Artefakt addon an.