Usage Guide

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

Quick Start

After installation, your WaterP1MeterKit 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

Energy Entities (P1)

Entity	Use For
Energy Consumed Tariff 1/2	Low/high tariff consumption (kWh)
Energy Produced Tariff 1/2	Solar feed-back per tariff (kWh)
Power Consumed/Produced	Current power usage (W)
Voltage L1/L2/L3	Voltage per phase
Current L1/L2/L3	Current per phase (A)
Gas Consumed	Gas consumption (m³)

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 energy and 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.

Adding Electricity Consumption

In the Energy Dashboard, under Electricity grid
Click Add Consumption
Add both tariff entities:
- Energy Consumed Tariff 1 (low tariff)
- Energy Consumed Tariff 2 (high tariff)

Adding Solar Production

If you have solar panels:

Under Electricity grid, click Add Return to grid
Add both tariff entities:
- Energy Produced Tariff 1
- Energy Produced Tariff 2

Adding Gas Consumption

Under Gas Consumption, click Add Gas Source
Select Gas Consumed entity

After ~5 minutes, your 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 WaterP1MeterKit 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.waterp1meterkit_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.waterp1meterkit_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.waterp1meterkit_water_total_consumption_daily') }} liters

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

3. High Power Usage Alert

Alert when power consumption is unusually high:

yaml

alias: "Energy - High power alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.waterp1meterkit_power_consumed
    above: 5000  # More than 5kW
    for:
      minutes: 5
action:
  - service: notify.mobile_app
    data:
      title: "⚡ High Power Usage"
      message: "Current power: {{ states('sensor.waterp1meterkit_power_consumed') }}W"

4. Solar Production Notification

Get notified when your solar panels are producing well:

yaml

alias: "Solar - Good production alert"
trigger:
  - platform: numeric_state
    entity_id: sensor.waterp1meterkit_power_produced
    above: 3000  # More than 3kW production
condition:
  - condition: time
    after: "10:00:00"
    before: "16:00:00"
action:
  - service: notify.mobile_app
    data:
      title: "☀️ Solar Power!"
      message: "Producing {{ states('sensor.waterp1meterkit_power_produced') }}W - great solar day!"

5. 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.waterp1meterkit_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"

6. Turn Off Boiler When Solar Production is Low

Save energy by controlling your boiler based on solar production:

yaml

alias: "Boiler - Solar-based control"
trigger:
  - platform: state
    entity_id: sensor.waterp1meterkit_power_produced
action:
  - choose:
      # High solar production - turn on boiler
      - conditions:
          - condition: numeric_state
            entity_id: sensor.waterp1meterkit_power_produced
            above: 2000
        sequence:
          - service: switch.turn_on
            target:
              entity_id: switch.boiler
      # Low solar production - turn off boiler
      - conditions:
          - condition: numeric_state
            entity_id: sensor.waterp1meterkit_power_produced
            below: 500
        sequence:
          - service: switch.turn_off
            target:
              entity_id: switch.boiler

7. Washing Machine Finished Detection

Detect when your washing machine is done:

yaml

alias: "Appliance - Washing machine finished"
trigger:
  - platform: numeric_state
    entity_id: sensor.waterp1meterkit_power_consumed
    below: 50  # Very low power
    for:
      minutes: 2
condition:
  - condition: state
    entity_id: input_boolean.washing_machine_running
    state: "on"
action:
  - service: input_boolean.turn_off
    target:
      entity_id: input_boolean.washing_machine_running
  - service: notify.mobile_app
    data:
      title: "🧺 Washing Done!"
      message: "Your washing machine has finished"

8. 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.waterp1meterkit_water_flow_rate
    above: 10  # High flow rate
    for:
      seconds: 3
condition:
  - condition: numeric_state
    entity_id: sensor.waterp1meterkit_water_flow_rate
    above: 10
action:
  - service: counter.increment
    target:
      entity_id: counter.toilet_flushes_today

Water Leak Sensor Automations (V3 Only)

The WaterP1MeterKit V3 has an expansion port for an optional water leak sensor. Here are some useful automations:

Basic Leak Alert

Get notified immediately when water is detected:

yaml

alias: "Water Leak - Alert"
trigger:
  - platform: state
    entity_id: binary_sensor.waterp1meterkit_water_leak_sensor
    to: "on"
action:
  - service: notify.mobile_app
    data:
      title: "🚨 Water Leak Detected!"
      message: "Water detected at the WaterP1MeterKit sensor location!"
      data:
        priority: high
        tag: water-leak

