HM Program I/O

Ein Zusatzsoftware-Addon für HomeMatic CCU3 / openCCU / RaspberryMatic, mit dem du HomeMatic-Programme (Zentralen-Programme aus der WebUI) als JSON exportieren und wieder importieren kannst.

Funktionen

• Übersicht aller Programme der CCU (ID, Name, Aktiv-Status, Sichtbarkeit, Beschreibung, letzte Ausführung)
• Export der ausgewählten (oder aller) Programme als JSON-Datei zum lokalen Download
• Import aus JSON-Datei:
  • existierende Programme (Match per Name) werden aktualisiert: Aktiv-Status und/oder Beschreibung
  • fehlende Programme werden optional als leere Programme angelegt
• Reines WebUI-Frontend, Backend = TCL-CGIs, die per tclrega.exe ReGa-Scripts ausführen

Was geht (ehrlich) nicht

Die Bedingungs- und Aktionsbäume eines HomeMatic-Programms (das eigentliche „Wenn… Dann…") sind intern als komplexe Objektstruktur in der ReGa abgelegt. Diese 1:1 per HMScript zu serialisieren und wiederherzustellen wäre ein erheblich größeres Projekt. Dieses Addon konzentriert sich daher bewusst auf den praktischen Hauptnutzen:

• Programme als Liste sichern (Doku/Versionierung)
• Aktiv-Status im Bulk umschalten (z. B. „alle Anwesenheits-Programme deaktivieren vor Urlaub")
• Beschreibungen übernehmen
• Programm-Hüllen anlegen, in denen du anschließend die Bedingungen in der WebUI definierst

Für ein vollständiges Backup deiner CCU bleibt der eingebaute Sicherungsmechanismus (System-Backup) die richtige Wahl.

Installation

1. Aus diesem Repo das Archiv hm_program_io.tar.gz bauen (siehe unten) oder herunterladen.
2. CCU-WebUI öffnen → Einstellungen → Systemsteuerung → Zusatzsoftware.
3. Installieren → das .tar.gz auswählen → die Sicherheitsabfrage bestätigen.
4. Aufruf der UI: http://<CCU-IP>/addons/hm_program_io/index.html (oder über den neuen Eintrag „HM Program I/O" in der Systemsteuerung).

Bedienung

Export

1. „Programme laden" klickt das Addon automatisch beim Öffnen.
2. Per Checkbox einzelne Programme markieren — oder keine, dann werden alle exportiert.
3. „Export starten" → Datei hm_programs_<timestamp>.json wird heruntergeladen.

Import

1. JSON-Datei wählen.
2. Optionen:
   • Fehlende anlegen — Programme, die noch nicht existieren, werden als leere Programme erzeugt.
   • Aktiv-Status übernehmen — active aus der Datei wird gesetzt.
   • Beschreibung übernehmen — description wird übernommen.
3. „Import starten" → das Addon iteriert über alle Einträge. Ergebnis-Zähler und ein Log-Bereich zeigen pro Programm UPD/NEW/SKIP/ERR.

JSON-Format

{
  "type": "hm_program_io_export",
  "version": 1,
  "exportedAt": "2026-05-13T19:00:00.000Z",
  "programs": [
    {
      "id": "1234",
      "name": "Flurlicht Bewegung",
      "description": "Schaltet das Flurlicht bei Bewegung",
      "active": 1,
      "visible": 1,
      "lastTrigger": "1715600000"
    }
  ]
}

Du kannst die Datei nach dem Export auch manuell editieren (z. B. active auf 0 setzen) und sie dann wieder importieren.

Technik

• update_script — Installer (Symlinks, Menüeintrag).
• rc.d/hm_program_io — Stub (kein Daemon).
• www/index.html, www/app.js, www/style.css — Frontend.
• www/list.cgi — listet Programme als JSON (ruft tclrega.exe mit ReGa-Script).
• www/import.cgi — importiert ein einzelnes Programm pro Aufruf, base64url-encoded Felder für saubere Übergabe beliebiger Strings.

Die CGIs schneiden den <xml>…</xml>-Footer aus der tclrega.exe-Antwort ab, sodass reines JSON beim Frontend ankommt.

Bauen des Archivs

Auf Windows (PowerShell, in diesem Verzeichnis):

.\build.ps1

Das Skript

• normalisiert alle Textdateien auf LF-Zeilenenden (wichtig für die Shell-Scripts auf der CCU),
• patcht die Mode-Bits im USTAR-Header auf 0755 (Windows tar.exe setzt sonst kein exec-Bit, der CCU-Installer /bin/install_addon lehnt sonst mit Exit 104 ab),
• erstellt hm_program_io.tar.gz im Eltern-Verzeichnis.

Auf Linux/Mac:

find hm_program_io -type f \( -name '*.sh' -o -name '*.cgi' -o -name 'update_script' -o -name 'hm_program_io' \) -exec chmod +x {} \;
tar -czf hm_program_io.tar.gz -C hm_program_io .

Wichtig: Das Archiv darf das Verzeichnis nicht als oberste Ebene enthalten — die Dateien (insbesondere update_script) müssen direkt auf der Wurzel des .tar.gz liegen, sonst erkennt die CCU das Paket nicht.

Lizenz / Haftung

MIT. Bitte teste den Import zuerst auf einer Test-CCU oder mache vorher ein System-Backup.