Firmware Guide

Local operation and GitHub update checks

The local Home Assistant firmware keeps WaterP1MeterKit measurements on your own network. Sensor readings go directly to Home Assistant and are not sent to GitHub or the SmartHomeShop cloud.

Wi-Fi and Ethernet firmware includes an ESPHome update entity. It periodically reads a small firmware manifest from SmartHomeShop GitHub Pages to compare the installed version with the latest release. Only firmware metadata is requested; the firmware file is downloaded only when you install an update.

Cloud firmware intentionally communicates with the SmartHomeShop app as part of its cloud features. Disabling the GitHub update check does not convert cloud firmware into local firmware. Thread firmware does not perform this check over Wi-Fi or Ethernet.

Use WaterP1MeterKit without internet access

You may block internet access for WaterP1MeterKit; its local measurements and Home Assistant connection continue to work. To prevent a blocked check from triggering the red status LED, take control of the device in the ESPHome Device Builder app/add-on, open its YAML and add this at the bottom:

update:
  - id: !extend firmware_update
    update_interval: never

Save the YAML, select Validate, and install the build using Install > Wirelessly. This disables scheduled checks only; it does not remove the update component or change any WaterP1MeterKit sensors.

The adopted YAML continues to contain a packages: link to the SmartHomeShop GitHub repository. ESPHome uses that link on the Home Assistant host when it compiles your firmware. The device itself no longer polls for firmware versions after the customized build is installed.

To restore automatic checks, remove the added update: block and install the firmware again. If ESPHome cannot find the firmware_update ID, update WaterP1MeterKit through the SmartHomeShop web flasher before applying this customization.

This guide explains how to flash, update, or switch firmware on your WaterP1MeterKit. Whether you want to switch between WiFi and Ethernet, update to the latest version, or customize the firmware, we've got you covered.

Firmware Options

The WaterP1MeterKit supports these firmware variants:

WiFi and Ethernet are also available as SmartHomeShop App (cloud) variant for the SmartHomeShop app. Home Assistant keeps working on those variants.

📦 Default: All devices ship with WiFi firmware pre-installed.

DSMR/MBus Water Support

WaterP1MeterKit supports Belgian digital water meters reported through DSMR/MBus on the P1 telegram.

• Belgian digital water meters via DSMR/MBus are now supported
• New DSMR water entities are available, disabled by default:
  • DSMR Water Consumed
  • DSMR Water Equipment ID
  • DSMR Water Device Type
  • DSMR Water Valve Position
• New DSMR gas/MBus diagnostic entities are available, disabled by default:
  • DSMR Gas Device Type
  • DSMR Gas Valve Position
  • DSMR Gas Equipment ID Belgium
• water_mbus_id was added with default 2 for Belgian digital water meters

Energy Dashboard note: use either the pulse water sensor (Water Total Consumption) or DSMR water (DSMR Water Consumed). Do not add both for the same physical water meter.

Method 1: Web Flasher (Recommended)

The easiest way to flash firmware is via our web-based flasher. No software installation required: just a USB-C cable and a Chrome/Edge browser.

Steps

1. Connect your WaterP1MeterKit to your computer via USB-C
2. Open our firmware page: smarthomeshop.io/firmware
3. Select your hardware version (V1, V2, V3, or V4)
4. Choose how you use the device: Local with Home Assistant or SmartHomeShop app + local use
5. Choose the firmware (WiFi or Ethernet)
6. Click "Install firmware", select the USB port of your device and wait for the process to complete

⚠️ Note: After flashing Ethernet firmware, WiFi will no longer work. Connect an Ethernet cable before powering on.

When to Use

• ✅ First-time setup
• ✅ Switching from WiFi to Ethernet (or vice versa)
• ✅ Device is not responding or needs recovery
• ✅ You don't use the ESPHome Device Builder app

Method 2: Home Assistant Selector (WiFi → Ethernet only)

If your WaterP1MeterKit is already connected to Home Assistant via WiFi, you can switch to Ethernet firmware directly from Home Assistant.

Steps

1. Connect an Ethernet cable to your WaterP1MeterKit first!
2. Open Home Assistant → Devices → WaterP1MeterKit
3. Find the "Firmware Variant" selector
4. Change from "WiFi (local)" to "Ethernet (local)"
5. The device will download and install the new firmware automatically
6. After reboot, the device will be available via Ethernet

⚠️ Important: This method only works for WiFi → Ethernet. To switch back from Ethernet to WiFi, use Method 1 (Web Flasher) or Method 3 (ESPHome).