Leak Alert with Shut-Off Valve

If you have a smart water shut-off valve, automatically close it when a leak is detected:

yaml

alias: "Water Leak - Emergency Shut-Off"
trigger:
  - platform: state
    entity_id: binary_sensor.waterp1meterkit_water_leak_sensor
    to: "on"
action:
  - service: switch.turn_off
    target:
      entity_id: switch.water_main_valve  # Your shut-off valve entity
  - service: notify.mobile_app
    data:
      title: "🚨 Water Leak - Valve Closed!"
      message: "Water leak detected! Main water valve has been automatically shut off."
      data:
        priority: high

Leak Resolved Notification

Get notified when the leak sensor dries up:

yaml

alias: "Water Leak - Resolved"
trigger:
  - platform: state
    entity_id: binary_sensor.waterp1meterkit_water_leak_sensor
    to: "off"
    for:
      minutes: 5  # Wait 5 minutes to confirm it's dry
action:
  - service: notify.mobile_app
    data:
      title: "✅ Water Leak Resolved"
      message: "The water leak sensor is now dry."
      data:
        tag: water-leak  # Clears the previous alert on iOS

Gas MBus Configuration

If your gas meter data is not showing in Home Assistant, the MBus ID might need to be changed. The gas meter communicates with the smart meter via MBus protocol, and the ID can be 1, 2, 3, or 4 depending on your setup.

How to Change the MBus ID

Adopt the WaterP1MeterKit in ESPHome
- Go to Home Assistant → ESPHome addon
- Click on your WaterP1MeterKit device
- Click Adopt if not already adopted
Edit the configuration
- Find the substitutions section at the top
- Change gas_mbus_id from "1" to "2", "3", or "4":

yaml

substitutions:
  device_name: waterp1meterkit
  friendly_name: WaterP1MeterKit
  gas_mbus_id: "2"  # Try 2, 3, or 4 if gas doesn't show

Save and Install
- Click Save then Install
- Choose Wirelessly to update over-the-air
Check Home Assistant
- After the device restarts, check if gas data appears
- If still no data, try the next MBus ID (3 or 4)

Why Different MBus IDs?

Your smart meter can have multiple devices connected via MBus (gas meter, water meter, heat meter, etc.). Each device has a unique ID (1-4). Most Dutch gas meters use ID 1, but Belgian and some other meters may use different IDs.

Still No Gas Data?

Verify your gas meter is actually connected to your smart meter
Some older gas meters don't transmit data digitally
Check if your energy provider has enabled gas transmission on the P1 port
Gas data is typically updated every hour, so wait at least an hour after setup

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.waterp1meterkit_water_total_consumption
- Meter reset cycle: Daily
Repeat for weekly and monthly

Recommended Dashboard Entities

Water Monitoring:

sensor.waterp1meterkit_water_total_consumption — Total water
sensor.waterp1meterkit_water_flow_rate — Current flow
sensor.waterp1meterkit_water_meter_total — Actual meter reading
sensor.water_daily — Daily usage (utility meter)

Energy Monitoring:

sensor.waterp1meterkit_power_consumed — Current power usage
sensor.waterp1meterkit_power_produced — Solar production
sensor.waterp1meterkit_energy_consumed_tariff_1 — Low tariff total
sensor.waterp1meterkit_energy_consumed_tariff_2 — High tariff total

Environment:

sensor.waterp1meterkit_temperature
sensor.waterp1meterkit_humidity

Example Dashboard Card - Water Overview

yaml

type: entities
title: 💧 Water
entities:
  - entity: sensor.waterp1meterkit_water_flow_rate
    name: Current Flow
  - entity: sensor.water_daily
    name: Today's Usage
  - entity: sensor.waterp1meterkit_water_meter_total
    name: Meter Reading

Example Dashboard Card - Energy Overview

yaml

type: entities
title: ⚡ Energy
entities:
  - entity: sensor.waterp1meterkit_power_consumed
    name: Power Usage
  - entity: sensor.waterp1meterkit_power_produced
    name: Solar Production
  - entity: sensor.waterp1meterkit_voltage_l1
    name: Voltage

Gauge Card for Power Usage

yaml

type: gauge
entity: sensor.waterp1meterkit_power_consumed
name: Current Power
min: 0
max: 10000
severity:
  green: 0
  yellow: 3000
  red: 6000
unit: W

Water Flow Gauge

yaml

