nwp500-python 9.2.1__tar.gz → 9.3.1__tar.gz

{nwp500_python-9.2.1 → nwp500_python-9.3.1}/.gitignore

@@ -49,6 +49,8 @@ build/*
 dist/*
 sdist/*
 docs/api/*
+docs/reference/api/*
+.obsidian/
 docs/_rst/*
 docs/_build/*
 cover/*

{nwp500_python-9.2.1 → nwp500_python-9.3.1}/CHANGELOG.rst

@@ -5,6 +5,269 @@ Changelog
 Unreleased
 ==========
 
+Version 9.3.1 (2026-08-29)
+==========================
+
+``NavienMqttClient.request_tou_settings()`` is removed. Not a breaking
+change in practice: the device never answered it, so no caller can have
+been getting a schedule out of it. Code that still names the method will
+now fail with ``AttributeError`` rather than time out. See Removed below.
+
+Added
+-----
+- **REST fields the cloud added since the models were written.**
+  ``/device/list`` now returns an ``error`` block (``errorCode``,
+  ``errorOccuredTime``) and the ``descaling`` block previously seen only
+  on ``/device/info``, and ``deviceInfo`` gained ``modelTypeCode`` and
+  ``installerId``. None of these were modelled, and ``NavienBaseModel``
+  ignores unknown keys, so all of them were silently discarded.
+  :class:`~nwp500.models.Device` gains optional ``error``
+  (:class:`~nwp500.models.DeviceErrorSummary`) and ``descaling``
+  (:class:`~nwp500.models.DescalingInfo`) sections, and
+  :class:`~nwp500.models.DeviceInfo` gains ``model_type_code`` and
+  ``installer_id``. ``error`` makes the device's last recorded fault
+  readable without an MQTT connection, including while the device is
+  offline. Every new field is optional, so responses that omit them - such
+  as ``/device/info``, which carries no ``error`` block - parse unchanged.
+  ``error_code`` is typed ``ErrorCode | int`` (validated left to right, so a
+  known code becomes an ``ErrorCode`` member and only an unknown one stays a
+  plain int) so an unrecognised code cannot make a whole listing unparseable. ``docs/openapi.yaml`` is
+  updated to match.
+
+Removed
+-------
+- **``request_tou_settings()`` removed - the device has no MQTT read for its
+  TOU schedule.** The method published a ``CommandCode.TOU_RESERVATION``
+  message to ``ctrl/tou/rd`` carrying only ``controllerSerialNumber``, then
+  waited for a reply on ``res/tou/rd``. No reply ever comes: a live device
+  with TOU provisioned (``program_reservation_use`` true, a valid controller
+  serial, and a plan the REST API returns in full) stayed silent for 45
+  seconds. ``ctrl/tou/rd`` with that command code is the *write* - it is what
+  :meth:`~nwp500.NavienMqttClient.configure_tou_schedule` publishes and what
+  the vendor app publishes from its TOU editor
+  (``TouScheduleViewmodel.setPublishMgppControlTou``) - and the device answers
+  on ``res/tou/rd`` only to confirm such a write. The vendor app reads TOU
+  over REST, which is the only TOU read the protocol has.
+
+  Beyond returning nothing, the call published a write-shaped command with no
+  schedule attached. This device ignored it - ``touStatus`` was unchanged
+  across repeated calls - but a firmware that took it at face value could read
+  it as "store an empty TOU schedule".
+
+  **Migration**: use :meth:`~nwp500.NavienAPIClient.get_tou_info`, which
+  returns the stored plan - rate name, utility, ZIP code and the seasonal
+  pricing intervals. The read itself is pure REST; it is keyed by the
+  controller serial number, which only the MQTT device-info response
+  publishes, so fetch that once and cache it.
+  :meth:`~nwp500.NavienMqttClient.subscribe_tou_response` is unaffected and
+  still delivers write confirmations. Enabling and disabling TOU
+  (:meth:`~nwp500.NavienMqttClient.set_tou_enabled`, command codes
+  ``TOU_ON``/``TOU_OFF``) is a separate path and is unaffected.
+
+Fixed
+-----
+- **CLI ``energy --months`` no longer duplicates ``--month`` output.**
+  ``handle_get_energy_request`` picked the view from the length of the
+  month list, so ``--months 5`` took the single-month branch and printed
+  the same daily breakdown as ``--month 5`` instead of the monthly
+  summary. The handler now takes an explicit ``daily`` flag set by the
+  option the user actually passed. ``energy`` also rejects ``--month``
+  and ``--months`` together rather than silently preferring ``--month``,
+  and validates the ``--months`` range and format the way ``--month``
+  already did. All of that validation now happens while Click parses the
+  arguments, so a bad invocation is a usage error (exit code 2) before any
+  authentication or MQTT connection is attempted - previously the command
+  body raised ``ClickException`` after connecting, where ``async_command``'s
+  catch-all reported it as an "Unexpected Error" with a traceback, and
+  anyone without working credentials saw an authentication failure instead
+  of the usage error. That catch-all now re-raises ``ClickException`` so any
+  command can report a usage error as itself.
+- **``DeviceFeature.mixing_valve_use`` now reads the device's actual key.**
+  The field was aliased to ``mixingValveUse``, but the device sends
+  ``mixingValueUse`` - "Value", not "Valve" - and the base model ignores
+  unknown keys, so the field silently reported its ``False`` default on
+  every device regardless of whether a thermostatic mixing valve was
+  supported. The CLI's "Mixing Valve" capability row was wrong for the
+  same reason. The misspelling is Navien's own: it appears in the vendor
+  app's ``KDResponseMgppDid$Feature`` class and in
+  ``docs/reference/protocol/device_features.rst``, which documented the
+  wire spelling correctly all along.
+
+- **``firmware_payload_capture.py`` captured almost nothing.** Its wildcards
+  covered ``cmd/{type}/{client_id}/res/#`` and the event topic, but the device
+  acknowledges control and query commands on
+  ``cmd/{type}/navilink-{mac}/{client_id}/res`` - which neither pattern
+  matches - so the device status and device info responses were missed, along
+  with every request published on the device path. A capture run recorded 2
+  payloads where it should have recorded 11. It now also subscribes to
+  ``cmd/{type}/navilink-{mac}/#``, which additionally picks up traffic from
+  other clients on the same device. Query results the device routes back to a
+  client-keyed topic, such as reservations and energy usage, were already
+  covered by the existing response wildcard.
+Version 9.3.0 (2026-08-03)
+==========================
+
+**BREAKING CHANGES**: two independent corrections land together.
+
+Tank energy values were wrong in two ways - a 2.5x unit-scale error and
+two actively misleading field names - and both are corrected. Reported
+tank energy is now 2.5x smaller and two public field names are removed.
+
+Separately, eight status flags change type from ``bool`` to
+``bool | None`` so the device's "unknown" state is no longer reported as
+a definite OFF.
+
+Changed
+-------
+- **Energy unit scale corrected.** ``totalEnergyCapacity`` and ``availableEnergyCapacity`` were
+  scaled by 10 on the assumption the device reported 10 Wh units. It does
+  not. Because ``totalEnergyCapacity`` is a whole-tank quantity, its slope
+  against the setpoint measures the quantum with no stratification
+  assumption: on a 65-gallon NWP500 that is 70.25 raw counts per Kelvin.
+  The field turns out to be bimodal - at a fixed setpoint it takes one of
+  two values exactly 2 degC apart - but both branches give the same slope
+  to within 0.2%, so the quantum is unaffected. Converting to Watt-hours needs a
+  water mass, and a "65 gallon" tank does not hold 65 gallons - so taking
+  the quantum to be round, as every other conversion in this protocol is,
+  4 Wh/count is the only candidate implying a water volume below the
+  nameplate (241.7 L). Two further checks agree: 183 individual heating
+  recoveries give 4.11 Wh/count by a noisier route, and integrating
+  ``currentInstPower`` over them implies a heat-pump COP of 2.89 at the new
+  scale against 7.02 at the old, the latter being physically impossible.
+  **Reported tank energy is now 2.5x smaller.**
+  Historical series logged from earlier versions need rescaling by 0.4 to
+  be comparable.
+
+- **Energy fields renamed.**
+  ``availableEnergyCapacity`` is not available energy - it is the energy
+  still *needed* to reach the setpoint. It falls as the tank heats and
+  reaches zero when the tank is fully charged, so code treating it as
+  stored energy had the signal backwards (regression against mean tank
+  temperature: negative slope, R-squared 0.93, zero crossing at the
+  setpoint). Likewise ``totalEnergyCapacity`` is not a fixed tank size but
+  the cost of a full recovery to the *current setpoint*, measured from the
+  device's own minimum setpoint of 104.9 degF; it moves by about 140 Wh
+  per 0.5 degC of setpoint change.
+
+  .. code-block:: python
+
+     # OLD (removed)
+     status.total_energy_capacity        # 15800.0
+     status.available_energy_capacity    # 11660.0
+
+     # NEW
+     status.full_recovery_energy         # 6320.0
+     status.energy_to_setpoint           # 4664.0
+
+  The protocol field names on the wire are unchanged. CLI rows are
+  relabelled from "Total Capacity"/"Available Capacity" to
+  "Full Recovery"/"Energy to Setpoint".
+
+- **Status flags now preserve the device's unknown state.** The protocol
+  encodes these flags as ``0 = unknown, 1 = OFF, 2 = ON``, and the library
+  was collapsing 0 to ``False`` - inventing an OFF the device never claimed.
+  Confirmed against Navien's own NaviLink app (2.03.00, versionCode 141),
+  which decodes exactly this set of fields through an enum declared
+  ``UNKNOWN(0), OFF(1), ON(2)``; two sibling enums render their zero as
+  ``"-"`` and ``"Not Applied"`` rather than as an off state.
+
+  Affected: ``operation_busy``, ``comp_use``, ``anti_legionella_use``,
+  ``anti_legionella_operation_busy``, ``heat_upper_use``, ``heat_lower_use``,
+  ``air_filter_alarm_use``, ``recirc_reservation_use``.
+
+  ``None`` is falsy, so ``if status.comp_use:`` is unaffected. Code that
+  distinguishes ``is False`` from "not reported", or does arithmetic or
+  formatting on these fields, needs a ``None`` check. For Home Assistant
+  this is the wanted shape: ``None`` renders as "Unknown" instead of writing
+  a fabricated OFF into the recorder database.
+
+- ``OnOffFlag`` gains the vendor's ``UNKNOWN = 0`` member. It previously
+  started at ``OFF = 1``, leaving the device's reserved value unrepresented.
+
+- The CLI renders these flags as ``Unknown`` rather than ``No``. Both
+  affected rows are updated: "Busy" under OPERATION STATUS and
+  "Operation Busy" under ANTI-LEGIONELLA.
+
+Added
+-----
+- **``DeviceStatus.usable_energy``**: drawable energy in Watt-hours,
+  computed as ``full_recovery_energy - energy_to_setpoint``. Both raw
+  fields are measured from the setpoint, so neither is a state of charge;
+  subtracting them cancels the setpoint and leaves the tank's heat above
+  the device's minimum operating temperature (104.9 degF), which is about
+  the lowest temperature usable for a shower. Robust despite
+  ``full_recovery_energy`` being bimodal, since both fields shift
+  together: the implied tank temperature tracks the thermistor mean to a
+  standard deviation of 0.57 degF over 12275 samples. Rendered by the CLI
+  as "Usable Energy".
+
+- ``converters.device_tristate_to_python`` and
+  ``models.status.DeviceTriState`` for flags the device may decline to
+  report. ``converters.device_bool_to_python`` is unchanged and remains
+  correct for capability flags.
+- New ``docs/explanation/unknown-values.rst`` recording which field families
+  use 0 as a sentinel and which do not, with the app evidence for each.
+
+Removed
+-------
+- **Misnamed energy fields**: removed ``DeviceStatus.total_energy_capacity``
+  and ``DeviceStatus.available_energy_capacity`` outright rather than
+  aliasing them, so a missed rename fails with ``AttributeError`` instead
+  of silently returning a number 2.5x too large. Use
+  ``full_recovery_energy`` and ``energy_to_setpoint``.
+
+- **Incorrect converter**: removed ``converters.mul_10``, which existed
+  only to apply the wrong 10 Wh scale. Use
+  ``converters.energy_count_to_wh`` and ``converters.WH_PER_ENERGY_COUNT``.
+
+Fixed
+-----
+- **Documentation contradicted itself and the code on energy capacity.**
+  Three incompatible descriptions were published: Watt-hours with no
+  conversion (protocol reference), Watt-hours with a x10 scale (the code),
+  and a 0-100 percentage (``how-to/track-energy.rst``,
+  ``reference/python_api/models.rst``, ``project/history.rst``). The
+  percentage claim was never true of any library version. All are now
+  consistent.
+- ``how-to/track-energy.rst`` documented four fields that do not exist on
+  ``DeviceStatus`` (``dhw_tank_upper_temp``, ``dhw_tank_lower_temp``,
+  ``comp_temp``, ``dhw_heatex_out_temp``); replaced with the real names.
+- ``dhwTemperature`` is documented as an outlet temperature but is
+  measured inside the tank: it tracks ``tankUpperTemperature`` to within
+  one 0.5 degC step, and the device has no sensor downstream of itself.
+  Navien's own app agrees, labelling it "DHW Temp." beside the tank
+  thermistors and showing ``dischargeTemperature`` separately.
+- ``docs/explanation/tank-energy.rst`` tabulated ``totalEnergyCapacity``
+  and ``availableEnergyCapacity`` at ten times their raw wire values,
+  under column headings naming the raw protocol fields. The series had
+  been logged through the pre-fix library, which multiplied by 10. The
+  prose beside the tables ("70.25 raw counts per Kelvin", "35 counts")
+  was already in true raw counts, so the page contradicted itself by
+  exactly the factor it exists to correct. Tables are now in raw counts;
+  1580 counts at a 145.4 degF setpoint matches the test fixtures and the
+  6320 Wh the CLI reports. No numeric conclusion changes.
+- ``docs/explanation/tank-energy.rst`` referred to a field
+  ``hpUpperOnTemperatureSetting``; the protocol name is
+  ``hpUpperOnTempSetting``.
+- The setpoint-per-0.5-degC figure is 140 Wh, not 143 Wh, which is what
+  the documented slope of 70.25 counts/K gives at 4 Wh/count. Corrected
+  in the changelog, the model field description and the protocol
+  reference.
+- New ``docs/explanation/tank-energy.rst`` records what the two fields
+  actually measure and the calibration evidence behind the scale change,
+  including that Navien's own NaviLink app (2.03.00, versionCode 141)
+  reads neither field, so no vendor-side corroboration exists.
+
+- Documented that **temperature fields carry no sentinel at all**. The app
+  has no out-of-band constant (no ``0xFFFF``/``-999``/``-1``), no zero-guard
+  in any display path, and formats whatever arrives - so a temperature of
+  zero means zero. This closes a recurring source of bugs where zero-as-none
+  was applied to temperature converters and reported working sensors as
+  missing during cold-weather operation.
+- Documented that capability flags are a distinct case: the app hides a
+  feature's entire UI when its DID ``Use`` flag reads 0, so 0 there means
+  "not fitted" and the existing ``bool`` mapping is correct.
+
 Version 9.2.1 (2026-07-30)
 ==========================
 

{nwp500_python-9.2.1/src/nwp500_python.egg-info → nwp500_python-9.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 9.2.1
+Version: 9.3.1
 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.2.1 → nwp500_python-9.3.1}/docs/explanation/index.rst

@@ -9,3 +9,5 @@ Understanding-oriented deep dives into the library's design and advanced feature
 
    advanced-features
    architecture
+   tank-energy
+   unknown-values