spacepak-modbus 0.1.0__tar.gz

spacepak_modbus-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

spacepak_modbus-0.1.0/.github/renovate.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "description": "Renovate configuration for spacepak-modbus",
+  "dependencyDashboard": false,
+  "extends": [
+    "config:recommended",
+    ":separateMajorReleases",
+    ":combinePatchMinorReleases",
+    "helpers:pinGitHubActionDigests"
+  ],
+  "rebaseWhen": "conflicted",
+  "ignorePaths": [
+    "**/node_modules/**"
+  ],
+  "github-actions": {
+    "enabled": true
+  },
+  "lockFileMaintenance": {
+    "enabled": true,
+    "schedule": [
+      "before 5am on monday"
+    ]
+  },
+  "packageRules": [
+    {
+      "matchManagers": [
+        "github-actions"
+      ],
+      "groupName": "GitHub Actions",
+      "minimumReleaseAge": "3 days"
+    },
+    {
+      "matchDepTypes": [
+        "dev",
+        "test"
+      ],
+      "groupName": "Dev & Test Dependencies",
+      "minimumReleaseAge": "3 days"
+    },
+    {
+      "matchPackageNames": [
+        "modbus-connection"
+      ],
+      "groupName": "Core Protocol Dependencies"
+    }
+  ]
+}

spacepak_modbus-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+# Written by Claude, guided by Chris.
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Install dependencies
+        run: uv sync
+      - name: Ruff format
+        run: uv run ruff format --check .
+      - name: Ruff lint
+        run: uv run ruff check .
+      - name: Mypy
+        run: uv run mypy
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Install dependencies
+        run: uv sync
+      - name: Run tests
+        run: uv run pytest

