Files
hotspring/README.md
T

112 lines
5.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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).