nwp500-python 9.4.1__py3-none-any.whl → 9.4.3__py3-none-any.whl

nwp500/models/status.py

@@ -240,7 +240,9 @@ class DeviceStatus(NavienBaseModel):
             "the current setpoint, in Watt-hours. This is NOT a fixed tank "
             "size: it tracks the setpoint, rising about 140 Wh per 0.5 degC "
             "of setpoint increase. Use it as the cost of a full recovery, "
-            "not as the tank's total heat content."
+            "not as the tank's total heat content. During a TOU window that "
+            "raises hp_upper_on_temp_setting, the reference is 2 degC "
+            "higher (about 108.5 degF)."
         ),
         json_schema_extra={
             "unit_of_measurement": "Wh",
@@ -252,9 +254,10 @@ class DeviceStatus(NavienBaseModel):
         description=(
             "Energy still NEEDED to bring the tank up to the setpoint, in "
             "Watt-hours - a heating deficit, not stored energy. It falls as "
-            "the tank heats and reaches zero at the setpoint. Despite the "
-            "protocol name 'availableEnergyCapacity' it is the inverse of "
-            "available energy."
+            "the tank heats and reaches zero at the setpoint - or, during a "
+            "TOU window that raises hp_upper_on_temp_setting, about 2 degC "
+            "short of it. Despite the protocol name 'availableEnergyCapacity' "
+            "it is the inverse of available energy."
         ),
         json_schema_extra={
             "unit_of_measurement": "Wh",
@@ -276,8 +279,8 @@ class DeviceStatus(NavienBaseModel):
     recirc_error_status: int = Field(description="Recirculation error status")
     current_inst_power: float = Field(
         description=(
-            "Current instantaneous power consumption in Watts. "
-            "Does not include heating element power when active"
+            "Current instantaneous power consumption of the whole unit "
+            "in Watts, including heating element power when active"
         ),
         json_schema_extra={
             "unit_of_measurement": "W",
@@ -958,12 +961,19 @@ class DeviceStatus(NavienBaseModel):
         estimate of what can actually be drawn - water colder than that
         still holds heat, but not heat you can wash with.
 
-        Robust in practice: ``full_recovery_energy`` is bimodal, taking
-        one of two values 2 degC apart at a fixed setpoint, but both
-        fields shift together so the difference is unaffected. Checked
-        against the tank thermistors over 12275 samples, the implied tank
+        Usually robust: ``full_recovery_energy`` is bimodal, taking one
+        of two values 2 degC apart at a fixed setpoint, but both fields
+        shift together so the difference is unaffected. Checked against
+        the tank thermistors over 12275 samples, the implied tank
         temperature agrees to a standard deviation of 0.57 degF.
 
+        The exception is a Time-of-Use window, when
+        ``hp_upper_on_temp_setting`` is raised to about the setpoint.
+        There ``energy_to_setpoint`` reaches 0 while the tank is still up
+        to about 2 degC short. This value then equals
+        ``full_recovery_energy`` and under-reads by up to about 560 Wh on
+        a 65-gallon tank. In that case, use the thermistors.
+
         Returns:
             Drawable energy in Watt-hours, clamped at zero.
         """

nwp500/mqtt/control.py

@@ -27,7 +27,7 @@ weekly reservation) have no method.
 """
 
 import logging
-from collections.abc import Awaitable, Callable, Sequence
+from collections.abc import Awaitable, Callable, Mapping, Sequence
 from datetime import UTC, datetime
 from typing import Any
 
@@ -120,6 +120,120 @@ def validate_recirculation_schedule(schedule: RecirculationSchedule) -> None:
                 )
 
 
+RESERVATION_ENTRY_FIELDS = ("enable", "week", "hour", "min", "mode", "param")
+# DhwOperationSetting ids are contiguous (1-6), so a range check covers them.
+_DHW_MODE_MIN = min(DhwOperationSetting)
+_DHW_MODE_MAX = max(DhwOperationSetting)
+
+
+def validate_reservation_entries(
+    reservations: Sequence[Mapping[str, Any]],
+    features: DeviceFeature | None = None,
+) -> None:
+    """Check raw reservation entries before they are written to the device.
+
+    :class:`~nwp500.models.ReservationEntry` accepts any integers so that
+    device read-backs always parse; writes are held to what the device
+    accepts. Each entry must carry the six protocol fields as plain
+    integers (a ``bool`` or ``float`` is rejected): ``enable`` 1 (off) or
+    2 (on), ``week`` a day bitfield (2-254, bit 0 clear), ``hour`` 0-23,
+    ``min`` 0-59 and ``mode`` a :class:`~nwp500.enums.DhwOperationSetting`
+    id.
+
+    ``param`` is the setpoint in half-degrees Celsius. With ``features``
+    it must lie within the range the heater reports,
+    ``dhw_temperature_min_raw`` to ``dhw_temperature_max_raw``; without
+    them, only within the single byte the protocol carries (0-255).
+
+    Args:
+        reservations: Raw entry dicts, as passed to ``update_reservations``.
+        features: The device's feature data, for its setpoint limits.
+
+    Raises:
+        ParameterValidationError: On a missing field, a non-integer field,
+            or a bad ``enable`` or ``week``.
+        RangeValidationError: On ``hour``, ``min``, ``mode`` or ``param``
+            outside its range.
+    """
+    for index, entry in enumerate(reservations, start=1):
+        _check_reservation_entry(index, entry)
+    if features is not None:
+        _check_reservation_setpoints(reservations, features)
+
+
+def _check_reservation_entry(index: int, entry: Mapping[str, Any]) -> None:
+    """Check one entry's fields, except ``param`` against device limits."""
+    for name in RESERVATION_ENTRY_FIELDS:
+        if name not in entry:
+            raise ParameterValidationError(
+                f"entry {index}: missing field {name!r}",
+                parameter=f"reservation[{index}].{name}",
+            )
+        if not _is_int(entry[name]):
+            raise ParameterValidationError(
+                f"entry {index}: {name} must be an integer",
+                parameter=f"reservation[{index}].{name}",
+                value=entry[name],
+            )
+
+    enable = entry["enable"]
+    if enable not in (1, 2):
+        raise ParameterValidationError(
+            f"entry {index}: enable must be 1 (off) or 2 (on), got {enable}",
+            parameter=f"reservation[{index}].enable",
+            value=enable,
+        )
+    week = entry["week"]
+    if not (0 < week <= 254 and week % 2 == 0):
+        raise ParameterValidationError(
+            f"entry {index}: week={week} is not a day bitfield "
+            "(Sun=128 .. Sat=2, at least one day, bit 0 clear)",
+            parameter=f"reservation[{index}].week",
+            value=week,
+        )
+
+    ranges = [
+        ("hour", 0, 23),
+        ("min", 0, 59),
+        ("mode", int(_DHW_MODE_MIN), int(_DHW_MODE_MAX)),
+        ("param", 0, 255),
+    ]
+    for name, low, high in ranges:
+        value = entry[name]
+        if not low <= value <= high:
+            raise RangeValidationError(
+                f"entry {index}: {name} must be between {low} and {high}, "
+                f"got {value}",
+                field=f"reservation[{index}].{name}",
+                value=value,
+                min_value=low,
+                max_value=high,
+            )
+
+
+def _check_reservation_setpoints(
+    reservations: Sequence[Mapping[str, Any]], features: DeviceFeature
+) -> None:
+    """Hold each entry's ``param`` to the setpoint range the heater reports.
+
+    Both ``param`` and the feature limits are half-degrees Celsius, so they
+    compare without conversion.
+    """
+    low = features.dhw_temperature_min_raw
+    high = features.dhw_temperature_max_raw
+    for index, entry in enumerate(reservations, start=1):
+        param = entry["param"]
+        if not low <= param <= high:
+            raise RangeValidationError(
+                f"entry {index}: param={param} (half-degrees C) is outside "
+                f"the device's setpoint range {low}-{high}",
+                field=f"reservation[{index}].param",
+                value=param,
+                min_value=low,
+                max_value=high,
+            )
+
+
 class MqttDeviceController:
     """
     Manages device control commands for Navien devices.
@@ -569,6 +683,27 @@ class MqttDeviceController:
             [preferred_to_half_celsius(temperature)],
         )
 
+    async def _get_reservation_limits(self, device: Device) -> DeviceFeature:
+        """Fetch the feature data that carries the device's setpoint range.
+
+        Mirrors :func:`~nwp500.command_decorators.requires_capability`: a
+        failed fetch (a feature-response timeout, a lost connection) is
+        reported as :class:`DeviceCapabilityError`, like a missing result.
+        """
+        capability = "dhw_temperature_setting_use"
+        message = "Unable to validate reservation temperatures"
+        try:
+            features = await self._get_device_features(device)
+        except DeviceCapabilityError:
+            raise
+        except Exception as e:
+            raise DeviceCapabilityError(capability, f"{message}: {e!s}") from e
+        if features is None:
+            raise DeviceCapabilityError(
+                capability, f"{message}: device features not available."
+            )
+        return features
+
     async def update_reservations(
         self,
         device: Device,
@@ -579,6 +714,11 @@ class MqttDeviceController:
         """
         Update programmed reservations for temperature/mode changes.
 
+        Every entry is checked before anything is sent (see
+        :func:`validate_reservation_entries`). Each ``param`` is held to
+        the setpoint range the heater reports in its feature data, which is
+        requested from the device if it is not cached yet.
+
         Args:
             device: Device object
             reservations: List of reservation entries
@@ -586,7 +726,21 @@ class MqttDeviceController:
 
         Returns:
             Publish packet ID
+
+        Raises:
+            ParameterValidationError: If an entry has a missing or
+                non-integer field, or a bad ``enable`` or ``week``.
+            RangeValidationError: If an entry's ``hour``, ``min`` or
+                ``mode`` is out of range, or its ``param`` is outside the
+                device's setpoint range.
+            DeviceCapabilityError: If the device's feature data, and so
+                its setpoint range, is not available.
         """
+        validate_reservation_entries(reservations)
+        if reservations:
+            features = await self._get_reservation_limits(device)
+            _check_reservation_setpoints(reservations, features)
+
         # See docs/reference/protocol/mqtt_protocol.rst "Reservations" for the
         # command code (16777226) and the reservation object fields
         # (enable, week, hour, min, mode, param).

nwp500/mqtt/subscriptions.py

@@ -40,7 +40,12 @@ from ..mqtt_events import (
 from ..topic_builder import MqttTopicBuilder
 from .state_tracker import DeviceStateTracker
 from .types import QoS, to_awscrt_qos
-from .utils import get_response_data, redact_topic, topic_matches_pattern
+from .utils import (
+    get_response_data,
+    redact_mac,
+    redact_topic,
+    topic_matches_pattern,
+)
 
 if TYPE_CHECKING:
     from ..device_info_cache import MqttDeviceInfoCache
@@ -614,13 +619,45 @@ class MqttSubscriptionManager:
         """
 
         def handler(topic: str, message: dict[str, Any]) -> None:
+            # Every branch that declines a message says so at debug level.
+            # Silence here is expensive to diagnose: a caller watching for a
+            # reply that never reaches its callback cannot tell a dropped
+            # message from one the cloud never sent, and the two want
+            # opposite fixes. The logs are the only evidence either way.
+            #
+            # Each log is guarded: redact_topic runs a dozen regexes, and
+            # these branches are the normal case for a handler registered
+            # under the device wildcard, which sees every message for that
+            # device and keeps only its own.
             if topic_suffix and not topic.endswith(topic_suffix):
+                if _logger.isEnabledFor(logging.DEBUG):
+                    _logger.debug(
+                        "Ignoring a message on %s: the topic does not end "
+                        "with %r, which this handler requires",
+                        redact_topic(topic),
+                        topic_suffix,
+                    )
                 return
             try:
                 data = get_response_data(message, key)
                 if not data:
+                    if _logger.isEnabledFor(logging.DEBUG):
+                        _logger.debug(
+                            "Ignoring a message on %s: no %s data to parse "
+                            "as %s",
+                            redact_topic(topic),
+                            f"{key!r}" if key else "response",
+                            model.__name__,
+                        )
                     return
                 if only_mac and not _same_device(data, message, only_mac):
+                    if _logger.isEnabledFor(logging.DEBUG):
+                        _logger.debug(
+                            "Ignoring a message on %s: it names another "
+                            "device, not %s",
+                            redact_topic(topic),
+                            redact_mac(only_mac),
+                        )
                     return
 
                 parsed = parse(data) if parse else model.model_validate(data)

nwp500/reservations.py

@@ -17,6 +17,7 @@ from typing import TYPE_CHECKING, Any
 from .converters import device_bool_from_python
 from .encoding import build_reservation_entry, encode_week_bitfield
 from .models import ReservationEntry, ReservationSchedule
+from .mqtt.control import validate_reservation_entries
 
 if TYPE_CHECKING:
     from .models import Device
@@ -119,7 +120,22 @@ async def update_reservations_confirmed(
         what was just written. This avoids resolving on a stale/unrelated
         ``rsv/rd`` message (e.g. from a concurrent read or a previous
         write) that happens to arrive in the same window.
+
+        Entries are checked before anything is sent; see
+        :func:`nwp500.mqtt.control.validate_reservation_entries`.
+
+    Raises:
+        ParameterValidationError: If an entry has a missing or non-integer
+            field, or a bad ``enable`` or ``week``.
+        RangeValidationError: If an entry's ``hour``, ``min`` or ``mode``
+            is out of range, or its ``param`` is outside the device's
+            setpoint range.
     """
+    # Structural checks first, so a bad entry neither subscribes nor builds
+    # a coerced expectation (``ReservationEntry`` turns ``True`` into 1).
+    # The setpoint range is checked by ``update_reservations`` against the
+    # device's feature data, still before anything is published.
+    validate_reservation_entries(reservations)
     expected = ReservationSchedule(
         reservationUse=device_bool_from_python(enabled),
         reservation=[ReservationEntry(**entry) for entry in reservations],

{nwp500_python-9.4.1.dist-info → nwp500_python-9.4.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 9.4.1
+Version: 9.4.3
 Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
 Home-page: https://github.com/eman/nwp500-python
 Author: Emmanuel Levijarvi

{nwp500_python-9.4.1.dist-info → nwp500_python-9.4.3.dist-info}/RECORD

@@ -16,7 +16,7 @@ nwp500/field_factory.py,sha256=DMQGOLZU5S-sAdT0Ue5nkmqyMAEMlGvCkEg2C8eCkB8,5200
 nwp500/mqtt_events.py,sha256=2qWDkWEzoMurZw5G6WwzL9nEtlvJ-GUCs_HvMa0024E,10148
 nwp500/openei.py,sha256=2gM3hEwrUvUEFykDgN-pKkamWomGuQNVT46XzFwOlxA,7071
 nwp500/py.typed,sha256=vlGtiygNDDmA_Ji2HjDl1SBJEcvpIC6cANFx_GonPMk,69
-nwp500/reservations.py,sha256=0i8QJ5SD8oaXX9VjLAGtx5TNbxXoTVh67lVmGneqpgU,12553
+nwp500/reservations.py,sha256=il5f0xVM0Kxanp5WsgpYwLjUgSgnVP-8hVurIh-aix0,13381
 nwp500/temperature.py,sha256=O9pyjFaMstzfKxWtQTUDNP12YOJbS9rSwBH76s4p4MY,7982
 nwp500/topic_builder.py,sha256=AmFFY-_b6qpS3VRzuGSyNYv6CPYDc6y-LrNDoWVz9s0,4137
 nwp500/tou_schedule.py,sha256=sPwceU3sXbEqJCrFMsNZsZRg4DE4TsROkgVN-qXzlk0,3675
@@ -39,7 +39,7 @@ nwp500/models/feature.py,sha256=7z1pDoW0LQGxv8__AlQn5M35lZRKgeybgwfnw2OCKIM,1543
 nwp500/models/firmware.py,sha256=cyp9fnewmenvQnsDcTXAsCz-298tqrdswOs1CSZ4duc,1490
 nwp500/models/mqtt_models.py,sha256=1Etfn0lqiWvoUsW2niT6wXdZtNvN0sGjn7F1uPJQ9yU,774
 nwp500/models/schedule.py,sha256=qQzWJP7Ik1x47GRYv6tfWeF2Ja4ONVkbLPkhK-mEjcs,11605
-nwp500/models/status.py,sha256=VOm6ARy3v8AITv04v1FBVjVoegu_fCpqKwdwWfHpXnI,37722
+nwp500/models/status.py,sha256=Riq42GD56n7UPALTF3tdOrlRziLJOH2lZwK4wWmv5UE,38358
 nwp500/models/tou.py,sha256=wwxhYwCSY4JIWgVDa2SlwUzlCEDqqRBN994NrkqdVg8,7018
 nwp500/mqtt/__init__.py,sha256=WYdBfpW-3tSLdFMObDWCX4pcLm_IqRBDluJqkPnQBN4,974
 nwp500/mqtt/_control_commands.py,sha256=NksQ7Fku_4Vswmyi3LONwse33MN9hJUFOF4qhdw1-80,8775
@@ -47,17 +47,17 @@ nwp500/mqtt/_device_subscriptions.py,sha256=rnTHQQ4l9i-pv1VAqnxOr106CFyS3yLA0I1n
 nwp500/mqtt/client.py,sha256=vEj5mZscGR5u-XePnmqvpDqGlYcL68tb_K_pe1SuVIQ,49284
 nwp500/mqtt/command_queue.py,sha256=wiNxNzQe6psMqa0PQ3wzatf9N6IDrtDwpl4DPq1kDdk,6517
 nwp500/mqtt/connection.py,sha256=fNrOtBJxsqk054YDUmipnwI3yfBHx1anXb_07e0X9XU,17712
-nwp500/mqtt/control.py,sha256=tw4Ih7ZClpHIE2oqcPQZuw5E174RiiJvuccPKYQWsr0,41071
+nwp500/mqtt/control.py,sha256=VRoX80Nm5hEOAr-13vHG9ve1OUNVfNTQI5zceBG4flA,47381
 nwp500/mqtt/diagnostics.py,sha256=NDkPExS4FObGCWJXAhENqNQUm8Bda5GDBR7_o3ylSAo,15723
 nwp500/mqtt/periodic.py,sha256=WKyyO61yTZJfOm9JAtBp6Onyk-XNj0U544sYMCKvTZw,14729
 nwp500/mqtt/reconnection.py,sha256=g9OuLlf1lVx_pbV6d7QHq7IcCflKkypPYSLSDTp58tQ,16499
 nwp500/mqtt/state_tracker.py,sha256=uZlDFNYn7DOXmXPbk-8jXva_QKEvLES9T_BYbQSkhvM,6364
-nwp500/mqtt/subscriptions.py,sha256=iCcXwP8KDRXqShlxdkbxGFk9e11i4YrD88kWKcp8cP8,38094
+nwp500/mqtt/subscriptions.py,sha256=lBO4IM_5bQbexhARy-PNf36aKNJNx9iiWQMgiMe5Y_0,39853
 nwp500/mqtt/types.py,sha256=86R7gwsc1XabA_ABWeALeC5EImlTziFFn1DrP1x8Yy4,1605
 nwp500/mqtt/utils.py,sha256=qXafc9GDpVY9o9o8DQLKBM8t0E401j3EPpZ0rC4snCY,13415
-nwp500_python-9.4.1.dist-info/licenses/LICENSE.txt,sha256=EUOsypJ3iEqJ-9tdo_TSZHwB0Rd-7p0JzToEI5CMBJU,1085
-nwp500_python-9.4.1.dist-info/METADATA,sha256=O5IuUShR2IRTsVTgs_C_sl12kP4Y9TdGLAOq2PuSTmQ,5091
-nwp500_python-9.4.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-nwp500_python-9.4.1.dist-info/entry_points.txt,sha256=p8vGDEbUIOT_TzDG-XnJ3lw-9yaeHrDPNN7fAx4-78I,52
-nwp500_python-9.4.1.dist-info/top_level.txt,sha256=DRPIenxKnssWeaetq428gYfwrKjLGN1z2NOtztIvxZE,7
-nwp500_python-9.4.1.dist-info/RECORD,,
+nwp500_python-9.4.3.dist-info/licenses/LICENSE.txt,sha256=EUOsypJ3iEqJ-9tdo_TSZHwB0Rd-7p0JzToEI5CMBJU,1085
+nwp500_python-9.4.3.dist-info/METADATA,sha256=LWySo-xhXgEEApUxOXin2dM-DDlFTySXKVCt1Z_dIR4,5091
+nwp500_python-9.4.3.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+nwp500_python-9.4.3.dist-info/entry_points.txt,sha256=p8vGDEbUIOT_TzDG-XnJ3lw-9yaeHrDPNN7fAx4-78I,52
+nwp500_python-9.4.3.dist-info/top_level.txt,sha256=DRPIenxKnssWeaetq428gYfwrKjLGN1z2NOtztIvxZE,7
+nwp500_python-9.4.3.dist-info/RECORD,,