What is BathButler?

BathButler is a smart bath filling controller that takes the guesswork out of running a bath. Set your desired temperature and water depth using the CrowPanel 1.28" rotary display — the system automatically controls hot and cold water valves to reach your target, then shuts off when done. No more burnt fingers testing the water, no more overflowing baths.

Hardware Architecture

BathButler uses a clean two-board design connected by a single 4-wire cable:

• Controller (Waveshare ESP32-S3-Relay-6CH) — The brain. Mounted near the plumbing, it drives the hot/cold solenoid valves via relays, reads the DS18B20 water temperature sensor, runs the safety logic (overheat cutoff, watchdog timer, valve protection), hosts the web dashboard, and handles Alexa voice control.
• Display (CrowPanel 1.28" HMI ESP32 Rotary Display) — The face. Wall-mounted in the bathroom, it shows a beautiful circular UI with live temperature, fill progress, and relay status. The rotary knob provides tactile control: twist to adjust, click to confirm. Five RGB LEDs provide at-a-glance status (green = filling, red = alert).

The two boards communicate over UART (115200 baud, JSON protocol) through a standard RJ45 Ethernet cable for easy installation and reliable long-distance connection.

The CrowPanel 1.28" Rotary Display

The CrowPanel is the star of the user experience. Its round form factor is perfect for a bath controller — it looks like a premium smart thermostat mounted on the wall. The interaction flow is simple and intuitive:

1. Twist the knob to set your target temperature (20–45°C)
2. Click to confirm, then twist to set water depth
3. Click to review your settings, click again to start filling
4. Watch live progress: current temperature, elapsed time, valve states
5. Bath ready! Three beeps and a solid green LED ring

The display automatically follows the controller state — if someone starts a fill from the web UI or Alexa, the display jumps to the live filling screen. If an overheat condition is detected, a pulsing red alert overrides everything. If the UART cable is disconnected, "NO SIGNAL" appears within 2 seconds.

Web Dashboard

The controller hosts a responsive circular web dashboard accessible from any device on the same WiFi network at http://bathbutler.local. It features:

• Live temperature with colour-coded display (blue = cold, green = in range, orange = hot)
• Fill progress ring with elapsed timer
• Start/Stop buttons
• Settings modal (temperature, tolerance, depth, fill time, valve protection timing)
• Flow rate calibration wizard
• WebSocket connection for real-time updates (no page refresh)

Key Features

• Safety first: Overheat cutoff (42°C default), hardware watchdog, relay minimum toggle time to protect solenoid valves, all relays off before any initialisation
• Multiple control methods: CrowPanel rotary knob, web dashboard, Amazon Alexa voice ("Alexa, turn on Bath Butler")
• Smart WiFi setup: Custom captive portal — connect to "BathButler" AP, setup page auto-opens on your phone, pick your network, done. Credentials saved to NVS.
• OTA updates: Flash new firmware over WiFi from PlatformIO — no USB cable needed after initial setup
• mDNS: Access at bathbutler.local — no need to remember IP addresses
• Flow rate calibration: Run each valve for a set duration, measure water depth, and the system calculates flow rates for accurate depth estimation — no level sensor required
• Configurable alerts: Buzzer sounds can be toggled on/off via API (overheat alarm always sounds for safety)
• RGB status LED: WS2812 on the controller shows state at a glance — green breathing (filling), red flashing (overheat), cyan (calibrating), purple (AP mode)
• Shared REST API: All interfaces consume the same versioned API (/api/v1/), making it easy to add new clients

Software Architecture

The firmware is modular, with each concern in its own header file:

• settings.h — NVS persistent settings with validation
• sensors.h — Async non-blocking DS18B20 temperature reading
• relays.h — Valve control with minimum toggle protection
• safety.h — Fill state machine, overheat detection, watchdog
• calibration.h — Flow rate measurement and depth estimation
• api.h — REST API v1 with CORS support
• websocket.h — Live push updates at 500ms intervals
• uart_protocol.h — JSON communication with the CrowPanel
• web_ui.h — Circular SPA dashboard served from PROGMEM
• wifi_setup.h — Custom WiFi manager with captive portal
• ota.h — Over-the-air firmware updates

Bill of Materials

• Waveshare ESP32-S3-Relay-6CH (~$25)
• CrowPanel 1.28" HMI ESP32 Rotary Display ($29)
• DS18B20 waterproof temperature sensor (~$3)
• 2x 12V/24V solenoid valves for hot/cold water
• RJ45 ethernet cable (any length)
• 3D printed enclosures (STL files included)
• 12V power supply