Sensor Definitions

This page provides detailed explanations of all sensors, controls, and entities available on the WaterFlowKit. Use this as a reference to understand what each value means and how to use it.

Source Code: View the complete ESPHome configuration on GitHub

Quick Navigation

• Water Flow Sensors
• Water Temperature Sensors
• Environment Sensors
• Device Controls
• Diagnostic Entities
• LED Indicators

---

Water Flow Sensors

The WaterFlowKit supports up to 2 flow sensors. Each sensor provides flow rate and total volume entities.

📖 ESPHome Documentation: Pulse Counter

Flow Rate (L/min)

Entity	ID	Description	Unit
Flow1 Current water usage	water_usage	Real-time flow rate through sensor 1	L/min
Flow2 Current water usage	sens2_water_usage	Real-time flow rate through sensor 2 (if connected)	L/min

Total Volume (L)

Entity	ID	Description	Unit
Flow1 Total Consumption	sensor_pulse_meter_total	Cumulative water volume through sensor 1. Use for Energy Dashboard.	L
Flow2 Total Consumption	sens_2_sensor_pulse_meter_total	Cumulative water volume through sensor 2. Use for Energy Dashboard.	L

How It Works

The sensors use a turbine mechanism:

1. Water flows through the sensor, spinning an internal turbine
2. The turbine generates electrical pulses
3. Each pulse represents a specific volume of water
4. The WaterFlowKit counts pulses and calculates flow rate

Default Multiplier Values

The default firmware uses these multiplier values:

filters:
  - multiply: 0.00172  # For current flow rate (L/min)

total:
  filters:
    - multiply: 0.00163  # For total consumption (L)

These default values are calibrated for general use. For precise measurements, calibrate based on your specific sensor model. See Usage Guide — Calibration.

Pulse Formulas by Sensor Model

Sensor	Formula	Approx. Pulses/Liter	Calculated Multiply Value
YF-B1, YF-B7	F ≈ 11 × Q	~660 pulses/L	0.00151515
YF-B5, YF-B6	F ≈ 6.6 × Q	~396 pulses/L	0.00252525
YF-B10	F ≈ 7.5 × Q – 3	~450 pulses/L	0.00222222
YF-DN40-S	F ≈ 0.45 × Q	~27 pulses/L	0.03703704
YF-DN50-S	F ≈ 0.20 × Q	~12 pulses/L	0.08333333

F = frequency (Hz), Q = flow rate (L/min)

---

Water Temperature Sensors

Available on YF-B7 and YF-B6 sensor models only.

📖 ESPHome Documentation: NTC Sensor

Entity	ID	Description	Unit
Flow1 Water Temperature	flow1_water_temperature	Water temperature through flow sensor 1	°C
Flow2 Temperature	flow2_water_temperature	Water temperature through flow sensor 2	°C

Technical Details

The temperature sensors are NTC thermistors integrated into the flow sensors:

sensor:
  - platform: ntc
    id: flow1_water_temperature
    sensor: resistance_sensor
    calibration:
      b_constant: 3950
      reference_temperature: 25°C
      reference_resistance: 50kOhm
    name: Flow1 Water Temperature

Specifications

• Range: -20°C to +80°C
• Accuracy: ±0.5°C
• Sensor type: NTC thermistor (50kOhm @ 25°C, B=3950)

Use Cases

• Monitor hot water system efficiency
• Detect water heater issues
• Track solar water heater performance
• Verify hot/cold water mixing
• Heat pump monitoring (supply/return temperatures)

---

Environment Sensors

The WaterFlowKit includes an HDC1080 sensor for ambient temperature and humidity monitoring.

📖 ESPHome Documentation: HDC1080

Entity	ID	Description	Unit
Temperature	sensor_temperature	Ambient temperature around the WaterFlowKit	°C
Humidity	sensor_humidity	Ambient relative humidity	%

Technical Details

sensor:
  - platform: hdc1080
    temperature:
      name: "Temperature"
      filters:
        offset: -4.5
    humidity:
      name: "Humidity"
      filters:
        offset: 12
    update_interval: 60s

Default Offsets

The firmware applies calibration offsets by default:

• Temperature: -4.5°C offset
• Humidity: +12% offset

These can be adjusted if your readings don't match a reference.

Use Cases

• Monitor conditions in meter cabinet
• Detect moisture issues
• Track environment where pipes are located

---

Device Controls

Switches

Entity	ID	Description
Restart	switch_restart	Restarts the WaterFlowKit. Useful after configuration changes.

---

Diagnostic Entities

Connection Status

Entity	ID	Description
WiFi Signal	sensor_wifi_signal	WiFi signal strength in dBm. Updates every 5 minutes. Values closer to 0 = better signal.
Uptime	sensor_uptime_timestamp	Timestamp when the device was last started.

Network Information

Entity	Description
IP address	Current IP address of the WaterFlowKit
Connected SSID	Name of the WiFi network
Connected BSSID	MAC address of the WiFi access point

Version Information

Entity	ID	Description
ESPHome Version	text_sensor_version	The ESPHome version running on the device
Software Version	text_sensor_waterflowkit_version	WaterFlowKit firmware version (e.g., "2025.11")

---

LED Indicators

The WaterFlowKit has 3 LEDs (configurable via ESPHome):

LED	ID	Color	Default Behavior
LED Green	light_led_green	Green	Available for custom use
LED Red	light_led_red	Red	Status LED (flashing = not connected)
LED Blue	light_led_blue	Blue	Available for custom use

LED Configuration in ESPHome

output:
  - platform: ledc
    pin: GPIO16
    id: output_led_green
  - platform: ledc
    pin: GPIO17
    id: output_led_red
  - platform: ledc
    pin: GPIO04
    id: output_led_blue

light:
  - platform: monochromatic
    id: light_led_green
    output: output_led_green
  - platform: status_led
    id: light_led_red
    output: output_led_red
  - platform: monochromatic
    id: light_led_blue
    output: output_led_blue

---

Entity Naming Convention

All entities follow this naming pattern:

sensor.waterflowkit_[sensor_name]
switch.waterflowkit_[switch_name]
light.waterflowkit_[light_name]

For example:

• sensor.waterflowkit_flow1_current_water_usage
• sensor.waterflowkit_flow1_total_consumption
• sensor.waterflowkit_flow1_water_temperature
• sensor.waterflowkit_temperature
• sensor.waterflowkit_humidity

---

Calibration

If your sensor readings don't match expected values, you can calibrate by adjusting the multiply filter values.

🔧 Calibration Guide: See Usage Guide — Calibration for step-by-step instructions.

---

ESPHome Configuration

For advanced users who want to customize the WaterFlowKit firmware:

🔧 Advanced Configuration: See Usage Guide — ESPHome Configuration for details.

---

Need Help?

• Usage Guide — Monitoring & automations
• Troubleshooting — Common issues
• FAQ — Frequently asked questions
• Discord — Community support