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

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.1
File Size Uploaded Provenance Actions
python_hotspring-4.0.1.tar.gz 29.3 kB With provenance Details for python_hotspring-4.0.1.tar.gz

Built distribution (wheel)

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

Total release size: 57.5 kB

Release files / python_hotspring-4.0.1.tar.gz

Download URL python_hotspring-4.0.1.tar.gz
Size 29.3 kB
Tags Source
SHA-256 checksum
How to use checksums
e427d5ac33a88a3d0c70fd4f42c9adf274c02be7800d446e537ecf0a2d056a05
BLAKE2b-256 checksum
How to use checksums
247d820b091f866170a2712adb810cab44e3421c125823f13caac419a96c03bc
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 Nov 4, 2026.

Transparency log

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

Download URL python_hotspring-4.0.1-py3-none-any.whl
Size 28.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
15f2f5ee77c68272becb3bc1cf44194616eb011d9a5fef8177dad763fd5e2ff4
BLAKE2b-256 checksum
How to use checksums
e71c9814b8d10ffe8ca7ffbb5c99c891bba7838d67c16a87d0901e71e4681001
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 Nov 4, 2026.

Transparency log

Security for python-hotspring 4.0.1

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.1.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 Nov 4, 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