ESP-IDF firmware for ESP32 + CC1101 — a Wireless M-Bus 868 MHz receiver/gateway for water meter telegram reception.
- Receives Wireless M-Bus T-mode telegrams on 868.95 MHz via CC1101
- Captures raw frames with RF metadata (RSSI, LQI, CRC status)
- Uses raw bytes as canonical in-pipeline frame representation (hex is derived for API/MQTT/UI)
- Publishes raw telegrams and telemetry via MQTT
- Uses
cJSON-based JSON serialization with RAII wrappers in API/services (no manual JSON escaping paths) - Maintains detected meters inventory and configurable watchlist (alias/note/enabled)
- Provides a built-in modern web control panel for diagnostics, meters/watchlist workflow, configuration, OTA, and support
- Includes first-boot Initial Setup UX in provisioning mode (WiFi + admin password + optional MQTT)
- Supports OTA firmware updates (HTTPS URL and direct binary upload endpoint with rollback support)
- Stores config in NVS with validation, migration, and import/export
- Integrates with Home Assistant and external decoders (e.g., wmbusmeters)
The ESP32 + CC1101 is primarily a robust RF receiver and gateway.
Heavy meter-specific decoding remains external by default.
See docs/ARCHITECTURE.md for the full design.
- ESP-IDF v5.2+
- CMake 3.16+
. $IDF_PATH/export.sh
idf.py buildidf.py -p /dev/ttyUSB0 flash monitorcd tests/host
mkdir -p build && cd build
cmake ..
cmake --build .
ctest --output-on-failure- ESP32 (4MB flash, any devkit)
- CC1101 868 MHz transceiver module
- Default SPI wiring (current board profile): MOSI=23, MISO=19, SCK=18, CS=5, GDO0=4, GDO2=2
- 868 MHz antenna (quarter-wave ~86mm wire or proper PCB antenna)
| Document | Description |
|---|---|
| Architecture | System design, task model, data flow |
| Repository Layout | File structure and dependency rules |
| Configuration | Config model, NVS, import/export |
| MQTT Topics | Topic hierarchy and payload contracts |
| Web Panel | Web UI pages and API endpoints |
| OTA | Firmware update procedures |
| Security | Threat model and security design |
| Provisioning | First-boot setup |
| Testing | Test strategy and guide |
| Hardware Bring-Up | First real board validation checklist |
| Operations | Operational guidance |
| Troubleshooting | Common issues |
| Limitations | Known constraints |
| Release Readiness | Pre-release and post-hardware checklists |
Core components are implemented but not yet validated on real hardware:
- Foundation types, event bus, config store with NVS persistence
- WiFi STA/AP, NTP, mDNS, MQTT with reconnect
- CC1101 SPI driver with T-mode register config (untested on hardware)
- WMBus pipeline with dedup and routing
- Detected meters + watchlist service with API/UI integration
- Auth service with SHA-256 password hashing
- HTTP server with auth middleware and REST API
- OTA manager (URL-based OTA and streamed binary upload endpoint)
- Web panel (static HTML/JS/CSS served from SPIFFS)
- Diagnostics, metrics, health monitoring, watchdog, support bundle
- 9 host test suites, CI pipeline
Status: Pre-hardware-validation. Host tests pass with a prepared host toolchain. Real RF reception, NVS persistence, WiFi/MQTT connectivity, and full ESP-IDF build validation still require local ESP-IDF environment verification and board testing.
Next: Hardware validation with real CC1101 + water meters.
Private project. Not open source.