When to Use

• ✅ Switching from WiFi to Ethernet without USB-C cable
• ✅ Device is already working in Home Assistant
• ✅ Quick and easy method

Method 3: ESPHome Device Builder app (Advanced)

For users who want full control over their firmware, you can adopt the WaterP1MeterKit in the ESPHome Device Builder app and compile your own firmware.

Steps

1. Open ESPHome in Home Assistant
2. Adopt the WaterP1MeterKit (it should appear automatically if on the same network)
3. Edit the device configuration
4. Replace the YAML with the configuration from our GitHub repository:
   • 📁 GitHub: WaterP1MeterKit YAML files

Example: WiFi Configuration

substitutions:
  name: waterp1meterkit
  friendly_name: WaterP1MeterKit

packages:
  smarthomeshop.waterp1meterkit: github://smarthomeshop/waterp1meterkit/waterp1meterkit-v4/waterp1meterkit-wifi.yaml@main

esphome:
  name: ${name}
  friendly_name: ${friendly_name}
  name_add_mac_suffix: false

api:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

Example: Ethernet Configuration

substitutions:
  name: waterp1meterkit
  friendly_name: WaterP1MeterKit

packages:
  smarthomeshop.waterp1meterkit: github://smarthomeshop/waterp1meterkit/waterp1meterkit-v4/waterp1meterkit-ethernet.yaml@main

esphome:
  name: ${name}
  friendly_name: ${friendly_name}
  name_add_mac_suffix: false

api:

💡 Tip: Use waterp1meterkit-v4 for the current ESP32-C6 hardware. Replace it with waterp1meterkit-v3, waterp1meterkit-v2, or waterp1meterkit-v1 if you have older hardware.

Customization

With ESPHome, you can:

• Add custom sensors
• Change update intervals
• Add automations directly on the device
• Integrate with other ESPHome features

When to Use

• ✅ You want to customize the firmware
• ✅ You're familiar with ESPHome and YAML
• ✅ You want to add extra sensors or features
• ✅ You prefer compiling firmware yourself

Firmware Files by Hardware

Make sure to select the correct firmware for your hardware version:

🔍 Not sure which version you have? See Hardware Versions

After Flashing

Switching to Ethernet

After flashing Ethernet firmware:

1. Disconnect USB-C power
2. Connect Ethernet cable to a PoE switch (V2/V3/V4) or regular switch + USB-C power (V1)
3. The device should appear in Home Assistant automatically

Switching to WiFi

After flashing WiFi firmware:

1. The device creates a hotspot: waterp1meterkit (V4 with older firmware: waterp1meterkit-v4, password: same as the name)
2. Connect and configure your home WiFi
3. The device should appear in Home Assistant automatically

Re-adopting in Home Assistant

If the device doesn't appear after flashing:

1. Go to Settings → Devices & Services
2. Look for new ESPHome devices
3. Click Configure to add it

V4 with Ethernet Firmware: Check This Before an Update

Older Ethernet firmware on V4 can start with Firmware Variant on WiFi (local), even though the kit runs on Ethernet. An update from Home Assistant then installs WiFi firmware.

Before you update, set Firmware Variant to Ethernet (local) or Ethernet + SmartHomeShop App (cloud).

Is the kit offline after an update and do you see its WiFi hotspot? Then it runs WiFi firmware. Flash the Ethernet firmware over USB-C with Method 1 (Web Flasher).

Troubleshooting

Device not detected via USB-C

• Try a different USB-C cable (some cables are charge-only)
• Try a different USB port
• Make sure no other program is using the serial port
• Only if the device is still not detected: install the CP210x driver

Flashing fails

• Try the web flasher in incognito/private mode
• Close other browser tabs using serial connections

Device not appearing in Home Assistant

• Check if device is on the same network/VLAN
• Check your router for the device's IP address
• Try adding ESPHome integration manually with the IP address

Source Code

All firmware source code is open source and available on GitHub:

📁 github.com/smarthomeshop/waterp1meterkit

Releases & Changelog

Every firmware release gets its own versioned release entry. Use these links to quickly see what changed before you update:

• GitHub Releases
• CHANGELOG.md

Need Help?

• Discord Community: Get help from the community
• Troubleshooting Guide: Common issues and solutions
• Network Configuration: WiFi/Ethernet setup details

Thread Firmware

WaterP1MeterKit V4 can also join a Thread network for local Home Assistant use, reading one DSMR telegram every 5 seconds. See Connect WaterP1MeterKit via Thread.