Raspi-Sump v2

What is Raspi-Sump?

Raspi-Sump is a sump pit water level monitoring system that uses a Raspberry Pi and an HC-SR04 or JSN-SR04T ultrasonic sensor. It monitors the water level in your sump pit and alerts you when water rises above a threshold. It is an early warning system for sump pump failures.

The project is freely available and open source. Version 2 is a full rewrite with a modern web interface, APT package installation, SQLite database, and support for all Raspberry Pi models including the Pi 5, running Raspberry Pi OS Bookworm or Trixie.

What’s New in Version 2

Web Interface

Full browser-based UI served by Flask and nginx. View real-time water levels, historical charts, configure the system, and control services, all from your local network.

APT Package Install

Install and update via a standard Debian package from the Linuxnorth APT repository. No virtualenv, no pip, just apt install raspisump.

SQLite Database

Readings stored in a proper database. Query by date, time range, or last N readings using the rsumplog command-line tool.

Client-Side Charts

Fast interactive charts powered by uPlot, rendered entirely in the browser. No server-side chart generation or matplotlib required.

Pump Cycle Detection

Experimental feature that detects and counts pump cycles throughout the day. Useful for monitoring pump health and activity over time.

Raspberry Pi 5 Support

Full support for the Raspberry Pi 5 via the lgpio library. All Raspberry Pi models are supported.

Trixie Support

Tested on Raspberry Pi OS 13 (Trixie) in addition to Bookworm. Raspi-Sump 2 is packaged for the modern Debian ecosystem.

Mastodon Alerts

Receive direct message alerts via Mastodon in addition to email. Stay notified from anywhere on the Fediverse.

Secure by Default

Self-signed TLS certificate, dedicated system user, nginx reverse proxy, and sudoers-controlled service management out of the box.

Web Interface

The Raspi-Sump v2 web interface runs locally on your Raspberry Pi and is accessible from any browser on your network. It provides real-time water level readings, historical charts, system status, and a full admin panel.

Raspi-Sump v2 web interface showing real-time water level readings and historical chart.

Supported Platforms

Operating System

Recommended Raspberry Pi OS 13 (Trixie)
Supported Raspberry Pi OS 12 (Bookworm)

Hardware

Recommended Raspberry Pi 2 and greater
Supported Raspberry Pi B

Sensors

Supported HC-SR04 ultrasonic sensor
Supported JSN-SR04T 2.0 waterproof ultrasonic sensor
Not Supported JSN-SR04T 3.0

Features

APT package installation, no virtualenv required
Configurable monitoring interval
Error handling for fringe sensor readings
SQLite database with rsumplog CLI query tool
Email (SMTP), Mastodon DM, and SMS alerts
High water and low water level alerts
Alert rate limiting to prevent notification spam
Heartbeat alerts to verify the alert system is working
On-demand alert testing via alerttest command
Metric (cm) and imperial (inches) measurement support
Interactive water level charts via uPlot (browser-rendered)
Historical data browsing by date or date range
Pump cycle detection (experimental)
Web interface with admin panel and service management
Automatic service monitoring and restart via systemd
Configuration via web interface or config file
Nginx reverse proxy with HTTPS
Discord community support

Installation

Raspi-Sump v2 is installed from the Linuxnorth APT repository. Full step-by-step instructions are in the documentation.

Quick start

curl -fsSL https://apt.linuxnorth.org/linuxnorth.gpg | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/linuxnorth.gpg
echo "deb https://apt.linuxnorth.org unstable main" | sudo tee /etc/apt/sources.list.d/linuxnorth.list
sudo apt update && sudo apt install raspisump

Full installation instructions ›

Hardware Setup

Pin Wiring — HC-SR04 to Raspberry Pi

Connect four wires from the HC-SR04 sensor to the Raspberry Pi GPIO header:

VCC → 5V
Ground → Ground
Trig → GPIO 17 (configurable)
Echo → GPIO 27 via voltage divider (configurable)

Any available GPIO pins can be used for Trig and Echo. Identify your pins in raspisump.conf.

HC-SR04 wiring diagram to Raspberry Pi GPIO header.

Voltage Divider

A voltage divider is required on the Echo wire. The sensor outputs 5V but the Pi GPIO pin is rated for 3.3V. Use a 470 Ω and a 1K Ω resistor (1K between Echo and Ground). This brings the voltage to approximately 3.4V, within safe limits.

Voltage divider using a 470 Ω and 1K Ω resistor. The orange wire is Echo; yellow goes to Ground on the Pi. Thanks to GitHub user @rhiller for this photo. Check out his related project pi-distance on GitHub.

Sensor Options

The HC-SR04 sensor mounted to a plastic bracket on wood strapping. A JSN-SR04T waterproof sensor can also be used in wetter environments.

HC-SR04 (left and centre) and JSN-SR04T waterproof sensor (right, contributed by GitHub user rfeng74).

Sump Pit Installation

Open sump pit with sensor and wiring in place.

Email Alert Example

SMS email alert triggered when water level exceeds the configured threshold.

Community & Support

Documentation

Installation, configuration, the web interface, alerts, and the CLI are all covered in the official documentation.

Read the Docs

Discord

Join the Raspi-Sump Discord server. A good place to get support, share your setup, and discuss ideas. You will need a Discord account.

Request an Invite

Issue Tracker

Found a bug or have a feature request? Open a ticket on GitHub. A GitHub account is required.

Open an Issue

Source Code

Raspi-Sump is open source under the Apache 2.0 License. Contributions and forks are welcome.

GitHub Repository

Background

Raspi-Sump started in 2014 as a simple Python script to monitor a basement sump pit. Al Audet wrote about it in the October 2014 Embedded Issue of Linux Journal. Version 2 is a complete rewrite, modernized for the current Raspberry Pi OS ecosystem with a proper web interface and APT packaging.