Files

T

Hank MuellerandClaude Opus 5 8cda06f7f3 Add Hot Spring Connected Spa integration

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

2026-09-01 14:22:37 +00:00

2.9 KiB

Raw Blame History

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):

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

Copy custom_components/hotspring/ into your Home Assistant config/custom_components/.
Place the three PEM files in /config/hotspring/certs/.
Restart Home Assistant.
Settings → Devices & Services → Add Integration → “Hot Spring Connected Spa”, and sign in with your account.

How it works

POST iotsupportportalapi.watkinsmfg.com/api/v1/login/ → JWT.
GET /user_spa_details/ → the spa's rootTopic (MQTT prefix).
mTLS GET iotfirmwareota.watkinsmfg.com:8577/ (client cert) → rotating HiveMQ broker host/user/pass.
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.

2.9 KiB Raw Blame History