Table of Contents

• ESPHome - Release V3.0.0
• Features
  • Full feature list
  • Advanced Frame Validation
• Integration Options
  • Option 1: ESPHome Component (Recommended)
  • Option 2: Standalone with MQTT
  • Quick Start: First Successful Reading
• Hardware
  • Connections (ESP32/ESP8266 to CC1101)
  • CC1101
• MQTT Integration
• Multiple Devices
• Home Assistant Best Practice: Utility Meter Helper
  • Migrating Sensor History Between Platforms
  • Historical Data from Meter
• Configuration
  • Local Development Setup
  • Reading Schedule
  • Time zone offset and wake-up window (simple)
  • Home Assistant Discovery Toggle (MQTT mode)
  • Radio and frequency (advanced)
  • Frequency Configuration
  • Adaptive Frequency Management
• Troubleshooting
  • Meter reads fail: near-field RF saturation (device too close to meter)
  • Corrupted or Invalid Volume Readings
  • ESP32 build: ModuleNotFoundError: No module named 'intelhex'
  • ESP32 compile errors about ESP8266 headers
  • Frequency Adjustment
  • Business Hours
  • Serial Number Starting with 0
  • Distance Between Device and Meter
• Important: Utility Read Counter Compatibility
  • Recommended Actions
• Credits
• Legal Notice
  • Community Resources

The firmware implements multiple layers of validation to ensure data integrity:

1. Custom Serial Decoding: RADIAN protocol uses a proprietary serial encoding with 1 start bit + 8 data bits (LSB first) + 3 stop bits per byte. Each bit is oversampled 4x for noise immunity (logical '1' = 0xF0, logical '0' = 0x0F). The decoder verifies bit-level transitions, counts consecutive samples, validates start/stop bits, and extracts clean data bytes. This is NOT standard Manchester encoding-it's custom serial framing that must be decoded in software.

2. CRC-16/KERMIT Checksum: Each RADIAN frame includes a 16-bit checksum (polynomial 0x8408, init 0x0000). Technically this is a Frame Check Sequence (FCS), not a true CRC, but it's highly effective at catching transmission errors and corrupted frames. The checksum is computed over the full 124-byte frame (bytes [0..121], including the length byte) and compared against the trailer in the last two bytes [122-123]. The firmware rejects any frame that fails this check.

3. Frame Structure Validation:

   • Preamble pattern matching (0xAAAAAAAA sync word)
   • Fixed-length frame verification (58 bytes expected)
   • Header field sanity checks (protocol version, frame type)
   • Meter serial number matching (only accepts frames from your configured meter)

4. Temporal Validation:

   • Wake window verification (Time Start/End must be valid 24-hour format)
   • Reading counter continuity checks (detects duplicate or out-of-sequence frames)
   • Battery level sanity bounds (0-200 months typical range)

5. Signal Quality Filtering:

   • RSSI threshold (configurable, default -90 dBm)
   • LQI (Link Quality Indicator) assessment
   • Frequency error estimation for adaptive tuning

6. Reading Plausibility (History Cross-Check):

   • The frame carries up to 13 months of historical volume snapshots. The firmware rejects the whole reading when the implied current-month usage (current volume minus the newest history snapshot) exceeds 100× the largest historical monthly usage. A corrupted current volume shows up as an absurd jump versus the meter's own history.
   • The check is skipped (the reading is accepted) when there is insufficient history to judge: fewer than 2 valid months, a flat history with no recorded usage, or a current volume that predates the newest snapshot. First reads and no-consumption meters are therefore unaffected.

Result: Data is only published after passing every check above, so corrupted or partial frames are discarded rather than reported to Home Assistant.

Best for: Users who want direct control, custom builds, or already use MQTT extensively.

• Full control over firmware
• PlatformIO-based development
• MQTT AutoDiscovery for Home Assistant
• Extensive customisation options

Quick start: Edit include/private.h and build with PlatformIO (see below).

Quick Start: First Successful Reading

1. Hardware you need

• ESP8266 (HUZZAH / Wemos D1 Mini) or ESP32 DevKit.
• CC1101 433 MHz RF module (3.3V only).
• USB cable and jumper wires.

See the Hardware section below for full wiring tables and pictures.

2. Files you must edit

