python-hilo 2026.10.2__tar.gz → 2026.11.1__tar.gz

{python_hilo-2026.10.2 → python_hilo-2026.11.1}/.github/workflows/tests.yaml

@@ -24,7 +24,7 @@ jobs:
           python-version: ${{ env.DEFAULT_PYTHON }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.3.1
+        uses: astral-sh/setup-uv@v10.3.3
 
       - name: Install dependencies
         run: uv sync --group dev
@@ -51,7 +51,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v10.3.1
+        uses: astral-sh/setup-uv@v10.3.3
 
       - name: Install dependencies
         run: uv sync --python ${{ matrix.python-version }} --group test

{python_hilo-2026.10.2 → python_hilo-2026.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-hilo
-Version: 2026.10.2
+Version: 2026.11.1
 Summary: A Python3, async interface to the Hilo API
 Project-URL: Repository, https://github.com/dvd-dev/python-hilo
 Author-email: David Vallee Delisle <me@dvd.dev>

python_hilo-2026.11.1/doc/graphql/onAnyDeviceUpdated-tstat.json

@@ -0,0 +1,52 @@
+{
+  "data": {
+    "onAnyDeviceUpdated": {
+      "deviceType": "tstat",
+      "locationHiloId": "urn:hilo:crm:00000-abcdef:0",
+      "transmissionTime": "2026-10-29T22:44:57.250Z",
+      "operationId": "00000000-0000-0000-0000-000000000003",
+      "status": "REPORT",
+      "device": {
+        "deviceType": "tstat",
+        "hiloId": "urn:hilo:philo:1a2b3c4d5e6f0001:0",
+        "physicalAddress": "1A2B3C4D5E6F0001",
+        "connectionStatus": "CONNECTED",
+        "ambientHumidity": 0,
+        "gDState": "EXCLUDED",
+        "version": "21",
+        "zigbeeVersion": "22",
+        "ambientTemperature": {
+          "value": 18,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "ambientTempSetpoint": {
+          "value": 15,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "maxAmbientTempSetpoint": {
+          "value": 30,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "minAmbientTempSetpoint": {
+          "value": 5,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "maxAmbientTempSetpointLimit": {
+          "value": 30,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "minAmbientTempSetpointLimit": {
+          "value": 5,
+          "kind": "DEGREE_CELSIUS"
+        },
+        "heatDemand": 0,
+        "power": {
+          "value": null,
+          "kind": "WATT"
+        },
+        "mode": "UNKNOWN",
+        "allowedModes": []
+      }
+    }
+  }
+}

{python_hilo-2026.10.2 → python_hilo-2026.11.1}/pyhilo/api.py

@@ -491,6 +491,12 @@ class API:
         req: list[dict[str, Any]] = await self.async_request("get", url)
         return (req[0]["id"], req[0]["locationHiloId"])
 
+    async def get_rate_plan(self, location_id: int) -> str:
+        """Return the current rate plan name of a location (e.g. "Flex", "D", "CH")."""
+        url = f"{API_AUTOMATION_ENDPOINT}/Locations/{location_id}"
+        location: dict[str, Any] = await self.async_request("get", url)
+        return str(location["ratePlan"]["current"])
+
     def set_device_cache(self, devices: list[dict[str, Any]]) -> None:
         """Store devices received from SignalR DeviceListInitialValuesReceived.
 
@@ -585,6 +591,18 @@ class API:
         LOG.debug("Device Attribute URL is %s", url)
         await self.async_request("put", url, json={key.hilo_attribute: value})
 
+    async def _set_device_attributes(
+        self,
+        device: HiloDevice,
+        attributes: dict[str, Union[str, float, int, None]],
+    ) -> None:
+        """Sets several device attributes in a single request."""
+        url = self._get_url(
+            f"Devices/{device.id}/Attributes", location_id=device.location_id
+        )
+        LOG.debug("Device Attributes URL is %s", url)
+        await self.async_request("put", url, json=attributes)
+
     async def get_event_notifications(self, location_id: int) -> dict[str, Any]:
         """This will return events notifications
         Event types:

{python_hilo-2026.10.2 → python_hilo-2026.11.1}/pyhilo/const.py

@@ -11,7 +11,7 @@ INSTANCE_ID: Final = str(uuid.uuid4())[24:]
 LOG: Final = logging.getLogger(__package__)
 DEFAULT_STATE_FILE: Final = "hilo_state.yaml"
 REQUEST_RETRY: Final = 9
-PYHILO_VERSION: Final = "2026.10.02"
+PYHILO_VERSION: Final = "2026.11.01"
 # TODO: Find a way to keep previous line in sync with pyproject.toml automatically
 
 CONTENT_TYPE_FORM: Final = "application/x-www-form-urlencoded"
@@ -219,15 +219,21 @@ HILO_READING_TYPES: Final = {
     "BatteryPercent": "Percentage",
     "Co2": "PPM",
     "ColorTemperature": "Integer",
+    "CoolTemperatureSet": "Celsius",
+    "CurrentState": "null",
     "CurrentTemperature": "Celsius",
     "Disconnected": "null",
     "DrmsState": "OnOff",
+    "FanMode": "null",
+    "FanSpeed": "null",
     "firmwareVersion": "null",
     "Heating": "Percentage",
     "Hue": "Integer",
     "Humidity": "Percentage",
     "Intensity": "Percentage",
+    "MaxCoolSetpoint": "Celsius",
     "MaxTempSetpoint": "Celsius",
+    "MinCoolSetpoint": "Celsius",
     "MinTempSetpoint": "Celsius",
     "Noise": "DB",
     "onlineStatus": "null",
@@ -237,6 +243,9 @@ HILO_READING_TYPES: Final = {
     "Saturation": "Integer",
     "Status": "OnOff",
     "TargetTemperature": "Celsius",
+    "Thermostat24VAllowedFanMode": "null",
+    "Thermostat24VAllowedMode": "null",
+    "Thermostat24VMode": "null",
     "Unpaired": "null",
     "WifiStatus": "Integer",
     "zigBeePairingActivated": "OnOff",

{python_hilo-2026.10.2 → python_hilo-2026.11.1}/pyhilo/device/__init__.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import UTC, datetime
 from typing import TYPE_CHECKING, Any, Dict, Union, cast
 
 from pyhilo.const import (
@@ -62,7 +62,7 @@ class HiloDevice:
                     "deviceId": self.id,
                     "hiloId": self.hilo_id,
                     "locationId": self.location_id,
-                    "timeStampUTC": datetime.utcnow().isoformat(),
+                    "timeStampUTC": datetime.now(UTC).isoformat(),
                     "value": value,
                     "device_attribute": DeviceAttribute(orig_att, reading_att),
                 }
@@ -127,7 +127,7 @@ class HiloDevice:
                     **{
                         "deviceId": self.id,
                         "locationId": self.location_id,
-                        "timeStampUTC": datetime.utcnow().isoformat(),
+                        "timeStampUTC": datetime.now(UTC).isoformat(),
                         "value": value,
                         "device_attribute": attribute,
                     }  # type: ignore
@@ -136,6 +136,40 @@ class HiloDevice:
         else:
             LOG.warning("%s Invalid attribute %s for device", self._tag, attribute)
 
+    async def set_attributes(
+        self, attributes: Dict[str, Union[str, int, float, None]]
+    ) -> None:
+        """Send several attributes to the device in a single request.
+
+        Some devices reject partial writes: 24 V thermostats require the mode
+        and both setpoints to be sent together, even when only one of them
+        changed.
+
+        This differs from set_attribute() on two deliberate points:
+
+        - it does not check settable_attributes. Hilo advertises only
+          ['Disconnected'] as settable on those thermostats, while the API does
+          accept and apply the write.
+        - it does not update the readings optimistically. The new values come
+          back through the normal read path, which makes a read-back an actual
+          confirmation rather than an echo.
+        """
+        payload: Dict[str, Union[str, int, float, None]] = {}
+        for attribute, value in attributes.items():
+            dev_attribute = self._api.dev_atts(attribute)
+            if not isinstance(dev_attribute, DeviceAttribute):
+                LOG.warning(
+                    "%s Unable to set attribute %s: Unknown attribute",
+                    self._tag,
+                    attribute,
+                )
+                continue
+            payload[dev_attribute.hilo_attribute] = value
+        if not payload:
+            return
+        LOG.debug("%s Setting attributes %s", self._tag, payload)
+        await self._api._set_device_attributes(self, payload)
+
     def get_attribute(self, attribute: str) -> Union[DeviceReading, None]:
         if dev_attribute := cast(DeviceAttribute, self._api.dev_atts(attribute)):
             return self._get_attribute(dev_attribute)

python_hilo-2026.11.1/pyhilo/device/climate.py

@@ -0,0 +1,247 @@
+"""Climate object."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+from pyhilo import API
+from pyhilo.const import LOG, STATE_UNKNOWN
+from pyhilo.device import HiloDevice
+
+# Attributes reported only by low voltage (24 V) thermostats. Thermostat24VMode
+# is emitted solely by GraphqlValueMapper._build_lowvoltage_thermostat(), which
+# makes its presence an exact discriminator.
+LOW_VOLTAGE_MODE = "thermostat24_v_mode"
+LOW_VOLTAGE_ALLOWED_MODES = "thermostat24_v_allowed_mode"
+LOW_VOLTAGE_ALLOWED_FAN_MODES = "thermostat24_v_allowed_fan_mode"
+
+
+def as_list(value: Any) -> list[str]:
+    """Return a list of strings from a Hilo list attribute.
+
+    Hilo sends those either as a real list or as a comma separated string
+    depending on the transport, so accept both.
+    """
+    if value is None or value in ("", STATE_UNKNOWN):
+        return []
+    if isinstance(value, (list, tuple, set)):
+        return [str(v).strip() for v in value if str(v).strip()]
+    return [v.strip() for v in str(value).split(",") if v.strip()]
+
+
+class Climate(HiloDevice):
+    """
+    Represents a climate device within the Hilo ecosystem.
+
+    This class provides methods to interact with and control climate-related
+    devices such as thermostats.
+    """
+
+    def __init__(
+        self, api: API, **kwargs: dict[str, str | int | dict[Any, Any]]
+    ) -> None:
+        """Initialize the Climate object.
+
+        Args:
+            api: The Hilo API instance.
+            **kwargs: Keyword arguments containing device data.
+        """
+        super().__init__(api, **kwargs)
+        LOG.debug("Setting up Climate device: %s", self.name)
+
+    @property
+    def current_temperature(self) -> float:
+        """
+        Gets the current temperature reported by the device.
+
+        Returns:
+            float: The current temperature.
+        """
+        return cast(float, self.get_value("current_temperature", 0))
+
+    @property
+    def target_temperature(self) -> float:
+        """
+        Gets the target temperature set for the device.
+
+        Returns:
+            float: The target temperature.
+        """
+        return cast(float, self.get_value("target_temperature", 0))
+
+    @property
+    def max_temp(self) -> float:
+        """
+        Gets the maximum temperature setpoint allowed for the device.
+
+        Returns:
+            float: The maximum temperature. Defaults to 36.0 if not defined.
+        """
+        value = self.get_value("max_temp_setpoint", 0)
+
+        if value is None or value == 0:
+            return 36.0
+        return float(value)
+
+    @property
+    def min_temp(self) -> float:
+        """
+        Gets the minimum temperature setpoint allowed for the device.
+
+        Returns:
+            float: The minimum temperature. Defaults to 5.0 if not defined.
+        """
+        value = self.get_value("min_temp_setpoint", 0)
+
+        if value is None or value == 0:
+            return 5.0
+        return float(value)
+
+    @property
+    def hvac_action(self) -> str:
+        """
+        Gets the current HVAC action of the device.
+
+        Returns:
+            str: 'heating' if heating is active, 'idle' otherwise.
+        """
+        attr = self.get_value("heating", 0)
+        return "heating" if attr > 0 else "idle"
+
+    async def async_set_temperature(self, temperature: float) -> None:
+        """
+        Sets the target temperature of the device.
+
+        Args:
+            temperature: The desired target temperature.
+        """
+        if self.is_low_voltage:
+            await self.async_set_low_voltage_state(target_temperature=temperature)
+            return
+        if temperature != self.target_temperature:
+            LOG.info("%s Setting temperature to %s", self._tag, temperature)
+            await self.set_attribute("target_temperature", str(temperature))
+
+    def _optional_float(self, attribute: str) -> float | None:
+        """Return a numeric reading, or None when absent or unusable."""
+        value = self.get_value(attribute, None)
+        if value is None or value == STATE_UNKNOWN:
+            return None
+        try:
+            return float(value)
+        except (TypeError, ValueError):
+            return None
+
+    def _optional_str(self, attribute: str) -> str | None:
+        """Return a textual reading, or None when absent or unusable."""
+        value = self.get_value(attribute, None)
+        if value is None or value == STATE_UNKNOWN:
+            return None
+        return str(value)
+
+    @property
+    def is_low_voltage(self) -> bool:
+        """Whether this is a low voltage (24 V) thermostat.
+
+        Baseboard thermostats report none of the 24 V attributes and therefore
+        keep their heat-only behaviour.
+        """
+        return self.low_voltage_mode is not None
+
+    @property
+    def low_voltage_mode(self) -> str | None:
+        """Operating mode reported by a 24 V thermostat, in Hilo's vocabulary."""
+        return self._optional_str(LOW_VOLTAGE_MODE)
+
+    @property
+    def allowed_modes(self) -> list[str]:
+        """Mode vocabulary advertised by a 24 V thermostat."""
+        return as_list(self.get_value(LOW_VOLTAGE_ALLOWED_MODES, None))
+
+    @property
+    def fan_mode(self) -> str | None:
+        """Current fan mode, when the device reports one."""
+        return self._optional_str("fan_mode")
+
+    @property
+    def allowed_fan_modes(self) -> list[str]:
+        """Fan mode vocabulary advertised by a 24 V thermostat."""
+        return as_list(self.get_value(LOW_VOLTAGE_ALLOWED_FAN_MODES, None))
+
+    @property
+    def current_state(self) -> str | None:
+        """Raw running state reported by a 24 V thermostat.
+
+        Exposed for consumers, but deliberately not mapped to hvac_action yet:
+        its vocabulary has not been observed in enough operating conditions.
+        """
+        return self._optional_str("current_state")
+
+    @property
+    def cool_setpoint(self) -> float | None:
+        """Cooling setpoint of a 24 V thermostat."""
+        return self._optional_float("cool_temperature_set")
+
+    @property
+    def min_cool_setpoint(self) -> float | None:
+        """Lowest cooling setpoint allowed by a 24 V thermostat."""
+        return self._optional_float("min_cool_setpoint")
+
+    @property
+    def max_cool_setpoint(self) -> float | None:
+        """Highest cooling setpoint allowed by a 24 V thermostat."""
+        return self._optional_float("max_cool_setpoint")
+
+    @property
+    def current_humidity(self) -> int | None:
+        """Ambient humidity, rounded to the nearest percent.
+
+        GraphqlValueMapper reports 0 for a device without a humidity sensor,
+        not None, so a reading of 0 is a real (if degenerate) value rather
+        than an absent one.
+        """
+        value = self._optional_float("humidity")
+        return None if value is None else round(value)
+
+    async def async_set_low_voltage_state(
+        self,
+        mode: str | None = None,
+        target_temperature: float | None = None,
+        cool_setpoint: float | None = None,
+        fan_mode: str | None = None,
+    ) -> None:
+        """Write the mode and both setpoints together.
+
+        24 V thermostats reject partial writes: the mode and both setpoints
+        have to be sent in one request even when only one of them changed.
+        Arguments left out keep their current value; values the device does
+        not report at all are omitted from the payload.
+
+        Raises:
+            ValueError: The mode isn't given and the device hasn't reported
+                one either. Silently dropping Thermostat24VMode from the
+                payload in that case would send setpoints without a mode,
+                exactly the partial write this method exists to prevent.
+        """
+        resolved_mode = mode if mode is not None else self.low_voltage_mode
+        if resolved_mode is None:
+            raise ValueError(
+                f"{self._tag} Cannot set low voltage state: no mode was given "
+                "and the device has not reported one. Pass mode explicitly."
+            )
+        payload: dict[str, str | int | float | None] = {
+            "Thermostat24VMode": resolved_mode,
+            "TargetTemperature": (
+                target_temperature
+                if target_temperature is not None
+                else self._optional_float("target_temperature")
+            ),
+            "CoolTemperatureSet": (
+                cool_setpoint if cool_setpoint is not None else self.cool_setpoint
+            ),
+        }
+        if fan_mode is not None:
+            payload["FanMode"] = fan_mode
+        payload = {k: v for k, v in payload.items() if v is not None}
+        LOG.info("%s Setting low voltage state to %s", self._tag, payload)
+        await self.set_attributes(payload)

{python_hilo-2026.10.2 → python_hilo-2026.11.1}/pyhilo/device/graphql_value_mapper.py

@@ -84,7 +84,9 @@ class GraphqlValueMapper:
             )
         attributes.append(
             self.build_attribute(
-                device["hiloId"], "Disconnected", device["connectionStatus"] == 2
+                device["hiloId"],
+                "Disconnected",
+                device["connectionStatus"] == "DISCONNECTED",
             ),
         )
         if device.get("power") is not None:
@@ -105,7 +107,9 @@ class GraphqlValueMapper:
         )
         attributes.append(
             self.build_attribute(
-                device["hiloId"], "Disconnected", device["connectionStatus"] == 2
+                device["hiloId"],
+                "Disconnected",
+                device["connectionStatus"] == "DISCONNECTED",
             )
         )  # Offline
         attributes.append(
@@ -174,11 +178,14 @@ class GraphqlValueMapper:
                 device["hiloId"], "ZigbeeVersion", device["zigbeeVersion"]
             )
         )
-        attributes.append(
-            self.build_attribute(
-                device["hiloId"], "Humidity", device.get("ambientHumidity") or 0
+        # Some models (e.g. the HT402) have no humidity sensor and always
+        # report 0, so only keep a real, non-zero reading.
+        if device.get("ambientHumidity"):
+            attributes.append(
+                self.build_attribute(
+                    device["hiloId"], "Humidity", device["ambientHumidity"]
+                )
             )
-        )
         if device.get("allowedModes") is not None:
             attributes.append(
                 self.build_attribute(
@@ -448,7 +455,7 @@ class GraphqlValueMapper:
             self.build_attribute(
                 device["hiloId"],
                 "Disconnected",
-                device["connectionStatus"] == "Disconnected",
+                device["connectionStatus"] == "DISCONNECTED",
             ),
         ]
 

{python_hilo-2026.10.2 → python_hilo-2026.11.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-hilo"
-version = "2026.10.2"
+version = "2026.11.1"
 description = "A Python3, async interface to the Hilo API"
 readme = "README.md"
 requires-python = ">=3.13"