Asynchronous Python client for Hot Spring Connected Spa Kit 2.
Warning
This library is currently in heavy development. Not all features might work perfectly, and some features may not be fully tested as they depend on the physical hardware available for testing.
The spa's energy consumption estimates (watts, power draw) are not accurate and are most likely incorrect, as the power calculation registers have not been fully reverse-engineered.
This package allows you to control and monitor a Hot Spring spa equipped with the Connected Spa Kit 2 programmatically via its local HTTP API. It communicates with the Home Network Adapter (HNA), which bridges your home network to the spa's control board over LoRA radio.
It is primarily designed to be used as the communication layer for an official Home Assistant integration.
- Temperature monitoring & control — Read current/target water temperature, set target temperature, change heating modes
- Jets & blower — Control jet speeds (off, low, high) across all jet pumps
- Multi-zone lighting — Set colors and brightness for up to 4 light zones plus the logo light
- Water care — Monitor FreshWater IQ salt system metrics (pH, chlorine, ORP, sensor life)
- Diagnostics & Test Metrics — Read raw hardware test point currents, line voltages, sensor flow/switch states, and failure diagnostics
- Runtime Tracking — Cumulative heater runtime and individual jet pump runtime in hours
- Connection monitoring — Check LoRA bridge and cloud connectivity status
- Energy saving schedules — View configured energy saving time windows
- Clean cycle — Start or stop the 10-minute clean cycle
This library works with any Hot Spring, Caldera, or Freeflow spa that supports the Connected Spa Kit 2 (compatible with spas from 2014 onwards that use the IQ2020/Eagle control board).
Note
This library has been primarily tested on a Hotspring Hot Spot Relay 2025. Compatibility with other specific models and configurations may vary.
pip install python-hotspringimport asyncio
from hotspring import HotSpring
async def main() -> None:
"""Show example of controlling your Hot Spring spa."""
async with HotSpring("192.168.1.100") as spa_client:
# Get full spa status
spa = await spa_client.update()
print(f"Water temperature: {spa.heater.current_temperature}°F")
print(f"Heater: {'on' if spa.heater.is_on else 'off'}")
print(f"Heating mode: {spa.heater.heating_mode.name}")
# Control the spa
await spa_client.set_temperature(102)
await spa_client.set_jet(1, "highSpeed")
await spa_client.set_light_color(1, "Blue")
await spa_client.set_clean_cycle(enabled=True)
if __name__ == "__main__":
asyncio.run(main())Several demonstration scripts are available in the demo/ directory to help you get started with the library and verify connectivity with your spa.
The Hot Spring Connected Spa Kit 2 uses a two-part system:
- HNA (Home Network Adapter) — Located inside the home, connects to WiFi/Internet and runs the local HTTP API that this library communicates with
- SNA (Spa Network Adapter) — Located inside the spa, wired to the IQ2020 control board via RS485, communicates with the HNA via LoRA radio
All API calls go through the HNA, which relays commands to the spa over LoRA. Commands typically take 2–5 seconds to process.
This repository keeps a change log using GitHub's releases functionality.
Releases are based on Semantic Versioning, and use the format
of MAJOR.MINOR.PATCH. In a nutshell, the version will be incremented
based on the following:
MAJOR: Incompatible or major changes.MINOR: Backwards-compatible new features and enhancements.PATCH: Backwards-compatible bugfixes and package updates.
This is an active open-source project. We are always open to people who want to use the code or contribute to it.
Thank you for being involved! 😍
This Python project is fully managed using the Poetry dependency manager.
You need at least:
- Python 3.12+
- Poetry
To install all packages, including all development requirements:
poetry installAs this repository uses the prek framework, all changes are linted and tested with each commit. You can run all checks and tests manually, using the following command:
poetry run prek run --all-filesTo run just the Python tests:
poetry run pytestThe original setup of this repository is by @Moustachauve.
The structure of this library is inspired by python-wled from @frenck and pytechnove from @Moustachauve.