Local, cloud-free monitoring for PumpSpy and PitBoss+ sump pump battery backup systems, in Home Assistant.
No vendor account. No cloud dependency. No polling delay.
Supports PumpSpy monitors and the PitBoss+ system from Richtech Industries, which share the same underlying platform.
These monitors report their telemetry to a vendor cloud service over unencrypted HTTP. pumpspy-local reads that traffic on your own network, parses it, and turns it into Home Assistant entities.
The result is real-time, entirely local sensors — no account, no credentials sent anywhere, and nothing that stops working when the vendor's API does. That claim has been tested against real outages, and it has a limit; both are below.
The device's data is still forwarded upstream unchanged, so the vendor's own app and alerting keep working exactly as before. This is a read-and-relay tool: it adds a local view of data your device already broadcasts.
On 2026-08-20 the vendor's device API stopped answering for hours. Their website stayed up; the port accepted connections and then never replied. The phone app went with it — and this is the part worth writing down, because it is the whole argument in one image: the app showed a green check mark and a confident-looking "last signal update" timestamp, five days stale, presented as current. A cloud service that fails this way does not announce that it has failed. It shows you old data with a reassuring tick beside it.
Home Assistant recorded battery voltage, Wi-Fi signal and the rest normally throughout, because parsing the device's traffic does not depend on the forward to the vendor succeeding.
That is the claim. The limit has to be stated in the same breath, because the device itself is not indifferent to the vendor. After roughly nine minutes of undelivered reports it concludes its token is stale, stops sending telemetry to anyone, and retries POST /oauth/token every eleven seconds until something answers. Nothing here is broken at that point — the device has simply stopped talking. Measured on the reference install during one 34-minute outage: it did this twice, and was silent to everyone for about fourteen of those thirty-four minutes.
So pumpspy-local answers that token request itself, once it can see the vendor is unreachable. The device gets a token in about two milliseconds and resumes its full reporting set within fifteen seconds, and local monitoring carries on for as long as the outage does. Recovery needs no mechanism: when the vendor returns it rejects the locally issued token, and a rejection is an answer rather than a silence, so the integration stops issuing them and the device re-authenticates for real.
Where this stops. A token is only issued once the vendor is judged unreachable — not answering at all. An outage where the vendor answers, with errors, counts as reached and mints nothing, so the device goes quiet as before. That gate is deliberate: it is the same rule that keeps a genuinely revoked account from being papered over, and a real credential problem has to stay visible. It is not hypothetical either — just after midnight UTC on 2026-08-21 the vendor's authentication tier returned 401s, and everything else 500s, rather than failing outright.
Other Home Assistant integrations for these pumps authenticate to the vendor's cloud API with your account and poll it every few minutes. This project doesn't talk to the vendor's API at all, and never handles your credentials. Readings arrive as the device reports them.
- Your network sends the device's reporting traffic to the machine running
pumpspy-localinstead of to the vendor — a redirect on your router, or a DNS rewrite if your device will re-resolve. The setup guide covers both, and why the redirect is usually the one that actually works. pumpspy-localreceives the device's HTTP telemetry and:- creates Home Assistant entities from it automatically, and
- forwards the original requests upstream to the vendor, unmodified.
Nothing is installed on the device. Its firmware is never modified.
Once the device's traffic goes through Home Assistant, the vendor's own alerting depends on Home Assistant being up — it did not before. The device does not buffer: it retries three times, then drops the event for good.
If you rely on those cloud alerts as a flood safety net, run the fail-open shim as well. It is a small nginx config that tries Home Assistant first and falls back to the vendor automatically. On the reference install it took the cost of a Home Assistant restart from more than seven minutes of lost vendor delivery down to zero.
- Battery voltage — resting, and under load (the reading that actually reveals a failing battery)
- Mains power — lost / restored
- High water alarm
- Pump failure alarm
- Pump cycles — per run: which pump, duration, motor current, estimated gallons
- Wi-Fi signal strength
- Entities appear automatically — no MQTT broker, no YAML
- Real-time updates, as the device reports
- Firmware update capture and hold-for-approval — new firmware can be quarantined for your review instead of installing silently (opt-in, off by default)
- Installs through HACS, and works on Home Assistant OS, Supervised, Container, and Core
- An optional dashboard built for the one question that matters at 2 a.m. — is the pit being kept dry, and will the backup work if it is needed
- In HACS, open the three-dot menu and choose Custom repositories.
- Add
https://github.com/matuszeg/pumpspy-local, with category Integration. - Find pumpspy-local in the HACS list, install it, and restart Home Assistant.
- Go to Settings → Devices & services → Add integration and search for pumpspy-local.
Copy custom_components/pumpspy_local/ into your Home Assistant configuration
directory, under custom_components/, and restart. Then add it from Settings →
Devices & services as above.
Installing it is the easy half. The integration sits there doing nothing until the device's traffic actually reaches it, and that part depends on your network — see the setup guide, which walks through the options and how to tell whether it worked.
- HACS for installation, or copy the integration in by hand
- A way to make the device's traffic reach Home Assistant: a router that can redirect it, or DNS you control and a device that will re-resolve. This is the one requirement that depends on your network — see the setup guide
Working, and running against real hardware. The protocol was decoded from packet captures rather than guessed at, and the integration, firmware quarantine, the dashboard and the fail-open shim are all in daily use on a real pump. Expect rough edges in setup rather than in operation: getting the device's traffic to Home Assistant is the part that varies most between networks.
This project is not affiliated with, endorsed by, or sponsored by PumpSpy, Richtech Industries, or any related company. "PumpSpy", "PitBoss", and "PitBoss+" are trademarks of their respective owners, used here only to identify the hardware this software is compatible with.
This software observes and relays data that your own device transmits on your own network. It is provided for interoperability and personal use, without warranty of any kind. You are responsible for how you use it.