Balboa Spa smart home integration, free and open source
Balboa spas with a BWA Wi-Fi module, locally: temperature, setpoint, pumps, lights, filtration.
Published by LM1LC3N7
- Devices
- Version 0.1.1
- Requires Gladys >=5.1.0
- ★ 0
Shows your Balboa spa in Gladys over your local network, through the BWA Wi-Fi module (the one of the Balboa Worldwide App), without any cloud: water temperature, setpoint, heat mode, pumps, blowers, lights, filter cycles and circulation pump.
Never tested with a real spa. The local protocol is not documented by Balboa: this integration follows what pybalboa (the library of Home Assistant's Balboa integration) does. Not affiliated with Balboa Water Group.
Before you start
- A Balboa controller (BP, GS, EL series…) with a BWA Wi-Fi module (BWG), connected to your Wi-Fi.
- The IP address of the module: look for it in your router (often named
BWGSpa) and give it a fixed address (DHCP reservation). - The module talks on TCP port 4257, without a password: keep it on a trusted network (no port forwarding from the internet).
- The module accepts few connections at once: if Gladys cannot connect, close the Balboa app on the local network, and do not run Home Assistant's Balboa integration on the same spa at the same time.
Setup
- Install the integration from the store.
- In its configuration, enter the IP address of the Wi-Fi module
(for example
192.168.1.80; another port can be added as192.168.1.80:4257), then save. - "Test the connection" shows the state: "Connected: Balboa BP501G1."
- In the Discovery tab, add the spa.
What you get
| Feature | Type | Notes |
|---|---|---|
| Water temperature | temperature (°C) | Sent at most every 10 to 15 s |
| Setpoint | thermostat (°C) | Command, see "Heating" |
| Heating | read only, 0/1 | 1 while the heater runs |
| Heat mode | list: Ready / Rest | Command, see "Heating" |
| Spa status | text | State, heat mode, heating, Wi-Fi notes |
| Temperature range | text | Low / High (read only) |
| Filter cycles 1 and 2 | read only, 0/1 | 1 while running |
| Circulation pump | read only, 0/1 | When the spa has one |
| Pumps 1 to 8 | list: Off / Low / High (or Off / On) | Pumps 1–6 commandable, 7–8 read only |
| Blowers | list | Commandable |
| Lights | light on/off | Commandable |
| Auxiliaries, misters | read only, 0/1 | When the spa has them |
A spa set to °F is shown in °C. The features follow the device configuration the spa reports; a feature never disappears from a device already created.
Heating
Off by default: turn on "Allow the heating commands" to let Gladys change the setpoint and put the heat mode on "Ready".
- Setpoint ceiling: Gladys never sets the spa above it. 38 °C by default, configurable from 30 to 40 °C, never above 40 °C (the limit of spa standards), whatever is typed. Steps of 0.5 °C; the spa must accept the value in its current range (low range: 10–37 °C, high range: 26.5–40 °C by default).
- "Rest" (heats during filtration only) is never refused by an option: it lowers the heating.
- "Ready" keeps the setpoint set on the spa: it is refused when that setpoint (perhaps set at the panel) is above the ceiling.
- The temperature range (low/high) is read only.
Pumps and blowers
Off by default: turn on "Allow the pumps" to start the jets. "Off" is never refused by an option, and cancels a command still running that is not a stop. It can still be refused when the spa state is unknown, when a previous press has not shown yet, or when there is no time left to send it. They are lists, never on/off switches: a "turn everything off" of a voice assistant or a scene cannot reach them. Several stops at once (a scene turning everything off) run side by side.
The spa only knows "next speed" presses: Gladys sends one press at a time and waits for the spa to show it before the next one (Low → High → Off for a two-speed pump).
When the spa has both a circulation pump and blower 1, the state of blower 1 is unknown (the protocol, as known, reads them from the same bit): it is not shown and not commanded until a real spa confirms how to read it.
Lights
On and off by default. Turn off "Allow turning the lights on" to only let Gladys turn them off.
How commands behave
- Each command waits for a status the spa sends after your click (the spa sends one about every second): nothing is decided on an old state, and a frame is not sent if a newer state arrived since the decision.
- The options and the ceiling are checked again right before each frame leaves.
- A frame is sent within 3.5 s of the click or not at all. If the spa does not show the change (in a state sent after the frame) by 4.3 s, the answer is "Command sent, without confirmation": check the spa a few seconds later. Gladys never sends another press on an unknown outcome (for 20 s, until the spa shows it): a new command is refused meanwhile, a stop waits for it.
- One command at a time, stops aside.
Troubleshooting
- "No connection to the spa": check the IP address, that the module is on your network, and that no other app keeps it busy. Gladys tries again after 10 s, 30 s, 1, 2, then every 5 minutes.
- "Connected to the Wi-Fi module, waiting for the spa…": the module answers but the spa sends nothing yet (spa starting, or the module lost the spa).
- The status shows "the spa does not answer the module": the module reports that it cannot talk to the spa controller.
Privacy
Everything stays on your local network. No account, no cloud, no password. The MAC address of the module is the identifier of the device in Gladys; it is never written in the logs.
Configuration settings
These are the settings Balboa Spa asks for in its configuration screen in Gladys.
| Setting | Type | Required | Description |
|---|---|---|---|
| Your spa | section | No | Shows your Balboa spa (BP, GS, EL controllers with a BWA Wi-Fi module, as used by the Balboa Worldwide App) in Gladys over your local network, without any cloud: water temperature, setpoint, heat mode, pumps, blowers, lights and filter cycles. Enter the IP address of the Wi-Fi module (give it a fixed address in your router), save, then add the spa from the Discovery tab. The module accepts few connections at once: close the Balboa app on the local network if Gladys cannot connect. The local protocol is not documented by Balboa and has no password: keep the module on a trusted network. Never tested with a real spa. Not affiliated with Balboa Water Group. |
| IP address of the Wi-Fi module | string | Yes | An IPv4 address or a host name (port 4257 unless you add one, for example 192.168.1.80:4257). |
| Allow the heating commands | boolean | No | Off by default. On: Gladys may change the setpoint (up to the ceiling below) and put the heat mode on "Ready". Off: these commands are refused. "Rest" (heats during filtration only) is always allowed. |
| Setpoint ceiling (°C) | number | No | Gladys never sets the spa above this temperature. 38 °C by default, from 30 to 40 °C (never more than 40 °C, the limit of spa standards, whatever is typed). |
| Allow the pumps | boolean | No | Off by default. On: Gladys may start the pumps and blowers (jets). Off: only "Off" is accepted. |
| Allow turning the lights on | boolean | No | On by default. Off: Gladys may only turn the spa lights off. |
| Language of the feature names | select | No | Used for the names of the device and features added from now on, for the state texts and for the command errors. |
How to install Balboa Spa in Gladys
- In Gladys, open Integrations: Balboa Spa appears in the catalog, next to the native integrations, with a community badge.
- Click Install. Gladys pulls the Docker image (
ghcr.io/lm1lc3n7/gladys-balboa:0.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration). - Open the Configuration screen of the integration, fill in the settings, and save.
- You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-balboa.
Balboa Spa requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.
Not running Gladys yet? It is free and open source: follow the installation guide to get started.
About external integrations
Balboa Spa is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.
- Browse all integrations, native and community
- Build and publish your own external integration
- Source code on GitHub — source of this documentation