# Hot Spring Connected Spa — Home Assistant integration Monitor and control a **Watkins / Hot Spring "Connected Spa"** hot tub from Home Assistant, without the vendor mobile app. - **Climate** — target setpoint + current water temperature (heater). - **Number** — FreshWater salt output level (0–10), settable. - **Switches** — spa lights (all zones) and jets. - **Sensors** — water temperature, salt cartridge state. - Live telemetry over the vendor's HiveMQ Cloud MQTT broker, or — optionally — polled from the spa's local `/status` endpoint (see below). Requests are sent with the same User-Agents and MQTT client-id format the official app uses, so the traffic is indistinguishable from it. This is an **unofficial** integration reverse-engineered from the official app. It talks to Watkins' cloud; there is **no local control path**. If Watkins changes their API it may break. ## Security / credentials This repository contains **no secrets**: - Your **account e-mail + password** are entered in the config-flow UI when you add the integration and stored in Home Assistant's encrypted config entry — never in this repo. - The vendor **mutual-TLS client certificate** required to fetch broker credentials is Watkins material (extractable from the app APK). It is **not redistributed here**. You provide it as three PEM files on the host (below). ## Prerequisites: the client certificate The integration needs three files in a directory on the Home Assistant host (default `/config/hotspring/certs/`): | File | Origin | |---|---| | `client1_cert.pem` | client cert from the app APK (`res/raw/client1.p12`) | | `client1_key.pem` | its private key | | `ca_cert.pem` | firmware CA (`res/raw/ca_cert.der`) | To produce them from the APK's `client1.p12` and `ca_cert.der` (the P12 is protected by a short static password embedded in the app — recover it from the decompiled APK and pass it to `openssl` below): ```sh P12PASS=... # static password embedded in the app APK openssl pkcs12 -legacy -in client1.p12 -passin pass:"$P12PASS" -clcerts -nokeys -out client1_cert.pem openssl pkcs12 -legacy -in client1.p12 -passin pass:"$P12PASS" -nocerts -nodes -out client1_key.pem openssl x509 -inform der -in ca_cert.der -out ca_cert.pem ``` ## Install 1. Copy `custom_components/hotspring/` into your Home Assistant `config/custom_components/`. 2. Place the three PEM files in `/config/hotspring/certs/`. 3. Restart Home Assistant. 4. **Settings → Devices & Services → Add Integration → “Hot Spring Connected Spa”**, and sign in with your account. ## How it works 1. `POST iotsupportportalapi.watkinsmfg.com/api/v1/login/` → JWT. 2. `GET /user_spa_details/` → the spa's `rootTopic` (MQTT prefix). 3. mTLS `GET iotfirmwareota.watkinsmfg.com:8577/` (client cert) → rotating HiveMQ broker host/user/pass. 4. Subscribe `/#` for telemetry; publish `//control` with `{"":{"control":{…}}}` for commands (temperature is an integer string in the spa's unit). The reusable protocol client lives under `custom_components/hotspring/api/` (`cloud.py`, `spa.py`, `protocol.py`); all constant values are in `constants.py`. ## Optional: local read path If Home Assistant is on the spa's LAN, set **Local `/status` URL** in the config flow (e.g. `http:///status`). Telemetry is then polled from the dongle's local HTTP endpoint instead of subscribed over the cloud broker, keeping monitoring on-LAN and off the vendor cloud. Control still uses the cloud MQTT connection. Leave it blank to use cloud MQTT for reads. The module has no DNS name and takes its address from DHCP. While the URL does not answer, telemetry is read from the cloud instead, and the local poll takes over again when it answers. To change the URL without signing in again, use **Reconfigure** on the integration entry. A Connected Spa kit can have two modules on the LAN that both serve `/status`. Only the one linked to the control box returns the spa's state; the other returns the blank document described below. Use the one with temperatures in it. ## Health and availability Every entity is **unavailable** unless telemetry arrived in the last five minutes and carries control-box data. A module that is online but cut off from the control box keeps serving, and publishing to the cloud, a full document of blank and default values: empty `setWaterTemperature`, `currentWaterTemperature` and `ControlBoxFirmwareVersion`, salt level 0, lights and jets off. Commands sent in that state change nothing. Power-cycling the module that is linked to the control box has recovered it; the entities come back on their own once real data arrives. The broker is the only control path and its credentials rotate. If the broker connection stays down for three minutes the integration reloads itself, which signs in again and fetches current credentials. To be told when the spa stops reporting, trigger an automation on an entity (for example the climate entity) being `unavailable` for a few minutes. ## License MIT — see [LICENSE](LICENSE).