SmartHomeShop Docs

Firmwarehandleiding

Lokale werking en GitHub-updatecontrole

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

WiFi- en Ethernetfirmware bevat een ESPHome-update-entiteit. Deze leest 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. Thread-firmware voert deze controle niet via WiFi of Ethernet uit.

WaterFlowKit zonder internettoegang gebruiken

Je mag internettoegang voor WaterFlowKit 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 WaterFlowKit-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 WaterFlowKit dan eerst bij via de SmartHomeShop-webflasher.

WaterFlowKit 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 WaterFlowKit firmware is 100% open source en beschikbaar op GitHub:

🔗 github.com/smarthomeshop/waterflowkit

De repository bevat:

  • Complete ESPHome configuraties voor V1 (ESP32) en V2 (ESP32-C6)
  • Flow sensor implementaties met temperatuurmonitoring
  • WiFi en Ethernet (V2) connectiviteitsopties
  • Geautomatiseerde builds via GitHub Actions
  • Community bijdragen welkom (PRs & issues)

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

Hardware Versies

WaterFlowKit is beschikbaar in twee hardware versies:

V1 - ESP32

  • Microcontroller: ESP32
  • Connectiviteit: Alleen WiFi
  • Flow Sensoren: Tot 2 sensoren
  • Features: Dual flow monitoring, watertemperatuur, omgevingssensoren
  • Geschikt voor: Basis flow monitoring setups

V2 - ESP32-C6 (Actueel)

  • Microcontroller: ESP32-C6
  • Connectiviteit: WiFi + Ethernet, of Thread met de Thread-firmware
  • Flow Sensoren: Tot 4 sensoren
  • Features: Quad flow monitoring, alle V1 features + bekabelde connectiviteit
  • Geschikt voor: Geavanceerde installaties met meerdere meetpunten

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

  1. Ga naar Instellingen → Apparaten & Services → Apparaten
  2. Selecteer je WaterFlowKit apparaat
  3. Open de Firmware update-entiteit en klik Installeren, of druk op de knop Firmware Update
  4. Het apparaat herstart automatisch

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 WaterFlowKit apparaat kaart
  3. Klik Install → kies Wirelessly
  4. Wacht tot de OTA update voltooid is

Methode 3: USB-C Web Flasher

Voor het wisselen van firmwarevarianten of herstel van apparaten:

  1. Verbind WaterFlowKit via USB-C kabel met je computer
  2. Open de flasher: smarthomeshop.io/firmware?product=waterflowkit
  3. Kies je hardware versie, hoe je het apparaat gebruikt (lokaal met Home Assistant, of met de SmartHomeShop-app) en de firmware (WiFi, of Ethernet op V2)
  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, sensortypes en kalibratie. Stel die daarna opnieuw in.

ESPHome Integratie Handleiding

Wil je je WaterFlowKit 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 WaterFlowKit 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 WaterFlowKit

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

  1. Open ESPHome vanuit de Home Assistant zijbalk
  2. Je WaterFlowKit verschijnt als een ontdekt apparaat
  3. Klik Adopt op de WaterFlowKit kaart
  4. Geef het een naam (bijv. "Keuken Flow Sensor")
  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: waterflowkit-a1b2c3
  friendly_name: WaterFlowKit A1B2C3

packages:
  smarthomeshop.waterflowkit: github://smarthomeshop/waterflowkit/waterflowkit-v2/waterflowkit-wifi.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 WaterFlowKit 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 WaterFlowKit draait nu op aangepaste firmware.

Geavanceerde Aanpassingen

Voorbeeld 1: Kalibreer Flow Sensoren

Hiervoor heb je geen YAML nodig. Zet in Home Assistant Flow1 Sensor Type op je sensormodel en stem fijn af met Flow1 Calibration %. Elke ingang heeft eigen instellingen. Zie de Gebruikshandleiding.

Voorbeeld 2: Voeg Flow Rate Alerts Toe

Krijg een melding wanneer flow verwachte niveaus overschrijdt (op V1 is het ID water_usage in plaats van water_usage1):

binary_sensor:
  - platform: template
    name: "Hoog Flow Alert"
    lambda: |-
      // Alert bij flow rate boven 20 L/min
      if (id(water_usage1).state > 20.0) {
        return true;
      }
      return false;
    filters:
      - delayed_on: 30s  # Moet 30 seconden hoog blijven

Voorbeeld 3: Bereken Waterkosten

Houd waterkosten per sensor bij (op V1 is het ID sensor_pulse_meter_total in plaats van sensor_pulse_meter_total1):

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

Voorbeeld 4: Temperatuur-Gebaseerde Automatiseringen

Bouw dit in Home Assistant in plaats van in de firmware. Zie de Warmwater Temperatuur Alert in de Gebruikshandleiding.

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

Configuratie Structuur

WaterFlowKit firmware gebruikt een modulaire architectuur:

waterflowkit-v1/
├── waterflowkit-wifi.yaml              # WiFi configuratie
├── waterflowkit-wifi-cloud.yaml        # WiFi + cloud-sync
└── [component bestanden]

