Skip to main content

GitHub Release Python Versions Project Stage Project Maintenance License

Build Status Code Coverage

Asynchronous Python client for Hot Spring Connected Spa Kit 2.

About

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.

Supported Features

  • 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

Compatible Spas

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

Installation

pip install python-hotspring

Usage

import 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())

Demos

Several demonstration scripts are available in the demo/ directory to help you get started with the library and verify connectivity with your spa.

Architecture

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.

Changelog & Releases

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.

Contributing

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! 😍

Setting up development environment

This Python project is fully managed using the Poetry dependency manager.

You need at least:

To install all packages, including all development requirements:

poetry install

As 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-files

To run just the Python tests:

poetry run pytest

Authors & contributors

The original setup of this repository is by @Moustachauve.

The structure of this library is inspired by python-wled from @frenck and pytechnove from @Moustachauve.

Metadata

Release files for python-hotspring 4.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-hotspring 4.0.0
File Size Uploaded Provenance Actions
python_hotspring-4.0.0.tar.gz 28.9 kB With provenance Details for python_hotspring-4.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for python-hotspring 4.0.0
File Interpreter ABI Platform Actions
python_hotspring-4.0.0-py3-none-any.whl Python 3 none any Details for python_hotspring-4.0.0-py3-none-any.whl

Total release size: 56.6 kB

Release files / python_hotspring-4.0.0.tar.gz

Download URL python_hotspring-4.0.0.tar.gz
Size 28.9 kB
Tags Source
SHA-256 checksum
How to use checksums
bc1f60ff24173a80bd813aa1ed147a3a70c9f3637b31ca614757c158285733d6
BLAKE2b-256 checksum
How to use checksums
277469586e032c783e98cab9992ab2bda1b235090197a1bbdf5d491a1ff08c59
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / python_hotspring-4.0.0-py3-none-any.whl

Download URL python_hotspring-4.0.0-py3-none-any.whl
Size 27.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
904cfb8b21e840ab666e54e54769b305e1932b71b3e25ccca210bf3f0e59779b
BLAKE2b-256 checksum
How to use checksums
d035b4f57a4241da815af62779d8ff1260fce0445eaf172482d296a48a42297d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Security for python-hotspring 4.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for python_hotspring-4.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page