Troubleshooting

Rapidly flashing red status LED on a VLAN without internet

If your WaterFlowKit continues to report measurements but its red status LED flashes rapidly after startup, the firmware update check may be blocked by your firewall or IoT VLAN.

The local WaterFlowKit firmware reads a small version manifest from SmartHomeShop GitHub Pages. This check only determines whether new firmware is available. It does not send sensor readings, Home Assistant data, Wi-Fi passwords or API keys to GitHub.

ESPHome's standard status LED reports errors from every firmware component. A blocked update check can therefore look like a device startup error even while WaterFlowKit itself is working normally.

Confirm the cause

Open the WaterFlowKit logs in ESPHome and look for http_request.update or Failed to fetch manifest. If these messages are not present, investigate power, network and sensor initialization before changing the update settings.

Disable scheduled firmware checks

1. Open the ESPHome Device Builder app/add-on in Home Assistant. This is different from the ESPHome integration under Settings > Devices & services.
2. Find WaterFlowKit and select Take control or Adopt.
3. Save a copy of the generated YAML, including its API encryption key.
4. Select Edit and add this block at the bottom of the YAML, without extra indentation:

update:
  - id: !extend firmware_update
    update_interval: never

5. Save the file, select Validate, and then select Install > Wirelessly.

After installation, WaterFlowKit keeps measuring and communicating locally with Home Assistant, but it no longer performs scheduled firmware checks. You can still update it later through ESPHome or the SmartHomeShop web flasher.

ESPHome still downloads the WaterFlowKit packages: configuration from GitHub while compiling. That request is made by the Home Assistant/ESPHome host, not by WaterFlowKit itself.

If validation says that firmware_update does not exist, remove the block again and install a current WaterFlowKit firmware version first. A rapidly flashing LED that remains after this change can indicate another real firmware or hardware error.

If you encounter any issues with the WaterFlowKit, try the following steps.

General Troubleshooting Steps

1. Ensure All Cables Are Securely Connected

   • Check USB-C power cable connection
   • Verify sensor cables are properly clicked into connectors
   • Check for damaged cables

2. Check the Power Source

   • Ensure the power adapter is plugged into a working outlet
   • Verify the power LED is on (red on V2, blue on V1)

3. Restart the WaterFlowKit

   • Unplug the power cable, wait 10 seconds, and reconnect

4. Restart Home Assistant

   • Navigate to Settings → System → Restart

5. Update Home Assistant

   • Go to Settings → System → Updates

WiFi Connectivity Issues

Can't Find the WaterFlowKit Hotspot

If the waterflowkit WiFi hotspot doesn't appear:

1. Wait 1-2 minutes after powering on
2. Check if already configured: the hotspot appears when no WiFi is configured, or about 90 seconds after the saved network cannot be reached
3. Ensure proper power: power LED should be on
4. Try a factory reset if the device was previously configured

Connected to Hotspot but No Captive Portal

1. Open browser manually to http://192.168.4.1/
2. Try a different device (phone vs laptop)
3. Disable mobile data on your phone
4. Try a different browser

Frequent WiFi Disconnections

1. Check WiFi signal strength at the installation location
2. Move closer to router or use a WiFi extender
3. Check for interference from other 2.4 GHz devices
4. Verify router settings:
   • Ensure 2.4 GHz band is enabled (5 GHz not supported)
   • Check if router has client limits

WiFi Network Requirements

Flow Sensor Issues

No Flow Data

If the flow sensor shows 0 L/min when water is flowing:

1. Check cable connection: ensure the 3-pin connector is fully clicked in
2. Verify water is actually flowing through the sensor (not bypassing it)
3. Check sensor orientation: some sensors have a flow direction arrow
4. Test with different flow rates: very low flow may not register
5. Check for blockages in the sensor turbine

Inaccurate Flow Readings

If readings seem incorrect:

