Usage Guide

This guide covers practical ways to use your WaterFlowKit in Home Assistant, including monitoring, calibration, automation examples, and dashboard tips.

Quick Start

After installation, your WaterFlowKit provides these key entities:

Flow Sensor Entities

Entity	Use For
Flow1 Current water usage	Real-time flow rate (L/min)
Flow1 Total Consumption	Cumulative volume — use for Energy Dashboard
Flow2 Current water usage	Real-time flow rate sensor 2 (if connected)
Flow2 Total Consumption	Cumulative volume sensor 2 — use for Energy Dashboard

Water Temperature Entity (if applicable)

Entity	Use For
Flow1 Water Temperature	Water temperature through sensor 1 (°C)
Flow2 Temperature	Water temperature through sensor 2 (°C)

Environment Sensor Entities

Entity	Use For
Temperature	Ambient temperature around the WaterFlowKit (°C)
Humidity	Ambient relative humidity (%)

Real-Time Monitoring

Open Home Assistant and navigate to Settings
Go to Devices & Services → ESPHome
Select your WaterFlowKit device
View all entities: flow rate, total volume, temperature (if applicable)

Disabling Unused Entities

If you're only using one sensor or don't have a temperature sensor:

Go to your WaterFlowKit device
Click on the unused entity
Toggle Enabled to off

Home Assistant Energy Dashboard

Add water consumption to the Energy Dashboard for beautiful visualizations.

Adding Water Consumption

Go to Settings → Dashboards → Energy
Under Water Consumption, click Add Water Source
Select your entity:
- Flow1 Total Consumption or
- Flow2 Total Consumption
Click Save

Note: Use the Total Consumption entities (cumulative volume), not the flow rate entities.

Calibration

If your sensor readings don't match expected values, you can calibrate.

Method 1: Measure Known Volume

Get a container with known volume (e.g., 10L bucket)
Reset the sensor total in Home Assistant
Fill the container through the monitored pipe
Compare the sensor reading with actual volume

Calculate correction factor:

Correction = Actual Volume / Sensor Reading

Method 2: Adjust Pulses Per Liter in ESPHome

Adopt the WaterFlowKit in ESPHome
Find the pulse counter configuration:

yaml

sensor:
  - platform: pulse_counter
    pin:
      number: GPIO26
      mode:
        input: true
        pullup: true
    name: "Flow1 Current water usage"
    filters:
      - multiply: 0.00172  # Adjust for flow rate (L/min)
    total:
      name: "Flow1 Total Consumption"
      unit_of_measurement: "L"
      filters:
        - multiply: 0.00163  # Adjust for total volume (L)

Adjust the multiply filter:
- Reading too high? Decrease the value
- Reading too low? Increase the value
Save and install

Default vs Sensor-Specific Values

The firmware ships with default values that work for most sensors:

Filter	Default Value	Description
Flow rate	0.00172	For L/min calculation
Total volume	0.00163	For L calculation

For more precision, use sensor-specific values:

Sensor	Multiply Value	Pulses/Liter
YF-B1, YF-B7	0.00151515	~660
YF-B5, YF-B6	0.00252525	~396
YF-B10	0.00222222	~450
YF-DN40-S	0.03703704	~27
YF-DN50-S	0.08333333	~12

Automation Examples

1. High Flow Alert

Alert when flow rate is unusually high (possible leak or open tap):

yaml

alias: "Water - High flow alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.waterflowkit_flow1_current_water_usage
    above: 15  # More than 15 L/min
    for:
      minutes: 5
action:
  - service: notify.mobile_app
    data:
      title: "High Water Flow!"
      message: "Flow rate: {{ states('sensor.waterflowkit_flow1_current_water_usage') }} L/min for 5+ minutes"

2. Prolonged Flow Detection (Leak Warning)

Detect water running for an extended period:

yaml

alias: "Water - Prolonged flow warning"
trigger:
  - platform: numeric_state
    entity_id: sensor.waterflowkit_flow1_current_water_usage
    above: 0.5
    for:
      minutes: 30
action:
  - service: notify.mobile_app
    data:
      title: "Water Running!"
      message: "Water has been flowing for 30+ minutes. Check for open taps or leaks."

3. Daily Water Usage Report

Send a notification with daily water usage:

yaml

alias: "Water - Daily report"
trigger:
  - platform: time
    at: "21:00:00"
action:
  - service: notify.mobile_app
    data:
      title: "Daily Water Report"
      message: "Today's usage: {{ states('sensor.water_daily') }} L"

Note: Requires a utility meter helper for daily tracking.

4. Shower Timer

Track shower duration based on flow:

yaml

alias: "Shower - Timer notification"
trigger:
  - platform: numeric_state
    entity_id: sensor.waterflowkit_flow1_current_water_usage
    below: 1
condition:
  - condition: state
    entity_id: input_boolean.shower_in_progress
    state: "on"
action:
  - service: input_boolean.turn_off
    target:
      entity_id: input_boolean.shower_in_progress
  - service: notify.mobile_app
    data:
      title: "Shower Finished"
      message: "Duration: {{ (as_timestamp(now()) - as_timestamp(states.input_boolean.shower_in_progress.last_changed)) | int // 60 }} minutes"

5. Hot Water Temperature Alert

Alert if hot water isn't hot enough (requires YF-B7 or YF-B6 sensor):

yaml

alias: "Hot Water - Temperature alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.waterflowkit_flow1_water_temperature
    below: 45
condition:
  - condition: numeric_state
    entity_id: sensor.waterflowkit_flow1_current_water_usage
    above: 2
action:
  - service: notify.mobile_app
    data:
      title: "Hot Water Issue"
      message: "Water temperature is only {{ states('sensor.waterflowkit_flow1_water_temperature') }}°C"

