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

Entity	Use For
Water Total Consumption	Liters since boot — use for Energy Dashboard
Water Meter Initial Value	Set your physical meter reading
Water Meter Total	Actual meter reading (Initial + Consumption)
Water Flow Rate	Current flow in L/min

Environment Entities

Entity	Use For
Temperature	Temperature at device location
Humidity	Humidity level

Home Assistant Energy Dashboard

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

Adding Water Consumption

Go to Settings → Dashboards → Energy
Under Water Consumption, click Add Water Source
Select Water Total Consumption entity
Click Save

Important: Use Water Total Consumption, not Water Meter Total. Home Assistant tracks the history of this entity even when it resets on reboot.

After ~5 minutes, your water data will appear in the Energy Dashboard!

Setting Your Water Meter Reading

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

First Time Setup

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

After Power Outage or Reboot

Your data is automatically preserved:

Saved every 5 minutes (if 50+ liters used)
Saved on every shutdown, OTA update, or restart

Maximum loss during unexpected power outage: ~50 liters.

Automation Examples

1. Water Leak Detection (Unusual Usage)

Alert when water has been running for too long:

yaml

alias: "Water - Leak detection alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.watermeterkit_water_flow_rate
    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_water_flow_rate') }} L/min)"
      data:
        priority: high
        tag: water-leak

2. Daily Water Usage Report

Send a notification with your daily water usage:

yaml

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') }} 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:

yaml

alias: "Water - Long shower alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.watermeterkit_water_flow_rate
    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):

yaml

alias: "Water - Night usage alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.watermeterkit_water_flow_rate
    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_water_flow_rate') }} L/min"
      data:
        priority: high

5. Toilet Flush Detection

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

yaml

alias: "Water - Toilet flush counter"
trigger:
  - platform: numeric_state
    entity_id: sensor.watermeterkit_water_flow_rate
    above: 10  # High flow rate
    for:
      seconds: 3
condition:
  - condition: numeric_state
    entity_id: sensor.watermeterkit_water_flow_rate
    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:

yaml

alias: "Water - Budget alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.water_weekly  # Utility meter
    above: 700  # 700 liters weekly limit
action:
  - service: notify.mobile_app
    data:
      title: "💧 Water Budget Warning"
      message: "You've used {{ states('sensor.water_weekly') }} liters this week!"

7. Washing Machine Water Detection

Detect when the washing machine is using water:

yaml

alias: "Water - Washing machine running"
trigger:
  - platform: numeric_state
    entity_id: sensor.watermeterkit_water_flow_rate
    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:

Go to Settings → Devices & Services → Helpers
Click Create Helper → Utility Meter
Configure:
- Name: Water Daily
- Input sensor: sensor.watermeterkit_water_total_consumption
- Meter reset cycle: Daily
Repeat for weekly and monthly

Recommended Dashboard Entities

Water Monitoring:

sensor.watermeterkit_water_total_consumption — Total water
sensor.watermeterkit_water_flow_rate — Current flow
sensor.watermeterkit_water_meter_total — Actual meter reading
sensor.water_daily — Daily usage (utility meter)

Environment:

sensor.watermeterkit_temperature
sensor.watermeterkit_humidity

Example Dashboard Card - Water Overview

yaml

type: entities
title: 💧 Water
entities:
  - entity: sensor.watermeterkit_water_flow_rate
    name: Current Flow
  - entity: sensor.water_daily
    name: Today's Usage
  - entity: sensor.watermeterkit_water_meter_total
    name: Meter Reading
  - entity: sensor.watermeterkit_temperature
    name: Temperature

Water Flow Gauge

yaml

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

History Graph - Daily Water Pattern

yaml

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

Statistics Card - This Week's Usage

yaml

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

Mini Graph Card (requires custom card)

yaml

type: custom:mini-graph-card
entities:
  - entity: sensor.watermeterkit_water_flow_rate
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:

Event	Data Preserved?
Reboot / Restart	✅ Yes
OTA firmware update	✅ Yes
Factory reset	✅ Yes (saved first)
Power outage	⚠️ May lose up to ~50 liters

