SmartHomeShop Docs

Firmwarehandleiding

Lokale werking en GitHub-updatecontrole

De lokale Home Assistant-firmware houdt de metingen van WaterMeterKit op je eigen netwerk. Sensorwaarden gaan rechtstreeks naar Home Assistant en worden niet naar GitHub of de SmartHomeShop-cloud gestuurd.

WaterMeterKit V3 WiFi-firmware bevat een ESPHome-update-entiteit. V1 en V2 hebben geen update-entiteit en doen geen updatecontrole. Op V3 leest deze periodiek een klein firmwaremanifest vanaf SmartHomeShop GitHub Pages om de geïnstalleerde versie met de nieuwste release te vergelijken. Alleen firmwaremetadata wordt opgevraagd; het firmwarebestand wordt pas gedownload wanneer je een update installeert.

Cloudfirmware communiceert voor de cloudfuncties bewust met de SmartHomeShop-app. Het uitschakelen van de GitHub-controle verandert cloudfirmware niet in lokale firmware. Op Thread-firmware blijft de update-entiteit inactief, omdat die internettoegang nodig heeft.

WaterMeterKit zonder internettoegang gebruiken

Je mag internettoegang voor WaterMeterKit blokkeren; de lokale metingen en Home Assistant-verbinding blijven werken. Wil je voorkomen dat een geblokkeerde controle de rode status-led activeert? Neem het apparaat dan over in de ESPHome Device Builder-app/add-on, open de YAML en voeg dit onderaan toe:

update:
  - id: !extend firmware_update
    update_interval: never

Sla de YAML op, kies Validate en installeer de build met Install > Wirelessly. Hiermee schakel je alleen geplande controles uit; het updatecomponent en alle WaterMeterKit-sensoren blijven aanwezig.

De geadopteerde YAML bevat nog steeds een packages:-verwijzing naar de SmartHomeShop GitHub-repository. ESPHome gebruikt die verwijzing op de Home Assistant-host tijdens het compileren. Nadat de aangepaste build is geïnstalleerd, vraagt het apparaat zelf niet meer periodiek de firmwareversie op.

Wil je automatische controles herstellen? Verwijder dan het toegevoegde update:-blok en installeer de firmware opnieuw. Kan ESPHome het ID firmware_update niet vinden, werk WaterMeterKit dan eerst bij via de SmartHomeShop-webflasher. V1 en V2 hebben dit ID niet en hebben deze aanpassing niet nodig.

WaterMeterKit draait op ESPHome, een open-source firmware platform dat werkt met Home Assistant. ESPHome stelt je in staat om elk aspect van je apparaat aan te passen terwijl je volledige lokale controle behoudt: geen cloud vereist.

Open Source & GitHub

Alle WaterMeterKit firmware is 100% open source en beschikbaar op GitHub:

🔗 github.com/smarthomeshop/watermeterkit

De repository bevat:

  • Complete ESPHome configuraties voor V1, V2 en V3 hardware
  • Magnetische water flow sensor implementatie
  • Waterverbruik tracking en berekeningen
  • Geautomatiseerde builds via GitHub Actions
  • Community bijdragen welkom (PRs & issues)

Je kunt de firmware bekijken, aanpassen en personaliseren naar wens: van het aanpassen van sensor gevoeligheid tot het toevoegen van compleet nieuwe functies.

Hardware Versies

WaterMeterKit is beschikbaar in drie hardwareversies:

V1 - ESP8266 (Legacy)

  • Microcontroller: ESP8266
  • Connectiviteit: Alleen WiFi (2.4GHz)
  • Sensoren: Magnetische water flow sensor, temperatuur, luchtvochtigheid
  • Metingen: Huidig verbruik (L/min), totaal verbruik (m³)
  • Status: Legacy hardware, alleen voor bestaande installaties