6. Flow Started/Stopped Events

Trigger automations when water flow starts or stops:

yaml

alias: "Water - Flow started"
trigger:
  - platform: numeric_state
    entity_id: sensor.waterflowkit_flow1_current_water_usage
    above: 0.5
action:
  # Add your actions here
  - service: logbook.log
    data:
      name: "Water Flow"
      message: "Started"

Dashboard Ideas

Creating Utility Meters

Track daily, weekly, and monthly water usage:

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

Recommended Dashboard Entities

Flow Monitoring:

sensor.waterflowkit_flow1_current_water_usage — Current flow rate
sensor.waterflowkit_flow1_total_consumption — Total volume
sensor.waterflowkit_flow1_water_temperature — Water temperature (if YF-B7/B6)

Environment Monitoring:

sensor.waterflowkit_temperature — Ambient temperature
sensor.waterflowkit_humidity — Ambient humidity

Example Dashboard Card - Water Overview

yaml

type: entities
title: Water Monitoring
entities:
  - entity: sensor.waterflowkit_flow1_current_water_usage
    name: Current Flow
  - entity: sensor.waterflowkit_flow1_total_consumption
    name: Total Volume
  - entity: sensor.waterflowkit_flow1_water_temperature
    name: Water Temperature
  - entity: sensor.waterflowkit_temperature
    name: Ambient Temperature
  - entity: sensor.waterflowkit_humidity
    name: Ambient Humidity

Flow Rate Gauge Card

yaml

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

History Graph - Daily Pattern

yaml

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

Best Practices

Installation Tips

Use thread seal tape (PTFE) on all threaded connections
Pressure test before final installation
Avoid installing where air bubbles can accumulate
Install in an accessible location for maintenance

Accuracy Tips

Ensure flow is within the sensor's rated range
Avoid very low flow rates (below minimum specification)
Calibrate after installation for best accuracy
Position sensor in a straight pipe section if possible

Multiple Sensor Setup

Using both sensors? Consider:

Hot and cold water lines
Water in vs water out (leak detection)
Before and after filter (filter efficiency)

ESPHome Configuration

For advanced users who want to customize the WaterFlowKit firmware.

Adopting in ESPHome

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

Using GitHub Packages

Import directly from GitHub:

yaml

packages:
  smarthomeshop.waterflowkit: 
    github://smarthomeshop/waterflowkit/waterflowkit.yaml@main

Source Code

GitHub Repository: smarthomeshop/waterflowkit

Common Use Cases

Scenario	Key Entities	Automation Ideas
Shower monitoring	Flow rate, Temperature	Duration timer, temperature alerts
Garden irrigation	Flow rate, Total	Usage tracking, schedule verification
Appliance tracking	Flow rate, Total	Washing machine detection
Leak detection	Flow rate	Prolonged flow alerts
Hot water efficiency	Temperature, Flow	Temperature monitoring

Integration Ideas

Combine with Other SmartHomeShop Products

Product	Combined Use
WaterMeterKit	Total + individual monitoring
WaterP1MeterKit	Water + energy correlation
CeilSense	Presence-based water usage

Need Help?

Installation Guide — Setup instructions
Sensor Definitions — All entities explained
Troubleshooting — Common issues
FAQ — Frequently asked questions
Discord — Community support

Usage Guide ​

Quick Start ​

Flow Sensor Entities ​

Water Temperature Entity (if applicable) ​

Environment Sensor Entities ​

Real-Time Monitoring ​

Disabling Unused Entities ​

Home Assistant Energy Dashboard ​

Adding Water Consumption ​

Calibration ​

Method 1: Measure Known Volume ​

Method 2: Adjust Pulses Per Liter in ESPHome ​

Default vs Sensor-Specific Values ​

Automation Examples ​

1. High Flow Alert ​

2. Prolonged Flow Detection (Leak Warning) ​

3. Daily Water Usage Report ​

4. Shower Timer ​

5. Hot Water Temperature Alert ​

6. Flow Started/Stopped Events ​

Dashboard Ideas ​

Creating Utility Meters ​

Recommended Dashboard Entities ​

Example Dashboard Card - Water Overview ​

Flow Rate Gauge Card ​

History Graph - Daily Pattern ​

Best Practices ​

Installation Tips ​

Accuracy Tips ​

Multiple Sensor Setup ​

ESPHome Configuration ​

Adopting in ESPHome ​

Using GitHub Packages ​

Source Code ​

Common Use Cases ​

Integration Ideas ​

Combine with Other SmartHomeShop Products ​

Need Help? ​

Usage Guide

Quick Start

Flow Sensor Entities

Water Temperature Entity (if applicable)

Environment Sensor Entities

Real-Time Monitoring

Disabling Unused Entities

Home Assistant Energy Dashboard

Adding Water Consumption

Calibration

Method 1: Measure Known Volume

Method 2: Adjust Pulses Per Liter in ESPHome

Default vs Sensor-Specific Values

Automation Examples

1. High Flow Alert

2. Prolonged Flow Detection (Leak Warning)

3. Daily Water Usage Report

4. Shower Timer

5. Hot Water Temperature Alert

6. Flow Started/Stopped Events

Dashboard Ideas

Creating Utility Meters

Recommended Dashboard Entities

Example Dashboard Card - Water Overview

Flow Rate Gauge Card

History Graph - Daily Pattern

Best Practices

Installation Tips

Accuracy Tips

Multiple Sensor Setup

ESPHome Configuration

Adopting in ESPHome

Using GitHub Packages

Source Code

Common Use Cases

Integration Ideas

Combine with Other SmartHomeShop Products

Need Help?