Common Use Cases

Scenario	Key Entities	Automation Ideas
Leak Detection	Water Flow Rate	Alert if running 30+ min
Shower Tracking	Water Flow Rate	Timer, usage per shower
Daily Reports	Utility Meters	Daily/weekly notifications
Budget Tracking	Utility Meters	Alert when approaching limit
Night Monitoring	Water Flow Rate	Alert for unexpected night usage
Appliance Detection	Water Flow Rate	Detect washing machine, toilet
Environmental	Temperature, Humidity	Monitor water meter location

Integration Ideas

Combine with Other SmartHomeShop Products

Product	Combined Use
WaterP1MeterKit	Add energy monitoring to your water monitoring
CeilSense	Correlate presence with water usage
UltimateSensor	Room climate + water monitoring

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:

Go to Home Assistant → ESPHome addon
Your WaterMeterKit should appear — click Adopt
Once adopted, you can edit the YAML configuration

Key Substitutions

The firmware uses substitutions for easy customization:

yaml

substitutions:
  device_name: watermeterkit
  friendly_name: WaterMeterKit

Substitution	Description
`device_name`	Internal device name (no spaces)
`friendly_name`	Display name in Home Assistant

Modifying Sensor Calibration

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

yaml

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

How to calibrate:

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

Using GitHub Packages

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

yaml

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

This automatically pulls the latest configuration while allowing you to add customizations below.

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:

Feature	WaterMeterKit	WaterP1MeterKit
Water monitoring	✅	✅
P1 energy meter	❌	✅
Gas monitoring	❌	✅
Solar production	❌	✅
Ethernet/PoE	❌	✅

Need Help?

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

Usage Guide ​

Quick Start ​

Water Entities ​

Environment Entities ​

Home Assistant Energy Dashboard ​

Adding Water Consumption ​

Setting Your Water Meter Reading ​

First Time Setup ​

After Power Outage or Reboot ​

Automation Examples ​

1. Water Leak Detection (Unusual Usage) ​

2. Daily Water Usage Report ​

3. Shower Timer / Long Shower Alert ​

4. Night Water Usage Alert ​

5. Toilet Flush Detection ​

6. Weekly Water Budget Alert ​

7. Washing Machine Water Detection ​

Dashboard Ideas ​

Creating Utility Meters ​

Recommended Dashboard Entities ​

Example Dashboard Card - Water Overview ​

Water Flow Gauge ​

History Graph - Daily Water Pattern ​

Statistics Card - This Week's Usage ​

Mini Graph Card (requires custom card) ​

Best Practices ​

Water Sensor Positioning ​

Persistent Data ​

Common Use Cases ​

Integration Ideas ​

Combine with Other SmartHomeShop Products ​

Third-Party Integrations ​

ESPHome Configuration ​

Adopting in ESPHome ​

Key Substitutions ​

Modifying Sensor Calibration ​

Using GitHub Packages ​

Source Code ​

Need Energy Monitoring Too? ​

Need Help? ​

Usage Guide

Quick Start

Water Entities

Environment Entities

Home Assistant Energy Dashboard

Adding Water Consumption

Setting Your Water Meter Reading

First Time Setup

After Power Outage or Reboot

Automation Examples

1. Water Leak Detection (Unusual Usage)

2. Daily Water Usage Report

3. Shower Timer / Long Shower Alert

4. Night Water Usage Alert

5. Toilet Flush Detection

6. Weekly Water Budget Alert

7. Washing Machine Water Detection

Dashboard Ideas

Creating Utility Meters

Recommended Dashboard Entities

Example Dashboard Card - Water Overview

Water Flow Gauge

History Graph - Daily Water Pattern

Statistics Card - This Week's Usage

Mini Graph Card (requires custom card)

Best Practices

Water Sensor Positioning

Persistent Data

Common Use Cases

Integration Ideas

Combine with Other SmartHomeShop Products

Third-Party Integrations

ESPHome Configuration

Adopting in ESPHome

Key Substitutions

Modifying Sensor Calibration

Using GitHub Packages

Source Code

Need Energy Monitoring Too?

Need Help?