V2 - Vorige Generatie

  • Microcontroller: ESP8266
  • Connectiviteit: Alleen WiFi (2.4GHz)
  • Sensoren: Magnetische water flow sensor, temperatuur, luchtvochtigheid
  • Status: Ondersteund voor bestaande klanten

V3 - ESP32-C6 (Actueel)

  • Microcontroller: ESP32-C6
  • Connectiviteit: WiFi (2.4GHz), of Thread met de Thread-firmware
  • Sensoren: Magnetische water flow sensor, temperatuur, luchtvochtigheid
  • Metingen: Huidig verbruik (L/min), totaal verbruik (m³)
  • Compatibel met: Actaris, Elster, Honeywell, Itron, Sensus analoge watermeters
  • Geschikt voor: Actuele WaterMeterKit installaties

Hoe controleer je jouw versie: Kijk op het apparaat label of check de "Hardware Version" sensor in Home Assistant.

Snelle Update Methodes

Methode 1: Home Assistant (Makkelijkste)

Voor reguliere firmware updates op V3 (aanbevolen):

  1. Ga naar Instellingen → Apparaten & Services → Apparaten
  2. Selecteer je WaterMeterKit apparaat
  3. Open de Firmware update-entiteit
  4. Klik Installeren om de update te downloaden en toe te passen
  5. Het apparaat herstart automatisch

⚠️ V1 en V2 hebben geen update-entiteit. Werk ze bij met Methode 2 of Methode 3. Door de 1MB flash kan een draadloze update mislukken met ESP does not have enough space to store OTA file. Flash in dat geval via USB-C.

Methode 2: ESPHome Device Builder

Voor updates met aangepaste configuraties:

⚠️ Belangrijk: Deze methode vereist de ESPHome Device Builder-app (niet alleen de ESPHome integratie). Als je deze nog niet hebt geïnstalleerd, zie de ESPHome Integratie Handleiding sectie hieronder voor stap-voor-stap installatie instructies.

  1. Open het ESPHome Device Builder in Home Assistant (vanuit de zijbalk)
  2. Klik op je WaterMeterKit apparaat kaart
  3. Klik Install → kies Wirelessly
  4. Wacht tot de OTA update voltooid is

Methode 3: USB-C Web Flasher

Voor het herstellen van apparaten of schone installaties:

  1. Verbind WaterMeterKit via USB-C kabel met je computer
  2. Open de flasher: smarthomeshop.io/firmware?product=watermeterkit
  3. Kies je hardwareversie (V1, V2 of V3), hoe je het apparaat gebruikt (lokaal met Home Assistant, of met de SmartHomeShop-app) en de firmware
  4. Start de installatie en selecteer de USB-poort van je apparaat
  5. Volg de instructies op het scherm

Opmerking: Flashen vanaf deze pagina zet het apparaat terug naar de fabrieksinstellingen, inclusief je WiFi-gegevens en de opgeslagen watermeterstand. Noteer eerst je meterstand en stel Water Meter Initial Value daarna opnieuw in.

Wisselen tussen Lokale en Cloudfirmware (V3)

WaterMeterKit V3 heeft in Home Assistant een Firmware Variant-keuze met de opties WiFi (local) en WiFi + SmartHomeShop App (cloud). Kies de andere optie en het apparaat installeert die firmware zelf via WiFi, binnen ongeveer 20 seconden. Daarvoor is internettoegang nodig. Op V1 en V2 wissel je met de webflasher (Methode 3).

ESPHome Integratie Handleiding

Wil je je WaterMeterKit firmware aanpassen? Volg deze stap-voor-stap handleiding om je apparaat te adopteren in ESPHome en aanpassingen te maken.

🚨 Belangrijk: Het Verschil Begrijpen

Veel gebruikers verwarren twee verschillende zaken:

  • ESPHome Integratie (Instellingen → Apparaten & Services → Integraties) - Dit is hoe je WaterMeterKit communiceert met Home Assistant. Deze heb je waarschijnlijk al. ✅
  • ESPHome Device Builder-app (Instellingen → Apps) - Dit is de tool die je nodig hebt om firmware te bewerken, builden en flashen. Deze moet je apart installeren! 🔧

Om firmware aan te passen, MOET je de ESPHome Device Builder-app hieronder installeren. Alleen de integratie hebben is niet genoeg!

Stap 1: Installeer de ESPHome Device Builder-app

Als je de ESPHome Device Builder-app nog niet hebt geïnstalleerd:

  1. Open Home Assistant → Instellingen → Apps
  2. Klik Installeer een app
  3. Zoek naar ESPHome Device Builder
  4. Open de app en klik Installeren
  5. Schakel Start bij opstarten en Toon in zijbalk in
  6. Klik Start

Stap 2: Adopteer je WaterMeterKit

Adopteren stelt ESPHome in staat om de configuratie van je apparaat te beheren:

  1. Open ESPHome vanuit de Home Assistant zijbalk
  2. Je WaterMeterKit verschijnt als een ontdekt apparaat
  3. Klik Adopt op de WaterMeterKit kaart
  4. Geef het een naam (bijv. "Hoofd Watermeter")
  5. Klik nogmaals Adopt om te bevestigen

ESPHome maakt nu een configuratie aan die verwijst naar ons package op GitHub.

Hoe ziet de geadopteerde configuratie eruit?

Na adoptie zie je een YAML configuratie die er zo uitziet:

substitutions:
  name: watermeterkit-a1b2c3
  friendly_name: WaterMeterKit A1B2C3

packages:
  smarthomeshop.watermeterkit: github://smarthomeshop/watermeterkit/watermeterkit-v3/watermeterkit.yaml@main

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

api:
  encryption:
    key: JOUW_UNIEKE_ENCRYPTIE_KEY_HIER==

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

Deze structuur begrijpen:

  • substitutions: Apparaat-specifieke variabelen (naam, weergavenaam). Pas deze aan om gedrag te customizen!
  • packages: Link naar de basis configuratie op GitHub. Dit haalt automatisch updates binnen wanneer beschikbaar.
  • api/wifi: Je apparaat's unieke encryptie key en WiFi inloggegevens.

Deze modulaire aanpak betekent: ✅ Je krijgt automatisch updates van GitHub ✅ Je customizations blijven gescheiden in substitutions ✅ Je hoeft niet de hele configuratie te kopiëren/plakken

Stap 3: Pas de Configuratie Aan

Na adoptie kun je de YAML configuratie aanpassen:

  1. Klik Edit op je geadopteerde WaterMeterKit apparaat
  2. De YAML editor opent met je huidige configuratie
  3. Maak je gewenste wijzigingen (zie voorbeelden hieronder)
  4. Klik Save

Stap 4: Upload Aangepaste Firmware

Na het maken van wijzigingen:

  1. Klik Install op je apparaat kaart
  2. Kies Wirelessly (aanbevolen) of Plug into this computer
  3. ESPHome compileert en uploadt je aangepaste firmware
  4. Wacht tot het apparaat herstart en opnieuw verbindt

✅ Klaar! Je WaterMeterKit draait nu op aangepaste firmware.

Geavanceerde Aanpassingen

Voorbeeld 1: Pas aan Hoe Vaak de Meterstand Wordt Opgeslagen

De sensor telt op elke ondersteunde watermeter één puls per liter, dus er is geen pulse rate om in te stellen. Je kunt wel aanpassen hoe vaak het apparaat de meterstand opslaat. Minder vaak opslaan betekent minder slijtage van het flashgeheugen, maar een plotselinge stroomuitval kan dan meer verbruik kosten:

substitutions:
  water_checkpoint_interval: "10min"  # Standaard: 5min op V3, 30min op V1 en V2

Voorbeeld 2: Voeg Waterverbruik Alerts Toe

Krijg een melding wanneer waterverbruik verwachte niveaus overschrijdt:

binary_sensor:
  - platform: template
    name: "Hoog Waterverbruik Alert"
    lambda: |-
      // Alert bij meer dan 100L verbruikt in 5 minuten
      if (id(sensor_pulse_meter).state > 20.0) {
        return true;
      }
      return false;
    filters:
      - delayed_on: 5min  # Moet 5 minuten hoog blijven

Voorbeeld 3: Bereken Totale Waterkosten

Houd de kosten van je meterstand bij:

sensor:
  - platform: template
    name: "Totale Waterkosten"
    unit_of_measurement: "EUR"
    device_class: monetary
    lambda: |-
      // Uitgaande van 2.00 EUR per m³
      float cost = id(sensor_water_meter_total).state * 2.0;
      return cost;
    update_interval: 60s

Voorbeeld 4: Lek Detectie

Detecteer potentiële lekken op basis van continue lage flow:

binary_sensor:
  - platform: template
    name: "Mogelijk Waterlek"
    lambda: |-
      // Alert bij water dat 2 uur continue stroomt op laag niveau
      if (id(sensor_pulse_meter).state > 0.1 && id(sensor_pulse_meter).state < 5.0) {
        return true;
      }
      return false;
    filters:
      - delayed_on: 2h  # Continue flow voor 2 uur

Meer info: Bekijk de ESPHome documentatie voor complete configuratie referentie.

Configuratie Structuur

WaterMeterKit firmware gebruikt een modulaire architectuur:

watermeterkit-v1/ en watermeterkit-v2/
├── watermeterkit.yaml              # WiFi firmware
├── watermeterkit-cloud.yaml        # WiFi + SmartHomeShop-app
├── base.yaml                       # Apparaat, sensoren en LEDs
├── wifi.yaml                       # WiFi connectiviteit
└── cloud.yaml                      # Cloud-sync

watermeterkit-v3/
├── watermeterkit.yaml              # WiFi firmware
├── watermeterkit-cloud.yaml        # WiFi + SmartHomeShop-app
├── watermeterkit-thread.yaml       # Thread-firmware
├── base.yaml                       # Apparaat, sensoren en LEDs
├── wifi.yaml                       # WiFi connectiviteit
├── thread.yaml                     # Thread-connectiviteit
└── cloud.yaml                      # Cloud-sync

packages/
└── water-persistence.yaml          # Slaat de meterstand op

Dit modulaire ontwerp maakt het makkelijk om:

  • Sensoren toe te voegen/verwijderen
  • Configuraties te delen tussen apparaten
  • Consistentie te behouden over updates
  • Verbeteringen terug te geven aan de community

Probleemoplossing

Apparaat Wil Niet OTA Updaten

Symptomen: OTA update mislukt of time-out

Oplossingen:

  1. Zorg dat het apparaat aanstaat en verbonden is met WiFi
  2. Controleer dat het apparaat binnen WiFi bereik is (sterk signaal)
  3. V1 en V2 (ESP8266): De fout ESP does not have enough space to store OTA file komt door de 1MB flash, flash in dat geval via USB-C
  4. Verifieer dat het apparaat succesvol is geadopteerd in ESPHome
  5. Als alles faalt, flash via USB-C kabel

Geen Water Flow Gedetecteerd

Symptomen: Waterverbruik toont 0 zelfs wanneer water loopt

Oplossingen:

  1. Check sensor positionering: Zorg dat magnetische sensor correct gepositioneerd is boven het roterende element van de watermeter
  2. Sensor afstand: Magnetische sensor moet zeer dichtbij de metalen indicator zijn (binnen 1-2mm)
  3. Watermeter compatibiliteit: Niet alle watermeters hebben magnetische indicatoren - check je meter model
  4. Check logs: Bekijk ESPHome logs voor pulse detectie berichten

Onnauwkeurige Watermetingen

Symptomen: Waterverbruik komt niet overeen met werkelijk verbruik

