{"id":51035379,"url":"https://github.com/tostmann/rfnethm","last_synced_at":"2026-06-22T05:02:27.386Z","repository":{"id":360441704,"uuid":"1235514948","full_name":"tostmann/RFNETHM","owner":"tostmann","description":"Network adapter for an unmodified HmIP-RFUSB stick — exposes BidCoS/HmIP radio over LAN to FHEM, Homegear, piVCCU, RaspberryMatic.","archived":false,"fork":false,"pushed_at":"2026-06-09T20:47:25.000Z","size":4601,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-06-09T22:20:14.919Z","etag":null,"topics":["busware","eq-3","esp32","esp32-s3","fhem","hmip","hmip-rfusb","homegear","homematic-ip","pivccu","raspberrymatic"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"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":null,"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-11T11:55:53.000Z","updated_at":"2026-06-09T20:49:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tostmann/RFNETHM","commit_stats":null,"previous_names":["tostmann/rfnethm"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/tostmann/RFNETHM","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tostmann%2FRFNETHM","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tostmann%2FRFNETHM/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tostmann%2FRFNETHM/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tostmann%2FRFNETHM/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tostmann","download_url":"https://codeload.github.com/tostmann/RFNETHM/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tostmann%2FRFNETHM/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":["busware","eq-3","esp32","esp32-s3","fhem","hmip","hmip-rfusb","homegear","homematic-ip","pivccu","raspberrymatic"],"created_at":"2026-06-22T05:02:26.366Z","updated_at":"2026-06-22T05:02:27.373Z","avatar_url":"https://github.com/tostmann.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RFNETHM — HmIP-Funk übers Netzwerk\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logos/Lab-Setup.jpeg\" alt=\"DIY WiFi Gateway: HmIP-RFUSB-Stick am ESP32-S3-Devkit\" width=\"420\"\u003e\n\u003c/p\u003e\n\n**Ein Adapter, der einen unmodifizierten HmIP-RFUSB-Stick (oder ein\nRPI-RF-MOD / HM-MOD-RPI-PCB am Pin-Header) ins Netzwerk hängt** — statt\nihn an einen lokalen USB-Port zu zwingen.  Damit wird der Funk-Stick\nzu einem netzwerkweit erreichbaren BidCoS-/HmIP-Frontend für FHEM,\nHomegear, piVCCU oder RaspberryMatic — ohne dass eine echte CCU oder\nein Pi am Funk-Standort stehen muss.\n\nStatus: **Firmware v0.15.0** (2026-05-25), Devkit-Bringup abgeschlossen,\nalle vier Kreuze der Ground-Truth-Matrix (HB-RF-ETH × {HM-MOD,\nRPI-RF-MOD} und RFNETHM × {HM-MOD, RPI-RF-MOD}) live ge-flasht. Multi-Client-\nStress-Test (4 HMU + 3 raw-UART + UDP + HTTP-Poll @5 Hz parallel) über\nmehrere Minuten ohne HTTP-Aussetzer, ohne Reconnect-Storm, Uptime\nungebrochen. v0.15.0 bringt OTA-Update-Badge (WebUI zeigt automatisch\nwenn auf [`install.busware.de/rfnethm/`](https://install.busware.de/rfnethm/)\neine neuere Firmware verfügbar ist) und einen vergrößerten LWIP-Socket-Pool\ngegen Reconnect-Storms. Eigenes PCB ist in Planung.\n\nFlashen geht am bequemsten über den **Browser-Webflasher** unter\n[`https://install.busware.de/rfnethm/`](https://install.busware.de/rfnethm/) —\nESP32-S3 anstecken, *Connect*, fertig.  Updates kommen danach OTA übers\nWebUI; das Gerät meldet selbst wenn eine neue Version online ist.\n\n---\n\n## Datenfluss\n\n```\n   HmIP-RFUSB           RFNETHM                dein Server\n   (eq-3 Original)      (ESP32 + WLAN/Eth)     (FHEM, Homegear,\n                                                piVCCU, RaspberryMatic)\n       USB ───────────► USB-Host\n                        │\n                        └─── WLAN/Ethernet ───►  hb_rf_eth.ko\n                                                 /dev/raw-uart\n                                                 oder TCP-Socket\n```\n\nAlternativ statt USB-Stick: **RPI-RF-MOD** oder **HM-MOD-RPI-PCB**\ndirekt auf den 40-Pin-Header — selber Adapter, gleicher Server-Pfad.\n\n---\n\n## Wozu das gut ist\n\n- **Funkstandort frei wählbar.** Stick steht da, wo der Empfang gut ist\n  (Estrich, Garage, Pegel-Sweet-Spot); die Hausautomation läuft woanders.\n- **Drop-in für alle gängigen Stacks.** Aus Sicht des Servers ist es\n  ein normales `hb_rf_eth`-Gerät (Alex Reinerts Kernel-Modul) **oder**\n  eine HM-MOD-RPI-PCB-Bridge (TCP/2330). Beide Wege gleichzeitig nutzbar.\n- **Kein zusätzlicher Pi nötig.** Wer bisher einen Pi nur als Funkträger\n  nutzt, kann ihn ersetzen.\n- **Kein Custom-RF-Stack.** Der Funk-Teil bleibt der echte eq-3-Stick mit\n  eq-3-Firmware — alle BidCoS-/HmIP-Eigenheiten, AES, Pegelhandling\n  sind genauso wie im Original.\n\n---\n\n## Netzwerk-Schnittstellen (parallel offen)\n\n| Port | Format | Was redet damit |\n|---|---|---|\n| **UDP 3008** | HB-RF-ETH wire-format | `hb_rf_eth.ko` → `/dev/raw-uart` für piVCCU / RaspberryMatic |\n| **TCP 2330** | HMUARTLGW | FHEM `CUL_HM`, Homegear, jeder Stack der eine HM-MOD-RPI-PCB-Bridge erwartet |\n| **TCP 2329** | Raw-Bytestream | bmcond, eigene Tools, Reverse-Engineering |\n| **HTTP 80** | WebUI + REST | Status, OTA-Update, WLAN-Setup, Live-Log |\n| **mDNS** | `_raw-uart._udp:3008` | Auto-Discovery (`rfnethm-XXXX.local` + Alias `rfnethm.local`) |\n\nEingehende Funk-Frames werden gleichzeitig an alle verbundenen Clients\ngespiegelt.  Senden ist mit einem **TX-Master-Soft-Lock** gegen\nMehrfach-Schreiber abgesichert (erster Sender bekommt den Stick für\n5 s, danach übernimmt der nächste; per WebUI festpinnbar).\n\n---\n\n## Was Du brauchst\n\n- **Funk-Hardware** (eine Variante):\n  - HmIP-RFUSB-Stick (eq-3 Original, USB `1B1F:C020`), oder\n  - RPI-RF-MOD am 40-Pin-Header — **braucht 5 V auf Header-Pin 2/4**\n    (eigener on-board-LDO, kein 3V3-Pfad), oder\n  - HM-MOD-RPI-PCB am 40-Pin-Header — 3,3 V auf Pin 1 reicht\n- **ESP32-S3-Devkit** mit nativem USB-OTG-PHY (z.B. YD-ESP32-S3 V1.4)\n  und Pin-Header für den HM-Modul-Slot.  Ein eigenes PCB (ESP32-S3-WROOM-1-N16R2\n  + W5500 + vertikaler USB-C-OTG-Stecker + HM-Slot) ist in Vorbereitung.\n- **5 V / 200 mA** Versorgung über die zweite USB-C-Buchse am Devkit.\n  Wer RPI-RF-MOD nutzt, muss zusätzlich 5 V auf den HM-Header (Pin 2/4)\n  durchziehen — siehe [`docs/breadboard_wiring.md`](docs/breadboard_wiring.md).\n- **WLAN** im Lab — Ethernet kommt mit dem eigenen PCB-Spin.\n\n---\n\n## Inbetriebnahme (Kurz)\n\n1. **Flashen.** Drei Wege, von \"einfach\" nach \"Source-Build\":\n\n   - **Webflasher (empfohlen)** — Browser auf\n     [`https://install.busware.de/rfnethm/`](https://install.busware.de/rfnethm/)\n     öffnen, ESP32-S3 per USB anstecken, **Connect** klicken. Funktioniert\n     auf Chrome / Edge / Opera (Web-Serial-API).  Kein lokaler Build,\n     keine PlatformIO-Installation nötig.\n   - **CLI mit fertigem Image** — siehe\n     [Vorgebackene Binaries](#vorgebackene-binaries-flash-via-esptool) unten.\n   - **Source-Build via PlatformIO**:\n     ```sh\n     pio run -e rfnethm -t upload\n     ```\n2. **WLAN provisionieren.** Zwei Wege:\n   - **Improv-Serial**: Browser → improv-wifi.com → ESP über die\n     Console-USB-Buchse verbinden → Credentials eingeben.\n   - **Captive-AP-Fallback**: erscheint nach 30 s als WLAN\n     `RFNetHM XXXX`, Handy verbindet sich, jede HTTP-Anfrage landet\n     im Setup-Formular.\n3. **Im WebUI** (`http://rfnethm.local` oder `http://rfnethm-XXXX.local`) Status checken; alle\n   Funk-Frames stehen sofort am Netzwerk-Port bereit.\n4. **Server-Seite** konfigurieren:\n   - piVCCU / RaspberryMatic: `hb_rf_eth.ko` mit der IP des RFNETHM laden\n     (Schritt-Screenshot weiter unten unter\n     [RaspberryMatic / OpenCCU einbinden](#raspberrymatic--openccu-einbinden)).\n   - FHEM: `define hmusb HMUARTLGW rfnethm-XXXX.local:2330`.\n\n---\n\n## Vorgebackene Binaries (Flash via esptool)\n\nFür CLI-Nutzer, die keinen Web-Serial-fähigen Browser haben oder den\nFlash skripten wollen, liegen unter [`webflasher/`](webflasher/) im\nRepo dieselben Images, die auch der Webflasher serviert:\n\n- **`webflasher/factory_rfnethm_esp32s3.bin`** — Komplett-Image\n  (bootloader + partition-table + ota_data + Applikation).  Erst-Flash\n  für ein jungfräuliches oder anders belegtes ESP32-S3.\n- **`webflasher/firmware_rfnethm_esp32s3.bin`** — nur die Applikation\n  (offset `0x10000`).  Für OTA-Updates über die WebUI, oder als\n  gezielter Re-Flash auf bereits provisioniertes Gerät.\n\nImage-Inhalt ist deckungsgleich mit dem aktuellen Release-Tag und der\nVersion, die der Webflasher unter\n[`https://install.busware.de/rfnethm/`](https://install.busware.de/rfnethm/)\nausliefert (siehe `webflasher/manifest.json`).\n\n```sh\n# 1) Erst-Flash via USB (ESP32-S3 im Download-Mode — BOOT-Button halten,\n#    RESET kurz, BOOT loslassen).  Port-Pfad gegebenenfalls anpassen.\nesptool.py --chip esp32s3 --port /dev/ttyACM0 --baud 921600 \\\n    write_flash 0x0 webflasher/factory_rfnethm_esp32s3.bin\n\n# 2) OTA-Update via WebUI (empfohlen sobald das Gerät im Netz ist —\n#    kein Druck auf BOOT-Button nötig, keine USB-Verbindung):\ncurl -X POST --data-binary @webflasher/firmware_rfnethm_esp32s3.bin \\\n    http://rfnethm-XXXX.local/api/ota\n\n# 3) Reiner Re-Flash der Anwendung über USB (ohne Partition-Tabelle\n#    anzufassen — z.B. wenn nur ein neuer Build aufgespielt werden soll):\nesptool.py --chip esp32s3 --port /dev/ttyACM0 --baud 921600 \\\n    write_flash 0x10000 webflasher/firmware_rfnethm_esp32s3.bin\n```\n\n`esptool.py` liegt bei PlatformIO bei (`~/.platformio/penv/bin/esptool.py`)\noder kommt out-of-the-box aus `pip install esptool`.  Auf macOS / Windows\nist der Port-Pfad entsprechend `/dev/cu.usbmodem*` bzw. `COMx`.\n\n---\n\n## WebUI\n\nDie eingebaute Web-Oberfläche ist unter `http://rfnethm.local/`\nerreichbar (kurzer Alias, gedacht für den Normalfall mit einem Stick im\nNetz) bzw. unter dem eindeutigen `http://rfnethm-XXXX.local/` (XXXX =\nletzte 4 Hex-Stellen der MAC, stabiler Pfad).  Sie zeigt\nSources, Sinks und System-Status als Kachel-Dashboard — inklusive\nReset-Reason, Heap- und Stack-HWM-Indikator für den Dauerlauf-Betrieb,\nTX-Master-Soft-Lock pro Sink, Live-Log, OTA-Update und WLAN-Provisioning.\n\n\u003e Falls mehrere RFNETHM-Sticks am gleichen LAN hängen: `rfnethm.local`\n\u003e wird von beiden gleichzeitig beworben — welcher tatsächlich antwortet,\n\u003e hängt vom mDNS-Race ab.  Wer eindeutig ansprechen will, nimmt\n\u003e `rfnethm-XXXX.local`.\nLight- und Dark-Theme sind per Toggle in der Headbar umschaltbar, die\nWahl wird pro Browser persistiert; ohne explizite Wahl folgt das\nTheme der OS-Präferenz (`prefers-color-scheme`).\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"logos/webUIDark.png\"\u003e\n    \u003cimg alt=\"RFNETHM WebUI (Light/Dark — folgt der OS-Präferenz beim Anzeigen auf GitHub)\" src=\"logos/webUI.png\" width=\"460\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n---\n\n## RaspberryMatic / OpenCCU einbinden\n\nIn RaspberryMatic bzw. OpenCCU unter **System-Optionen → Erweiterte\nEinstellungen** trägst Du die IP-Adresse (oder den mDNS-Namen\n`rfnethm-XXXX.local`) des RFNETHM in das Feld\n**„IP-Adresse (HB-RF-ETH)\"** ein und bestätigst mit *Änderungen\nspeichern*.  Danach lädt RaspberryMatic den `hb_rf_eth.ko`-Pfad neu\nund der angeschlossene HmIP-RFUSB-Stick (oder das RPI-RF-MOD am\nPin-Header) erscheint als lokales `/dev/raw-uart`.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logos/CCU-Config.png\" alt=\"OpenCCU / RaspberryMatic — IP-Adresse (HB-RF-ETH) eintragen\" width=\"640\"\u003e\n\u003c/p\u003e\n\n---\n\n## Status — was funktioniert\n\n**Verifiziert (live gegen reale Hardware):**\n\n- USB-Host-Init des HmIP-RFUSB-Stick, Mode-Switch BL → App\n- Beide HM-Modul-Familien am Pin-Header (HM-MOD-RPI-PCB / Co_CPU\n  und RPI-RF-MOD / DualCoPro), Auto-Erkennung beim Boot\n- HMUARTLGW-Codec byte-genau gegen Live-Captures\n- `hb_rf_eth.ko`-Pfad bis zur Aktor-Toggle-Schaltung in RaspberryMatic\n- FHEM `CUL_HM` / HMUARTLGW-Bridge bis Phase D (TX, RX, AES-Key-Storage)\n- Coprocessor-Firmware-Flash von beiden Modul-Familien über bmcond\n  via UDP-Transport (RPI-RF-MOD 4.4.22 ⇆ 4.2.14, HM-MOD 2.8.6 ⇆ 2.2.1)\n- Multi-Client-Fanout, TX-Master-Lock, mDNS, Captive-AP-Fallback, OTA\n\n**Nicht fertig:**\n\n- AES-Authentifizierung in der Legacy-Bridge (Phase E — mehrtägig,\n  kein Blocker für AES-aware Devices).\n- Eigenes PCB (Schaltplan und Pin-Mapping stehen; siehe\n  `docs/decisions.md`).\n\n---\n\n## Was RFNETHM **nicht** ist\n\n- **Kein** Drop-in-Replacement für den HmIP-RFUSB am unmodifizierten\n  RaspberryMatic-Kernel-Treiber: der USB-Pfad ist via ECDSA gesperrt\n  (bewusste Design-Entscheidung von Alex Reinert, wird respektiert).\n  Variante B des Projekts (CP2102N mit OTP-Brand `1B1F:C020`) ist eine\n  separate Bauform und ohne ESP32.\n- **Kein** eigenes Wireformat.  UDP/3008 mit HB-RF-ETH-Frames und\n  TCP/2330 mit HMUARTLGW sind die Default-Sprachen.\n- **Keine** BidCoS-/HmIP-Protokoll-Interpretation in der Stick-Firmware\n  — reiner Transport, alle HM-Logik bleibt downstream.\n\n---\n\n## Ist das was für mich?\n\n- **Ja**, wenn Du HmIP-Funk in einer Linux-Hausautomation (FHEM,\n  Homegear, piVCCU, RaspberryMatic) nutzt und Funk-Standort vom\n  Server-Standort entkoppeln willst.\n- **Ja**, wenn Du einen alten Pi loswerden willst der nur den\n  HmIP-Stick / das RPI-RF-MOD trägt.\n- **Nein**, wenn Du eine vollständige CCU-Funktionalität ohne\n  Server-Stack willst — dafür ist RaspberryMatic die richtige Adresse,\n  RFNETHM ist nur der Funk-Adapter.\n- **Nein**, wenn Du Klassik-Homematic-Funk (BidCoS, AskSinPP) ohne\n  HmIP brauchst — da ist ein CUL/COC der bessere Match.\n\n---\n\n## Mehr lesen\n\n- [`docs/intro.md`](docs/intro.md) — ausführliche Einführung\n- [`docs/breadboard_wiring.md`](docs/breadboard_wiring.md) — Verkabelung\n  am Devkit\n- [`docs/ethernet_addition.md`](docs/ethernet_addition.md) — Ethernet-\n  Anbindung für den PCB-Spin\n- [`docs/diagrams/`](docs/diagrams/) — Architektur- und\n  Message-Flow-Diagramme\n\n---\n\n## Lizenz\n\nGPL-2.0-or-later (analog PIIF / CULFW32).  Listener-Code ist eigene\nReimplementierung gegen die HB-RF-ETH-Spec — kein Copy aus dem\nCC-BY-NC-SA-4.0-lizenzierten Original-Repo.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"logos/busmatic.png\" alt=\"busmatic\" width=\"160\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003csub\u003eRFNETHM ist ein Lab-Projekt aus dem Tostmann-RF-Lab.\u003c/sub\u003e\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftostmann%2Frfnethm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftostmann%2Frfnethm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftostmann%2Frfnethm/lists"}