• include/private.h (copy from include/private.example.h):
  • Wi‑Fi SSID/password
  • MQTT broker/port (+ credentials, if used)
  • ENABLE_HA_DISCOVERY - set to 0 to disable Home Assistant discovery topic publishing (homeassistant/...) and keep raw MQTT topics only
  • METER_CODE (full under-barcode code with dashes)
  • METER_TYPE - set to "water" (default) or "gas" depending on your meter type
  • GDO2 - required by default (v3.0.0+): GPIO connected to CC1101 GDO2 (hardware FIFO management). To opt out and use legacy SPI polling, define DISABLE_GDO2_FIFO_MANAGEMENT instead. The firmware will not compile until you do one or the other.
  • MAX_RETRIES - maximum reading retry attempts before cooldown (optional, default is 5)
  • AUTO_SCAN_ON_FAILURE_ENABLED - set to 1 to automatically run a frequency scan once after MAX_RETRIES is reached (recovers from carrier-frequency drift unattended); default is 0 (disabled)
  • ADAPTIVE_THRESHOLD - how many successful reads before adjusting frequency (optional, default is 1 = adjust after each read)
  • WIFI_SERIAL_MONITOR_ENABLED - set to 1 to enable WiFi serial monitor for remote debugging (default is 0 for security)
• platformio.ini: select env:huzzah (ESP8266 HUZZAH) or env:esp32dev (ESP32 DevKit).

Meter Type Configuration

This project supports both water meters and gas meters. The main differences are:

To configure your meter type, set METER_TYPE in include/private.h:

#define METER_TYPE "water"  // For water meters
// OR
#define METER_TYPE "gas"    // For gas meters

Gas Meter Volume Divisor

For gas meters, this firmware assumes an internal count in litre-equivalents and converts those values to cubic metres (m³) before publishing to Home Assistant. If your gas meter uses a different base unit or scaling, you may need to adjust the meter configuration or conversion logic accordingly.

The conversion uses a configurable gas volume divisor that can be set in include/private.h:

// Default: 100 (equivalent to 0.01 m³ per unit)
#define GAS_VOLUME_DIVISOR 100

Important: The correct divisor depends on your meter's pulse weight configuration:

• 100: 0.01 m³ per unit (typical for modern EverBlu Cyble gas modules)
• 1000: 0.001 m³ per unit (0.1 L per unit, less common)

How We Determined the Correct Divisor

If your readings seem incorrect: Verify your specific meter's pulse weight (often printed on the device label) and adjust GAS_VOLUME_DIVISOR accordingly.

3. Build and upload the firmware

First-time USB Upload

1. Wire the CC1101 to your board as shown in the Hardware section.
2. Connect the board to your computer via USB.
3. Open the project folder in VS Code with PlatformIO installed.
4. Select your board environment using the PlatformIO status bar at the bottom:
   • For Adafruit HUZZAH ESP8266: select env:huzzah
   • For WeMos D1 Mini: select env:d1_mini
   • For WeMos D1 Mini Pro: select env:d1_mini_pro
   • For NodeMCU v2: select env:nodemcuv2
   • For ESP32 DevKit: select env:esp32dev
5. Click the PlatformIO: Upload and Monitor button (→ with line) in the status bar, or use the PlatformIO sidebar:
   • Click the PlatformIO icon on the left sidebar
   • Expand your environment (e.g., "huzzah")
   • Click "Upload and Monitor"
6. Wait for the build and upload to complete.
7. On first boot, wait up to ~2 minutes while the automatic wide frequency scan runs (serial monitor will show progress).
8. Once the scan finishes, you should see meter data in the serial monitor and MQTT topics everblu/cyble/{PARSED_SERIAL}/... on your broker/Home Assistant.

Over-The-Air (OTA) Updates

Once your device is running and connected to Wi-Fi, you can update it wirelessly:

1. In platformio.ini, find your board's -ota environment (e.g., [env:huzzah-ota]).

2. Update the IP address to match your device's IP:

   upload_port = 192.168.2.21  ; Change to your device's IP
   monitor_port = socket://192.168.2.21:23  ; Change to match upload_port

3. Select the OTA environment in PlatformIO:

   • For HUZZAH: select env:huzzah-ota
   • For D1 Mini: select env:d1_mini-ota
   • For D1 Mini Pro: select env:d1_mini_pro-ota
   • For NodeMCU v2: select env:nodemcuv2-ota
   • For ESP32 DevKit: select env:esp32dev-ota

4. Click PlatformIO: Upload and Monitor as before.

5. The firmware will be uploaded over your Wi-Fi network.

Note: You can find your device's IP address in the serial monitor output at startup, or check your router's DHCP client list, or look at the everblu/cyble/{PARSED_SERIAL}/wifi_ip MQTT topic in Home Assistant.

Regulatory Notes