type: gauge
entity: sensor.waterp1meterkit_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.waterp1meterkit_water_flow_rate
hours_to_show: 24

Statistics Card - This Week's Usage

yaml

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

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

Energy Monitoring Tips

Check tariff times: Ensure your low/high tariff times match your energy contract
Monitor phases: If you have 3-phase power, check each phase for imbalances
Solar optimization: Use the production data to time high-power appliances

Persistent Data

The WaterP1MeterKit 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
Solar Optimization	Power Produced	Control boiler, EV charger
Appliance Detection	Power Consumed	Washing machine, dishwasher alerts
Cost Tracking	Energy Consumed	Calculate costs per tariff
Environmental	Temperature, Humidity	Monitor utility room climate

Integration Ideas

Combine with Other SmartHomeShop Products

Product	Combined Use
CeilSense	Correlate presence with water/energy usage
UltimateSensor	Room-by-room climate + whole-house energy
WaterMeterKit	Multiple water meters (garden, washing machine)

Third-Party Integrations

Grafana: Create detailed energy 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 WaterP1MeterKit firmware.

Adopting in ESPHome

To customize your WaterP1MeterKit:

Go to Home Assistant → ESPHome addon
Your WaterP1MeterKit 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: waterp1meterkit
  friendly_name: WaterP1MeterKit
  project_version: "1.4"
  hardware_version: "V3"
  gas_mbus_id: "1"  # Change to 2, 3, or 4 if gas doesn't show

Substitution	Description
`device_name`	Internal device name (no spaces)
`friendly_name`	Display name in Home Assistant
`gas_mbus_id`	MBus ID for gas meter (1-4)

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 WaterP1MeterKit 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.waterp1meterkit: 
    github://smarthomeshop/waterp1meterkit/waterp1meterkit-v3/waterp1meterkit-wifi.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/waterp1meterkit
📄 V3 Base Config: waterp1meterkit-v3/base.yaml

Need Help?

Hardware Versions — Compare V1, V2, and V3
Network Configuration — WiFi/Ethernet setup
Troubleshooting — Common issues
FAQ — Frequently asked questions

Usage Guide ​

Quick Start ​

Water Entities ​

Energy Entities (P1) ​

Environment Entities ​

Home Assistant Energy Dashboard ​

Adding Water Consumption ​

Adding Electricity Consumption ​

Adding Solar Production ​

Adding Gas 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. High Power Usage Alert ​

4. Solar Production Notification ​

5. Shower Timer / Long Shower Alert ​

6. Turn Off Boiler When Solar Production is Low ​

7. Washing Machine Finished Detection ​

8. Toilet Flush Detection ​

Water Leak Sensor Automations (V3 Only) ​

Basic Leak Alert ​

Leak Alert with Shut-Off Valve ​

Leak Resolved Notification ​

Gas MBus Configuration ​

How to Change the MBus ID ​

Why Different MBus IDs? ​

Still No Gas Data? ​

Dashboard Ideas ​

Creating Utility Meters ​

Recommended Dashboard Entities ​

Example Dashboard Card - Water Overview ​

Example Dashboard Card - Energy Overview ​

Gauge Card for Power Usage ​

Water Flow Gauge ​

History Graph - Daily Water Pattern ​

Statistics Card - This Week's Usage ​

Best Practices ​

Water Sensor Positioning ​

Energy Monitoring Tips ​

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 Help? ​

Usage Guide

Quick Start

Water Entities

Energy Entities (P1)

Environment Entities

Home Assistant Energy Dashboard

Adding Water Consumption

Adding Electricity Consumption

Adding Solar Production

Adding Gas 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. High Power Usage Alert

4. Solar Production Notification

5. Shower Timer / Long Shower Alert

6. Turn Off Boiler When Solar Production is Low

7. Washing Machine Finished Detection

8. Toilet Flush Detection

Water Leak Sensor Automations (V3 Only)

Basic Leak Alert

Leak Alert with Shut-Off Valve

Leak Resolved Notification

Gas MBus Configuration

How to Change the MBus ID

Why Different MBus IDs?

Still No Gas Data?

Dashboard Ideas

Creating Utility Meters

Recommended Dashboard Entities

Example Dashboard Card - Water Overview

Example Dashboard Card - Energy Overview

Gauge Card for Power Usage

Water Flow Gauge

History Graph - Daily Water Pattern

Statistics Card - This Week's Usage

Best Practices

Water Sensor Positioning

Energy Monitoring Tips

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 Help?