SmartHomeShop Docs

Firmware Guide

Local operation and GitHub update checks

The local Home Assistant firmware keeps WaterMeterKit measurements on your own network. Sensor readings go directly to Home Assistant and are not sent to GitHub or the SmartHomeShop cloud.

WaterMeterKit V3 WiFi firmware includes an ESPHome update entity. V1 and V2 have no update entity and do no update check. On V3 it periodically reads a small firmware manifest from SmartHomeShop GitHub Pages to compare the installed version with the latest release. Only firmware metadata is requested; the firmware file is downloaded only when you install an update.

Cloud firmware intentionally communicates with the SmartHomeShop app as part of its cloud features. Disabling the GitHub update check does not convert cloud firmware into local firmware. On Thread firmware the update entity stays inactive, because it needs internet access.

Use WaterMeterKit without internet access

You may block internet access for WaterMeterKit; its local measurements and Home Assistant connection continue to work. To prevent a blocked check from triggering the red status LED, take control of the device in the ESPHome Device Builder app/add-on, open its YAML and add this at the bottom:

update:
  - id: !extend firmware_update
    update_interval: never

Save the YAML, select Validate, and install the build using Install > Wirelessly. This disables scheduled checks only; it does not remove the update component or change any WaterMeterKit sensors.

The adopted YAML continues to contain a packages: link to the SmartHomeShop GitHub repository. ESPHome uses that link on the Home Assistant host when it compiles your firmware. The device itself no longer polls for firmware versions after the customized build is installed.

To restore automatic checks, remove the added update: block and install the firmware again. If ESPHome cannot find the firmware_update ID, update WaterMeterKit through the SmartHomeShop web flasher before applying this customization. V1 and V2 do not have this ID and do not need this customization.

WaterMeterKit runs on ESPHome, an open-source firmware platform that works with Home Assistant. ESPHome allows you to customize every aspect of your device's behavior while maintaining full local control, no cloud required.

Open Source & GitHub

All WaterMeterKit firmware is 100% open source and available on GitHub:

🔗 github.com/smarthomeshop/watermeterkit

The repository includes:

  • Complete ESPHome configurations for V1, V2, and V3 hardware
  • Magnetic water flow sensor implementation
  • Water consumption tracking and calculations
  • Automated builds via GitHub Actions
  • Community contributions welcome (PRs & issues)

You can view, modify, and customize the firmware to suit your needs, from adjusting sensor sensitivity to adding completely new features.

Hardware Versions

WaterMeterKit is available in three hardware versions:

V1 - ESP8266 (Legacy)

  • Microcontroller: ESP8266
  • Connectivity: WiFi only (2.4GHz)
  • Sensors: Magnetic water flow sensor, temperature, humidity
  • Measurements: Current usage (L/min), total consumption (m³)
  • Status: Legacy hardware, kept for existing installations

V2 - Previous Generation

  • Microcontroller: ESP8266
  • Connectivity: WiFi only (2.4GHz)
  • Sensors: Magnetic water flow sensor, temperature, humidity
  • Status: Supported for existing customers

V3 - ESP32-C6 (Current)

  • Microcontroller: ESP32-C6
  • Connectivity: WiFi (2.4GHz), or Thread with the Thread firmware
  • Sensors: Magnetic water flow sensor, temperature, humidity
  • Measurements: Current usage (L/min), total consumption (m³)
  • Compatible with: Actaris, Elster, Honeywell, Itron, Sensus analog water meters
  • Best for: Current WaterMeterKit installations

How to check your version: Look at the device label or check the "Hardware Version" sensor in Home Assistant.

Quick Update Methods

Method 1: Home Assistant (Easiest)

For regular firmware updates on V3 (recommended):

  1. Go to Settings → Devices & Services → Devices
  2. Select your WaterMeterKit device
  3. Open the Firmware update entity
  4. Click Install to download and apply the update
  5. The device will reboot automatically

⚠️ V1 and V2 have no update entity. Update them with Method 2 or Method 3. Because of the 1MB flash, a wireless update can fail with ESP does not have enough space to store OTA file. If that happens, flash via USB-C.

Method 2: ESPHome Device Builder

For updates with custom configurations:

⚠️ Important: This method requires the ESPHome Device Builder app (not just the ESPHome integration). If you haven't installed it yet, see the ESPHome Integration Guide section below for step-by-step installation instructions.

  1. Open the ESPHome Device Builder in Home Assistant (from the sidebar)
  2. Click on your WaterMeterKit device card
  3. Click Install → choose Wirelessly
  4. Wait for the OTA update to complete

Method 3: USB-C Web Flasher

For recovering devices or clean installations:

  1. Connect WaterMeterKit via USB-C cable to your computer
  2. Open the flasher: smarthomeshop.io/en/firmware?product=watermeterkit
  3. Choose your hardware version (V1, V2, or V3), how you use the device (local with Home Assistant, or with the SmartHomeShop app) and the firmware
  4. Start the installation and select the USB port of your device
  5. Follow the on-screen prompts

Note: Flashing from this page returns the device to its factory settings, including your WiFi credentials and the stored water meter reading. Write down your meter reading first and set Water Meter Initial Value again afterwards.

