SmartHomeShop Docs

Network Configuration

This guide explains how WaterFlowKit connects over WiFi or Ethernet, which options are available per hardware version, and how to switch safely between firmware variants.

Quick Overview

Variant V1 V2 Typical power Notes
WiFi ✅ ✅ USB-C Default shipping firmware
WiFi Cloud ✅ ✅ USB-C Cloud-sync variant
Ethernet ❌ ✅ USB-C or PoE Wired Ethernet
Ethernet Cloud ❌ ✅ USB-C or PoE Wired + cloud sync
Thread ❌ ✅ USB-C Local only, see Connect via Thread

WaterFlowKit ships with WiFi firmware by default. On WaterFlowKit V2 you can later switch to Ethernet, WiFi Cloud, or Ethernet Cloud through USB-C flashing or through the firmware selector in Home Assistant.

Start here if you want Ethernet on WaterFlowKit V2. The Ethernet port only works when the device runs an Ethernet firmware variant.

Which version supports what?

V1

  • WiFi
  • WiFi Cloud
  • captive portal
  • Improv BLE
  • Improv Serial

V2

  • WiFi
  • Ethernet
  • WiFi Cloud
  • Ethernet Cloud
  • captive portal
  • Improv BLE
  • Improv Serial
  • PoE support on V2 hardware

Important: Only WaterFlowKit V2 supports Ethernet and PoE.

WiFi Setup

First-time setup through the fallback hotspot

When WiFi firmware is not configured yet, WaterFlowKit creates a fallback hotspot:

  • SSID: waterflowkit
  • Password: waterflowkit

Step by step:

  1. Connect your phone or laptop to the waterflowkit network.
  2. The captive portal should open automatically.
  3. Choose your 2.4 GHz WiFi network and enter the password.
  4. WaterFlowKit reboots and joins your network.

If the captive portal does not open:

  • open http://192.168.4.1/ manually

Additional onboarding options on WiFi firmware

The current WiFi builds also support:

  • Improv BLE for provisioning over Bluetooth
  • Improv Serial over USB, with redirect support to the SmartHomeShop onboarding flow

This is especially useful on WaterFlowKit V2 when you want faster onboarding from Home Assistant or a provisioning tool.

WiFi requirements

  • 2.4 GHz network
  • WPA2 or WPA3
  • enough signal strength at the installation point

WiFi tips

  • Check coverage before mounting the unit in a technical room, cabinet, or utility space.
  • Use Ethernet on V2 if WiFi is structurally weak at that location.
  • If no valid WiFi is stored yet, or the saved network cannot be reached for about 90 seconds, the fallback hotspot comes up.

Ethernet Setup (V2 Only)

WaterFlowKit V2 has an Ethernet port for wired networking. It is intended for installations where stability matters more than wireless flexibility.

Why choose Ethernet?

  • more stable than WiFi
  • no wireless interference
  • useful in technical rooms or cabinets
  • PoE possible on V2 hardware
  • available on both local and cloud firmware variants

Requirements

Before switching to Ethernet:

  • make sure your network provides DHCP
  • confirm that Home Assistant and WaterFlowKit are on the same network or VLAN
  • connect the network cable before switching to Ethernet firmware
  • if using PoE, use a suitable injector or switch

First switch to Ethernet

The safest method:

  1. Connect WaterFlowKit V2 over USB-C.
  2. Open the web flasher.
  3. Choose WaterFlowKit, hardware version V2, how you use the device (local or with the app) and then Ethernet.
  4. Flash the firmware.
  5. Then connect the Ethernet cable if you have not already done so.

During first setup you can also choose Ethernet in the setup page on the waterflowkit hotspot. You still enter your WiFi once: the device uses it to install the Ethernet firmware in the background. Allow at least 2 minutes, then plug in the network cable.

Switching from Home Assistant

