{"id":51035380,"url":"https://github.com/tostmann/headlessccu","last_synced_at":"2026-06-22T05:02:27.423Z","repository":{"id":357446777,"uuid":"1236950870","full_name":"tostmann/headlessCCU","owner":"tostmann","description":"HomeMatic CCU stack without WebUI / ReGaHss — bmcond + rfd + HMIPServer.jar packaged as Home Assistant add-on and plain Docker image.","archived":false,"fork":false,"pushed_at":"2026-06-07T16:57:38.000Z","size":157,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-07T18:27:06.997Z","etag":null,"topics":["bmcond","ccu","docker","home-assistant","home-assistant-addon","homematic","homematic-ip","raspberrymatic"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tostmann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-12T18:22:40.000Z","updated_at":"2026-06-07T16:57:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tostmann/headlessCCU","commit_stats":null,"previous_names":["tostmann/headlessccu"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/tostmann/headlessCCU","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tostmann%2FheadlessCCU","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tostmann%2FheadlessCCU/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tostmann%2FheadlessCCU/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tostmann%2FheadlessCCU/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tostmann","download_url":"https://codeload.github.com/tostmann/headlessCCU/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tostmann%2FheadlessCCU/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34635038,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bmcond","ccu","docker","home-assistant","home-assistant-addon","homematic","homematic-ip","raspberrymatic"],"created_at":"2026-06-22T05:02:26.535Z","updated_at":"2026-06-22T05:02:27.410Z","avatar_url":"https://github.com/tostmann.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# headlessCCU\n\nHomeMatic CCU **without the WebUI / ReGaHss**.  Bundles\n[bmcond](https://github.com/tostmann/bmcond) + eQ-3's `rfd` +\n`HMIPServer.jar` + a JSON-RPC stub for `aiohomematic` in a single\ncontainer.\n\nThis repository follows the Home Assistant **Add-On Repository**\nlayout: `repository.yaml` at the root, and the actual add-on under\n`headlessccu/`.  Both the HA-Supervisor \"Add Repository\" UI and a\nplain `docker compose` from the subdirectory work out of the box.\n\nTwo distribution paths from the same image:\n\n- **Home Assistant Add-On** (HA Supervisor / HAOS) — install via the\n  Add-On store, configure via UI, [`homematicip_local`](https://github.com/SukramJ/homematicip_local)\n  connects to it locally.\n- **Plain Docker / docker-compose** — on any host with Docker and an\n  HmIP-RFUSB stick plugged in.  Speaks XML-RPC on `:2001` (BidCoS) and\n  `:2010` (HmIP) plus JSON-RPC on `:8765`, so any consumer (Home\n  Assistant `homematicip_local`, ioBroker, Homegear, NodeRED, custom\n  scripts) just connects.\n\n## Why not the regular CCU?\n\nThe eQ-3 CCU stack pulls in ReGaHss (Tcl logic engine), HMServer.jar,\nWebUI, eshlight, and a few hundred MB of Tcl/web assets — none of which\nare needed when Home Assistant is your automation engine.  headlessCCU\nstrips the stack down to just the parts that actually move RF frames:\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ Home Assistant (or any XML-RPC consumer)                    │\n└──┬──────────────────────────────────────────────────────────┘\n   │ XML-RPC :2001 (BidCoS), :2010 (HmIP), JSON-RPC :80 / :8765\n┌──▼──────────────────────────────────────────────────────────┐\n│ headlessCCU container                                       │\n│  ┌────────────┐  ┌────────────┐  ┌─────────────────────┐    │\n│  │ rfd        │  │ HMIPServer │  │ rega_session_mock   │    │\n│  │ (BidCoS)   │  │ (HmIP)     │  │ (aiohomematic stub) │    │\n│  └─────┬──────┘  └──────┬─────┘  └─────────────────────┘    │\n│  /dev/mmd_bidcos    /dev/mmd_hmip    ↑ JSON-RPC :8765       │\n│        ▲                  ▲           (Session.login etc.)  │\n│        └─────────┬────────┘                                 │\n│             multimacd                                       │\n│        (eq-3 Mac-Layer: DUTY, CSMA, AES, demux)             │\n│                  │                                          │\n│             /dev/raw-uart (PTY)                             │\n│                  │                                          │\n│               bmcond                                        │\n│        (userspace transport — libusb / UDP / TCP / UART)    │\n└────────────┬───────────────────────────────────────────────┘\n             │ libusb-direct  /dev/bus/usb\n       ┌─────▼─────┐\n       │ HmIP-RFUSB │\n       └────────────┘\n```\n\n`bmcond` claims `/dev/bus/usb`, detaches whatever kernel driver had\nbound the stick, and exposes the radio's wire bytes as a PTY symlink.\n`multimacd` opens that PTY as its `Coprocessor Device Path` and\nhandles all Mac-Layer concerns (DUTY-cycle, CSMA, AES, retransmits,\nLLMAC ↔ APP translation, BidCoS / HmIP demuxing).  No\n`/dev/ttyUSB0`, no udev rule, no `cp210x` module blacklist needed for\nthe default path.  An HA-side `rega_session_mock` answers the\nJSON-RPC calls `aiohomematic` issues during setup — no ReGaHss\nrunning on the container side.\n\n## Quick install — Home Assistant Add-On (HAOS)\n\nThis is the recommended path on HAOS / Home Assistant Supervisor.\n\n**Step 1 — Add this repository to the Add-On store.**\n\n1. Settings → Add-ons → Add-on Store\n2. Click the three-dots menu (top right) → **Repositories**\n3. Paste `https://github.com/tostmann/headlessCCU` → **Add**, then close\n\n**Step 2 — Install the add-on.**\n\n1. The repository panel now appears at the bottom of the Add-on Store.\n   Click **headlessCCU**.\n2. Click **Install**.  HA Supervisor builds the image locally; this\n   takes ~5 minutes on a Raspberry Pi 5 because eQ-3 binaries are\n   fetched at build time from `apt.debmatic.de` (no eQ-3 closed-source\n   blobs are vendored into this repository).\n3. Once installed, plug in your **eQ-3 HmIP-RFUSB** stick if it isn't\n   already (USB-ID `1b1f:c020`).\n\n**Step 3 — Defaults work out of the box.**\n\nThe default `hmid: \"auto\"` makes the add-on roll a random 3-byte\ngateway address on first start and persist it.  Default transport\n`usb=1b1f:c020` opens the HmIP-RFUSB via libusb directly.  No\nconfiguration is required for a single-stick setup.\n\nIf you have more than one CCU-like instance in the same LAN, or you\nwant to migrate pairings from an existing eQ-3 / debmatic install, set\nthe `hmid` option to a fixed 6-hex value.\n\n**Step 4 — Start the add-on.**\n\n1. Toggle **Start on boot** and **Watchdog** on.\n2. Press **Start**.\n3. Open **Log**.  You should see a banner with the firmware bundle\n   version, an `eQ-3 HmIP-RFUSB` backend coming up via libusb, and\n   `── BusMatic-HASS up ──` after ~30 s.\n4. Open **headlessCCU** in the HA sidebar (Ingress panel) — the bmcond\n   web UI shows the source inventory and slot mapping.\n\n**Step 5 — Connect Home Assistant.**\n\nInstall the `homematicip_local` custom integration (e.g. via HACS).\nThen **Settings → Devices \u0026 Services → Add Integration → HomematicIP\nLocal**:\n\n| Field | Value |\n| --- | --- |\n| Instance name | `headlessccu` (or whatever) |\n| Host | `172.30.32.1` (the HA Supervisor bridge gateway) |\n| Username / Password | anything — the mock accepts any credentials |\n| `custom_port_config` | leave off — defaults work |\n\nThe integration auto-detects both `BidCos-RF` and `HmIP-RF` interfaces.\nConfirm the device list (initially empty) and finish setup.\n\n**Step 6 — Pair your first device.**\n\nIn Home Assistant, **Settings → Devices \u0026 Services → HomematicIP Local\n→ … (kebab) → Reload** to make the integration register interfaces.\n\nTo put the gateway into pair mode:\n\n```bash\n# in any host with access to the HA host:\ncurl -X POST http://172.30.32.1:2001/ \\\n  -d '\u003c?xml version=\"1.0\"?\u003e\u003cmethodCall\u003e\u003cmethodName\u003esetInstallMode\u003c/methodName\u003e\u003cparams\u003e\u003cparam\u003e\u003cvalue\u003e\u003cboolean\u003e1\u003c/boolean\u003e\u003c/value\u003e\u003c/param\u003e\u003cparam\u003e\u003cvalue\u003e\u003ci4\u003e60\u003c/i4\u003e\u003c/value\u003e\u003c/param\u003e\u003c/params\u003e\u003c/methodCall\u003e'\n\ncurl -X POST http://172.30.32.1:2010/ \\\n  -d '\u003c?xml version=\"1.0\"?\u003e\u003cmethodCall\u003e\u003cmethodName\u003esetInstallMode\u003c/methodName\u003e\u003cparams\u003e\u003cparam\u003e\u003cvalue\u003e\u003cboolean\u003e1\u003c/boolean\u003e\u003c/value\u003e\u003c/param\u003e\u003cparam\u003e\u003cvalue\u003e\u003ci4\u003e60\u003c/i4\u003e\u003c/value\u003e\u003c/param\u003e\u003c/params\u003e\u003c/methodCall\u003e'\n```\n\nPress the pair button on your HM-Classic or HmIP device.  Once the\ndevice announces itself, it appears as a new entity in HA within a few\nseconds.\n\n## Quick install — Plain Docker / docker-compose\n\n```bash\ngit clone https://github.com/tostmann/headlessCCU\ncd headlessCCU/headlessccu      # add-on lives in a subdir (HA-repo layout)\n./build.sh                      # builds headlessccu:dev image (~5 min)\ndocker compose up -d\n```\n\n`docker-compose.yml` sets `network_mode: host` (required so XML-RPC\ncallbacks from `rfd` reach Home Assistant) and passes\n`/dev/bus/usb` through to the container.  See the file for the full\nport and environment-variable layout.\n\n`build.sh` pulls the matching [bmcond](https://github.com/tostmann/bmcond)\nversion (default `2026.5.1`, override via `BMCOND_VERSION=main ./build.sh`)\nand the pinned eq-3 bundle (`DEBMATIC_VERSION=3.85.7-123` by default;\noverride via `DEBMATIC_VERSION=latest ./build.sh`) at Docker-build time —\nno local source-staging required.\n\nVerify with the included smoke test (in this repo's parent project):\n\n```bash\ncurl http://localhost:9126/api/effective | jq .running\n```\n\nshould print a `version` and a non-zero `uptime_s`.\n\n## Configuration options\n\n| Option | Default | Description |\n| --- | --- | --- |\n| `hmid` | `auto` | `auto` = random 3-byte hex on first start, persisted to `/data/etc-config/ids`.  Or a fixed 6-hex string |\n| `serial` | `BMC0000001` | 10-char gateway serial reported to clients |\n| `firmware` | `2.8.6` | Firmware version reported to clients |\n| `bidcos_radio` | `usb=1b1f:c020` | Transport for the BidCoS plane |\n| `hmip_radio` | `usb=1b1f:c020` | Transport for the HmIP plane.  Empty or `none` = HmIP disabled |\n| `loglevel` | `3` | `rfd` loglevel (0–5) |\n| `log_level_mock` | `INFO` | `rega_session_mock` Python logging level |\n\nTransport-string formats: `usb=VID:PID` (libusb-direct),\n`rfusb=/dev/ttyXXX` (kernel-driver UART), `host:port` (TCP, e.g.\nCULFW32 or HM-LGW2), `udp=host:port` (HB-RF-ETH / RFNetHM).\n\nFor HA Supervisor: configurable via the Add-On UI.  Plain Docker:\nenvironment variables in `docker-compose.yml`.\n\n## BidCoS-only setup (HmIP disabled)\n\nSet `hmip_radio` to empty or `none`.  Effects:\n\n- `bmcond` runs without an HmIP PTY (no `/tmp/mmd_hmip`).\n- `HMIPServer.jar` is not started; port 2010 returns no service.\n- `confgen` writes `InterfacesList.xml` without the `HmIP-RF` slot, so\n  `aiohomematic` only registers the BidCoS interface.\n\nUseful for HM-Classic-only deployments — e.g. when the only RF source\nis a CULFW32 acting as a BidCoS gateway over `_hmuartlgw._tcp:2327`.\n\n## Legacy: cp210x-via-kernel path\n\nIf you want to keep the old kernel-driver path (e.g. coexisting with\nanother tool that owns `/dev/ttyUSB0`), set\n`bidcos_radio: \"rfusb=/dev/ttyUSB0\"` in the options and apply this\none-time host setup:\n\n```bash\n# /etc/modprobe.d/blacklist-eq3.conf\nblacklist hb_rf_usb_2\nblacklist hb_rf_usb\nblacklist generic_raw_uart\n\n# /etc/modules-load.d/cp210x.conf\ncp210x\n\n# /etc/udev/rules.d/70-hmip-rfusb-cp210x.rules\nACTION==\"add\", SUBSYSTEM==\"usb\", ATTRS{idVendor}==\"1b1f\", ATTRS{idProduct}==\"c020\", \\\n  RUN+=\"/sbin/modprobe cp210x\", \\\n  RUN+=\"/bin/sh -c 'echo 1b1f c020 \u003e /sys/bus/usb-serial/drivers/cp210x/new_id'\"\n```\n\nRe-plug the stick after udev reload — `ls -l /dev/ttyUSB0` should now\nappear.  The container then receives it via\n`--device /dev/ttyUSB0:/dev/ttyUSB0`.\n\n## License\n\nGPL-2.0-or-later — see [LICENSE](LICENSE).\n\n\u003e The Docker image *built* by this repo bundles eQ-3 closed-source\n\u003e binaries fetched from `apt.debmatic.de`.  Do **not redistribute the\n\u003e built image publicly** — each user builds locally from upstream\n\u003e debmatic, which is what Alexander Reinert's packaging\n\u003e ([alexreinert/debmatic](https://github.com/alexreinert/debmatic)) is\n\u003e designed for.\n\n## Project context\n\nPart of the BusMatic effort by Dirk Tostmann\n([@tostmann](https://github.com/tostmann)).  `bmcond`\n([github.com/tostmann/bmcond](https://github.com/tostmann/bmcond))\nprovides the userspace radio transport layer; this repo wraps it\ntogether with eQ-3's `multimacd`, `rfd` and `HMIPServer.jar` into a\nsingle container for HA / Docker consumption.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftostmann%2Fheadlessccu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftostmann%2Fheadlessccu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftostmann%2Fheadlessccu/lists"}