The EU declaration of conformity for the Cyble RF family (Cyble NRF, Cyble NRF HT, Cyble OMS wM-Bus 434) specifies operation in the 434 MHz ISM band with ≤ 10 mW radiated power. The CC1101 settings used in this project stay within that envelope, but ensure your antenna choice and deployment follow local regulations.

Quick Reference: Wemos D1 Mini

CC1101 → Wemos D1 Mini
VCC    → 3V3
GND    → G
SCK    → D5 (GPIO 14)
MISO   → D6 (GPIO 12)
MOSI   → D7 (GPIO 13)
CSN    → D8 (GPIO 15)
GDO0   → D1 (GPIO 5)
GDO2   → D2 (GPIO 4)  ← required by default, set #define GDO2 in private.h (or opt out)

Quick Reference: Adafruit Feather HUZZAH ESP8266

CC1101 → HUZZAH ESP8266
VCC    → 3V
GND    → GND
SCK    → #14 (GPIO 14)
MISO   → #12 (GPIO 12)
MOSI   → #13 (GPIO 13)
CSN    → #15 (GPIO 15)
GDO0   → #5  (GPIO 5)
GDO2   → #4  (GPIO 4)  ← required by default, set #define GDO2 in private.h (or opt out)

Quick Reference: ESP32 DevKit (esp32dev)

CC1101 → ESP32 DevKit
VCC    → 3V3
GND    → GND
SCK    → SCK (GPIO 18 on most DevKit boards)
MISO   → MISO (GPIO 19)
MOSI   → MOSI (GPIO 23)
CSN    → GPIO 25 (recommended; avoids the GPIO 5 strapping pin)
GDO0   → GPIO 4 (or GPIO 27)  ← set this in include/private.h as GDO0
GDO2   → GPIO 27 (or another free GPIO)  ← required by default, set #define GDO2 in private.h (or opt out)

Notes for ESP32

• Use the board’s hardware SPI pins (SCK/MISO/MOSI). The defaults are provided by the Arduino core and used automatically by this project.
• For chip-select (CSN/CS), prefer a non-strapping GPIO such as GPIO 25. The common default SS (GPIO 5) is a strapping pin and logs a boot-time warning, though it still works.
• Choose a free GPIO for GDO0 (e.g., 4 or 27) and set #define GDO0 <pin> in include/private.h.
• Wire GDO2 to another free GPIO and set #define GDO2 <pin> to enable hardware FIFO threshold management (required by default since v3.0.0); to keep legacy SPI polling instead, define DISABLE_GDO2_FIFO_MANAGEMENT.
• Power the CC1101 from 3.3V only.

Adafruit Feather HUZZAH Silkscreen Labels

To make wiring dead-simple on the HUZZAH, here’s the exact silkscreen text next to each pin we use and what it connects to on the CC1101:

• Power

  • Board label: "3V" → CC1101 VCC (3.3V only)
  • Board label: "GND" → CC1101 GND

• SPI signals

  • Board label: "SCK / #14" → CC1101 SCK (SPI Clock)
  • Board label: "MISO / #12" → CC1101 MISO
  • Board label: "MOSI / #13" → CC1101 MOSI
  • Board label: "SS / #15" → CC1101 CSN (Chip Select)

• CC1101 interrupt (data ready)

  • Board label: "#5" → CC1101 GDO0 (default; configurable via private.h)

Notes

• On the HUZZAH, many pins show both the function and the GPIO number, e.g. "SCK / #14". You can use either reference when wiring.
• Only use the 3V (3.3V) pin to power the CC1101. Do not use 5V.

