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

Choose one water source: use either the pulse water sensor entities (Water Total Consumption, Water Current Usage) or the DSMR water entity (DSMR Water Consumed). Do not add both together in the Energy Dashboard.

Energy Entities (P1)

Environment Entities

Home Assistant Energy Dashboard

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

Adding Water Consumption

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

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

Adding Water Flow Rate

Recent Home Assistant versions also let you select a separate Water flow rate statistic in the same water configuration screen.

1. In the same Water Consumption setup screen
2. Open the Water flow rate dropdown
3. Select Water Current Usage
4. Save the configuration

Good to know: this works because the latest firmware exposes Water Current Usage as a proper flow-rate measurement entity. If you do not see it in the dropdown yet, update the WaterP1MeterKit firmware first and then restart Home Assistant or wait for statistics to refresh.

Belgian DSMR/MBus Digital Water Meters

Recent firmware adds support for Belgian digital water meters that are reported by the smart meter through DSMR/MBus on the P1 telegram.

1. Update to firmware V1 1.13, V2 1.14, V3 1.13, or V4 1.11 or newer
2. Open the WaterP1MeterKit device in Home Assistant
3. Enable the disabled DSMR Water Consumed entity
4. Add DSMR Water Consumed as the water source in the Energy Dashboard
5. Do not also add Water Total Consumption for the same physical water meter

The related diagnostic entities DSMR Water Equipment ID, DSMR Water Device Type, and DSMR Water Valve Position are also disabled by default. Enable them only if you need to check which digital water meter is being reported by your smart meter.

Important: DSMR Water Consumed is for digital water data coming through the P1 telegram. The physical MBus port on some meters is not used by the WaterP1MeterKit.

Adding Electricity Consumption

1. In the Energy Dashboard, under Electricity grid
2. Click Add grid connection
3. Select Energy Consumed Tariff 1 (low tariff) as Energy imported from grid and click Save
4. Add a second grid connection with Energy Consumed Tariff 2 (high tariff)

Adding Solar Production

If you have solar panels:

1. Open the grid connection of tariff 1 and select Energy Produced Tariff 1 as Energy exported to grid
2. Do the same in the grid connection of tariff 2 with Energy Produced Tariff 2

Adding Gas Consumption

1. Under Gas Consumption, click Add Gas Source
2. 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

1. Read your physical water meter (e.g., 125.456 m³)
2. In Home Assistant, find the WaterP1MeterKit 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

The meter logic works like this:

• Water Meter Initial Value is saved immediately when you enter it
• the running water total is saved every 5 minutes when it has changed (firmware V1 1.15, V2 1.16, V3 1.15, V4 1.14 and newer)
• during a normal restart or OTA update, the remaining unsaved delta is added during shutdown

This means:

• normal restarts and OTA updates preserve your meter reading
• an unexpected power outage can lose the water used since the last save, so at most about five minutes of usage

Automation Examples

Before you copy: the examples use sensor.waterp1meterkit_.... Your kit adds its MAC suffix to the name, so the real ID looks like sensor.waterp1meterkit_a1b2c3_power_consumed. Look up your own IDs under Settings → Devices & Services → Entities. Also replace notify.mobile_app with your own notify service, such as notify.mobile_app_your_phone.

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.waterp1meterkit_water_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.waterp1meterkit_water_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') }} m³

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:

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:

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:

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

6. Turn Off Boiler When Solar Production is Low

Save energy by controlling your boiler based on solar production:

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:

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

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

Water Leak Sensor Automations (V3/V4)

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

Basic Leak Alert

Get notified immediately when water is detected:

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:

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:

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 and Water MBus Configuration

If your gas meter data is not showing in Home Assistant, the gas 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.

Belgian digital water meters use the separate water_mbus_id setting. The default is 2, which matches many Belgian digital water meter setups.

How to Change the MBus IDs

1. Adopt the WaterP1MeterKit in ESPHome

   • Go to Home Assistant → ESPHome Device Builder app
   • Click on your WaterP1MeterKit device
   • Click Adopt if not already adopted

2. Edit the configuration

   • Find the substitutions section at the top. Keep the lines that are already there
   • Add gas_mbus_id with the value "2", "3", or "4" if gas does not show (the default is "1")
   • Add water_mbus_id only if Belgian DSMR water does not show and you know your meter uses another MBus ID

substitutions:
  name: waterp1meterkit-a1b2c3
  friendly_name: WaterP1MeterKit A1B2C3
  gas_mbus_id: "2"  # Try 2, 3, or 4 if gas doesn't show
  water_mbus_id: "2"  # Default for Belgian digital water meters

3. Save and Install

   • Click Save then Install
   • Choose Wirelessly to update over-the-air

4. 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

Still No DSMR Water Data?

