Skip to content

spa2mqtt

spa2mqtt connects the RS485 bus of a Balboa-family "encrypted" hot-tub controller to Home Assistant. RS485 is the two-wire serial bus that the tub's control board uses to talk to its topside panel. The Jacuzzi J235 is the first supported tub. Related Jacuzzi and Sundance boards use the same protocol family. The MQTT bridge also reads one unencrypted Jacuzzi, the J345, through its ProLink module.

You can run it in two ways. Both use the same tub definitions, so both give the same entities in Home Assistant.

MQTT bridge ESPHome component
Runs on Any Docker host (Python) An ESP32 with an RS485 transceiver
Connects to the tub through An RS485-to-TCP adapter such as the EW11A, or a USB RS485 adapter The ESP32's own UART
Talks to Home Assistant through An MQTT broker, with MQTT discovery The ESPHome native API
Install guide Docker Compose or Portainer ESPHome
spa2mqtt architecture The spa control board RS485 header connects either to an EW11A RS485-to-TCP adapter that feeds the spa2mqtt Docker container, which publishes to an MQTT broker read by Home Assistant, or to an ESP32 running the ESPHome spa_bus component, which talks to Home Assistant over the ESPHome native API. Spa control board RS485 header for a second topside panel EW11A RS485 to TCP, port 8899 spa2mqtt Python, Docker MQTT broker e.g. Mosquitto ESP32 + RS485 ESPHome, spa_bus Home Assistant same entities Option A: MQTT bridge Option B: ESPHome (no extra box) TCP MQTT ESPHome native API RS485 A/B

Mains voltage

A spa contains mains voltage and can deliver a large fault current. Isolate the spa at its breaker before you open any panel. Wiring anything into it is at your own risk. Read Safety before you start.

Receive-only by default

spa2mqtt never transmits to the tub unless you enable transmit. With transmit off, it only listens, so a wrong setting or a wrong tub definition cannot change the tub. Buttons and the temperature setpoint still appear in Home Assistant, but they show as unavailable. See Safety for what changes when you enable transmit.

Where to start

  1. Read Getting started. It helps you choose between the MQTT bridge and ESPHome, and it shows a read-only first run.
  2. Install with Docker Compose, Portainer or ESPHome.
  3. Look up settings in Configuration.

Supported tubs

Model Board Definition Status
Jacuzzi J235 (2018) Encrypted (C4/CC frames) jacuzzi_j235 Sensors confirmed against labelled captures. The transmit path is tested against a simulated board, not yet against the tub. See the J235 guide.
Jacuzzi J345 (J-300 series) Plain (0x16 frames) via the ProLink module jacuzzi_j345 MQTT bridge only. Decoded from the owner's captures; transmit reproduces captured pyjacuzzi frames; not yet run against the tub by this project. See the J345 guide.

To add your tub, see Monitor and capture and Tub definitions.

Credits

spa2mqtt builds on community reverse engineering: HyperActiveJ, dhmsjs/pyjacuzzi, garbled1/pybalboa, ccutrer/balboa_worldwide_app, jackbrown1993/Jacuzzi-RS485 and Iraithium/sundance-rs485-controller.