SmartHomeShop Docs

Firmware Guide

Local operation and GitHub update checks

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

Wi-Fi and Ethernet firmware includes an ESPHome update entity. 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. Thread firmware does not perform this check over Wi-Fi or Ethernet.

Use WaterFlowKit without internet access

You may block internet access for WaterFlowKit; 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 WaterFlowKit 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 WaterFlowKit through the SmartHomeShop web flasher before applying this customization.

WaterFlowKit 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 WaterFlowKit firmware is 100% open source and available on GitHub:

🔗 github.com/smarthomeshop/waterflowkit

The repository includes:

  • Complete ESPHome configurations for V1 (ESP32) and V2 (ESP32-C6)
  • Flow sensor implementations with temperature monitoring
  • WiFi and Ethernet (V2) connectivity options
  • Automated builds via GitHub Actions
  • Community contributions welcome (PRs & issues)

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

Hardware Versions

WaterFlowKit is available in two hardware versions:

V1 - ESP32

  • Microcontroller: ESP32
  • Connectivity: WiFi only
  • Flow Sensors: Up to 2 sensors
  • Features: Dual flow monitoring, water temperature, ambient sensors
  • Best for: Basic flow monitoring setups

V2 - ESP32-C6 (Current)

  • Microcontroller: ESP32-C6
  • Connectivity: WiFi + Ethernet, or Thread with the Thread firmware
  • Flow Sensors: Up to 4 sensors
  • Features: Quad flow monitoring, all V1 features + wired connectivity
  • Best for: Advanced installations with multiple monitoring points

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 (recommended):

  1. Go to Settings → Devices & Services → Devices
  2. Select your WaterFlowKit device
  3. Open the Firmware update entity and click Install, or press the Firmware Update button
  4. The device will reboot automatically

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 WaterFlowKit device card
  3. Click Install → choose Wirelessly
  4. Wait for the OTA update to complete

Method 3: USB-C Web Flasher

For changing firmware variants or recovering devices:

  1. Connect WaterFlowKit via USB-C cable to your computer
  2. Open the flasher: smarthomeshop.io/en/firmware?product=waterflowkit
  3. Choose your hardware version, how you use the device (local with Home Assistant, or with the SmartHomeShop app) and the firmware (WiFi, or Ethernet on V2)
  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, sensor types and calibration. Set them again afterwards.

ESPHome Integration Guide

Want to customize your WaterFlowKit 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 WaterFlowKit 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 WaterFlowKit

Adopting allows ESPHome to manage your device's configuration:

  1. Open ESPHome from the Home Assistant sidebar
  2. Your WaterFlowKit should appear as a discovered device
  3. Click Adopt on the WaterFlowKit card
  4. Give it a name (e.g., "Kitchen Flow Sensor")
  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: waterflowkit-a1b2c3
  friendly_name: WaterFlowKit A1B2C3

packages:
  smarthomeshop.waterflowkit: github://smarthomeshop/waterflowkit/waterflowkit-v2/waterflowkit-wifi.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 WaterFlowKit 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 WaterFlowKit is now running custom firmware.

Advanced Customization

Example 1: Calibrate Flow Sensors

You do not need YAML for this. In Home Assistant, set Flow1 Sensor Type to your sensor model and fine-tune with Flow1 Calibration %. Every input has its own settings. See the Usage Guide.

Example 2: Add Flow Rate Alerts

Get notified when flow exceeds expected levels (on V1 the ID is water_usage instead of water_usage1):

binary_sensor:
  - platform: template
    name: "High Flow Alert"
    lambda: |-
      // Alert if flow rate exceeds 20 L/min
      if (id(water_usage1).state > 20.0) {
        return true;
      }
      return false;
    filters:
      - delayed_on: 30s  # Must stay high for 30 seconds

Example 3: Calculate Water Costs

Track water expenses per sensor (on V1 the ID is sensor_pulse_meter_total instead of sensor_pulse_meter_total1):

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

Example 4: Temperature-Based Automations

Build these in Home Assistant instead of in the firmware. See the Hot Water Temperature Alert in the Usage Guide.

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

Configuration Structure

WaterFlowKit firmware uses a modular architecture:

waterflowkit-v1/
├── waterflowkit-wifi.yaml              # WiFi configuration
├── waterflowkit-wifi-cloud.yaml        # WiFi + cloud sync
└── [component files]

waterflowkit-v2/
├── waterflowkit-wifi.yaml              # WiFi configuration
├── waterflowkit-ethernet.yaml          # Ethernet configuration
├── waterflowkit-wifi-cloud.yaml        # WiFi + cloud sync
├── waterflowkit-ethernet-cloud.yaml    # Ethernet + cloud sync
├── waterflowkit-thread.yaml            # Thread firmware
└── [component files]

This modular design makes it easy to:

  • Add/remove sensors
  • Switch between WiFi and Ethernet (V2)
  • Switch between local and cloud variants
  • Share configurations across devices
  • 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 network
  2. Check that the device is within WiFi/Ethernet range (strong signal)
  3. Verify sufficient power supply (USB-C 5V 1A minimum)
  4. Try rebooting the device via Home Assistant
  5. If all else fails, flash via USB-C cable

Flow Sensor Not Detecting Flow

Symptoms: Flow rate shows 0 even when water is running

Solutions:

  1. Check sensor installation: Ensure flow sensor is installed in correct direction (arrow pointing flow direction)
  2. Verify connections: Check that sensor wires are properly connected to WaterFlowKit
  3. Sensor type: Check that Flow1 Sensor Type matches your sensor
  4. Minimum flow: Some sensors require minimum flow rate (typically 1-2 L/min) to register
  5. Check logs: View ESPHome logs for pulse detection messages

Inaccurate Flow Measurements

Symptoms: Flow readings don't match actual consumption

Solutions:

  1. Calibrate sensor: Set Flow1 Sensor Type and fine-tune Flow1 Calibration %
  2. Test measurement: Run exactly 10L of water and compare with reported usage
  3. Check sensor type: Ensure you're using the correct calibration for your sensor model
  4. Air bubbles: Air in pipes can cause inaccurate readings
  5. Flow rate: Sensors are most accurate within their specified flow range

Device Not Discovered After Flashing

Symptoms: WaterFlowKit 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. V2 with Improv: Use Improv via BLE to reconfigure WiFi:
    • Open Home Assistant companion app
    • Go to Settings → Devices → Add Device
    • Select your WaterFlowKit from the BLE devices list
  4. Alternatively, connect to the captive portal:
    • Device creates a WiFi AP named "waterflowkit" (password: waterflowkit)
    • Connect to it and configure WiFi through the web interface

Temperature Readings Incorrect

Symptoms: Water temperature shows unexpected values

Solutions:

  1. NTC sensor calibration: Temperature sensors may need calibration in ESPHome config
  2. Sensor placement: Ensure NTC sensor is properly installed in water stream
  3. Ambient temperature: Check if reading ambient instead of water temperature
  4. Check wiring: Verify NTC sensor connections are secure

Ethernet Not Working (V2)

Symptoms: Ethernet connection fails or unstable

Solutions:

  1. Ensure you flashed the Ethernet firmware variant (not WiFi)
  2. Verify Ethernet cable is properly connected
  3. Check that your router/switch is working
  4. Test with a known-good Ethernet cable
  5. For V2: Ethernet and WiFi are mutually exclusive - only one can be active

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 supply (use quality USB adapter)
  3. Router settings: Disable WiFi band steering and enable 2.4GHz only
  4. Interference: Move away from sources of interference
  5. Consider Ethernet: If V2, switch to Ethernet for more stable connection

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

Flow Sensor Specifications

WaterFlowKit is compatible with standard Hall-effect flow sensors:

Sensor Size Thread Typical Pulses/L Flow Range Common Use
G1/2" (DN15) 1/2" ~660 1-25 L/min Faucets, showers
G3/4" (DN20) 3/4" ~396 1-30 L/min Washing machines
G1" (DN25) 1" ~450 1-50 L/min Main lines
G1½" (DN40) 1½" ~27 5-150 L/min Large appliances
G2" (DN50) 2" ~12 10-200 L/min Main supply

Note: Select the matching model in the Sensor Type setting in Home Assistant.

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

WaterFlowKit V2 can also join a Thread network instead of WiFi or Ethernet, for local Home Assistant use through a Thread border router. See Connect WaterFlowKit via Thread.