python-hotspring 1.0.0__tar.gz

python_hotspring-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Christophe Gagnier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python_hotspring-1.0.0/PKG-INFO

@@ -0,0 +1,208 @@
+Metadata-Version: 2.4
+Name: python-hotspring
+Version: 1.0.0
+Summary: Asynchronous Python client for Hot Spring Connected Spa Kit 2.
+License: MIT
+License-File: LICENSE
+Keywords: hotspring,spa,hot-tub,home-assistant,iq2020
+Author: Christophe Gagnier
+Author-email: christopheextensions@gmail.com
+Maintainer: Christophe Gagnier
+Maintainer-email: christopheextensions@gmail.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: aiohttp (>=3.0.0)
+Requires-Dist: awesomeversion (>=22.1.0)
+Requires-Dist: backoff (>=2.2.0)
+Requires-Dist: yarl (>=1.6.0)
+Project-URL: Bug Tracker, https://github.com/Moustachauve/python-hotspring/issues
+Project-URL: Changelog, https://github.com/Moustachauve/python-hotspring/releases
+Project-URL: Documentation, https://github.com/Moustachauve/python-hotspring
+Project-URL: Homepage, https://github.com/Moustachauve/python-hotspring
+Project-URL: Repository, https://github.com/Moustachauve/python-hotspring
+Description-Content-Type: text/markdown
+
+[![GitHub Release][releases-shield]][releases]
+[![Python Versions][python-versions-shield]][pypi]
+![Project Stage][project-stage-shield]
+![Project Maintenance][maintenance-shield]
+[![License][license-shield]](LICENSE)
+
+[![Build Status][build-shield]][build]
+[![Code Coverage][codecov-shield]][codecov]
+
+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.
+
+## About
+
+This package allows you to control and monitor a Hot Spring spa equipped with the
+[Connected Spa Kit 2](https://www.hotspring.com/) 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](https://www.home-assistant.io/) 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** — Read voltage, power consumption, and failure states
+- **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).
+
+> [!NOTE]
+> This library has been primarily tested on a **Hotspring Hot Spot Relay 2025**.
+> Compatibility with other specific models and configurations may vary.
+
+## Installation
+
+```bash
+pip install python-hotspring
+```
+
+## Usage
+
+```python
+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/](demo/README.md) 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][releases]
+functionality.
+
+Releases are based on [Semantic Versioning][semver], 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! :heart_eyes:
+
+## Setting up development environment
+
+This Python project is fully managed using the [Poetry][poetry] dependency
+manager.
+
+You need at least:
+
+- Python 3.12+
+- [Poetry][poetry-install]
+
+To install all packages, including all development requirements:
+
+```bash
+poetry install
+```
+
+As this repository uses the [prek][prek] framework, all changes
+are linted and tested with each commit. You can run all checks and tests
+manually, using the following command:
+
+```bash
+poetry run prek run --all-files
+```
+
+To run just the Python tests:
+
+```bash
+poetry run pytest
+```
+
+## Authors & contributors
+
+The original setup of this repository is by @Moustachauve.
+
+The structure of this library is inspired by [python-wled][python-wled] from
+@frenck and [pytechnove][pytechnove] from @Moustachauve.
+
+[build-shield]: https://github.com/Moustachauve/python-hotspring/actions/workflows/tests.yaml/badge.svg
+[build]: https://github.com/Moustachauve/python-hotspring/actions/workflows/tests.yaml
+[codecov-shield]: https://codecov.io/gh/Moustachauve/python-hotspring/branch/main/graph/badge.svg
+[codecov]: https://codecov.io/gh/Moustachauve/python-hotspring
+[license-shield]: https://img.shields.io/github/license/Moustachauve/python-hotspring.svg
+[maintenance-shield]: https://img.shields.io/maintenance/yes/2026.svg
+[poetry-install]: https://python-poetry.org/docs/#installation
+[poetry]: https://python-poetry.org
+[prek]: https://github.com/j178/prek
+[project-stage-shield]: https://img.shields.io/badge/project%20stage-experimental-yellow.svg
+[pypi]: https://pypi.org/project/python-hotspring/
+[python-versions-shield]: https://img.shields.io/pypi/pyversions/python-hotspring
+[releases-shield]: https://img.shields.io/github/release/Moustachauve/python-hotspring.svg
+[releases]: https://github.com/Moustachauve/python-hotspring/releases
+[semver]: http://semver.org/spec/v2.0.0.html
+[python-wled]: https://github.com/frenck/python-wled
+[pytechnove]: https://github.com/Moustachauve/pytechnove/
+

python_hotspring-1.0.0/README.md

@@ -0,0 +1,174 @@
+[![GitHub Release][releases-shield]][releases]
+[![Python Versions][python-versions-shield]][pypi]
+![Project Stage][project-stage-shield]
+![Project Maintenance][maintenance-shield]
+[![License][license-shield]](LICENSE)
+
+[![Build Status][build-shield]][build]
+[![Code Coverage][codecov-shield]][codecov]
+
+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.
+
+## About
+
+This package allows you to control and monitor a Hot Spring spa equipped with the
+[Connected Spa Kit 2](https://www.hotspring.com/) 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](https://www.home-assistant.io/) 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** — Read voltage, power consumption, and failure states
+- **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).
+
+> [!NOTE]
+> This library has been primarily tested on a **Hotspring Hot Spot Relay 2025**.
+> Compatibility with other specific models and configurations may vary.
+
+## Installation
+
+```bash
+pip install python-hotspring
+```
+
+## Usage
+
+```python
+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/](demo/README.md) 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][releases]
+functionality.
+
+Releases are based on [Semantic Versioning][semver], 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! :heart_eyes:
+
+## Setting up development environment
+
+This Python project is fully managed using the [Poetry][poetry] dependency
+manager.
+
+You need at least:
+
+- Python 3.12+
+- [Poetry][poetry-install]
+
+To install all packages, including all development requirements:
+
+```bash
+poetry install
+```
+
+As this repository uses the [prek][prek] framework, all changes
+are linted and tested with each commit. You can run all checks and tests
+manually, using the following command:
+
+```bash
+poetry run prek run --all-files
+```
+
+To run just the Python tests:
+
+```bash
+poetry run pytest
+```
+
+## Authors & contributors
+
+The original setup of this repository is by @Moustachauve.
+
+The structure of this library is inspired by [python-wled][python-wled] from
+@frenck and [pytechnove][pytechnove] from @Moustachauve.
+
+[build-shield]: https://github.com/Moustachauve/python-hotspring/actions/workflows/tests.yaml/badge.svg
+[build]: https://github.com/Moustachauve/python-hotspring/actions/workflows/tests.yaml
+[codecov-shield]: https://codecov.io/gh/Moustachauve/python-hotspring/branch/main/graph/badge.svg
+[codecov]: https://codecov.io/gh/Moustachauve/python-hotspring
+[license-shield]: https://img.shields.io/github/license/Moustachauve/python-hotspring.svg
+[maintenance-shield]: https://img.shields.io/maintenance/yes/2026.svg
+[poetry-install]: https://python-poetry.org/docs/#installation
+[poetry]: https://python-poetry.org
+[prek]: https://github.com/j178/prek
+[project-stage-shield]: https://img.shields.io/badge/project%20stage-experimental-yellow.svg
+[pypi]: https://pypi.org/project/python-hotspring/
+[python-versions-shield]: https://img.shields.io/pypi/pyversions/python-hotspring
+[releases-shield]: https://img.shields.io/github/release/Moustachauve/python-hotspring.svg
+[releases]: https://github.com/Moustachauve/python-hotspring/releases
+[semver]: http://semver.org/spec/v2.0.0.html
+[python-wled]: https://github.com/frenck/python-wled
+[pytechnove]: https://github.com/Moustachauve/pytechnove/

