Usage Guide

This guide covers practical ways to use your WaterMeterKit in Home Assistant, including Energy Dashboard setup, automation examples, and dashboard tips.

Quick Start

After installation, your WaterMeterKit provides these key entities:

Water Entities

Environment Entities

Home Assistant Energy Dashboard

The Energy Dashboard gives you beautiful visualizations of your water consumption.

Adding Water Consumption

1. Go to Settings → Dashboards → Energy
2. Under Water Consumption, click Add Water Source
3. Select the Total Consumption entity
4. Click Save

Important: Use Total Consumption, not Water Meter Total. Home Assistant tracks the history of this entity even when it resets on reboot, while Water Meter Total jumps the moment you enter your meter reading.

It can take up to 2 hours before your water data appears in the Energy Dashboard.

Setting Your Water Meter Reading

To track your actual meter reading (not just consumption since installation):

First Time Setup

1. Read your physical water meter (e.g., 125.456 m³)
2. In Home Assistant, find the WaterMeterKit device
3. Set Water Meter Initial Value to 125.456
4. Water Meter Total now shows your actual meter reading

After Power Outage or Reboot

Your data is automatically preserved:

• Saved every 5 minutes on V3 and every 30 minutes on V1 and V2, when the reading has changed
• Saved on every clean restart or OTA update, and right after you set Water Meter Initial Value

A sudden power cut can lose the usage since the last save: up to 5 minutes on V3, up to 30 minutes on V1 and V2. Water used while the device is off cannot be counted.

Automation Examples

Note: In all examples below, replace a1b2c3 with the ID of your own device and notify.mobile_app with your own notify service. Copy the exact entity ID from the entity in Home Assistant.

1. Water Leak Detection (Unusual Usage)

Alert when water has been running for too long:

alias: "Water - Leak detection alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.watermeterkit_a1b2c3_watermeterkit_current_usage
    above: 0.5  # More than 0.5 L/min
    for:
      minutes: 30  # For more than 30 minutes
action:
  - service: notify.mobile_app
    data:
      title: "⚠️ Possible Water Leak!"
      message: "Water has been running for 30+ minutes ({{ states('sensor.watermeterkit_a1b2c3_watermeterkit_current_usage') }} L/min)"
      data:
        priority: high
        tag: water-leak

2. Daily Water Usage Report

Send a notification with your daily water usage:

alias: "Water - Daily usage report"
trigger:
  - platform: time
    at: "21:00:00"
action:
  - service: notify.mobile_app
    data:
      title: "💧 Daily Water Report"
      message: >
        Today's water usage: {{ (states('sensor.water_daily') | float(0) * 1000) | round(0) }} liters

Note: You'll need to create a utility meter helper for daily tracking (see Dashboard section below).

3. Shower Timer / Long Shower Alert

Detect when someone is taking a long shower:

alias: "Water - Long shower alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.watermeterkit_a1b2c3_watermeterkit_current_usage
    above: 5  # Typical shower flow
    for:
      minutes: 15
action:
  - service: notify.mobile_app
    data:
      title: "🚿 Long Shower"
      message: "Shower has been running for 15+ minutes"

4. Night Water Usage Alert

Detect unexpected water usage at night (potential leak):

alias: "Water - Night usage alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.watermeterkit_a1b2c3_watermeterkit_current_usage
    above: 0.5
    for:
      minutes: 5
condition:
  - condition: time
    after: "01:00:00"
    before: "05:00:00"
action:
  - service: notify.mobile_app
    data:
      title: "🌙 Night Water Usage"
      message: "Water is running at {{ states('sensor.watermeterkit_a1b2c3_watermeterkit_current_usage') }} L/min"
      data:
        priority: high

5. Toilet Flush Detection

Detect toilet flushes (typically 6-9 liters of quick water usage):

alias: "Water - Toilet flush counter"
trigger:
  - platform: numeric_state
    entity_id: sensor.watermeterkit_a1b2c3_watermeterkit_current_usage
    above: 10  # High flow rate
    for:
      seconds: 3
condition:
  - condition: numeric_state
    entity_id: sensor.watermeterkit_a1b2c3_watermeterkit_current_usage
    above: 10
action:
  - service: counter.increment
    target:
      entity_id: counter.toilet_flushes_today

6. Weekly Water Budget Alert

Alert when approaching your weekly water budget:

alias: "Water - Budget alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.water_weekly  # Utility meter
    above: 0.7  # 0.7 m³ is 700 liters
action:
  - service: notify.mobile_app
    data:
      title: "💧 Water Budget Warning"
      message: "You've used {{ (states('sensor.water_weekly') | float(0) * 1000) | round(0) }} liters this week!"

7. Washing Machine Water Detection

Detect when the washing machine is using water:

alias: "Water - Washing machine running"
trigger:
  - platform: numeric_state
    entity_id: sensor.watermeterkit_a1b2c3_watermeterkit_current_usage
    above: 8  # Typical washing machine fill rate
    for:
      seconds: 10
action:
  - service: input_boolean.turn_on
    target:
      entity_id: input_boolean.washing_machine_running
  - service: notify.mobile_app
    data:
      title: "🧺 Washing Machine"
      message: "Washing machine is filling with water"

Dashboard Ideas

Creating Utility Meters

To track daily, weekly, and monthly consumption, create utility meter helpers:

1. Go to Settings → Devices & Services → Helpers
2. Click Create Helper → Utility Meter
3. Configure:
   • Name: Water Daily
   • Input sensor: sensor.watermeterkit_a1b2c3_watermeterkit_total_consumption
   • Meter reset cycle: Daily
4. Repeat for weekly and monthly

Recommended Dashboard Entities

Water Monitoring:

• sensor.watermeterkit_a1b2c3_watermeterkit_total_consumption: Total water
• sensor.watermeterkit_a1b2c3_watermeterkit_current_usage: Current flow
• sensor.watermeterkit_a1b2c3_watermeterkit_water_meter_total: Actual meter reading
• sensor.water_daily: Daily usage (utility meter)

Environment:

• sensor.watermeterkit_a1b2c3_watermeterkit_temperature
• sensor.watermeterkit_a1b2c3_watermeterkit_humidity

Example Dashboard Card - Water Overview

type: entities
title: 💧 Water
entities:
  - entity: sensor.watermeterkit_a1b2c3_watermeterkit_current_usage
    name: Current Flow
  - entity: sensor.water_daily
    name: Today's Usage
  - entity: sensor.watermeterkit_a1b2c3_watermeterkit_water_meter_total
    name: Meter Reading
  - entity: sensor.watermeterkit_a1b2c3_watermeterkit_temperature
    name: Temperature

Water Flow Gauge

type: gauge
entity: sensor.watermeterkit_a1b2c3_watermeterkit_current_usage
name: Water Flow
min: 0
max: 20
severity:
  green: 0
  yellow: 10
  red: 15
unit: L/min

History Graph - Daily Water Pattern

type: history-graph
title: Water Usage Today
entities:
  - entity: sensor.watermeterkit_a1b2c3_watermeterkit_current_usage
hours_to_show: 24

Statistics Card - This Week's Usage

type: statistic
entity: sensor.watermeterkit_a1b2c3_watermeterkit_total_consumption
period:
  calendar:
    period: week
stat_type: change
name: This Week's Water

Mini Graph Card (requires custom card)

type: custom:mini-graph-card
entities:
  - entity: sensor.watermeterkit_a1b2c3_watermeterkit_current_usage
name: Water Flow
hours_to_show: 12
points_per_hour: 4
line_color: "#2196F3"

Best Practices

Water Sensor Positioning

The sensor detects the rotating metal plate inside your water meter. Proper positioning is critical for accurate readings.

How it works:

• Inside your water meter is a small metal plate that rotates with each liter of water
• The sensor detects this metal plate as it passes by
• The sensor has a crosshair/center point that must be positioned so the metal plate passes through it once per rotation

Correct positioning:

• Position the sensor so it covers approximately 50% of the rotating metal 1-liter indicator
• The crosshair (center point) of the sensor should be aligned so the metal plate passes through it exactly once per full rotation
• The side with the red LED must face DOWN (toward the water meter)
• The black side must be visible (facing up)

✅ Do:

• Position sensor to cover ~50% of the rotating metal indicator
• Align the crosshair so metal passes once per rotation
• Keep red LED side facing down, black side visible
• Keep sensor firmly pressed into holder
• Test by running water: green LED should flash once per liter

❌ Don't:

• Cover the entire rotating indicator (sensor won't detect transitions)
• Position sensor off-center from the metal plate path
• Mount with red LED facing up (wrong orientation)
• Over-tighten mounting screws
• Let the sensor touch the water meter glass

Persistent Data

The WaterMeterKit stores your water consumption persistently:

Common Use Cases

Integration Ideas

Combine with Other SmartHomeShop Products

Third-Party Integrations

• Grafana: Create detailed water usage dashboards
• InfluxDB: Long-term data storage and analysis
• Node-RED: Complex automation flows
• Google Sheets: Export data for analysis

ESPHome Configuration

For advanced users who want to customize the WaterMeterKit firmware.

Adopting in ESPHome

To customize your WaterMeterKit:

1. Open the ESPHome Device Builder app in Home Assistant
2. Your WaterMeterKit should appear. Click Adopt
3. Once adopted, you can edit the YAML configuration

Key Substitutions

The firmware uses substitutions for easy customization:

substitutions:
  device_name: watermeterkit
  friendly_name: WaterMeterKit

Modifying Sensor Calibration

The HDC1080 temperature and humidity sensors have built-in calibration offsets. If your readings are inaccurate, you can adjust them:

sensor:
  - platform: hdc1080
    temperature:
      filters:
        offset: -5.5  # Default offset, adjust if needed
    humidity:
      filters:
        offset: 12  # Default offset, adjust if needed

How to calibrate:

1. Compare WaterMeterKit readings with a known accurate thermometer/hygrometer
2. Calculate the difference (e.g., if it reads 2°C too high, change offset to -7.5)
3. Save and install the updated configuration

Using GitHub Packages

Instead of copying all YAML, you can use the packages feature to import from GitHub:

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

This automatically pulls the latest V3 configuration while allowing you to add customizations below. Use the matching watermeterkit-v2 or watermeterkit-v1 package if you have older hardware.

Source Code

The complete ESPHome configuration is open source:

• 📁 GitHub Repository: smarthomeshop/watermeterkit

Need Energy Monitoring Too?

The WaterMeterKit focuses purely on water monitoring. If you also want to monitor your energy consumption (electricity, gas, solar), consider the WaterP1MeterKit:

Need Help?

• Installation Guide: Setup instructions
• Troubleshooting: Common issues
• Firmware Guide: Update firmware
• Discord Community: Get help