@camstack/addon-provider-bosch 0.1.50 → 0.1.52

package/python/homecom_normalize.py

@@ -0,0 +1,300 @@
+"""Normalize a `homecom_alt` K40/icom device reading into the JSON the TypeScript side parses.
+
+Pure: no third-party import, so it is tested without the library installed. Every value the
+gateway did not answer, refused (the library turns a 403/404 into `{}`), or flagged as a sensor
+fault is `None`, never `0` (D393).
+
+Output shape (camelCase, every key always present):
+
+  heatSource: { heatPumpType, supplyTemp, returnTemp, modulationPct, pressureBar, starts,
+                outdoorTemp, thermalKwh, electricalKwh }
+  system:     { away, silent, additionalHeater, holiday }            # Setting | None
+  heatingCircuits: [ { id, name, operationMode, heatCoolMode, currentSuWiMode, suWiSwitchMode,
+                       roomTemp, humidity, currentRoomSetpoint, manualRoomSetpoint,
+                       coolingRoomSetpoint, comfortSetpoint, ecoSetpoint, maxFlowTemp } ]
+  dhwCircuits:     [ { id, operationMode, actualTemp, currentTemperatureLevel, charge,
+                       chargeDuration, singleChargeSetpoint, currentSetpoint,
+                       temperatureLevels: { <level>: Setting } } ]
+  heatSourceProbe: { <path>: "answered" | "refused" | "absent" | "transient" }
+
+Setting = { value: str | number | None, min, max, allowed: [str], writeable: bool | None }
+"""
+from __future__ import annotations
+
+import math
+from typing import Any, Dict, List, Optional
+
+ROOM_TEMP_RANGE = (-40.0, 60.0)
+HUMIDITY_RANGE = (0.0, 100.0)
+
+
+def _finite(raw: Any) -> Optional[float]:
+    if isinstance(raw, bool) or not isinstance(raw, (int, float)):
+        return None
+    value = float(raw)
+    return value if math.isfinite(value) else None
+
+
+def _fault_markers(envelope: Dict[str, Any]) -> List[float]:
+    """The sentinel values a sensor reports when it is open or shorted (`state` list)."""
+    markers: List[float] = []
+    state = envelope.get("state")
+    if not isinstance(state, list):
+        return markers
+    for entry in state:
+        if not isinstance(entry, dict):
+            continue
+        for raw in entry.values():
+            number = _finite(raw)
+            if number is not None:
+                markers.append(number)
+    return markers
+
+
+def envelope_of(raw: Any) -> Optional[Dict[str, Any]]:
+    """A resource payload, or None for an absent, refused (`{}`) or malformed one."""
+    if not isinstance(raw, dict) or len(raw) == 0:
+        return None
+    if "value" not in raw and "values" not in raw:
+        return None
+    return raw
+
+
+def number_of(raw: Any, bounds: Optional[tuple] = None) -> Optional[float]:
+    envelope = envelope_of(raw)
+    if envelope is None:
+        return None
+    value = _finite(envelope.get("value"))
+    if value is None or value in _fault_markers(envelope):
+        return None
+    if bounds is not None and not bounds[0] <= value <= bounds[1]:
+        return None
+    return value
+
+
+def text_of(raw: Any) -> Optional[str]:
+    envelope = envelope_of(raw)
+    if envelope is None:
+        return None
+    value = envelope.get("value")
+    return value if isinstance(value, str) else None
+
+
+def _string_list(raw: Any) -> List[str]:
+    if not isinstance(raw, list):
+        return []
+    return [item for item in raw if isinstance(item, str)]
+
+
+def _writeable(raw: Any) -> Optional[bool]:
+    if isinstance(raw, bool):
+        return raw
+    if isinstance(raw, int):
+        return raw != 0
+    return None
+
+
+def setting_of(raw: Any) -> Optional[Dict[str, Any]]:
+    """One answered resource as a setting. A `values` list (holiday) answers with its first item."""
+    envelope = envelope_of(raw)
+    if envelope is None:
+        return None
+    if "value" in envelope:
+        value = envelope.get("value")
+        if isinstance(value, bool) or not isinstance(value, (str, int, float)):
+            value = None
+        elif not isinstance(value, str):
+            value = _finite(value)
+            if value is not None and value in _fault_markers(envelope):
+                value = None
+    else:
+        listed = _string_list(envelope.get("values"))
+        value = listed[0] if listed else ""
+    return {
+        "value": value,
+        "min": _finite(envelope.get("minValue")),
+        "max": _finite(envelope.get("maxValue")),
+        "allowed": _string_list(envelope.get("allowedValues")),
+        "writeable": _writeable(envelope.get("writeable")),
+    }
+
+
+def emon_part(raw: Any, part: str) -> Optional[float]:
+    """One part of an `emonValue`: the `values` item that is a dict carrying `part`."""
+    envelope = envelope_of(raw)
+    if envelope is None:
+        return None
+    values = envelope.get("values")
+    if not isinstance(values, list):
+        return None
+    for item in values:
+        if isinstance(item, dict) and part in item:
+            return _finite(item[part])
+    return None
+
+
+def _first(source: Dict[str, Any], *keys: str) -> Any:
+    for key in keys:
+        if key in source and source[key] not in (None, {}):
+            return source[key]
+    return None
+
+
+def _ref_id(ref: Dict[str, Any]) -> Optional[str]:
+    raw = ref.get("id")
+    if not isinstance(raw, str):
+        return None
+    tail = [part for part in raw.split("/") if part]
+    return tail[-1] if tail else None
+
+
+def _starts(heat_sources: Dict[str, Any], aggregate: Any) -> Optional[float]:
+    starts = _first(heat_sources, "starts", "numberOfStarts")
+    total = emon_part(starts, "total")
+    if total is not None:
+        return total
+    plain = number_of(starts)
+    return plain if plain is not None else number_of(aggregate)
+
+
+def _electrical_kwh(consumption: Any) -> Optional[float]:
+    compressor = emon_part(consumption, "compressor")
+    eheater = emon_part(consumption, "eheater")
+    if compressor is None or eheater is None:
+        return None
+    return compressor + eheater
+
+
+def normalize_heat_source(
+    heat_sources: Any, outdoor: Any, aggregate_starts: Any = None
+) -> Dict[str, Any]:
+    hs = heat_sources if isinstance(heat_sources, dict) else {}
+    consumption = _first(hs, "consumption", "totalConsumption")
+    return {
+        "heatPumpType": text_of(_first(hs, "pumpType", "type")),
+        "supplyTemp": number_of(_first(hs, "actualSupplyTemperature", "supplyTemperature")),
+        "returnTemp": number_of(hs.get("returnTemperature")),
+        "modulationPct": number_of(_first(hs, "actualModulation", "modulation")),
+        "pressureBar": number_of(hs.get("systemPressure")),
+        "starts": _starts(hs, aggregate_starts),
+        "outdoorTemp": number_of(outdoor if outdoor not in (None, {}) else hs.get("outdoorTemp")),
+        "thermalKwh": emon_part(consumption, "outputProduced"),
+        "electricalKwh": _electrical_kwh(consumption),
+    }
+
+
+PROBE_OUTCOMES = ("answered", "refused", "absent", "transient")
+
+
+def probe_outcome(status: int) -> str:
+    """One GET of a heat-pump-only resource, by HTTP status.
+
+    The library reads a 403 and a 404 alike as an empty answer, so the identity resources
+    are probed on their own: 200 answers; 403 and 500 mean the resource exists but is
+    refused (a heat pump the gateway will not let us read); 404 means it is absent (a
+    boiler); anything else (429, 502, 503, 504 …) is transient and proves nothing.
+    """
+    if status == 200:
+        return "answered"
+    if status in (403, 500):
+        return "refused"
+    if status == 404:
+        return "absent"
+    return "transient"
+
+
+def _probe_map(raw: Any) -> Dict[str, str]:
+    if not isinstance(raw, dict):
+        return {}
+    return {
+        path: outcome
+        for path, outcome in raw.items()
+        if isinstance(path, str) and outcome in PROBE_OUTCOMES
+    }
+
+
+def normalize_heating_circuit(ref: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    circuit_id = _ref_id(ref)
+    if circuit_id is None:
+        return None
+    name = ref.get("name")
+    return {
+        "id": circuit_id,
+        "name": name if isinstance(name, str) and name.strip() else None,
+        "operationMode": setting_of(ref.get("operationMode")),
+        "heatCoolMode": setting_of(ref.get("heatCoolMode")),
+        "currentSuWiMode": setting_of(ref.get("currentSuWiMode")),
+        "suWiSwitchMode": setting_of(ref.get("suWiSwitchMode")),
+        "roomTemp": number_of(_first(ref, "roomTemp", "roomtemperature"), ROOM_TEMP_RANGE),
+        "humidity": number_of(ref.get("actualHumidity"), HUMIDITY_RANGE),
+        "currentRoomSetpoint": setting_of(ref.get("currentRoomSetpoint")),
+        "manualRoomSetpoint": setting_of(ref.get("manualRoomSetpoint")),
+        "coolingRoomSetpoint": setting_of(ref.get("coolingRoomTempSetpoint")),
+        "comfortSetpoint": setting_of(ref.get("temperatureLevelComfort2")),
+        "ecoSetpoint": setting_of(ref.get("temperatureLevelEco")),
+        "maxFlowTemp": setting_of(ref.get("maxFlowTemp")),
+    }
+
+
+def normalize_dhw_circuit(
+    ref: Dict[str, Any], charge_duration: Any = None
+) -> Optional[Dict[str, Any]]:
+    circuit_id = _ref_id(ref)
+    if circuit_id is None:
+        return None
+    levels: Dict[str, Any] = {}
+    raw_levels = ref.get("tempLevel")
+    if isinstance(raw_levels, dict):
+        for level, payload in raw_levels.items():
+            setting = setting_of(payload)
+            if isinstance(level, str) and setting is not None:
+                levels[level] = setting
+    duration = ref.get("chargeDuration")
+    return {
+        "id": circuit_id,
+        "operationMode": setting_of(ref.get("operationMode")),
+        "actualTemp": number_of(ref.get("actualTemp")),
+        "currentTemperatureLevel": setting_of(ref.get("currentTemperatureLevel")),
+        "charge": setting_of(ref.get("charge")),
+        "chargeDuration": setting_of(duration if duration not in (None, {}) else charge_duration),
+        "singleChargeSetpoint": setting_of(ref.get("singleChargeSetpoint")),
+        "currentSetpoint": setting_of(ref.get("currentSetpoint")),
+        "temperatureLevels": levels,
+    }
+
+
+def _refs(raw: Any) -> List[Dict[str, Any]]:
+    if not isinstance(raw, list):
+        return []
+    return [ref for ref in raw if isinstance(ref, dict)]
+
+
+def normalize_reading(
+    device: Dict[str, Any], extras: Optional[Dict[str, Any]] = None
+) -> Dict[str, Any]:
+    """`device` is the library's update dataclass as a dict; `extras` the separate reads.
+
+    extras keys: `silentMode`, `additionalHeaterMode`, `aggregateStarts`,
+    `chargeDuration` ({ dhw id: payload }), `heatSourceProbe` ({ path: probe outcome }).
+    """
+    more = extras or {}
+    durations = more.get("chargeDuration") if isinstance(more.get("chargeDuration"), dict) else {}
+    heating = [normalize_heating_circuit(ref) for ref in _refs(device.get("heating_circuits"))]
+    dhw = [
+        normalize_dhw_circuit(ref, durations.get(_ref_id(ref) or ""))
+        for ref in _refs(device.get("dhw_circuits"))
+    ]
+    return {
+        "heatSource": normalize_heat_source(
+            device.get("heat_sources"), device.get("outdoor_temp"), more.get("aggregateStarts")
+        ),
+        "system": {
+            "away": setting_of(device.get("away_mode")),
+            "silent": setting_of(more.get("silentMode")),
+            "additionalHeater": setting_of(more.get("additionalHeaterMode")),
+            "holiday": setting_of(device.get("holiday_mode")),
+        },
+        "heatingCircuits": [c for c in heating if c is not None],
+        "dhwCircuits": [c for c in dhw if c is not None],
+        "heatSourceProbe": _probe_map(more.get("heatSourceProbe")),
+    }

package/python/homecom_worker.py

@@ -0,0 +1,250 @@
+#!/usr/bin/env python3
+"""One-shot HomeCom Easy reader/writer for a heat-pump gateway (k40, k30, icom).
+
+Runs the MIT `homecom_alt` library (its device classes' own bulk read and write methods),
+one spawn per poll. The OAuth login, the keychain and the token refresh stay in
+TypeScript: this script receives a short-lived access token on stdin and nothing else. The
+library is built with `auth_provider=False`, so it never refreshes, never logs in, and never
+writes a token anywhere; nothing here touches the disk.
+
+stdin JSON:  { "token": "<access token>", "gatewayId": "101…", "deviceType": "k40",
+               "action": "read" }
+          or { …, "action": "write", "write": { "op": "<op>", "circuitId"?: "hc1",
+               "level"?: "eco", "value": <string | number> } }
+stdout JSON: { "ok": true, "reading": { … } }          (read; shape in homecom_normalize.py)
+          or { "ok": true, "written": "<op>" }          (write)
+          or { "ok": false, "kind": "auth|unreachable|refused|api|protocol|bad-request",
+               "error": "…" }
+Diagnostics go to stderr. The token is never printed, on either stream.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import sys
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from homecom_normalize import normalize_reading, probe_outcome  # noqa: E402
+
+DEVICE_TYPES = ("k40", "k30", "icom")
+
+
+class WorkerError(Exception):
+    def __init__(self, kind: str, message: str) -> None:
+        super().__init__(message)
+        self.kind = kind
+
+
+def _text(request: Dict[str, Any], key: str) -> str:
+    value = request.get(key)
+    if not isinstance(value, str) or len(value) == 0:
+        raise WorkerError("bad-request", f"{key} must be a non-empty string")
+    return value
+
+
+def _scalar(write: Dict[str, Any]) -> Any:
+    value = write.get("value")
+    if isinstance(value, bool) or not isinstance(value, (str, int, float)):
+        raise WorkerError("bad-request", "write.value must be a string or a number")
+    return value
+
+
+WriteCall = Callable[[Any, str, Dict[str, Any]], Awaitable[None]]
+
+
+def _circuit(write: Dict[str, Any]) -> str:
+    return _text(write, "circuitId")
+
+
+WRITES: Dict[str, WriteCall] = {
+    "hcOperationMode": lambda c, d, w: c.async_put_hc_operation_mode(d, _circuit(w), _scalar(w)),
+    "hcHeatCoolMode": lambda c, d, w: c.async_put_hc_heatcool_mode(d, _circuit(w), _scalar(w)),
+    "hcSuWiSwitchMode": lambda c, d, w: c.async_put_hc_suwi_switch_mode(
+        d, _circuit(w), _scalar(w)
+    ),
+    "hcManualRoomSetpoint": lambda c, d, w: c.async_set_hc_manual_room_setpoint(
+        d, _circuit(w), _scalar(w)
+    ),
+    "hcCoolingRoomSetpoint": lambda c, d, w: c.async_set_hc_cooling_room_temp_setpoint(
+        d, _circuit(w), _scalar(w)
+    ),
+    "hcComfortSetpoint": lambda c, d, w: c.async_set_hc_temp_level_comfort2(
+        d, _circuit(w), _scalar(w)
+    ),
+    "hcEcoSetpoint": lambda c, d, w: c.async_set_hc_temp_level_eco(d, _circuit(w), _scalar(w)),
+    "hcMaxFlowTemp": lambda c, d, w: c.async_set_hc_max_flow_temp(d, _circuit(w), _scalar(w)),
+    "dhwOperationMode": lambda c, d, w: c.async_put_dhw_operation_mode(
+        d, _circuit(w), _scalar(w)
+    ),
+    "dhwTemperatureLevel": lambda c, d, w: c.async_put_dhw_current_temp_level(
+        d, _circuit(w), _scalar(w)
+    ),
+    "dhwLevelTemp": lambda c, d, w: c.async_set_dhw_temp_level(
+        d, _circuit(w), _text(w, "level"), _scalar(w)
+    ),
+    "dhwCharge": lambda c, d, w: c.async_set_dhw_charge(d, _circuit(w), _scalar(w)),
+    "dhwChargeDuration": lambda c, d, w: c.async_set_dhw_charge_duration(
+        d, _circuit(w), _scalar(w)
+    ),
+    "awayMode": lambda c, d, w: c.async_put_away_mode(d, _scalar(w)),
+    "silentMode": lambda c, d, w: c.async_put_silent_mode(d, _scalar(w)),
+    "additionalHeaterMode": lambda c, d, w: c.async_put_additional_heater_mode(d, _scalar(w)),
+    "holidayMode": lambda c, d, w: c.async_put_holiday_mode(d, _scalar(w)),
+}
+
+
+def parse_request(raw: str) -> Dict[str, Any]:
+    """Validate stdin before any library import. Raises WorkerError('bad-request')."""
+    try:
+        request = json.loads(raw)
+    except json.JSONDecodeError as err:
+        raise WorkerError("bad-request", f"stdin is not JSON: {err.msg}") from None
+    if not isinstance(request, dict):
+        raise WorkerError("bad-request", "stdin must be a JSON object")
+    _text(request, "token")
+    _text(request, "gatewayId")
+    if request.get("deviceType") not in DEVICE_TYPES:
+        raise WorkerError("bad-request", f"deviceType must be one of {', '.join(DEVICE_TYPES)}")
+    action = request.get("action")
+    if action == "write":
+        write = request.get("write")
+        if not isinstance(write, dict) or write.get("op") not in WRITES:
+            raise WorkerError("bad-request", "write.op is not a known write")
+    elif action != "read":
+        raise WorkerError("bad-request", "action must be read or write")
+    return request
+
+
+def _as_dict(value: Any) -> Dict[str, Any]:
+    if is_dataclass(value) and not isinstance(value, type):
+        return asdict(value)
+    return value if isinstance(value, dict) else {}
+
+
+async def _optional(call: Awaitable[Any]) -> Any:
+    """An extra read the device may not have: its failure is an unknown value, never fatal."""
+    from homecom_alt import AuthFailedError
+
+    try:
+        return await call
+    except AuthFailedError:
+        raise
+    except Exception as err:  # noqa: BLE001 - one unanswered extra must not sink the poll
+        print(f"[homecom_worker] optional read failed: {type(err).__name__}", file=sys.stderr)
+        return None
+
+
+HEAT_SOURCE_IDENTITY = ("/heatSources/hs1/heatPumpType", "/heatSources/hs1/heatPumpPower")
+PROBE_TIMEOUT_S = 15
+
+
+async def _probe_heat_source(session: Any, token: str, gateway_id: str) -> Dict[str, str]:
+    """GET each heat-pump-only resource and keep its outcome (see `probe_outcome`).
+
+    Only asked when the bulk read left the heat-pump type unknown: a gateway that refuses
+    its heat source still has a heat pump, and the library cannot tell that from a 404.
+    """
+    import aiohttp
+    from homecom_alt.const import BOSCHCOM_DOMAIN, BOSCHCOM_ENDPOINT_GATEWAYS
+
+    outcomes: Dict[str, str] = {}
+    for path in HEAT_SOURCE_IDENTITY:
+        url = f"{BOSCHCOM_DOMAIN}{BOSCHCOM_ENDPOINT_GATEWAYS}{gateway_id}/resource{path}"
+        try:
+            async with session.get(
+                url,
+                headers={"Authorization": f"Bearer {token}"},
+                timeout=aiohttp.ClientTimeout(total=PROBE_TIMEOUT_S),
+            ) as resp:
+                outcomes[path] = probe_outcome(resp.status)
+        except (aiohttp.ClientError, asyncio.TimeoutError) as err:
+            print(f"[homecom_worker] probe failed: {type(err).__name__}", file=sys.stderr)
+            outcomes[path] = "transient"
+    return outcomes
+
+
+async def _read(
+    client: Any, session: Any, token: str, gateway_id: str, device_type: str
+) -> Dict[str, Any]:
+    device = _as_dict(await client.async_update(gateway_id))
+    extras: Dict[str, Any] = {
+        "aggregateStarts": await _optional(client.async_get_hs_total_number_of_starts(gateway_id)),
+    }
+    if device_type != "icom":
+        extras["silentMode"] = await _optional(client.async_get_silent_mode(gateway_id))
+        extras["additionalHeaterMode"] = await _optional(
+            client.async_get_additional_heater_mode(gateway_id)
+        )
+        durations: Dict[str, Any] = {}
+        for ref in device.get("dhw_circuits") or []:
+            dhw_id = str(ref.get("id", "")).split("/")[-1] if isinstance(ref, dict) else ""
+            if dhw_id:
+                durations[dhw_id] = await _optional(
+                    client.async_get_dhw_charge_duration(gateway_id, dhw_id)
+                )
+        extras["chargeDuration"] = durations
+    if normalize_reading(device)["heatSource"]["heatPumpType"] is None:
+        extras["heatSourceProbe"] = await _probe_heat_source(session, token, gateway_id)
+    return normalize_reading(device, extras)
+
+
+async def run(request: Dict[str, Any]) -> Dict[str, Any]:
+    import aiohttp
+    from homecom_alt import (
+        ApiError,
+        AuthFailedError,
+        ConnectionOptions,
+        HomeComIcom,
+        HomeComK40,
+        NotRespondingError,
+    )
+
+    gateway_id = request["gatewayId"]
+    device_type = request["deviceType"]
+    options = ConnectionOptions(token=request["token"], auth_provider=False)
+    cls = HomeComIcom if device_type == "icom" else HomeComK40
+    try:
+        async with aiohttp.ClientSession() as session:
+            client = cls(session, options, gateway_id, False)
+            if request["action"] == "read":
+                reading = await _read(client, session, request["token"], gateway_id, device_type)
+                return {"ok": True, "reading": reading}
+            write = request["write"]
+            await WRITES[write["op"]](client, gateway_id, write)
+            return {"ok": True, "written": write["op"]}
+    except AuthFailedError:
+        raise WorkerError("auth", "HomeCom refused the access token") from None
+    except NotRespondingError as err:
+        raise WorkerError("unreachable", f"HomeCom did not respond: {err}") from None
+    except ApiError as err:
+        raise WorkerError("refused", f"HomeCom refused the request: {err}") from None
+    except aiohttp.ClientError as err:
+        raise WorkerError("unreachable", f"{type(err).__name__}: {err}") from None
+
+
+def _emit(answer: Dict[str, Any]) -> None:
+    print(json.dumps(answer), flush=True)
+
+
+def main() -> int:
+    # The library logs request URLs at DEBUG; WARNING on stderr carries no token.
+    logging.basicConfig(level=logging.WARNING, stream=sys.stderr)
+    try:
+        request = parse_request(sys.stdin.read())
+        _emit(asyncio.run(run(request)))
+        return 0
+    except WorkerError as err:
+        _emit({"ok": False, "kind": err.kind, "error": str(err)})
+        return 1
+    except Exception as err:  # noqa: BLE001 - the bridge needs one JSON answer, always
+        _emit({"ok": False, "kind": "api", "error": f"{type(err).__name__}: {err}"})
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/python/requirements.txt

@@ -0,0 +1,2 @@
+# HomeCom Easy cloud client (MIT). Pinned exactly: the worker reads its payload shapes.
+homecom-alt==1.9.2