senertec-dachs 0.1.0__tar.gz

senertec_dachs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 skuza.it
+
+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.

senertec_dachs-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: senertec-dachs
+Version: 0.1.0
+Summary: Async Python client for the SenerTec Dachs CHP unit: local MSR2 GLT interface and Dachsportal cloud
+Author: skuza.it
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/skuzait/senertec-dachs
+Project-URL: Repository, https://github.com/skuzait/senertec-dachs
+Project-URL: Issues, https://github.com/skuzait/senertec-dachs/issues
+Keywords: senertec,dachs,msr2,chp,cogeneration,home-assistant
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4,>=3.11
+Provides-Extra: test
+Requires-Dist: pytest<10,>=8.4; extra == "test"
+Requires-Dist: pytest-asyncio<2,>=0.24; extra == "test"
+Dynamic: license-file
+
+# senertec-dachs
+
+Async Python library for the SenerTec Dachs combined heat and power unit.
+
+One `Dachs` device object, two backends, the same API everywhere:
+
+- **Local**: the MSR2 GLT interface on your LAN (HTTP, port 8080, Basic
+  auth `glt`). Live values, direct writes.
+- **Cloud**: the SenerTec Dachsportal — the backend the official DachsApp
+  uses. Works from anywhere; values are the portal's cached polls of the
+  device, so freshness is surfaced explicitly (`device_online`,
+  `data_fetched_at`).
+
+Typed readings for all 118 documented MSR2 keys, honest units
+(unevidenced scales surface as `UNVERIFIED` with the raw value preserved,
+never a guess), and safe writes with `outcome_unknown` semantics —
+uncertain outcomes are never retried blindly.
+
+## Install
+
+```bash
+pip install senertec-dachs
+```
+
+or straight from GitHub:
+
+```bash
+pip install "senertec-dachs @ git+https://github.com/skuzait/senertec-dachs"
+```
+
+Requires Python 3.11+, depends only on aiohttp.
+
+## Local quickstart
+
+```python
+import asyncio
+from senertec_dachs import Dachs
+
+async def main() -> None:
+    async with Dachs("192.168.1.50") as dachs:   # MSR2 address, port 8080 default
+        await dachs.update()
+
+        print(dachs.power_kw)            # Decimal or None
+        print(dachs.running)             # True/False/None
+        print(dachs.outdoor_temperature) # °C as Decimal
+        print(dachs.electrical_energy_kwh, dachs.thermal_energy_kwh)
+        print(dachs.maintenance_due)
+
+asyncio.run(main())
+```
+
+`Dachs(host)` accepts an IP or hostname. Properties return `None` unless
+the reading is cleanly available; the ten keys whose scale is still
+unverified have no property — use `dachs.snapshot` (all 118 keys with
+states and raw text) or `dachs.client` (raw reads) for those.
+
+## Cloud quickstart
+
+```python
+async with Dachs.cloud("12345", "portal-password") as dachs:
+    await dachs.update()
+    print(dachs.power_kw)        # same properties as local
+    print(dachs.device_online)   # could the portal reach the unit?
+    print(dachs.data_fetched_at) # UTC timestamp of the portal's last poll
+```
+
+The portal ID is the trailing part of the Dachs serial number; the
+password is the DachsApp password. No local network access needed.
+Cloud extras live on the client:
+`reports()`, `daily_profile()`, `schedules()`, `statistics()`,
+`metainfo()`, `portal_news()`.
+
+Differences worth knowing: portal values are cached polls (check
+`device_online`), small rounding differences vs local are normal, and
+the portal's `ulArbeitThermHka` includes the condenser share while the
+local key reports the unit alone.
+
+## Demand operations
+
+Both calls work identically on both backends:
+
+```python
+await dachs.request_run()      # one-shot "run, please"
+await dachs.request_power(2)   # per-module external demand, 0-10
+```
+
+- `request_run()` — local: the documented GLT demand with one module;
+  cloud: the app's `dachsAnfordern` (portal default demand).
+- `request_power(n)` — the documented `Stromf_Ew.Anforderung_GLT` write
+  on both backends. The cloud path is unconfirmed against a real portal —
+  treat its first real use as an experiment.
+
+A demand is valid for ten minutes; renew sooner for sustained demand.
+A clean acknowledgement proves acceptance, not that a module started.
+Errors on writes carry `outcome_unknown=True` when the outcome cannot be
+confirmed; nothing is retried automatically.
+
+## Reading states
+
+Every reading is a `Reading` with `raw` (wire text), `value`, `state`:
+
+| State | Meaning |
+|---|---|
+| `AVAILABLE` | Clean typed value. |
+| `MISSING` | Key absent (optional equipment). |
+| `INVALID` | Malformed wire value; `raw` preserved. |
+| `UNVERIFIED` | Well-formed, but the scale/unit is not evidenced; `raw` preserved. |
+| `UNAVAILABLE` | Device sentinel (temperature sensors return `127` where not connected). |
+
+## MQTT
+
+`examples/mqtt_publish.py` publishes a JSON state message on an interval,
+from either backend (`pip install paho-mqtt`, not a library dependency):
+
+```bash
+DACHS_HOST=192.168.1.50 MQTT_HOST=mosquitto.local python examples/mqtt_publish.py
+```
+
+More examples: `examples/read_local.py`, `examples/read_cloud.py`,
+`examples/read_all.py` (full typed dump of all 118 keys).
+
+## Development
+
+```bash
+py -m venv .venv
+.venv\Scripts\pip install -e ".[test]"
+.venv\Scripts\pytest -q
+```
+
+Tests run against loopback fakes — no device, portal, or credentials
+needed. `tests/fixtures/local-protocol.json` doubles as the
+language-neutral protocol contract for the planned Node.js port.
+
+MIT license.

