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

Water Temperature Entity (if applicable)

Environment Sensor Entities

Real-Time Monitoring

1. Open Home Assistant and navigate to Settings
2. Go to Devices & Services → ESPHome
3. Select your WaterFlowKit device
4. 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:

1. Go to your WaterFlowKit device
2. Click on the unused entity
3. Toggle Enabled to off

Home Assistant Energy Dashboard

Add water consumption to the Energy Dashboard for beautiful visualizations.

Adding Water Consumption

1. Go to Settings → Dashboards → Energy
2. Under Water Consumption, click Add Water Source
3. Select your entity:
   • Flow1 Total Consumption
   • Flow2 Total Consumption
   • Flow3 Total Consumption (V2)
   • Flow4 Total Consumption (V2)
4. 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: Select Your Sensor Type

Start here. Each input has a Flow1 Sensor Type setting in Home Assistant (Flow1 and Flow2 on V1, Flow1 to Flow4 on V2). The default is YF-B1 / YF-B7, so with any other sensor the readings are wrong until you select the right type:

1. Open your WaterFlowKit device in Home Assistant
2. Under Configuration, set Flow1 Sensor Type to your sensor model
3. Repeat for every input you use

Method 2: Measure Known Volume

1. Get a container with known volume (e.g., 10L bucket)
2. Note the current Flow1 Total Consumption value
3. Fill the container through the monitored pipe
4. Compare the increase of the total with the actual volume
5. Set Flow1 Calibration % under Configuration to the current percentage × actual volume / measured increase. The range is 50 to 150%, the default is 100%.

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. High Flow Alert

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

alias: "Water - High flow alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.waterflowkit_a1b2c3_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_a1b2c3_flow1_current_water_usage') }} L/min for 5+ minutes"

2. Prolonged Flow Detection (Leak Warning)

Detect water running for an extended period:

alias: "Water - Prolonged flow warning"
trigger:
  - platform: numeric_state
    entity_id: sensor.waterflowkit_a1b2c3_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:

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:

alias: "Shower - Timer notification"
trigger:
  - platform: numeric_state
    entity_id: sensor.waterflowkit_a1b2c3_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):

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

6. Flow Started/Stopped Events

Trigger automations when water flow starts or stops:

alias: "Water - Flow started"
trigger:
  - platform: numeric_state
    entity_id: sensor.waterflowkit_a1b2c3_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:

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

Recommended Dashboard Entities

Flow Monitoring:

• sensor.waterflowkit_a1b2c3_flow1_current_water_usage: Current flow rate
• sensor.waterflowkit_a1b2c3_flow1_total_consumption: Total volume
• sensor.waterflowkit_a1b2c3_flow1_water_temperature: Water temperature (if YF-B7/B6)

Environment Monitoring:

• sensor.waterflowkit_a1b2c3_temperature: Ambient temperature
• sensor.waterflowkit_a1b2c3_humidity: Ambient humidity

Example Dashboard Card - Water Overview

type: entities
title: Water Monitoring
entities:
  - entity: sensor.waterflowkit_a1b2c3_flow1_current_water_usage
    name: Current Flow
  - entity: sensor.waterflowkit_a1b2c3_flow1_total_consumption
    name: Total Volume
  - entity: sensor.waterflowkit_a1b2c3_flow1_water_temperature
    name: Water Temperature
  - entity: sensor.waterflowkit_a1b2c3_temperature
    name: Ambient Temperature
  - entity: sensor.waterflowkit_a1b2c3_humidity
    name: Ambient Humidity

Flow Rate Gauge Card

type: gauge
entity: sensor.waterflowkit_a1b2c3_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

type: history-graph
title: Water Usage Today
entities:
  - entity: sensor.waterflowkit_a1b2c3_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

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

Using GitHub Packages

Import directly from GitHub:

packages:
  smarthomeshop.waterflowkit: 
    github://smarthomeshop/waterflowkit/waterflowkit-v2/waterflowkit-wifi.yaml@main

Source Code

• GitHub Repository: smarthomeshop/waterflowkit

Common Use Cases

Integration Ideas

Combine with Other SmartHomeShop Products

Need Help?

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