I wanted local status and control for a Balboa spa without routing my automations through a vendor cloud. This project adds a small ESP32 Wi‑Fi gateway that connects to the spa’s main Balboa control board on the existing RS485 bus—you do not need Balboa’s Wi‑Fi module for this gateway (local web UI, MQTT, and Home Assistant). The ESP is another peer on that bus, not a replacement for the main board.
On my tub, the spa control panel (topside) still works, and the official Balboa Spa Control app still works too alongside the gateway (I still have Balboa’s factory connectivity path; the ESP does not disable it). Your panel should behave the same way; app coexistence depends on how your tub was already set up—see caveat below.
Not affiliated with Balboa Water Group. “Balboa” and app names are used only to describe compatibility, not endorsement.
Firmware is open source (Apache 2.0), currently v2.10.0, maintained here: GitHub - shomanjk/esp32_balboa_spa: ESP32 Based Balboa Spa wifi controller module for M5stack Atom with Atomic RS485 Base · GitHub
What it does today
-
Home Assistant via MQTT auto-discovery — entities appear under device Balboa Spa (temperatures, climate/setpoint, pumps as switch or select depending on capability, lights, blower, mister, heating/spa state enums, etc.)
-
MQTT commands on
Spa/<gateway>/cmd/…with JSON outcomes onSpa/<gateway>/cmd/result(set temp, heat mode, temp range preset, temp units, panel clock, pump/light toggles) -
Built-in web UI — phone-friendly
/statusfor live data and v1 controls;/configfor equipment and controller identity;/statefor Wi‑Fi and RS485 health -
OTA for documented M5 tub-side builds (
M5AtomLite-tub-ota) -
Optional legacy TCP bridge on port 4257 for Homebridge users (
BRIDGEbuild flag)
Protocol semantics follow the community reference: ccutrer/balboa_worldwide_app protocol.md
Home Assistant setup (summary)
-
Flash the ESP32 and configure Wi‑Fi + MQTT in
config.h(copy fromconfig-example.h). -
Use the same MQTT broker as Home Assistant’s MQTT integration.
-
On connect, the gateway publishes retained discovery under
homeassistant/…— look for device Balboa Spa. -
Default discovery temperature unit is °F; for Celsius tubs set
MQTT_HA_TEMP_UNITinconfig.h. -
device.configuration_urlpoints athttp://<gatewayName>.local/status(mDNS); use a DHCP reservation if.localdoes not resolve on your LAN.
Disable discovery with #define MQTT_HA_DISCOVERY 0 if you only want manual MQTT entities.
MQTT command topics (v1)
| Topic | Payload examples |
|-------|------------------|
| Spa/<gateway>/cmd/setTemp | 102, 39.5 |
| Spa/<gateway>/cmd/mode | heat, off |
| Spa/<gateway>/cmd/preset | Low Range, High Range |
| Spa/<gateway>/cmd/tempUnits | F, C |
| Spa/<gateway>/cmd/setTime | HH:MM |
| Spa/<gateway>/cmd/syncTime | any non-empty |
| Spa/<gateway>/cmd/button/<code> | toggle, on, off; pumps: Off, Low, High |
Full list: README — MQTT and Home Assistant
What you need (honest scope)
This is moderate DIY, not a sealed product:
-
Balboa spa with RS485 access (ccutrer physical layer wiki)
-
2.4 GHz Wi‑Fi, USB for first flash, PlatformIO build
-
Documented tub stack: M5 Atom Lite + Atomic RS485 Base (~$30–50 parts) or generic ESP32 + RS485 module (default UART GPIO 16/17 in config example)
-
Time to confirm traffic and controls on
/statusbefore you trust automations
Getting started checklist: Getting started · shomanjk/esp32_balboa_spa Wiki · GitHub
M5 stack + harness (what I used on BP501)
On my Balboa BP501, the cleanest tap was a Molex 0451320403 4‑circuit plug (DigiKey WM16117-ND) on the factory header on the main control board—short harness to the Atomic RS485 base VH‑3.96 terminals (12 V, GND, A, B). You still need the correct crimp terminals for that housing and must verify pinout against ccutrer physical layer and your board label before power-on. More community notes: Hardware field notes.
Power (tub install): The Atomic RS485 Base includes 12 V → 5 V for the Atom. On my setup it runs from the spa board’s accessory 12 V—no separate wall wart in the cabinet (USB is still fine on the bench for flashing). 12 V/GND are not the RS485 A/B pair—wire power and bus separately. Generic ESP32 + MAX485 builds may still need their own 3.3 V/5 V supply plan.
Screenshots
-
/statuspage
-
equipment / controller identity
-
Home Assistant Balboa Spa device or dashboard
-
Cabinet photo of ESP32 + RS485 wiring
Official Balboa app vs this gateway
| This ESP32 gateway | Balboa Spa Control app (typical) | |
|---|---|---|
| Needs Balboa Wi‑Fi/cloud module? | No — RS485 tap + ESP only for local HA/MQTT/web | Often yes — usually via Balboa’s own connectivity hardware |
| Replaces main control board? | No | No |
If you already use the official app with Balboa’s module, many tubs can run both (panel + app + ESP as RS485 peers). If you never had Balboa Wi‑Fi hardware, this project is how you get local/Home Assistant control without buying theirs—not a substitute for their cloud account features you never had.
Lineage
Built on the ESP32 port of the NorthernMan54 Balboa gateway line; active development on the fork above. Not affiliated with Balboa Water Group or M5Stack.
Ask
If you have already tapped RS485 on a Balboa board (e.g. BP501 family), I am collecting connector / harness field notes in the wiki: Hardware field notes · shomanjk/esp32_balboa_spa Wiki · GitHub — please reply with board label, connector part number, and PlatformIO env if you try this.
Questions welcome. I am happy to share what worked on my setup and what still varies by tub.