Oplossingen:

  1. Sensor uitlijning: Zorg dat sensor gecentreerd is boven het roterende element
  2. Test meting: Laat exact 10L water lopen en vergelijk met gerapporteerd verbruik
  3. Interferentie: Houd sensor weg van sterke magnetische velden of metalen objecten
  4. Meter type: De sensor moet de roterende 1-liter indicator lezen, hij telt één puls per liter

Apparaat Niet Ontdekt Na Flashen

Symptomen: WaterMeterKit verschijnt niet in ESPHome na USB flashen

Oplossingen:

  1. Het apparaat heeft mogelijk WiFi inloggegevens verloren tijdens flashen
  2. Verbind via USB-C en bekijk de logs in ESPHome
  3. Gebruik Improv via Serial om WiFi opnieuw te configureren:
    • Houd USB-C aangesloten
    • Bezoek web.esphome.io
    • Verbind en configureer WiFi via browser
  4. Alternatief, gebruik de captive portal:
    • Apparaat creëert een WiFi AP genaamd "watermeterkit" (wachtwoord: watermeterkit)
    • Verbind ermee en configureer WiFi via de webinterface

Hoge WiFi Herverbinding Rate

Symptomen: Apparaat verbreekt en herverbindt frequent

Oplossingen:

  1. Check signaal sterkte: Zorg voor sterk WiFi signaal (-70 dBm of beter)
  2. Voeding: Verifieer stabiele 5V voeding via USB-C (minimum 1A)
  3. Router instellingen: Schakel WiFi band steering uit en schakel alleen 2.4GHz in
  4. V1 / ESP8266 beperking: Bekend minder stabiel op drukke WiFi netwerken
  5. Afstand: Verplaats apparaat dichter bij WiFi access point of voeg WiFi extender toe

Compilatie Fouten in ESPHome

Symptomen: Custom YAML compileert niet

Oplossingen:

  1. Controleer op YAML syntax fouten (inspringingen moeten consistent zijn)
  2. Verifieer dat je een compatibele ESPHome versie gebruikt (check GitHub repo vereisten)
  3. Bekijk de compilatie log voor specifieke foutmeldingen
  4. Vergelijk je wijzigingen met de officiële configuratie
  5. Vraag om hulp op GitHub Issues of onze Discord community

Water Totaal Reset naar Nul

Symptomen: Totaal waterverbruik reset onverwacht

Oplossingen:

  1. Dit is normaal voor Total Consumption: Die teller begint na elke herstart bij nul. Home Assistant bewaart de historie, en Water Meter Total bewaart je absolute meterstand
  2. Stel je meterstand in: Vul je fysieke meterstand in bij Water Meter Initial Value. Die wordt direct opgeslagen
  3. Stroomuitval: Een plotselinge stroomuitval kan het verbruik sinds de laatste opslag kosten, tot 5 minuten op V3 en tot 30 minuten op V1 en V2. Water dat je gebruikt terwijl het apparaat uit staat, wordt niet geteld
  4. Na een USB-flash of fabrieksreset: De opgeslagen stand is weg, stel Water Meter Initial Value dus opnieuw in

Watermeter Compatibiliteit

WaterMeterKit werkt met analoge watermeters die een roterend metalen indicator hebben. Compatibele merken zijn onder andere:

  • Actaris (Itron)
  • Elster (Honeywell)
  • Honeywell
  • Itron
  • Sensus

Belangrijkste vereiste: Je watermeter moet een zichtbare roterende metalen schijf, tandwiel, of wijzer hebben die magnetisch gedetecteerd kan worden. Zie de volledige lijst.

Firmware Changelog

Nieuwste wijzigingen worden bij releases aangekondigd. Grote updates verschijnen hier.

Waar vind je wijzigingen:

Aanvullende Bronnen

Hulp nodig? Bezoek ons Support Portal of join onze Discord community!

Thread-firmware

De WaterMeterKit V3 kan in plaats van WiFi ook een Thread-netwerk joinen, voor lokaal gebruik met Home Assistant via een Thread border router. Zie WaterMeterKit verbinden via Thread.