spacepak_modbus-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+# Written by Claude, guided by Chris.
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: Existing release tag to build and publish (e.g. 4.0.1)
+        required: true
+        type: string
+
+env:
+  RELEASE_TAG: ${{ inputs.tag || github.event.release.tag_name }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          ref: ${{ env.RELEASE_TAG }}
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Set package version from release tag
+        run: |
+          VERSION="${RELEASE_TAG#v}"
+          sed -i "s/^version = \"0\\.0\\.0\"$/version = \"${VERSION}\"/" pyproject.toml
+      - name: Verify the version was substituted
+        run: |
+          VERSION="${RELEASE_TAG#v}"
+          grep -qx "version = \"${VERSION}\"" pyproject.toml
+      - run: uv build
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1

spacepak_modbus-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage

spacepak_modbus-0.1.0/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <https://unlicense.org>

spacepak_modbus-0.1.0/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.5
+Name: spacepak-modbus
+Version: 0.1.0
+Summary: Read and control SpacePak Solstice Inverter Extreme (ILAHP) heat pumps over Modbus.
+Project-URL: Homepage, https://github.com/cwm12345/spacepak-modbus
+Author: spacepak-modbus contributors
+License: Unlicense
+License-File: LICENSE
+Keywords: air-to-water,heat-pump,hvac,modbus,spacepak
+Classifier: License :: OSI Approved :: The Unlicense (Unlicense)
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Requires-Dist: modbus-connection[tmodbus]>=4.12.1
+Description-Content-Type: text/markdown
+
+<!-- Written by Claude, guided by Chris. -->
+
+# spacepak-modbus
+
+Read and control SpacePak Solstice Inverter Extreme (ILAHP) air-to-water heat
+pumps over Modbus, as typed Python objects rather than register numbers.
+
+The library maps the ILAHP register set onto
+[modbus-connection](https://github.com/home-assistant-libs/modbus-connection)'s
+device model: you hand it a `ModbusUnit`, call `async_update()`, and read
+sub-systems as attributes. It owns no connection and no I/O policy. The caller
+does.
+
+## Status
+
+This is a working reference pulled from one real installation, shared in case
+it is useful. It is **not an actively maintained package**: there is no
+commitment to triage issues or pull requests, or to track future
+modbus-connection changes. Forks are welcome, and so is anyone who wants to take
+it over.
+
+## Supported devices
+
+The SpacePak Solstice Inverter Extreme (ILAHP) range, per the register map in
+its installation manual (ILHP2-0423). It has been exercised against two units
+behind a Modbus TCP gateway. Other SpacePak models are untested.
+
+The unit speaks Modbus RTU at 9600 baud, 8N1, on its RS-485 port. Every
+register this library reads is a holding register.
+
+## What it covers
+
+| Component | Registers | What |
+| :--- | :--- | :--- |
+| `controls` | 1011-1012, 1028, 1158-1165 | Power, operating mode, whether the hot water function is enabled, heating and cooling targets, the unit's own setpoint limits |
+| `status` | 2011-2032 | Running, current mode (defrost included), load outputs, compressor hours |
+| `measurements` | 2042-2072 | Water, air, coil and refrigerant temperatures, currents, voltages, compressor frequency |
+| `faults` | 2081-2090 | The nine failure registers, decoded into named faults |
+
+The manual lists room temperature (T09, 2058) and water flow (T39, 2077) as not
+used on this unit, so they are left out. The hot water tank temperature (T08)
+only has a sensor behind it when the unit's hot water function is enabled
+(`controls.hot_water_enabled`).
+
+The installer parameters (registers 1013-1270: compressor frequency curves, EEV
+steps, defrost timing, weather compensation, timers) are deliberately left out.
+Writing those by mistake would misconfigure the heat pump, not just misreport
+it.
+
+Every temperature is stored in tenths of a degree Celsius, whatever the unit's
+display is set to show, so every temperature here is in °C.
+
+## Usage
+
+```python
+import asyncio
+
+from modbus_connection import ModbusTcpParams
+from modbus_connection.tmodbus import ModbusConnection
+from spacepak_modbus import IlahpHeatPump
+
+
+async def main() -> None:
+    connection = ModbusConnection(ModbusTcpParams(host="192.168.1.50", port=502))
+    try:
+        heat_pump = IlahpHeatPump(connection.for_unit(1))
+        await heat_pump.async_update()
+
+        print("Running:", heat_pump.status.running, heat_pump.status.unit_mode)
+        print("Outlet:", heat_pump.measurements.outlet_temperature, "°C")
+        print("Outdoor:", heat_pump.measurements.ambient_temperature, "°C")
+        print("Target:", heat_pump.controls.heating_target_temperature, "°C")
+        print("Faults:", [fault.key for fault in heat_pump.faults.active_faults])
+    finally:
+        await connection.close()
+
+
+asyncio.run(main())
+```
+
+### Readings and settings refresh separately
+
+- `async_update_readings()` reads `status`, `measurements` and `faults`: what the
+  unit measures and reports.
+- `async_update_settings()` reads `controls`: registers that change when
+  something writes them. Run one after a write to read back what took effect.
+- `async_update()` does both, in one report.
+
+Each returns an `UpdateReport`. A component whose block the unit refuses keeps
+its previous values and is listed in `report.failed`; the rest still refresh. A
+dead link (`ModbusConnectionError`) raises, and so does a timeout before
+anything has answered.
+
+### Writing
+
+```python
+await heat_pump.controls.write("power_on", True)
+await heat_pump.controls.write("heating_target_temperature", 45.0)
+await heat_pump.async_update_settings()
+```
+
+Setpoint writes are checked against the widest range each register accepts.
+The unit applies its own tighter limits too, which it reports as
+`min_heating_setpoint`/`max_heating_setpoint` and
+`min_cooling_setpoint`/`max_cooling_setpoint`. Clamp to those before writing.
+
+The operating mode is read-only here. The mode register's values depend on
+whether the installer enabled cooling (parameter H05), and a wrong mode can
+leave a hydronic system without heat.
+
+### Faults
+
+The unit reports faults as nine bitmask registers. `faults.active_faults`
+decodes them into `Fault` entries, each with its failure register, bit, a
+stable snake_case `key`, and a description. `FAULTS` is the full table of the
+bits the manual names. A set bit the manual does not name (failure register 3
+has no published bit table) is still reported, as `failure_<n>_bit_<b>`, so
+nothing is hidden. `faults.any_fault` is true when any register has a bit set.
+
+## Checking a real heat pump
+
+`script/query.py` reads one unit once and prints every value, which is the
+quickest way to see whether a unit is reachable and addressed correctly:
+
+```bash
+uv run script/query.py 192.168.1.50 --port 502 --unit 1
+uv run script/query.py socket://192.168.1.50:8899 --transport serial --unit 1
+uv run script/query.py /dev/ttyUSB0 --transport serial --baudrate 9600 --unit 1 --raw
+```
+
+`--raw` adds every register it read, undecoded, which is what an issue about a
+wrong value should quote. A raw dump loads straight into modbus-connection's
+mock with `load_raw()`, so it can become a test.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+The tests run against modbus-connection's in-memory mock backend. No hardware
+is needed.
+
+## Source
+
+The register map comes from the SpacePak ILAHP Installation, Operation &
+Maintenance manual (ILHP2-0423), Modbus section. Addresses, scales and the
+enum and bit tables follow it. On live units:
+
+- 1011, 1158 and 1159 have been read and written.
+- Every register this library reads has been read from two units and checked
+  against the values an existing integration reported for the same units.
+- The operating mode (1012) and the setpoint limits (1162-1165) read as
+  expected. The limits are whatever the installer configured, so they differ
+  from the manual's defaults.
+
+## License
+
+[Unlicense](LICENSE): public domain.

spacepak_modbus-0.1.0/README.md

@@ -0,0 +1,161 @@
+<!-- Written by Claude, guided by Chris. -->
+
+# spacepak-modbus
+
+Read and control SpacePak Solstice Inverter Extreme (ILAHP) air-to-water heat
+pumps over Modbus, as typed Python objects rather than register numbers.
+
+The library maps the ILAHP register set onto
+[modbus-connection](https://github.com/home-assistant-libs/modbus-connection)'s
+device model: you hand it a `ModbusUnit`, call `async_update()`, and read
+sub-systems as attributes. It owns no connection and no I/O policy. The caller
+does.
+
+## Status
+
+This is a working reference pulled from one real installation, shared in case
+it is useful. It is **not an actively maintained package**: there is no
+commitment to triage issues or pull requests, or to track future
+modbus-connection changes. Forks are welcome, and so is anyone who wants to take
+it over.
+
+## Supported devices
+
+The SpacePak Solstice Inverter Extreme (ILAHP) range, per the register map in
+its installation manual (ILHP2-0423). It has been exercised against two units
+behind a Modbus TCP gateway. Other SpacePak models are untested.
+
+The unit speaks Modbus RTU at 9600 baud, 8N1, on its RS-485 port. Every
+register this library reads is a holding register.
+
+## What it covers
+
+| Component | Registers | What |
+| :--- | :--- | :--- |
+| `controls` | 1011-1012, 1028, 1158-1165 | Power, operating mode, whether the hot water function is enabled, heating and cooling targets, the unit's own setpoint limits |
+| `status` | 2011-2032 | Running, current mode (defrost included), load outputs, compressor hours |
+| `measurements` | 2042-2072 | Water, air, coil and refrigerant temperatures, currents, voltages, compressor frequency |
+| `faults` | 2081-2090 | The nine failure registers, decoded into named faults |
+
+The manual lists room temperature (T09, 2058) and water flow (T39, 2077) as not
+used on this unit, so they are left out. The hot water tank temperature (T08)
+only has a sensor behind it when the unit's hot water function is enabled
+(`controls.hot_water_enabled`).
+
+The installer parameters (registers 1013-1270: compressor frequency curves, EEV
+steps, defrost timing, weather compensation, timers) are deliberately left out.
+Writing those by mistake would misconfigure the heat pump, not just misreport
+it.
+
+Every temperature is stored in tenths of a degree Celsius, whatever the unit's
+display is set to show, so every temperature here is in °C.
+
+## Usage
+
+```python
+import asyncio
+
+from modbus_connection import ModbusTcpParams
+from modbus_connection.tmodbus import ModbusConnection
+from spacepak_modbus import IlahpHeatPump
+
+
+async def main() -> None:
+    connection = ModbusConnection(ModbusTcpParams(host="192.168.1.50", port=502))
+    try:
+        heat_pump = IlahpHeatPump(connection.for_unit(1))
+        await heat_pump.async_update()
+
+        print("Running:", heat_pump.status.running, heat_pump.status.unit_mode)
+        print("Outlet:", heat_pump.measurements.outlet_temperature, "°C")
+        print("Outdoor:", heat_pump.measurements.ambient_temperature, "°C")
+        print("Target:", heat_pump.controls.heating_target_temperature, "°C")
+        print("Faults:", [fault.key for fault in heat_pump.faults.active_faults])
+    finally:
+        await connection.close()
+
+
+asyncio.run(main())
+```
+
+### Readings and settings refresh separately
+
+- `async_update_readings()` reads `status`, `measurements` and `faults`: what the
+  unit measures and reports.
+- `async_update_settings()` reads `controls`: registers that change when
+  something writes them. Run one after a write to read back what took effect.
+- `async_update()` does both, in one report.
+
+Each returns an `UpdateReport`. A component whose block the unit refuses keeps
+its previous values and is listed in `report.failed`; the rest still refresh. A
+dead link (`ModbusConnectionError`) raises, and so does a timeout before
+anything has answered.
+
+### Writing
+
+```python
+await heat_pump.controls.write("power_on", True)
+await heat_pump.controls.write("heating_target_temperature", 45.0)
+await heat_pump.async_update_settings()
+```
+
+Setpoint writes are checked against the widest range each register accepts.
+The unit applies its own tighter limits too, which it reports as
+`min_heating_setpoint`/`max_heating_setpoint` and
+`min_cooling_setpoint`/`max_cooling_setpoint`. Clamp to those before writing.
+
+The operating mode is read-only here. The mode register's values depend on
+whether the installer enabled cooling (parameter H05), and a wrong mode can
+leave a hydronic system without heat.
+
+### Faults
+
+The unit reports faults as nine bitmask registers. `faults.active_faults`
+decodes them into `Fault` entries, each with its failure register, bit, a
+stable snake_case `key`, and a description. `FAULTS` is the full table of the
+bits the manual names. A set bit the manual does not name (failure register 3
+has no published bit table) is still reported, as `failure_<n>_bit_<b>`, so
+nothing is hidden. `faults.any_fault` is true when any register has a bit set.
+
+## Checking a real heat pump
+
+`script/query.py` reads one unit once and prints every value, which is the
+quickest way to see whether a unit is reachable and addressed correctly:
+
+```bash
+uv run script/query.py 192.168.1.50 --port 502 --unit 1
+uv run script/query.py socket://192.168.1.50:8899 --transport serial --unit 1
+uv run script/query.py /dev/ttyUSB0 --transport serial --baudrate 9600 --unit 1 --raw
+```
+
+`--raw` adds every register it read, undecoded, which is what an issue about a
+wrong value should quote. A raw dump loads straight into modbus-connection's
+mock with `load_raw()`, so it can become a test.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+The tests run against modbus-connection's in-memory mock backend. No hardware
+is needed.
+
+## Source
+
+The register map comes from the SpacePak ILAHP Installation, Operation &
+Maintenance manual (ILHP2-0423), Modbus section. Addresses, scales and the
+enum and bit tables follow it. On live units:
+
+- 1011, 1158 and 1159 have been read and written.
+- Every register this library reads has been read from two units and checked
+  against the values an existing integration reported for the same units.
+- The operating mode (1012) and the setpoint limits (1162-1165) read as
+  expected. The limits are whatever the installer configured, so they differ
+  from the manual's defaults.
+
+## License
+
+[Unlicense](LICENSE): public domain.

spacepak_modbus-0.1.0/RELEASING.md

@@ -0,0 +1,26 @@
+<!-- Written by Claude, guided by Chris. -->
+
+# Releasing `spacepak-modbus`
+
+This document describes how to release a new version of `spacepak-modbus` to PyPI.
+
+## Tagging Convention
+
+> [!IMPORTANT]
+> **Release tags must be bare semantic versions without a leading `v`** (e.g. `0.1.5`, `1.0.0`).
+> Do not use `v`-prefixed tags like `v0.1.5`.
+
+Release tags are directly substituted into `pyproject.toml` during the release workflow to set the package version according to PEP 440.
+
+## Release Process
+
+1. **Verify CI**: Ensure that the `CI` workflow is green on the `main` branch.
+2. **Draft a GitHub Release**:
+   - Go to GitHub Releases: **Draft a new release**.
+   - **Choose a tag**: Enter the new version number as a bare tag (e.g. `0.1.5`).
+   - **Target**: `main`.
+   - **Title**: Enter the version number (e.g. `0.1.5`).
+   - **Description**: Provide release notes / changelog.
+3. **Publish the Release**:
+   - Click **Publish release**.
+   - The `.github/workflows/publish.yml` workflow will automatically trigger, build the wheel and source distribution, and publish the package to PyPI via Trusted Publishing.

spacepak_modbus-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+# Written by Claude, guided by Chris.
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spacepak-modbus"
+version = "0.1.0"
+description = "Read and control SpacePak Solstice Inverter Extreme (ILAHP) heat pumps over Modbus."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "Unlicense" }
+authors = [{ name = "spacepak-modbus contributors" }]
+keywords = ["modbus", "spacepak", "heat-pump", "air-to-water", "hvac"]
+classifiers = [
+    "License :: OSI Approved :: The Unlicense (Unlicense)",
+    "Programming Language :: Python :: 3",
+    "Topic :: Home Automation",
+]
+# The caller injects a ModbusUnit; tmodbus is the backend this is exercised against.
+dependencies = ["modbus-connection[tmodbus]>=4.12.1"]
+
+[project.urls]
+Homepage = "https://github.com/cwm12345/spacepak-modbus"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.11",
+    "pytest>=8",
+    "pytest-asyncio>=0.24",
+    "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spacepak_modbus"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py312"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "D"]
+# D401 wants imperative docstrings; this codebase names things, matching
+# modbus-connection's own style. D107 is covered by the class docstring.
+ignore = ["D107", "D401"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "pep257"
+
+[tool.ruff.lint.per-file-ignores]
+# A test's name is its documentation; docstrings are for the ones that need a why.
+"tests/*" = ["D100", "D103", "D104"]
+
+[tool.mypy]
+python_version = "3.12"
+files = ["src", "tests", "script"]
+strict = true