senertec_dachs-0.1.0/README.md

@@ -0,0 +1,134 @@
+# senertec-dachs
+
+Async Python library for the SenerTec Dachs combined heat and power unit.
+
+One `Dachs` device object, two backends, the same API everywhere:
+
+- **Local**: the MSR2 GLT interface on your LAN (HTTP, port 8080, Basic
+  auth `glt`). Live values, direct writes.
+- **Cloud**: the SenerTec Dachsportal — the backend the official DachsApp
+  uses. Works from anywhere; values are the portal's cached polls of the
+  device, so freshness is surfaced explicitly (`device_online`,
+  `data_fetched_at`).
+
+Typed readings for all 118 documented MSR2 keys, honest units
+(unevidenced scales surface as `UNVERIFIED` with the raw value preserved,
+never a guess), and safe writes with `outcome_unknown` semantics —
+uncertain outcomes are never retried blindly.
+
+## Install
+
+```bash
+pip install senertec-dachs
+```
+
+or straight from GitHub:
+
+```bash
+pip install "senertec-dachs @ git+https://github.com/skuzait/senertec-dachs"
+```
+
+Requires Python 3.11+, depends only on aiohttp.
+
+## Local quickstart
+
+```python
+import asyncio
+from senertec_dachs import Dachs
+
+async def main() -> None:
+    async with Dachs("192.168.1.50") as dachs:   # MSR2 address, port 8080 default
+        await dachs.update()
+
+        print(dachs.power_kw)            # Decimal or None
+        print(dachs.running)             # True/False/None
+        print(dachs.outdoor_temperature) # °C as Decimal
+        print(dachs.electrical_energy_kwh, dachs.thermal_energy_kwh)
+        print(dachs.maintenance_due)
+
+asyncio.run(main())
+```
+
+`Dachs(host)` accepts an IP or hostname. Properties return `None` unless
+the reading is cleanly available; the ten keys whose scale is still
+unverified have no property — use `dachs.snapshot` (all 118 keys with
+states and raw text) or `dachs.client` (raw reads) for those.
+
+## Cloud quickstart
+
+```python
+async with Dachs.cloud("12345", "portal-password") as dachs:
+    await dachs.update()
+    print(dachs.power_kw)        # same properties as local
+    print(dachs.device_online)   # could the portal reach the unit?
+    print(dachs.data_fetched_at) # UTC timestamp of the portal's last poll
+```
+
+The portal ID is the trailing part of the Dachs serial number; the
+password is the DachsApp password. No local network access needed.
+Cloud extras live on the client:
+`reports()`, `daily_profile()`, `schedules()`, `statistics()`,
+`metainfo()`, `portal_news()`.
+
+Differences worth knowing: portal values are cached polls (check
+`device_online`), small rounding differences vs local are normal, and
+the portal's `ulArbeitThermHka` includes the condenser share while the
+local key reports the unit alone.
+
+## Demand operations
+
+Both calls work identically on both backends:
+
+```python
+await dachs.request_run()      # one-shot "run, please"
+await dachs.request_power(2)   # per-module external demand, 0-10
+```
+
+- `request_run()` — local: the documented GLT demand with one module;
+  cloud: the app's `dachsAnfordern` (portal default demand).
+- `request_power(n)` — the documented `Stromf_Ew.Anforderung_GLT` write
+  on both backends. The cloud path is unconfirmed against a real portal —
+  treat its first real use as an experiment.
+
+A demand is valid for ten minutes; renew sooner for sustained demand.
+A clean acknowledgement proves acceptance, not that a module started.
+Errors on writes carry `outcome_unknown=True` when the outcome cannot be
+confirmed; nothing is retried automatically.
+
+## Reading states
+
+Every reading is a `Reading` with `raw` (wire text), `value`, `state`:
+
+| State | Meaning |
+|---|---|
+| `AVAILABLE` | Clean typed value. |
+| `MISSING` | Key absent (optional equipment). |
+| `INVALID` | Malformed wire value; `raw` preserved. |
+| `UNVERIFIED` | Well-formed, but the scale/unit is not evidenced; `raw` preserved. |
+| `UNAVAILABLE` | Device sentinel (temperature sensors return `127` where not connected). |
+
+## MQTT
+
+`examples/mqtt_publish.py` publishes a JSON state message on an interval,
+from either backend (`pip install paho-mqtt`, not a library dependency):
+
+```bash
+DACHS_HOST=192.168.1.50 MQTT_HOST=mosquitto.local python examples/mqtt_publish.py
+```
+
+More examples: `examples/read_local.py`, `examples/read_cloud.py`,
+`examples/read_all.py` (full typed dump of all 118 keys).
+
+## Development
+
+```bash
+py -m venv .venv
+.venv\Scripts\pip install -e ".[test]"
+.venv\Scripts\pytest -q
+```
+
+Tests run against loopback fakes — no device, portal, or credentials
+needed. `tests/fixtures/local-protocol.json` doubles as the
+language-neutral protocol contract for the planned Node.js port.
+
+MIT license.