HUZZAH Boot-Strap Pins and Red LED (GPIO #0)

On the Adafruit Feather HUZZAH ESP8266, GPIO #0 has a red LED attached and is also a boot-strap pin used to enter the ROM bootloader. Important implications:

• If GPIO #0 is held LOW during reset/power-up, the ESP8266 will enter the bootloader instead of running your sketch.
• The red LED on GPIO #0 is wired “reverse”: writing LOW turns the LED ON, writing HIGH turns it OFF.
• GPIO #0 does not have an internal pull-up by default.

Because of the above, do not use GPIO #0 for CC1101 GDO0. This project defaults to using GPIO #5 for GDO0 on HUZZAH, which is safe and avoids accidental bootloader entry. You can still use GPIO #0 for simple LED indication in your own code, but avoid wiring CC1101 signals to it.

Also note other ESP8266 boot-strap pins on HUZZAH:

• GPIO #15 (used here as CS/SS) must be LOW at boot (the HUZZAH board provides the correct pull-down). Don’t force it HIGH during reset.
• GPIO #2 should normally be HIGH at boot (not used by this project).

CC1101

Some modules are not labelled on the PCB. Below is the pinout for one:

The following MQTT topics are used to integrate the device with Home Assistant via AutoDiscovery:

Note on RSSI (%). The percentage is a display convenience, not a calibrated measurement. It maps the -120 to -40 dBm range onto 0-100% so Home Assistant can show a signal bar; the endpoints were chosen to span roughly "unusable" to "right next to the meter" and have no physical meaning. Judge link quality from the dBm and LQI values instead. The same scale is used by the ESPHome rssi_percentage sensor and by the device log.

Local Development Setup

1. Install Required Tools

   • Download and install Visual Studio Code.
   • Install the PlatformIO extension for VS Code.
   • This will install all required dependencies and may require restarting VS Code.

2. Prepare Configuration Files

   • Copy include/private.example.h to include/private.h.
   • Update the following details in private.h:

     • Wi-Fi and MQTT credentials. If your MQTT setup does not require a username and password, comment out those lines using //.

     • Meter Code - Copy the code under the barcode (ignore the manufacturing date):

       • Label format: YY-SSSSSSS-NNN (example: 23-1875247-234)
       • Set METER_CODE to the same value with dashes - suffix -NNN is optional
       • Year is parsed from the first 2 digits (YY)
       • Serial is parsed from the middle section (SSSSSSS) and used in topics/entity prefixes
       • Last 3 digits (NNN), if present, are ignored by the radio protocol

     • Example:

       // Label text: 23-1875247-234  (with suffix, 12 digits)
       #define METER_CODE "23-1875247-234"
       
       // Same meter, without suffix (9 digits - also valid)
       #define METER_CODE "23-1875247"
       
       // Label with leading zeros in serial: 23-0123456-234
       #define METER_CODE "23-0123456-234"

     • 

     • Wi-Fi PHY Mode: To enable 802.11g Wi-Fi PHY mode, set ENABLE_WIFI_PHY_MODE_11G to 1 in the private.h file. By default, it is set to 0 (disabled).

     • Radio debug: control verbose CC1101/RADIAN debug output with DEBUG_CC1101 in private.h.

       • #define DEBUG_CC1101 1 enables verbose radio debugging (default in the example file).
       • #define DEBUG_CC1101 0 disables verbose radio debugging.

3. Select Your Board Environment

   • Use the PlatformIO status bar at the bottom of VS Code to select your board:
     • env:huzzah - Adafruit HUZZAH ESP8266 (USB upload)
     • env:huzzah-ota - Adafruit HUZZAH ESP8266 (OTA upload)
     • env:d1_mini - WeMos D1 Mini (USB upload)
     • env:d1_mini-ota - WeMos D1 Mini (OTA upload)
     • env:d1_mini_pro - WeMos D1 Mini Pro (USB upload)
     • env:d1_mini_pro-ota - WeMos D1 Mini Pro (OTA upload)
     • env:nodemcuv2 - NodeMCU v2 (USB upload)
     • env:nodemcuv2-ota - NodeMCU v2 (OTA upload)
     • env:esp32dev - ESP32 DevKit (USB upload)
     • env:esp32dev-ota - ESP32 DevKit (OTA upload)
   • For first-time setup: Use the standard environment (without -ota)
   • For OTA updates: After your device is running on Wi-Fi, use the -ota environment and update the IP address in platformio.ini
   • See the "Quick Start" section above for detailed build and upload instructions

4. Perform Frequency Discovery (First-Time Setup)

   • On the very first boot (or anytime there is no stored frequency offset), the firmware automatically launches a wide scan while AUTO_SCAN_ENABLED is set to 1 (default).
   • If you need to skip the scan during development (for example, when you already know the meter's frequency), add #define AUTO_SCAN_ENABLED 0 to your include/private.h.
   • Compile and upload the code to your ESP device using PlatformIO. Use PlatformIO > Upload and Monitor.
   • Keep the device connected to your computer during this process. The serial monitor will display debug output as the device scans frequencies in the 433 MHz range.
   • Important: During the initial scan (first boot with no stored frequency offset), the device performs a wide frequency scan that takes approximately 2 minutes before connecting to MQTT. You will see no MQTT/Home Assistant activity during this time - this is normal. Monitor the serial output to see the scan progress. Once the scan completes and the optimal frequency is found, the device will connect to MQTT and publish telemetry data.
   • Once the correct frequency is identified, update the FREQUENCY value in private.h if needed (the automatic scan stores the offset, so manual adjustment is usually not required).
   • To re-run the deep scan later, either set CLEAR_EEPROM_ON_BOOT to 1 for a single boot cycle, re-enable AUTO_SCAN_ENABLED, or press the Deep Frequency Scan button (mdi:radar) exposed in Home Assistant to trigger a full ±150 kHz fine-step sweep on demand. A faster Fast Frequency Scan button (mdi:magnify-scan) is also available for a quicker ±150 kHz coarse-step recalibration. Note: Both on-demand scan buttons can block for 1–2 minutes during which Wi-Fi/MQTT may temporarily disconnect and reconnect. This is expected, and Home Assistant will reconnect automatically once the scan completes.
   • Automatic recovery on failure: Separately from the first-boot scan, when a full streak of read attempts fails (MAX_RETRIES reached) and the firmware enters its cooldown period, it can run a frequency scan once to check for meter carrier-frequency (crystal) drift. This is controlled by AUTO_SCAN_ON_FAILURE_ENABLED (default 0, opt-in). Set #define AUTO_SCAN_ON_FAILURE_ENABLED 1 in include/private.h to enable it; it runs at most once per failure streak (reset after the next successful read).
   • For best results, perform this step during local business hours when the meter is most likely to transmit. Refer to the "Frequency Adjustment" section below for additional guidance.

5. Build and Upload

   • Follow the build and upload instructions in the "Quick Start" section above.
   • For first-time setup, use USB upload with the standard environment (e.g., env:huzzah).
   • Keep the device connected to your computer during USB upload.

6. Verify Meter Data

   • After WiFi and MQTT connection is established (or after the initial frequency scan completes), the meter data should appear in the terminal (bottom panel) and be pushed to MQTT.
   • If Frequency Discovery is still enabled, its output will also be displayed during this step.
   • Note: On first boot with no stored frequency offset, there will be a ~2 minute delay before any MQTT activity while the wide frequency scan runs. This is normal - monitor the serial output to see progress.

7. Automatic Meter Query

   • The device will automatically query the meter once every 24 hours.
   • If the query fails, it will retry every hour until successful.

Reading Schedule

The Reading Schedule feature allows you to configure the days when the meter should be queried. By default, the schedule is set to Monday-Friday. You can change this in the private.h file by modifying the DEFAULT_READING_SCHEDULE.

Available options:

• "Monday-Friday": Queries the meter only on weekdays.
• "Monday-Saturday": Queries the meter from Monday to Saturday.
• "Monday-Sunday": Queries the meter every day.
• "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday": Queries the meter only on that day.

Example configuration in private.h:

#define DEFAULT_READING_SCHEDULE "Monday-Saturday"

Time zone offset and wake-up window (simple)

Meters often have a local wake window (Time Start/End). The firmware keeps its clock in UTC and applies a simple offset:

Configuration (in include/private.h):

// Minutes from UTC. Examples: 0 (UTC), 60 (UTC+1), -300 (UTC-5)
#define TIMEZONE_OFFSET_MINUTES 0

Behaviour:

• The device schedules reads using UTC+offset (your local time). The default read time is 10:00 (local by offset).
• Auto-align can shift the read hour to the meter's wake window (midpoint by default) in local-offset time; the UTC publish is derived from that.

MQTT topics exposed:

• everblu/cyble/reading_time: scheduled time in UTC (HH:MM)

In serial logs at startup you’ll see:

• The UTC time pulled from the time server
• The configured offset (minutes)
• The local (UTC+offset) time

Home Assistant Discovery Toggle (MQTT mode)

By default, the standalone MQTT firmware publishes Home Assistant discovery topics under homeassistant/... so entities are created automatically.

If you only want raw MQTT topics and do not use Home Assistant discovery, set this in include/private.h:

#define ENABLE_HA_DISCOVERY 0

Default behaviour (if not defined) is enabled:

#define ENABLE_HA_DISCOVERY 1

With discovery disabled, telemetry and command topics under everblu/cyble/... continue to work normally. If discovery was enabled previously, retained homeassistant/... config topics may remain on the broker until you clear them (or switch to a different discovery prefix), so existing Home Assistant entities may not disappear immediately.

Radio and frequency (advanced)

Most users can skip this section: the firmware auto-calibrates, and on first boot it runs a wide scan if no frequency offset is stored.

// Optional: base frequency in MHz
// If not defined, defaults to 433.82 MHz
#define FREQUENCY 433.82

> Frequency (effective): 433.820000 MHz

#define CLEAR_EEPROM_ON_BOOT 1

#define CLEAR_EEPROM_ON_BOOT 0