waterflowkit-v2/
├── waterflowkit-wifi.yaml              # WiFi configuratie
├── waterflowkit-ethernet.yaml          # Ethernet configuratie
├── waterflowkit-wifi-cloud.yaml        # WiFi + cloud-sync
├── waterflowkit-ethernet-cloud.yaml    # Ethernet + cloud-sync
├── waterflowkit-thread.yaml            # Thread-firmware
└── [component bestanden]

Dit modulaire ontwerp maakt het makkelijk om:

  • Sensoren toe te voegen/verwijderen
  • Te wisselen tussen WiFi en Ethernet (V2)
  • Te wisselen tussen lokale en cloud-varianten
  • Configuraties te delen tussen apparaten
  • 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 netwerk
  2. Controleer dat het apparaat binnen WiFi/Ethernet bereik is (sterk signaal)
  3. Verifieer voldoende voeding (USB-C 5V 1A minimum)
  4. Probeer het apparaat te herstarten via Home Assistant
  5. Als alles faalt, flash via USB-C kabel

Flow Sensor Detecteert Geen Flow

Symptomen: Flow rate toont 0 zelfs wanneer water loopt

Oplossingen:

  1. Check sensor installatie: Zorg dat flow sensor in correcte richting is geïnstalleerd (pijl wijst flow richting)
  2. Verifieer verbindingen: Check dat sensor draden goed verbonden zijn met WaterFlowKit
  3. Sensortype: Controleer of Flow1 Sensor Type bij je sensor past
  4. Minimum flow: Sommige sensoren vereisen minimale flow rate (typisch 1-2 L/min) om te registreren
  5. Check logs: Bekijk ESPHome logs voor pulse detectie berichten

Onnauwkeurige Flow Metingen

Symptomen: Flow metingen komen niet overeen met werkelijk verbruik

Oplossingen:

  1. Kalibreer sensor: Stel Flow1 Sensor Type in en stem fijn af met Flow1 Calibration %
  2. Test meting: Laat exact 10L water lopen en vergelijk met gerapporteerd verbruik
  3. Check sensor type: Zorg dat je de correcte kalibratie gebruikt voor je sensor model
  4. Luchtbellen: Lucht in leidingen kan onnauwkeurige metingen veroorzaken
  5. Flow rate: Sensoren zijn het nauwkeurigst binnen hun gespecificeerde flow bereik

Apparaat Niet Ontdekt Na Flashen

Symptomen: WaterFlowKit 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. V2 met Improv: Gebruik Improv via BLE om WiFi opnieuw te configureren:
    • Open Home Assistant companion app
    • Ga naar Instellingen → Apparaten → Apparaat toevoegen
    • Selecteer je WaterFlowKit uit de BLE apparaten lijst
  4. Alternatief, gebruik de captive portal:
    • Apparaat creëert een WiFi AP genaamd "waterflowkit" (wachtwoord: waterflowkit)
    • Verbind ermee en configureer WiFi via de webinterface

Temperatuur Metingen Incorrect

Symptomen: Watertemperatuur toont onverwachte waarden

Oplossingen:

  1. NTC sensor kalibratie: Temperatuur sensoren kunnen kalibratie nodig hebben in ESPHome config
  2. Sensor plaatsing: Zorg dat NTC sensor goed geïnstalleerd is in water stroom
  3. Omgevingstemperatuur: Check of omgevings- in plaats van watertemperatuur wordt gemeten
  4. Check bedrading: Verifieer dat NTC sensor verbindingen goed vast zitten

Ethernet Werkt Niet (V2)

Symptomen: Ethernet verbinding mislukt of instabiel

Oplossingen:

  1. Zorg dat je de Ethernet firmware variant hebt geflasht (niet WiFi)
  2. Verifieer dat Ethernet kabel goed aangesloten is
  3. Check dat je router/switch werkt
  4. Test met een bekende werkende Ethernet kabel
  5. Voor V2: Ethernet en WiFi zijn mutueel exclusief - slechts één kan actief zijn

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 (gebruik kwaliteits USB adapter)
  3. Router instellingen: Schakel WiFi band steering uit en schakel alleen 2.4GHz in
  4. Interferentie: Verplaats weg van interferentie bronnen
  5. Overweeg Ethernet: Als V2, schakel over naar Ethernet voor stabilere verbinding

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

Flow Sensor Specificaties

WaterFlowKit is compatibel met standaard Hall-effect flow sensoren:

Sensor Maat Draad Typische Pulses/L Flow Bereik Veelgebruikt Voor
G1/2" (DN15) 1/2" ~660 1-25 L/min Kranen, douches
G3/4" (DN20) 3/4" ~396 1-30 L/min Wasmachines
G1" (DN25) 1" ~450 1-50 L/min Hoofdleidingen
G1½" (DN40) 1½" ~27 5-150 L/min Grote apparaten
G2" (DN50) 2" ~12 10-200 L/min Hoofd toevoer

Let op: Kies het juiste model bij de instelling Sensor Type in Home Assistant.

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 WaterFlowKit V2 kan in plaats van WiFi of Ethernet ook een Thread-netwerk joinen, voor lokaal gebruik met Home Assistant via een Thread border router. Zie WaterFlowKit verbinden via Thread.