• Confirm that your smart meter actually reports digital water data over the P1 telegram
• Enable DSMR Water Consumed manually in Home Assistant, because it is disabled by default
• Keep water_mbus_id: "2" first; only try another ID if your meter documentation or support case indicates a different MBus ID
• Use either DSMR water or the pulse water sensor, not both for the same meter

Older DSMR Meters & Regional P1 Settings

If your WaterP1MeterKit powers on correctly but electricity values stay N/A, unknown, or only some sensors fill in, the most common cause is that the smart meter uses an older DSMR serial profile than the default firmware expects.

When to Change the UART / DSMR Settings

This is worth trying when:

• the P1 cable is connected correctly
• the kit is powered, but power / tariff / total sensors stay empty
• reflashing the standard firmware did not help
• you have an older DSMR 2 or DSMR 3 meter

Step 1: Adopt the WaterP1MeterKit in ESPHome

Before changing any YAML:

1. Go to Home Assistant → ESPHome Device Builder app
2. Click on your WaterP1MeterKit device
3. Click Adopt if it is not adopted yet
4. Open the YAML editor for the device
5. Save and install after each change you test

DSMR 2/3 Profile

After adopting the device in ESPHome, this is the first override we recommend testing on older DSMR 2 and DSMR 3 meters:

uart:
  id: uart_dsmr
  baud_rate: 9600
  data_bits: 7
  parity: EVEN
  stop_bits: 1

dsmr:
  id: dsmr_instance
  uart_id: uart_dsmr
  crc_check: false

DSMR 2.2 Alternative

ESPHome officially documents DSMR 2.2 support with this older serial profile:

uart:
  id: uart_dsmr
  baud_rate: 9600
  data_bits: 7
  parity: NONE
  stop_bits: 1

dsmr:
  id: dsmr_instance
  uart_id: uart_dsmr
  crc_check: false

Regional Notes for Belgium and Other Markets

• Belgium: the first thing to check is usually gas_mbus_id. Many Belgian installations do not use the default gas ID 1.
• Power: the kit does not get power from the P1 port. It always needs USB-C or PoE, also with the P1 cable connected.
• Decryption key: only add decryption_key if your utility or meter documentation explicitly says your P1 telegrams are encrypted and gives you a 32-character key. ESPHome specifically documents this for encrypted setups such as Luxembourg Smarty. For most Dutch and Belgian P1 installations, leave this unset.

dsmr:
  decryption_key: !secret dsmr_decryption_key

Recommended Order to Troubleshoot

1. Check that the kit is powered via USB-C or PoE.
2. Adopt the kit in ESPHome.
3. Test the DSMR 2/3 profile above.
4. If your meter is confirmed DSMR 2.2, test the DSMR 2.2 alternative.
5. If gas is still missing, cycle through gas_mbus_id: "1" to "4" and wait up to one hour between checks.

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

Recommended Dashboard Entities

Water Monitoring:

• sensor.waterp1meterkit_water_total_consumption: Total water
• sensor.waterp1meterkit_water_current_usage: 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

type: entities
title: 💧 Water
entities:
  - entity: sensor.waterp1meterkit_water_current_usage
    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

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_phase_1
    name: Voltage

Gauge Card for Power Usage

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

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

Statistics Card - This Week's Usage

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:

Common Use Cases

Integration Ideas

Combine with Other SmartHomeShop Products

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:

1. Go to Home Assistant → ESPHome Device Builder app
2. Your WaterP1MeterKit 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: waterp1meterkit-v4
  friendly_name: WaterP1MeterKit
  gas_mbus_id: "1"  # Change to 2, 3, or 4 if gas doesn't show
  water_mbus_id: "2"  # Default for Belgian digital water meters

Modifying Sensor Calibration

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

sensor:
  - id: !extend hdc1080_sensor  # V4 firmware
    temperature:
      filters:
        offset: -4.5  # Default offset, adjust if needed
    humidity:
      filters:
        offset: 12  # Default offset, adjust if needed

How to calibrate:

1. Compare WaterP1MeterKit readings with a known accurate thermometer/hygrometer
2. Calculate the difference (e.g., if it reads 2°C too high, change offset to -6.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.waterp1meterkit: 
    github://smarthomeshop/waterp1meterkit/waterp1meterkit-v4/waterp1meterkit-wifi.yaml@main

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

Source Code

The complete ESPHome configuration is open source:

• 📁 GitHub Repository: smarthomeshop/waterp1meterkit
• 📄 V4 Base Config: waterp1meterkit-v4/base.yaml

DSMR Reader

Want to store and analyse raw P1 telegrams in a separate local database? The optional DSMR Reader (Docker) guide explains exactly what is forwarded, how to install the container service and how to connect it securely to an adopted WaterP1MeterKit.

Need Help?

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