If the device is already connected to Home Assistant, you can also switch through:

  1. open the device in Home Assistant
  2. set Firmware Type to:
    • WiFi (local)
    • Ethernet (local)
    • WiFi + SmartHomeShop App (cloud)
    • Ethernet + SmartHomeShop App (cloud)
  3. on WiFi firmware the device starts installing that variant by itself within about 20 seconds
  4. on Ethernet firmware, press the Firmware Update button to start the installation

Important: The device needs internet access to download the new firmware. Connect the network cable first when you switch to Ethernet.

After switching to Ethernet

  • the device gets an IP address through DHCP by default
  • Home Assistant can rediscover the device
  • if auto-discovery does not work, check your router DHCP leases
  • add ESPHome manually by IP address if needed

Ethernet and PoE

WaterFlowKit V2 supports Ethernet and is intended for setups where PoE is also desirable.

In practice this means:

  • you can run V2 wired instead of over WiFi
  • PoE setups can reduce the need for separate power adapters
  • if Ethernet behaves unexpectedly, testing with plain USB-C power is still the fastest way to rule out a power issue

If Ethernet does not work:

  • test with a normal Ethernet cable and DHCP first
  • then test without PoE, using USB-C power

Switching Back to WiFi

You can move from Ethernet back to WiFi in two ways:

Method 1: USB-C web flasher

This is the safest method when the device is no longer easy to reach:

  1. connect USB-C
  2. open the web flasher
  3. choose WaterFlowKit, hardware version V2, how you use the device (local or with the app) and then Wi-Fi
  4. flash the firmware again
  5. configure WiFi through hotspot, Improv BLE, or Improv Serial

Method 2: Home Assistant

If the device is still reachable on Ethernet:

  1. choose WiFi (local) or WiFi + SmartHomeShop App (cloud) in the Firmware Type selector
  2. press the Firmware Update button
  3. let the device reboot
  4. configure WiFi if required

Tip: For first-time setup, recovery, or uncertain situations, USB-C is still the most predictable method.

Static IP

WaterFlowKit uses DHCP by default. If you need a fixed IP, adopt the device in ESPHome and add manual_ip yourself.

For WiFi

wifi:
  manual_ip:
    static_ip: 192.168.1.100
    gateway: 192.168.1.1
    subnet: 255.255.255.0

For Ethernet

ethernet:
  manual_ip:
    static_ip: 192.168.1.100
    gateway: 192.168.1.1
    subnet: 255.255.255.0

Use an address outside your DHCP pool, or create a DHCP reservation in your router.

Network Communication & Privacy

Local by default

The standard WiFi and Ethernet variants work locally with Home Assistant and ESPHome.

Local data includes:

  • flow rate
  • total consumption
  • per-input water temperature
  • ambient temperature and humidity
  • configuration and automations

Cloud variants

WaterFlowKit also has WiFi Cloud and Ethernet Cloud firmware variants. These are meant for setups where you also want SmartHomeShop cloud sync.

So choose intentionally:

  • WiFi / Ethernet for local use
  • WiFi Cloud / Ethernet Cloud for cloud-sync use

Troubleshooting

WiFi hotspot does not appear

  • wait 1 to 2 minutes after boot
  • check whether the device was already configured
  • try a reboot or factory reset

WiFi is unstable

  • check 2.4 GHz coverage
  • avoid installations directly behind heavy metal surfaces
  • use Ethernet on V2 when the location has consistently poor WiFi

Ethernet does not work

Check:

  1. that you are really running the Ethernet or Ethernet Cloud firmware
  2. that the cable is connected properly
  3. that DHCP is active
  4. that Home Assistant can reach the same network
  5. that you rule out PoE issues by temporarily powering through USB-C

No new IP appears

  • check your router DHCP lease table
  • try another switch port
  • try another Ethernet cable

Device stays offline in Home Assistant

  • reboot the device
  • ping the last known IP address
  • open the built-in web server through http://[device-ip]/
  • reflash over USB-C if needed

Need Help?