# 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 `<rootTopic>/#` for telemetry; publish
   `<rootTopic>/<subsystem>/control` with `{"<subsystem>":{"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://<spa-ip>/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.

## License

MIT — see [LICENSE](LICENSE).