A custom Home Assistant integration for WaterGenius water softener devices. Connects directly over Bluetooth Low Energy (BLE) to read sensor data and control your water softener — no cloud, no internet required.
- Automatic BLE discovery — WaterGenius devices (advertising as
XPG-GAgent-xxxx) are detected automatically - 20+ sensor entities — water hardness, flow rate, capacity, salt level, regeneration status, water usage, and more
- 2 binary sensors — alarm status and regeneration activity
- 2 action buttons — trigger immediate or scheduled regeneration
- 1 switch — toggle salt alarm sound
- No cloud dependency — communicates directly with the device over Bluetooth
- Official data point schema — byte offsets sourced from the Gizwits product API (218 data points)
- Home Assistant 2024.1 or newer
- A Bluetooth adapter on your Home Assistant host (built-in or USB)
- The WaterGenius device must be within Bluetooth range (~10m) of the HA host
- Important: Only one BLE client can connect to the device at a time. Close the WaterGenius phone app before the integration connects.
- Open HACS in Home Assistant
- Click the three dots menu (top right) → Custom repositories
- Add
https://github.com/tvdeynde/watergenius-hawith category Integration - Search for "WaterGenius" and install
- Restart Home Assistant
- Download or clone this repository
- Copy the
custom_components/watergeniusfolder into your Home Assistantconfig/custom_components/directory - Restart Home Assistant
- Go to Settings → Devices & Services → Add Integration
- Search for WaterGenius
- Select your device from the list — it appears as
XPG-GAgent-xxxx - If not listed, choose "Enter address manually..." and type the Bluetooth MAC address
- The integration creates a device with all entities
If no devices are found:
- Make sure the WaterGenius phone app is fully closed (BLE allows only one connection)
- Verify your HA host has a working Bluetooth adapter
- Ensure the device is powered on and within Bluetooth range
- Check the WaterGenius phone app (device info/settings)
- Look in your phone's Bluetooth settings while connected to the device
- The device advertises as
XPG-GAgent-xxxxwherexxxxis the last 4 characters of the MAC
| Entity | Description | Unit |
|---|---|---|
| Incoming Hardness | Water hardness before softening | mg/L |
| Outgoing Hardness | Water hardness after softening | mg/L |
| Hardness Unit | Active hardness unit (mg/L, °dH, °fH, etc.) | — |
| Current Flow Rate | Real-time water flow | L/min |
| Remaining Capacity | Remaining softening capacity before regeneration | L |
| Remaining Capacity % | Remaining capacity as percentage | % |
| Total Capacity | Total softening capacity | L |
| Salt Level | Current salt level in the brine tank | % |
| Days to Next Regeneration | Estimated days until next regeneration cycle | days |
| Average Daily Water Usage | Average daily water consumption | L |
| Today Water Usage | Water used today | L |
| Total Water Usage | Cumulative water usage since installation | L |
| Total Hardness Removal | Cumulative hardness removed since installation | mg CaCO₃ |
| Valve State | Current valve position (In Service, Brine, Backwash, Rinse, Refill) | — |
| Regeneration Countdown | Time remaining in current regeneration phase | seconds |
| Peak Flow Rate | Highest recorded flow rate | — |
| Total Regeneration Count | Total number of regeneration cycles | — |
| Error Log | Device error code | — |
| Entity | Description | Device Class |
|---|---|---|
| Alarm | Active when the device has an alarm condition (e.g. low salt) | Problem |
| Regenerating | Active during a regeneration cycle | Running |
| Entity | Type | Description |
|---|---|---|
| Immediate Proportional Regeneration | Button | Triggers an immediate partial regeneration |
| Full Regeneration Tonight | Button | Schedules a full regeneration for tonight |
| Salt Alarm Sound | Switch | Toggle the audible salt level alarm |
┌─────────────────────────────────┐
│ Gizwits Data Points │ ← 218 named data points with known byte offsets
├─────────────────────────────────┤
│ Proprietary Binary Protocol │ ← 38-byte header + 807-byte payload over BLE
├─────────────────────────────────┤
│ Bluetooth Low Energy (BLE) │ ← Service 0xABF0, characteristic 0xABF7
└─────────────────────────────────┘
| Item | Value |
|---|---|
| Service UUID | 0000ABF0-0000-1000-8000-00805F9B34FB |
| Characteristic UUID | 0000ABF7-... (single characteristic for read/write/notify) |
| Manufacturer ID | 0x1910 (Gizwits) |
| Device name pattern | XPG-GAgent-xxxx |
| Protocol | Proprietary binary dump (unencrypted) |
- Discovery — HA detects the device by service UUID (
0xABF0) or name (XPG-GAgent-xxxx) - Connect — Standard BLE GATT connection (no encryption or pairing needed)
- Subscribe — Enable notifications on characteristic
0xABF7 - Receive — Device sends a
0xFFFFhandshake, then a full data dump (~845 bytes) split across multiple 128-byte BLE packets approximately 8 seconds after connection - Poll — Periodic status updates (~42 bytes) arrive every ~7 seconds; full status re-requested every 60 seconds
The device sends its complete state as a raw binary dump:
- 38-byte header — device metadata
- 807-byte Gizwits payload — all 218 data points packed sequentially per the Gizwits product schema
Data point byte offsets were obtained from the official Gizwits API using the device's product key. Values are big-endian encoded.
This integration was built by reverse-engineering the WaterGenius Android APK (v1.0.27):
- APK analysis — Extracted the React Native JavaScript bundle to find data point names (
g_uiHardness,g_ucRegenStatus, etc.) and the Gizwits product key - BLE discovery — Identified the device as a Gizwits GAgent (
XPG-GAgent) using service UUID0xABF0and manufacturer ID0x1910 - Characteristic discovery — Found the device uses a single characteristic
0xABF7(not the standardABF1/ABF2split) - Protocol analysis — Determined the device sends raw binary dumps (not standard Gizwits serial framing)
- Schema mapping — Fetched the official 218-data-point product schema from the Gizwits API to get exact byte offsets and lengths
The integration includes the following hardening measures:
- Bounded BLE buffer — the packet reassembly buffer is capped at 2KB to prevent memory exhaustion from misbehaving or spoofed BLE devices
- Characteristic pinning — connects to the known WaterGenius characteristic UUID (
0xABF7) rather than accepting any writable/notifiable characteristic on the device - Minimal logging — sensor telemetry and raw BLE payloads are only logged at
debuglevel; no sensitive household data appears in default logs - MAC address validation — manual address entry validates hexadecimal format
- No cloud or network exposure — all communication is local BLE; no outbound connections, no authentication secrets stored
- Ensure the WaterGenius phone app is fully closed (it holds an exclusive BLE connection)
- Check that your HA host has a working Bluetooth adapter
- Move the HA host closer to the device (BLE range is ~10m)
- Use the manual MAC address entry option if the device doesn't appear in the list
- Some sensors (Valve State, Regenerating) only populate after a full data dump is received, which takes ~10 seconds after connection
- If sensors stay "Unknown", check HA logs for connection errors
- Try removing and re-adding the integration
- Only one BLE client can connect at a time — close the phone app
- Try power-cycling the WaterGenius device
- Check that no other Bluetooth integration is holding a connection
Add to your configuration.yaml:
logger:
default: warning
logs:
custom_components.watergenius: debugThis logs raw BLE packets and parsed data point values — useful for diagnosing connection or data issues.
- Control commands (regeneration buttons, salt alarm switch) are defined but the exact write protocol for this device's proprietary format has not yet been validated
- Concurrent access — the phone app and HA cannot connect simultaneously; close the app before HA connects
- BLE range — requires the HA host to be within ~10m of the water softener
This project is provided as-is for personal use. Not affiliated with or endorsed by WaterGenius or Gizwits.
- Data point schema from Gizwits IoT Platform
- Protocol analysis referenced Gizwits GAgent source
- Built for Home Assistant