python_hotspring-1.0.0/pyproject.toml

@@ -0,0 +1,176 @@
+[tool.poetry]
+authors = ["Christophe Gagnier <christopheextensions@gmail.com>"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Natural Language :: English",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+description = "Asynchronous Python client for Hot Spring Connected Spa Kit 2."
+documentation = "https://github.com/Moustachauve/python-hotspring"
+homepage = "https://github.com/Moustachauve/python-hotspring"
+keywords = ["hotspring", "spa", "hot-tub", "home-assistant", "iq2020"]
+license = "MIT"
+maintainers = ["Christophe Gagnier <christopheextensions@gmail.com>"]
+name = "python-hotspring"
+packages = [
+  {include = "hotspring", from = "src"},
+]
+readme = "README.md"
+repository = "https://github.com/Moustachauve/python-hotspring"
+version = "1.0.0"
+
+[tool.poetry.dependencies]
+aiohttp = ">=3.0.0"
+awesomeversion = ">=22.1.0"
+backoff = ">=2.2.0"
+python = "^3.12"
+yarl = ">=1.6.0"
+
+[tool.poetry.urls]
+"Bug Tracker" = "https://github.com/Moustachauve/python-hotspring/issues"
+Changelog = "https://github.com/Moustachauve/python-hotspring/releases"
+
+[tool.poetry.group.dev.dependencies]
+aresponses = "3.0.0"
+codespell = "2.4.2"
+covdefaults = "2.3.0"
+coverage = {version = "7.13.5", extras = ["toml"]}
+mypy = "1.20.1"
+pre-commit-hooks = "6.0.0"
+prek = "0.3.9"
+pylint = "4.0.5"
+pytest = "9.0.3"
+pytest-asyncio = "1.3.0"
+pytest-cov = "7.1.0"
+ruff = "0.15.11"
+safety = "3.7.0"
+yamllint = "1.38.0"
+
+[tool.coverage.run]
+plugins = ["covdefaults"]
+source = ["hotspring"]
+
+[tool.coverage.report]
+fail_under = 90
+show_missing = true
+
+[tool.mypy]
+platform = "linux"
+python_version = "3.12"
+follow_imports = "normal"
+ignore_missing_imports = true
+
+# be strict
+check_untyped_defs = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+disallow_subclassing_any = true
+disallow_untyped_calls = true
+disallow_untyped_decorators = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+no_implicit_reexport = true
+strict_optional = true
+warn_incomplete_stub = true
+warn_no_return = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unused_configs = true
+warn_unused_ignores = true
+
+[tool.pylint.MASTER]
+ignore = ["tests"]
+
+[tool.pylint.BASIC]
+good-names = [
+  "_",
+  "ex",
+  "fp",
+  "i",
+  "id",
+  "j",
+  "k",
+  "on",
+  "ph",
+  "Run",
+  "T",
+]
+
+[tool.pylint."MESSAGES CONTROL"]
+disable = [
+  "too-few-public-methods",
+  "duplicate-code",
+  "format",
+  "unsubscriptable-object",
+]
+
+[tool.pylint.SIMILARITIES]
+ignore-imports = true
+
+[tool.pylint.FORMAT]
+max-line-length = 88
+
+[tool.pylint.DESIGN]
+max-attributes = 30
+
+[tool.pytest.ini_options]
+addopts = "--cov"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+exclude = ["demo"]
+
+[tool.ruff.lint]
+ignore = [
+  "ANN401", # Opinionated warning on disallowing dynamically typed expressions
+  "D203",   # Conflicts with other rules
+  "D213",   # Conflicts with other rules
+  "D417",   # False positives in some occasions
+  "PLR2004", # Just annoying, not really useful
+
+  # Conflicts with the Ruff formatter
+  "COM812",
+  "ISC001",
+]
+select = ["ALL"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+  "FBT001",  # Boolean positional args are idiomatic in parametrized tests
+  "FBT002",  # Boolean defaults are idiomatic in parametrized tests
+  "PLC0415", # Inline imports are acceptable in tests
+  "S101",    # Use of assert detected — expected in test code
+  "SLF001",  # Private member access acceptable for test verification
+]
+"demo/**/*.py" = [
+  "T201",    # allow print statements in demo
+  "S101",    # allow assert in demo
+  "PTH118",  # allow os.path.join
+  "PTH109",  # allow os.getcwd
+  "INP001",  # implicit namespace package is fine for demo
+  "ERA001",  # commented out code is fine in demo
+  "E501",    # line too long is fine
+]
+
+[tool.ruff.lint.flake8-pytest-style]
+fixture-parentheses = false
+mark-parentheses = false
+
+[tool.ruff.lint.isort]
+known-first-party = ["hotspring"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 25
+
+[tool.codespell]
+ignore-words-list = "hass,loopUp,loopDown"
+
+[build-system]
+build-backend = "poetry.core.masonry.api"
+requires = ["poetry-core>=1.0.0"]

python_hotspring-1.0.0/src/hotspring/__init__.py

@@ -0,0 +1,67 @@
+"""Asynchronous Python client for Hot Spring Connected Spa Kit 2."""
+
+from .const import (
+    BrightnessLevel,
+    HeatingMode,
+    JetSpeed,
+    LightColor,
+    LightWheelMode,
+    SpaFailureState,
+    TemperatureUnit,
+)
+from .exceptions import (
+    HotSpringCommandError,
+    HotSpringConnectionError,
+    HotSpringConnectionTimeoutError,
+    HotSpringError,
+    HotSpringNotReadyError,
+)
+from .hotspring import HotSpring
+from .models import (
+    Blower,
+    CleanCycle,
+    ConnectionStatus,
+    Diagnostics,
+    EnergySaving,
+    FreshWaterIQ,
+    Heater,
+    Jet,
+    LightZone,
+    LogoLight,
+    Spa,
+    SpaInfo,
+    SpaLock,
+    Versions,
+    WaterCare,
+)
+
+__all__ = [
+    "Blower",
+    "BrightnessLevel",
+    "CleanCycle",
+    "ConnectionStatus",
+    "Diagnostics",
+    "EnergySaving",
+    "FreshWaterIQ",
+    "Heater",
+    "HeatingMode",
+    "HotSpring",
+    "HotSpringCommandError",
+    "HotSpringConnectionError",
+    "HotSpringConnectionTimeoutError",
+    "HotSpringError",
+    "HotSpringNotReadyError",
+    "Jet",
+    "JetSpeed",
+    "LightColor",
+    "LightWheelMode",
+    "LightZone",
+    "LogoLight",
+    "Spa",
+    "SpaFailureState",
+    "SpaInfo",
+    "SpaLock",
+    "TemperatureUnit",
+    "Versions",
+    "WaterCare",
+]