112 lines
5.0 KiB
Markdown
112 lines
5.0 KiB
Markdown
# 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.
|
||
|
||
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).
|