senertec_dachs-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "senertec-dachs"
+version = "0.1.0"
+description = "Async Python client for the SenerTec Dachs CHP unit: local MSR2 GLT interface and Dachsportal cloud"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "skuza.it" }]
+
+keywords = ["senertec", "dachs", "msr2", "chp", "cogeneration", "home-assistant"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Home Automation",
+    "Typing :: Typed",
+]
+dependencies = ["aiohttp>=3.11,<4"]
+
+[project.urls]
+Homepage = "https://github.com/skuzait/senertec-dachs"
+Repository = "https://github.com/skuzait/senertec-dachs"
+Issues = "https://github.com/skuzait/senertec-dachs/issues"
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.4,<10",
+    "pytest-asyncio>=0.24,<2",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+senertec_dachs = ["data/*.json", "py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

senertec_dachs-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

senertec_dachs-0.1.0/src/senertec_dachs/__init__.py

@@ -0,0 +1,79 @@
+"""Async client library for the SenerTec Dachs MSR2 local GLT interface.
+
+Local access uses the documented HTTP interface of the Dachs MSR2
+Ethernet board (SenerTec 11/4798.444.000): HTTP Basic authentication on
+port 8080, ``GET /getKey`` with repeated ``k`` parameters, and
+form-encoded ``POST /setKeys``.
+"""
+
+from .errors import (
+    AuthenticationError,
+    ConnectionError,
+    DachsError,
+    HttpError,
+    ProtocolError,
+    RequestTimeoutError,
+    WriteError,
+)
+from .keys import LOCAL_KEYS
+from .cloud.client import CloudClient, CloudStatus
+from .device import Dachs, ModuleStatus
+from .local.client import LocalClient
+from .models import (
+    ActuatorsData,
+    DAILY_RUN_SLOT_START_HOURS,
+    HydraulicsData,
+    IdentityData,
+    Key,
+    KeyType,
+    MaintenanceData,
+    MeasurementsData,
+    ModuleData,
+    ModuleStatisticsData,
+    Normalization,
+    OperatingData,
+    Reading,
+    ReadingState,
+    SecondGeneratorData,
+    Snapshot,
+    TemperaturesData,
+    TemperatureTargetsData,
+    YearEndData,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AuthenticationError",
+    "ConnectionError",
+    "DachsError",
+    "HttpError",
+    "ProtocolError",
+    "RequestTimeoutError",
+    "WriteError",
+    "LOCAL_KEYS",
+    "Dachs",
+    "CloudClient",
+    "CloudStatus",
+    "ModuleStatus",
+    "LocalClient",
+    "ActuatorsData",
+    "DAILY_RUN_SLOT_START_HOURS",
+    "HydraulicsData",
+    "IdentityData",
+    "Key",
+    "KeyType",
+    "MaintenanceData",
+    "MeasurementsData",
+    "ModuleData",
+    "ModuleStatisticsData",
+    "Normalization",
+    "OperatingData",
+    "Reading",
+    "ReadingState",
+    "SecondGeneratorData",
+    "Snapshot",
+    "TemperaturesData",
+    "TemperatureTargetsData",
+    "YearEndData",
+]

senertec_dachs-0.1.0/src/senertec_dachs/_reader.py

@@ -0,0 +1,52 @@
+"""Shared reading logic used by both the local and the cloud client."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from .keys import LOCAL_KEYS
+from .models import Reading, Snapshot
+
+
+def normalize_requested_keys(keys: Sequence[str]) -> list[str]:
+    """Validate keys and deduplicate while retaining first-seen order."""
+    requested: list[str] = []
+    seen: set[str] = set()
+    for key in keys:
+        if not isinstance(key, str) or key == "":
+            raise ValueError("keys must be non-empty strings")
+        if any(character.isspace() for character in key):
+            raise ValueError(f"keys must not contain whitespace: {key!r}")
+        if key not in seen:
+            seen.add(key)
+            requested.append(key)
+    return requested
+
+
+class SnapshotReaderMixin:
+    """Adds ``read_readings``/``read_snapshot`` to any client with ``read_keys``.
+
+    Both backends return raw wire-text values from ``read_keys``; the typed
+    model on top of that is shared, so a snapshot means the same thing
+    regardless of where the values came from.
+    """
+
+    async def read_readings(self, keys: Sequence[str]) -> dict[str, Reading[Any]]:
+        """Read the given documented keys as typed :class:`Reading` objects."""
+        requested = normalize_requested_keys(keys)
+        unknown = [key for key in requested if key not in LOCAL_KEYS]
+        if unknown:
+            raise ValueError(
+                f"Key is not in the documented catalogue "
+                f"(use read_keys for raw access): {unknown[0]!r}"
+            )
+        raw = await self.read_keys(requested)
+        return {
+            key: Reading.from_raw(LOCAL_KEYS[key], raw.get(key)) for key in requested
+        }
+
+    async def read_snapshot(self) -> Snapshot:
+        """Read all documented keys and return them as one typed snapshot."""
+        raw = await self.read_keys(list(LOCAL_KEYS))
+        return Snapshot.from_raw(raw)

senertec_dachs-0.1.0/src/senertec_dachs/cloud/__init__.py

@@ -0,0 +1 @@
+"""Cloud (Dachsportal) transport for the SenerTec Dachs."""