Hank MuellerandClaude Opus 5
8cda06f7f3
Unofficial cloud integration for Watkins/Hot Spring "Connected Spa" hot tubs. Reverse-engineered from the official Android app. - climate entity (setpoint + current water temp) via heater/control - sensors: water temperature, salt output level, salt cartridge - REST (JWT) login + spa discovery; mTLS fetch of rotating HiveMQ broker creds; MQTT subscribe (telemetry) / publish (control) - config flow prompts for account email + password (stored encrypted, never in repo) - no secrets committed: vendor mTLS client cert is loaded from host PEM files (see README); .gitignore blocks pem/p12/der/key/env Fixes bug-41mqxddz7zeh Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01F6B8b3iYNv6QUftK2FDfYb
71 lines
2.9 KiB
Markdown
71 lines
2.9 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** entity — target setpoint + current water temperature (heater).
|
|
- **Sensors** — water temperature, salt output level, salt cartridge state.
|
|
- Cloud-push: live telemetry over the vendor's HiveMQ Cloud MQTT broker.
|
|
|
|
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`) and has no Home Assistant dependency.
|
|
|
|
## License
|
|
|
|
MIT — see [LICENSE](LICENSE).
|