geberit-aquaclean

Python bridge between a Geberit AquaClean smart toilet and your home automation system.

Port of Thomas Bingel's C# geberit-aquaclean library to Python.

Key enhancements over the original:

Non-blocking, on-demand BLE — connects only for the duration of each request, then releases the connection immediately. The original holds BLE permanently, causing the device to stop responding after a few days. On-demand mode eliminates this entirely.
ESPHome Bluetooth Proxy — use an ESP32 as a remote BLE-to-IP bridge, eliminating the need for local Bluetooth hardware; run the bridge anywhere on your network
Filter status & lifetime tracking — reads the ceramic honeycomb filter counter directly from the device: days until replacement, last reset date, total shower cycles. The original C# library has no filter status support.
Dryer spray intensity — exposes the dryer spray intensity setting (read and write), discovered through independent BLE protocol analysis. Not present in the original C# library.
MQTT — publishes device state in real time; accepts control and configuration commands
REST API + web UI — live dashboard, per-request queries, runtime configuration without restart
CLI — one-shot commands for scripting, diagnostics, and automation
Home Assistant (HACS) — native HA integration installable via HACS; no separate Linux machine or MQTT broker needed
Home Assistant (MQTT) — automatic entity creation via MQTT Discovery, no manual YAML required
openHAB — integrates via MQTT; subscribe to device topics and publish control commands
Voice control — trigger commands by voice via Home Assistant or openHAB (e.g. Amazon Alexa, Google Assistant, Apple Siri)

Web UI — live status, on-demand queries, runtime config

Home Assistant HACS integration — native entities, no MQTT broker needed

Features

BLE bridge — connects to the toilet over Bluetooth LE
MQTT — publishes device state and accepts control commands
REST API + web UI — live dashboard, on-demand queries, runtime config
CLI — one-shot commands for scripting and diagnostics
Home Assistant (HACS) — native integration; install via HACS, no MQTT broker or separate server required — see docs/hacs-integration.md
Home Assistant (MQTT) — automatic entity creation via MQTT Discovery — see homeassistant/SETUP_GUIDE.md
openHAB — integrates via MQTT; subscribe to device topics and publish control commands
Use cases — greet, play music, dismiss, time sessions, control lights, voice commands — see docs/use-cases.md

Quick start

Two installation paths:

Option A — Standalone bridge Option B — HACS integration

What you need Raspberry Pi / Linux server + MQTT broker Home Assistant + ESP32 proxy

Install curl | bash (see below) HACS custom repository

Config config.ini HA config flow (UI)

Use if You want MQTT, REST API, CLI, openHAB You only need Home Assistant entities

For Option B see docs/hacs-integration.md. The steps below cover Option A.

1. Install

Easy — no clone needed (Raspberry Pi / Linux server):

curl -fsSL https://raw.githubusercontent.com/jens62/geberit-aquaclean/main/operation_support/install.sh | bash -s -- latest

curl | bash executes code from the internet directly. Review the script first if preferred: curl -fsSL https://raw.githubusercontent.com/jens62/geberit-aquaclean/main/operation_support/install.sh

The script installs system packages and creates ~/venv if they don't exist yet, then installs the bridge and prints the next steps. Re-running it with a new version upgrades in-place.

If you already have the repo cloned:

bash operation_support/install.sh latest

Manual (replace <version> with a release tag — list available releases):

curl -fsSL https://api.github.com/repos/jens62/geberit-aquaclean/releases | grep '"tag_name"'

python3 -m venv ~/venv
~/venv/bin/pip install --upgrade pip setuptools wheel
~/venv/bin/pip install git+https://github.com/jens62/geberit-aquaclean.git@<version>

Upgrading an existing install (preserves your config.ini, stops/restarts the service automatically):

curl -fsSL https://raw.githubusercontent.com/jens62/geberit-aquaclean/main/operation_support/update.sh | bash

To upgrade to a specific version:

curl -fsSL https://raw.githubusercontent.com/jens62/geberit-aquaclean/main/operation_support/update.sh | bash -s -- v2.4.63

Or if you have the repo cloned:

bash operation_support/update.sh latest

Dependencies installed

Package	Purpose
bleak	BLE connectivity (BlueZ on Linux, CoreBluetooth on macOS)
aioesphomeapi	ESPHome Bluetooth proxy backend
paho-mqtt	MQTT broker client
aiorun	Asyncio run loop with clean shutdown handling
fastapi	REST API framework
uvicorn	ASGI server for FastAPI

2. Find the BLE address

bluetoothctl scan on
# Look for: [NEW] Device XX:XX:XX:XX:XX:XX Geberit AC PRO

3. Edit config.ini

Find the installed config file:

python3 -c "import os, aquaclean_console_app; print(os.path.join(os.path.dirname(aquaclean_console_app.__file__), 'config.ini'))"
# → /path/to/venv/lib/python3.x/site-packages/aquaclean_console_app/config.ini

Edit the key values:

[BLE]
device_id = XX:XX:XX:XX:XX:XX   # from step 2

[MQTT]
server = 192.168.0.xxx           # your MQTT broker IP

Full config reference: docs/configuration.md

4. Install as a background service (recommended for production)

Linux / systemd only:

curl -fsSL https://raw.githubusercontent.com/jens62/geberit-aquaclean/main/operation_support/setup-service.sh | bash

The script downloads the service and logrotate templates, substitutes your username and venv path automatically, and starts the service.

sudo systemctl status aquaclean-bridge
tail -f /var/log/aquaclean/aquaclean.log

5. Or run manually

Goal	Command
REST API + web UI + MQTT	`aquaclean-bridge --mode api`
Background service (MQTT only)	`aquaclean-bridge`
One-off CLI command	`aquaclean-bridge --mode cli --command <cmd>`