Switch Between Local and Cloud Firmware (V3)

WaterMeterKit V3 has a Firmware Variant selector in Home Assistant with the options WiFi (local) and WiFi + SmartHomeShop App (cloud). Choose the other option and the device installs that firmware by itself over WiFi, starting within about 20 seconds. It needs internet access for this. On V1 and V2 you switch with the web flasher (Method 3).

ESPHome Integration Guide

Want to customize your WaterMeterKit firmware? Follow this step-by-step guide to adopt your device in ESPHome and make modifications.

🚨 Critical: Understanding the Difference

Many users get confused between two different things:

  • ESPHome Integration (Settings → Devices & Services → Integrations) - This is how your WaterMeterKit communicates with Home Assistant. You probably already have this. ✅
  • ESPHome Device Builder app (Settings → Apps) - This is the tool you need to edit, build, and flash firmware. You need to install this separately! 🔧

To customize firmware, you MUST install the ESPHome Device Builder app below. Having just the integration is not enough!

Step 1: Install the ESPHome Device Builder App

If you haven't installed the ESPHome Device Builder app yet:

  1. Open Home Assistant → Settings → Apps
  2. Click Install app
  3. Search for ESPHome Device Builder
  4. Open it and click Install
  5. Enable Start on boot and Show in sidebar
  6. Click Start

Step 2: Adopt Your WaterMeterKit

Adopting allows ESPHome to manage your device's configuration:

  1. Open ESPHome from the Home Assistant sidebar
  2. Your WaterMeterKit should appear as a discovered device
  3. Click Adopt on the WaterMeterKit card
  4. Give it a name (e.g., "Main Water Meter")
  5. Click Adopt again to confirm

ESPHome now creates a configuration that points to our package on GitHub.

What does the adopted configuration look like?

After adoption, you'll see a YAML configuration that looks like this:

substitutions:
  name: watermeterkit-a1b2c3
  friendly_name: WaterMeterKit A1B2C3

packages:
  smarthomeshop.watermeterkit: github://smarthomeshop/watermeterkit/watermeterkit-v3/watermeterkit.yaml@main

esphome:
  name: ${name}
  name_add_mac_suffix: false
  friendly_name: ${friendly_name}

api:
  encryption:
    key: YOUR_UNIQUE_ENCRYPTION_KEY_HERE==

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

Understanding this structure:

  • substitutions: Device-specific variables (name, friendly name). Change these to customize behavior!
  • packages: Links to the base configuration on GitHub. This automatically pulls updates when available.
  • api/wifi: Your device's unique encryption key and WiFi credentials.

This modular approach means: ✅ You get automatic updates from GitHub ✅ Your customizations stay separate in substitutions ✅ You don't need to copy/paste the entire configuration

Step 3: Customize the Configuration

After adoption, you can modify the YAML configuration:

  1. Click Edit on your adopted WaterMeterKit device
  2. The YAML editor opens with your current configuration
  3. Make your desired changes (see examples below)
  4. Click Save

Step 4: Upload Modified Firmware

After making changes:

  1. Click Install on your device card
  2. Choose Wirelessly (recommended) or Plug into this computer
  3. ESPHome will compile and upload your custom firmware
  4. Wait for the device to reboot and reconnect

✅ Done! Your WaterMeterKit is now running custom firmware.

Advanced Customization

Example 1: Change How Often the Meter Reading Is Saved

The sensor counts one pulse per liter on every supported water meter, so there is no pulse rate to set. You can change how often the device saves its meter reading. Saving less often means less flash wear, but a sudden power cut can then lose more usage:

substitutions:
  water_checkpoint_interval: "10min"  # Default: 5min on V3, 30min on V1 and V2

Example 2: Add Water Usage Alerts

Get notified when water usage exceeds expected levels:

binary_sensor:
  - platform: template
    name: "High Water Usage Alert"
    lambda: |-
      // Alert if more than 100L used in 5 minutes
      if (id(sensor_pulse_meter).state > 20.0) {
        return true;
      }
      return false;
    filters:
      - delayed_on: 5min  # Must stay high for 5 minutes

Example 3: Calculate Total Water Cost

Track the cost of your meter reading:

sensor:
  - platform: template
    name: "Total Water Cost"
    unit_of_measurement: "EUR"
    device_class: monetary
    lambda: |-
      // Assuming 2.00 EUR per m³
      float cost = id(sensor_water_meter_total).state * 2.0;
      return cost;
    update_interval: 60s

Example 4: Leak Detection

Detect potential leaks based on continuous low flow:

binary_sensor:
  - platform: template
    name: "Possible Water Leak"
    lambda: |-
      // Alert if water flows continuously for 2 hours at low rate
      if (id(sensor_pulse_meter).state > 0.1 && id(sensor_pulse_meter).state < 5.0) {
        return true;
      }
      return false;
    filters:
      - delayed_on: 2h  # Continuous flow for 2 hours

Learn More: Check the ESPHome documentation for complete configuration reference.

Configuration Structure

WaterMeterKit firmware uses a modular architecture:

watermeterkit-v1/ and watermeterkit-v2/
├── watermeterkit.yaml              # WiFi firmware
├── watermeterkit-cloud.yaml        # WiFi + SmartHomeShop app
├── base.yaml                       # Device, sensors and LEDs
├── wifi.yaml                       # WiFi connectivity
└── cloud.yaml                      # Cloud sync

watermeterkit-v3/
├── watermeterkit.yaml              # WiFi firmware
├── watermeterkit-cloud.yaml        # WiFi + SmartHomeShop app
├── watermeterkit-thread.yaml       # Thread firmware
├── base.yaml                       # Device, sensors and LEDs
├── wifi.yaml                       # WiFi connectivity
├── thread.yaml                     # Thread connectivity
└── cloud.yaml                      # Cloud sync

packages/
└── water-persistence.yaml          # Saves the meter reading

This modular design makes it easy to:

  • Add/remove sensors
  • Share configurations across devices
  • Maintain consistency across updates
  • Contribute improvements back to the community

Troubleshooting

Device Won't Update OTA

Symptoms: OTA update fails or times out

Solutions:

  1. Ensure the device is powered on and connected to WiFi
  2. Check that the device is within WiFi range (strong signal)
  3. V1 and V2 (ESP8266): The error ESP does not have enough space to store OTA file comes from the 1MB flash, flash via USB-C instead
  4. Verify the device has been successfully adopted in ESPHome
  5. If all else fails, flash via USB-C cable

No Water Flow Detected

Symptoms: Water usage shows 0 even when water is running

Solutions:

  1. Check sensor positioning: Ensure magnetic sensor is correctly positioned over water meter's rotating element
  2. Sensor distance: Magnetic sensor should be very close to the metal indicator (within 1-2mm)
  3. Water meter compatibility: Not all water meters have magnetic indicators - check your meter model
  4. Check logs: View ESPHome logs for pulse detection messages

Inaccurate Water Measurements

Symptoms: Water consumption doesn't match actual usage

Solutions:

  1. Sensor alignment: Ensure sensor is centered over the rotating element
  2. Test measurement: Run exactly 10L of water and compare with reported usage
  3. Interference: Keep sensor away from strong magnetic fields or metal objects
  4. Meter type: The sensor must read the rotating 1-liter indicator, it counts one pulse per liter

Device Not Discovered After Flashing

Symptoms: WaterMeterKit doesn't appear in ESPHome after USB flashing

Solutions:

  1. The device may have lost WiFi credentials during flashing
  2. Connect via USB-C and check the logs in ESPHome
  3. Use Improv via Serial to reconfigure WiFi:
    • Keep USB-C connected
    • Visit web.esphome.io
    • Connect and configure WiFi through browser
  4. Alternatively, use the captive portal:
    • Device creates a WiFi AP named "watermeterkit" (password: watermeterkit)
    • Connect to it and configure WiFi through the web interface

High WiFi Reconnection Rate

Symptoms: Device frequently disconnects and reconnects

Solutions:

  1. Check signal strength: Ensure strong WiFi signal (-70 dBm or better)
  2. Power supply: Verify stable 5V power via USB-C (minimum 1A)
  3. Router settings: Disable WiFi band steering and enable 2.4GHz only
  4. V1 / ESP8266 limitation: Known to be less stable on busy WiFi networks
  5. Distance: Move device closer to WiFi access point or add WiFi extender

Compilation Errors in ESPHome

Symptoms: Custom YAML fails to compile

Solutions:

  1. Check for YAML syntax errors (indentation must be consistent)
  2. Verify you're using compatible ESPHome version (check GitHub repo requirements)
  3. Check the compilation log for specific error messages
  4. Compare your changes against the official configuration
  5. Ask for help on GitHub Issues or our Discord community

Water Total Resets to Zero

Symptoms: Total water consumption resets unexpectedly

Solutions:

  1. This is normal for Total Consumption: That counter starts at zero after every reboot. Home Assistant keeps the history, and Water Meter Total keeps your absolute reading
  2. Set your meter reading: Enter your physical meter reading in Water Meter Initial Value. It is saved right away
  3. Power loss: A sudden power cut can lose the usage since the last save, up to 5 minutes on V3 and up to 30 minutes on V1 and V2. Water used while the device is off cannot be counted
  4. After a USB flash or factory reset: The stored reading is gone, so set Water Meter Initial Value again

Water Meter Compatibility

WaterMeterKit works with analog water meters that have a rotating metal indicator. Compatible brands include:

  • Actaris (Itron)
  • Elster (Honeywell)
  • Honeywell
  • Itron
  • Sensus

Key requirement: Your water meter must have a visible rotating metal disc, gear, or pointer that can be detected magnetically. See the full list.

Firmware Changelog

Latest changes are announced alongside releases. Major updates will appear here.

Where to find changes:

Additional Resources

Need help? Visit our Support Portal or join our Discord community!

Thread Firmware

WaterMeterKit V3 can also join a Thread network instead of WiFi, for local Home Assistant use through a Thread border router. See Connect WaterMeterKit via Thread.