Powered by Smartsupp
WellSenseOS

Home Assistant integration for WellSenseOS

Bring well and tank levels into Home Assistant as native sensors — percent full, volume, water level, and distance — using a read-only API key from the WellSenseOS portal.

Written by WellSenseOS Engineering Team · Published 2026-08-17 · 8 min read

Why Home Assistant

If you already run Home Assistant for lighting, HVAC, or energy, water storage belongs there too. Dashboards, automations (“notify when the cistern is below 20%”), and history graphs can use the same sensors as the rest of the house or farm — without replacing the WellSenseOS cloud dashboard.

WellSenseOS remains the source of truth: the Raspberry Pi agent still posts ultrasonic readings to the cloud; Home Assistant polls the latest snapshot. You do not need MQTT or a second sensor on the tank.

How it works

  1. The Pi (or other edge agent) sends distance readings to WellSenseOS over HTTPS.
  2. The platform converts distance to water level, litres, and percent full.
  3. You create a read-only API key in the portal (Settings → Integrations).
  4. The WellSenseOS custom integration in Home Assistant calls GET /api/v1/ha/wells on a timer (default 60 seconds) and updates sensors.

Create an API key

  1. Sign in to the WellSenseOS portal (create an account with the free trial if you do not have one yet).
  2. Open Settings → Integrations.
  3. Click Create API key, name it (for example “Home Assistant”), and copy the wsk_… secret once.

Store the key in Home Assistant only. Treat it like a password — anyone with the key can read your well list and latest levels.

Install the integration

The integration is a custom component (not yet in official Home Assistant Core). Copy it from the WellSenseOS repository: 

integrations/homeassistant/custom_components/wellsenseos/

into your Home Assistant config:

config/custom_components/wellsenseos/

Restart Home Assistant. You can also add the WellSenseOS git repository as a HACS custom repository of type Integration and install WellSenseOS.

Configure in Home Assistant

Go to Settings → Devices & services → Add integration → WellSenseOS.

  • API base URL — the WellSenseOS API host (the same base URL the Pi agent uses), for example https://api.wellsenseos.com. Do not add a path suffix.
  • API key — the wsk_… value from the portal.
  • Poll interval — 60 seconds is a good default (allowed range 30–300).

Sensors you get

Each well or tank becomes a Home Assistant device with four sensors:

  • Percent full (%)
  • Volume (litres)
  • Water level (cm, m, or in — your well’s preferred unit)
  • Sensor-to-water distance (same unit)

Attributes include well_id and measured_at. Use percent full or volume in automations — for example notify on Telegram when percent full drops below a threshold, or turn on a pump helper when level is low.

Limits and notes

  • v1 is cloud polling only — no MQTT Discovery and no write-back (you cannot change Pi interval from HA).
  • Wells created after you add the integration: reload WellSenseOS (or restart HA) so new sensors appear.
  • Display spike filtering in the portal also applies to HA snapshots when that filter is enabled.
  • For the full dashboard (history charts, Event Hub, billing), keep using the WellSenseOS portal.