1. Compare with known volume: fill a container and check sensor reading
2. Check flow range: ensure flow is within sensor specifications
3. Look for air bubbles: air in the line affects accuracy
4. Calibrate the sensor: see Usage Guide: Calibration

Flow Reading Jumps or Fluctuates

1. Check for air in the line: bleed air from pipes
2. Verify stable water pressure: pressure fluctuations affect readings
3. Check cable for interference: route away from power cables
4. Ensure sensor is properly mounted: vibration can affect readings

Temperature Sensor Issues

Temperature Not Showing

If you have a YF-B7 or YF-B6 but temperature doesn't show:

1. Check the 2-pin cable is connected properly
2. Enable the entity in Home Assistant (may be disabled by default)
3. Wait for initial reading: can take a few seconds after boot

Inaccurate Temperature

1. Allow time to stabilize: sensor needs water flow to measure accurately
2. Check for external heat sources near the sensor
3. Verify sensor is in contact with water (internal to flow sensor)

Home Assistant Issues

Device Not Discovered

If Home Assistant doesn't find the WaterFlowKit:

1. Verify WiFi connection: WaterFlowKit must be on same network as HA
2. Check ESPHome integration is enabled
3. Add manually:
   • Go to Settings → Devices & Services
   • Click Add Integration → ESPHome
   • Enter the WaterFlowKit's IP address

Entities Missing

1. Check the device page in Home Assistant
2. Enable disabled entities: some are disabled by default
3. Restart Home Assistant after adding the device

Water Leak Issues

Leak at Sensor Connections

If water is leaking at the sensor fittings:

1. Turn off water supply immediately
2. Dry the connections
3. Apply more thread seal tape (PTFE)
4. Retighten connections: but don't overtighten
5. Test under pressure before finalizing

⚠️ Important: We are not responsible for water damage from leaks. Always test installations carefully.

Temperature Sensor Fitting Leaking

The temperature sensor connection often requires extra attention:

1. Apply thread seal tape to the temperature sensor probe
2. Tighten firmly: this fitting may need more torque
3. Check the O-ring or washer if present

LED Indicator Issues

No LEDs at All

1. Check power cable connection
2. Try a different USB-C cable
3. Try a different power adapter
4. Check if USB-C port is damaged

Red LED Flashing Slowly

Meaning: Not connected to WiFi network or Home Assistant.

Solution: Follow the WiFi setup steps or check your network connection.

Advanced Troubleshooting

Accessing the Web Interface

If you can't connect to WiFi normally:

1. Connect to the waterflowkit hotspot
2. Navigate to http://192.168.4.1/
3. Configure WiFi from the web interface

Firmware Updates

Ensure you're running the latest firmware:

• Install the update from the Firmware entity in Home Assistant
• Or flash via USB-C: see Firmware Guide

Factory Reset

To completely reset the WaterFlowKit:

1. Via USB-C flashing:

   • Connect to computer via USB-C
   • Flash the latest firmware from smarthomeshop.io/firmware
   • This removes all configuration including WiFi credentials

2. Via Home Assistant:

   • Enable the Factory Reset button on the device page (it is disabled by default)
   • Press it. This also removes your WiFi credentials and your sensor type and calibration settings

Checking Logs

For detailed debugging:

1. Adopt the device in the ESPHome Device Builder app
2. View logs from the ESPHome dashboard
3. Look for error messages or connection issues

Network Communication & Privacy

100% Local Operation

With the local firmware, the WaterFlowKit works entirely locally. All sensor data stays on your local network:

External Communication

With the local firmware, the only external communication is the firmware update check:

With the local firmware, no sensor data is ever sent externally. Cloud firmware also sends your readings to the SmartHomeShop app.

Additional Resources

• 📖 Installation Guide: Step-by-step setup
• 📖 Usage Guide: Monitoring & automations
• 📖 FAQ: Frequently asked questions
• 💬 Discord Community: Get help from the community

If you continue to experience problems after trying these steps, please reach out on Discord for personalized assistance.