Documentation

Topic	File
HACS integration (Option B)	docs/hacs-integration.md
Use cases	docs/use-cases.md
On-demand BLE connection	docs/on-demand-ble.md
BLE coexistence (bridge vs Geberit Home app)	docs/ble-coexistence.md
Operating modes	docs/modes.md
Configuration reference	docs/configuration.md
REST API	docs/rest-api.md
Web UI	docs/webapp.md
CLI commands	docs/cli.md
MQTT topics	docs/mqtt.md
Home Assistant (MQTT)	docs/home-assistant.md
HA MQTT full setup guide	homeassistant/SETUP_GUIDE.md
ESPHome Bluetooth Proxy	docs/esphome.md
ESPHome troubleshooting	docs/esphome-troubleshooting.md
ESPHome developer notes	docs/esphome-developer-notes.md

Tested environments

Hardware	OS	Python
Raspberry Pi 5	Kali Linux (arm64)	3.13
Raspberry Pi 5	Kali Linux 2024.4 (arm64)	3.12.8
MacBookAir + VirtualBox	Ubuntu 24.04 (x86-64)	3.12.3
Debian server (arm64)	Debian 12 Bookworm	3.11.2

Device	Status	Firmware
Geberit AquaClean Mera Comfort	✅ Confirmed working	• RS28.0 TS199 • RS30.0 TS206 (@Kiana321, #12)
Geberit AquaClean Mera Classic	✅ Confirmed working via HACS integration (#28)	RS30.0 TS206
Geberit AquaClean Sela	✅ Confirmed working via HACS integration (@msperl, #27)	RS08.0 TS57
Geberit AquaClean Alba	✅ Supported via HACS integration (known limitation: remote control conflict #21)	RS03.0 TS89

Architecture

# Option A — Standalone bridge (MQTT, REST API, CLI)
AquaClean (BLE) ←→ ESP32 proxy ←→ [TCP] ←→ Raspberry Pi / server ←→ MQTT broker ←→ HA / openHAB
                [ESPHome proxy]  port 6053          ↕
                                              REST API / Web UI

# Option B — HACS native integration (Home Assistant only, no separate server)
AquaClean (BLE) ←→ ESP32 proxy ←→ [TCP] ←→ Home Assistant (HACS integration)
                [ESPHome proxy]  port 6053

Key improvements over the original C# port

The original Thomas Bingel library (and the initial Python port) keeps a permanent BLE connection to the device. In practice this causes the AquaClean to stop responding after a few days of continuous use — a known limitation of the device firmware.

This project introduces an on-demand BLE connection mode that eliminates the problem:

	Persistent (original)	On-demand (new)
BLE connection	Kept open permanently	Connected per request, then released
Long-term stability	Device stops responding after a few days	No long-term connection held — device stays healthy
Latency	Instant (always connected)	~1–2 s per request (connect + query + disconnect)
Use case	Continuous monitoring, service mode	REST API, scripting, integrations that poll occasionally

Beyond connection handling, this project also extends the protocol coverage of the original:

Feature	Original C#	This project
Filter status & lifetime	✗ not implemented	✓ days until replacement, last reset, shower cycle count
Dryer spray intensity	✗ not in original	✓ read + write, discovered via independent BLE analysis

On-demand mode is selected in config.ini:

[SERVICE]
ble_connection = on-demand

Or switched at runtime with no restart needed:

# via REST API
curl -X POST http://localhost:8080/config/ble-connection \
     -H "Content-Type: application/json" \
     -d '{"value": "on-demand"}'

# via MQTT
mosquitto_pub -h YOUR_BROKER \
  -t "Geberit/AquaClean/centralDevice/config/bleConnection" \
  -m "on-demand"

The web UI also has a one-click toggle button. See docs/modes.md for a full comparison.

References

Credits

Original C# library by Thomas Bingel.

Name		Name	Last commit message	Last commit date
Latest commit History 1,396 Commits
.agents/skills		.agents/skills
.claude		.claude
.github		.github
POLICIES		POLICIES
aquaclean_ble_relay		aquaclean_ble_relay
aquaclean_console_app		aquaclean_console_app
custom_components/geberit_aquaclean		custom_components/geberit_aquaclean
docs		docs
esphome		esphome
graphics		graphics
homeassistant		homeassistant
lovelace		lovelace
memory		memory
operation_support		operation_support
tests		tests
tools		tools
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
CLAUDE_BACKUP_2026-06-03_10-12.md		CLAUDE_BACKUP_2026-06-03_10-12.md
LICENSE		LICENSE
README.md		README.md
event.json		event.json
hacs.json		hacs.json
pyproject.toml		pyproject.toml

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

geberit-aquaclean

Features

Quick start

1. Install

2. Find the BLE address

3. Edit config.ini

4. Install as a background service (recommended for production)

5. Or run manually

Documentation

Tested environments

Architecture

Key improvements over the original C# port

References

Credits

About

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

	Option A — Standalone bridge	Option B — HACS integration
What you need	Raspberry Pi / Linux server + MQTT broker	Home Assistant + ESP32 proxy
Install	`curl \| bash` (see below)	HACS custom repository
Config	`config.ini`	HA config flow (UI)
Use if	You want MQTT, REST API, CLI, openHAB	You only need Home Assistant entities

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

geberit-aquaclean

Features

Quick start

1. Install

2. Find the BLE address

3. Edit config.ini

4. Install as a background service (recommended for production)

5. Or run manually

Documentation

Tested environments

Architecture

Key improvements over the original C# port

References

Credits

About

Topics

Resources

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages