nwp500-python 9.3.2__tar.gz → 9.4.0__tar.gz

{nwp500_python-9.3.2 → nwp500_python-9.4.0}/CHANGELOG.rst

@@ -5,6 +5,164 @@ Changelog
 Unreleased
 ==========
 
+Version 9.4.0 (2026-09-12)
+==========================
+
+This release realigns the MQTT command set with what the NaviLink app
+actually sends. The app (version 2.03.00) was decompiled and its request
+builder compared with the library; every query it sends now has a
+method, six commands it never sends were removed, and the recirculation
+schedule write was corrected. Breaking changes are listed under
+*Removed* and *Changed*.
+
+Added
+-----
+- **Installer diagnostics query.** ``request_diagnostics()`` /
+  ``subscribe_diagnostics()`` and the ``nwp-cli diagnostics`` command
+  return the lifetime counters the app's installer screen shows: heat
+  pump and element energy, days since installation, fault event counts,
+  demand-response operation times, hot-water draw statistics and
+  component run times and start counts, as
+  :class:`~nwp500.models.DeviceDiagnostics`. The device answers the
+  ``st/td/rd`` query with packed hex; the NaviLink cloud decodes it into
+  JSON only when the reply topic has the app's five-segment form, so the
+  library requests that form. Verified live: the energies and compressor
+  and element run times match the energy query's lifetime totals.
+- **Monthly energy query.** ``request_energy_usage_monthly()`` /
+  ``subscribe_energy_usage_monthly()`` and ``nwp-cli energy --years``
+  return one entry per year with twelve per-month items. Verified live.
+- **Hourly energy query.** ``request_energy_usage_hourly()`` /
+  ``subscribe_energy_usage_hourly()`` send the app's per-hour query. The
+  NWP500 tested never answered it in four attempts, so it has no CLI
+  command.
+- **Recirculation schedule read.** ``request_recirculation_schedule()``
+  and ``nwp-cli recirc-schedule get``; the write is exposed as
+  ``nwp-cli recirc-schedule set``, which checks the JSON before
+  connecting (known keys only, integers in range, at most 20 entries).
+  The read was verified live on a unit that reports recirculation
+  scheduling but has no pump (empty, disabled schedule); the write and
+  its echo are unverified. The CLI reports a write as updated only when
+  the echo matches what was written. ``RecirculationSchedule`` and
+  ``RecirculationScheduleEntry`` fields are strict integers, so ``True``
+  or ``6.0`` is rejected instead of coerced.
+- **Firmware download info.** ``request_firmware_download_info()`` /
+  ``subscribe_firmware_download_info()`` and ``nwp-cli firmware info``
+  return :class:`~nwp500.models.FirmwareDownloadInfo`. The device replies
+  on its own topic rather than a client-keyed one. Verified live.
+- **Session end.** ``end_session()`` sends the ``st/end`` query the app
+  sends whenever it leaves a device. No reply to it has been observed.
+  Unlike other commands it is never queued while disconnected (it raises
+  ``MqttNotConnectedError``), since a session end replayed after a
+  reconnect would end the new session.
+- ``MqttConnectionConfig.send_session_end_on_disconnect`` (default
+  ``True``) controls whether ``disconnect()`` sends it.
+- ``subscribe_firmware_commit_response()`` receives the reply to
+  ``commit_firmware_update()``, which is requested on the app-form
+  ``res/commit-ota`` topic that no other subscription covers.
+- **Controls with app builder cases that had no method:**
+  ``set_vacation_duration(days)`` (``goout-day``; the app has a builder
+  case but no screen that calls it; verified live to change the day count
+  without changing the operation mode),
+  ``set_air_filter_life(hours)`` (``air-filter-life``; the wire value is
+  hours divided by 500, matching the app's 0 or 1000-10000 picker;
+  verified live) and ``reset_condenser_fault()`` (``cond-fault-reset``,
+  installer-level in the app; acknowledged live, clearing effect not
+  observable without a fault). CLI: ``vacation-duration``,
+  ``filter-life``, ``reset-condenser-fault``.
+- **Command codes** for every member of the app's ``DeviceControlMGPP``
+  enum, with the declared-but-never-sent ones annotated.
+- ``EnergyUsageResponse.type_of_usage``, ``get_year_data()``,
+  ``MonthlyEnergyData.day`` and ``EnergyUsageDay.ep_usage`` /
+  ``water_usage`` (declared by the app; not reported by the NWP500).
+
+Changed
+-------
+- **Recirculation schedule models take the app's entry shape** (breaking).
+  :class:`~nwp500.models.RecirculationScheduleEntry` is now
+  ``enable``/``week``/``hour``/``min``/``mode``/``param`` like a
+  reservation entry (``mode`` is the entry's pump on/off toggle in the
+  app's editor) and :class:`~nwp500.models.RecirculationSchedule` carries
+  ``reservation_use`` plus ``reservation`` instead of ``schedule``. The
+  previous start/end window fields were not what the device accepts.
+- ``MonthlyEnergyData.month`` is optional: monthly-query entries have no
+  month.
+- **``NavienMqttClient.disconnect()`` now sends ``st/end``** to every
+  device that was passed to any subscription, as the NaviLink app does
+  when it leaves a device. The publishes go straight to the connection,
+  never into the offline command queue, stop if the connection drops,
+  are bounded by a short timeout and never fail the disconnect. What it
+  does to other clients connected to the same device (for example a Home
+  Assistant integration) is not known; turn it off with
+  ``MqttConnectionConfig(send_session_end_on_disconnect=False)``.
+- **CLI energy summaries total the requested periods.** ``energy
+  --month``, ``--months`` and ``--years`` printed the device's lifetime
+  total under a per-month or per-year heading. Each summary now covers
+  only the rows shown, and the lifetime total is printed once under its
+  own heading. (The response's ``total`` is lifetime whatever is
+  requested; checked live.)
+- **Parameter validation.** ``set_air_filter_life()``,
+  ``set_vacation_duration()`` and the daily, monthly and hourly energy
+  queries reject non-integers (including ``True`` and floats) and
+  out-of-range values; years must be 2000-2099 and ``--years`` drops
+  duplicates. ``filter-life``, ``--year`` and ``--years`` reject bad
+  input before connecting. ``request_energy_usage()`` now rejects an
+  empty month list.
+
+Fixed
+-----
+- **``configure_recirculation_schedule()`` published to the wrong topic
+  with the wrong keys.** It sent ``{"schedule": [...]}`` on the bare
+  ``ctrl`` topic; the app publishes RECIR_RESERVATION on
+  ``ctrl/recirc-rsv/rd`` with ``reservationUse`` and ``reservation`` and
+  asks for the echo on ``recirc-rsv/rd``.
+- **``commit_firmware_update()`` published to the bare ``ctrl`` topic.**
+  The app publishes OTA_COMMIT on ``ctrl/commit-ota`` and asks for the
+  reply on ``res/commit-ota``; the library now does the same. Not
+  exercised against a device.
+- **Unsubscribing could remove the wrong handler.** When one callback was
+  registered for more than one device-wildcard subscription (status,
+  feature, firmware info), unsubscribing one removed whichever handler
+  came first. Handlers are now matched on subscription kind as well.
+- **Query replies could reach another device's callback.** Client-keyed
+  reply topics are shared by every device a client queries, so with two
+  devices subscribed a reservation, energy, TOU, diagnostics or
+  recirculation reply reached both callbacks. Typed subscriptions now
+  ignore replies whose ``macAddress`` names a different device.
+- Recirculation read-backs in hex carry the unused ``param`` as ``0xFF``
+  and in JSON as ``-1``; the model normalizes to ``-1`` so the two compare
+  equal.
+- **Protocol documentation** rewritten from the decompiled request
+  builder and live captures: real topic structure, the anti-legionella
+  modes (``anti-leg-on [days]`` / ``anti-leg-off``, not
+  ``anti-legionella-setting``), the message example that paired the
+  weekly-reservation code with ``dhw-temperature``, the undocumented
+  16777226 reservation write, response shapes for every query, and the
+  quick reference's invented ``header``/``body`` format with 0x11/0x21/0x31
+  codes that never existed. Stale ``docs/protocol/`` paths in code
+  comments and docstrings now point at ``docs/reference/protocol/``.
+- ``models/schedule.py`` docstrings cited 33554444 (the hot button) for
+  the recirculation reservation; it is 33554440.
+- CLI reference: token cache path is ``~/.nwp500_tokens.json``, ``-vv``
+  is a repeated ``-v`` (there was no ``--very-verbose``), and the
+  ``--unit-system`` option and ``tou rates``/``plan``/``apply`` commands
+  are documented.
+
+Removed
+-------
+- **Six MQTT commands the NaviLink app never sends** (breaking):
+  ``check_firmware_update()``, ``reconnect_wifi()``, ``reset_wifi()``,
+  ``set_freeze_protection_temperature()``, ``run_smart_diagnostic()`` and
+  ``update_weekly_reservation()`` with
+  ``subscribe_weekly_reservation_response()`` and the
+  ``WeeklyReservationEntry`` / ``WeeklyReservationSchedule`` models. The
+  app's enum declares the first five codes but its request builder has
+  no case for them, so the library's ``ota-check``, ``wifi-reconnect``,
+  ``wifi-reset``, ``frez-temp`` and ``smart-diagnostic`` mode strings were
+  invented. The app's weekly schedule is the ordinary reservation
+  program: it writes with 16777226 on ``ctrl/rsv/rd``
+  (``update_reservations()``), never with 33554438 or a ``rsv-weekly/rd``
+  topic. The ``CommandCode`` members stay, annotated as declared only.
+
 Version 9.3.2 (2026-09-01)
 ==========================
 
@@ -129,6 +287,7 @@ Fixed
   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)
 ==========================
 

{nwp500_python-9.3.2/src/nwp500_python.egg-info → nwp500_python-9.4.0}/PKG-INFO

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

@@ -10,4 +10,5 @@ Understanding-oriented deep dives into the library's design and advanced feature
    advanced-features
    architecture
    tank-energy
+   tou-recovery-cap
    unknown-values

nwp500_python-9.4.0/docs/explanation/tou-recovery-cap.rst

@@ -0,0 +1,188 @@
+==========================
+The TOU Recovery Cap
+==========================
+
+When a Time-of-Use schedule is active, the NWP500 stops a heat-pump
+recovery at about **90 % charge** instead of running to the setpoint. The
+tank finishes roughly 1.9 degC below ``hp_lower_off_temp_setting`` and
+stays there. Nothing in the protocol announces this, and no error is
+raised - the compressor simply stops early.
+
+This matters for anything that waits for the tank to reach its setpoint:
+under an active TOU window that instant never arrives.
+
+.. contents::
+   :local:
+   :depth: 2
+
+
+The short version
+=================
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Observation
+     - Value
+   * - Charge at termination
+     - ``dhw_charge_per`` = 90 % (p10 89, p90 91). Never reaches 100.
+   * - Shortfall below setpoint
+     - ``tank_lower_temperature`` finishes 1.9 degC (3.42 degF) below
+       ``hp_lower_off_temp_setting``
+   * - Precondition
+     - An expensive TOU period in force, un-overridden. ``tou_status``
+       alone is **not** the test - see below.
+   * - Frequency
+     - 59 of 333 recoveries (18 %) over 260 days
+
+A normal recovery, for contrast, ends with ``dhw_charge_per`` at 100 %
+(p10 99) and the lower probe at or above the setpoint.
+
+
+Evidence
+========
+
+Measured across 333 heat-pump recovery cycles of 15-480 minutes, from
+2025-12-28 to 2026-09-06, on one unit. 196 reached the lower-off
+setpoint; 137 did not.
+
+The shortfall of the 137 is **bimodal**, not a spread:
+
+.. code:: text
+
+   shortfall below hp_lower_off_temp_setting, cycles that never reached it
+
+     min 0.18   p10 1.66   p25 3.42   median 3.42   p75 4.32
+     p90 31.03  max 58.86     (degF)
+
+   most common values:  3.42 degF x 59 cycles    3.24 x 6    3.60 x 6
+
+The spike at 3.42 degF is 1.9 degC exactly, and 19 steps of the 0.1 degC
+tank-probe quantum. It holds across eight different setpoints from 140.0
+to 147.2 degF and appears in all nine months observed, so it is an
+offset in the control logic rather than a proportional effect or a
+seasonal one. The long tail beyond 8 degF is ordinary interruption -
+a draw starting mid-recovery, a mode change - and is unrelated.
+
+``tou_status`` looks like a clean separator, and is not one:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 14 26 26
+
+   * - Population
+     - n
+     - ``tou_status`` True
+     - ``tou_override_status`` True
+   * - Stopped 3.42 degF short
+     - 59
+     - **59 / 59 (100 %)**
+     - 0 / 59
+   * - Other unreached
+     - 78
+     - 49 / 78 (63 %)
+     - 6 / 78
+   * - Reached setpoint
+     - 196
+     - 98 / 196 (50 %)
+     - 27 / 196
+
+All 59 ran in ``HEAT_PUMP`` mode throughout, so this is not
+``ENERGY_SAVER`` or ``VACATION`` behaviour.
+
+But read that table carefully: 98 cycles reached the setpoint with
+``tou_status`` True. **The flag only reports that TOU scheduling is
+enabled.** It says nothing about whether the recovery ran inside an
+expensive period, and the cap bites only when it did - outside one, an
+enabled schedule does nothing at all.
+
+The device marks a period itself. While inside one it applies non-zero
+``*_diff_temp_setting`` offsets and reverts them at the end; on the unit
+measured this toggles at 21:00 and 04:00 UTC daily. Using that as the
+in-period test, among ``tou_status`` True cycles:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 22 22 22
+
+   * - At cycle end
+     - Capped
+     - Reached
+     - Other
+   * - Inside a period
+     - **42 (62 %)**
+     - 12
+     - 14
+   * - Outside a period
+     - 16 (12 %)
+     - 86
+     - 34
+
+Test it at the moment the cycle *ended*, not when it began: a recovery
+that starts off-peak and runs into a period is still capped, and testing
+the start catches 17 of 59 against 43 testing the end.
+
+Two plausible explanations were tested and **refuted**:
+
+- *The upper zone satisfied its own cut-out first.* No -
+  ``tank_upper_temperature`` reached ``hp_upper_off_temp_setting`` on
+  only 2 of 137 unreached cycles, against 179 of 196 reached ones. The
+  upper probe finishes short too, by a median of 4.5 degF.
+- *The device terminates on outlet temperature.* No -
+  ``dhw_outlet_temperature`` reached the setpoint on only 2 of 136.
+
+
+What is not yet established
+===========================
+
+Being inside a period is a strong predictor but not a deterministic one:
+12 cycles reached the setpoint from inside one, and 16 were capped from
+outside. Some of that is the marker's own resolution - it is sampled at
+the cycle end, and a period boundary crossed mid-recovery is not captured
+- but it has not been reconciled against the schedule the device was
+actually holding, which ``configure_tou_schedule_confirmed`` can read
+back.
+
+The 90 % figure has been observed on one unit under one TOU schedule. It
+is not known whether the ceiling is fixed in firmware, derived from the
+schedule, or configurable.
+
+A note on reading ``tou_status`` over time: the field emits brief
+``unknown`` values on integration reconnect - sub-second blips that
+return immediately to the value they interrupted - so a raw state history
+contains entries that are not transitions. Stores that keep only boolean
+values drop these, which is the right behaviour and leaves a faithful
+record of the genuine changes.
+
+Do not read a low record count as lost data. It means the state was
+*held*: on the unit measured, ``tou_status`` logged 165 changes in one
+month and 5 in another, and the sparse month was the one in which TOU was
+active nearly continuously. Forward-filling the genuine transitions is
+correct. It can be corroborated against the ``*_diff_temp_setting``
+fields, which toggle away from zero at the start of each TOU window and
+back at the end.
+
+
+Working with the cap
+====================
+
+**Do not wait for the setpoint.** Code that treats "tank reached
+``hp_lower_off_temp_setting``" as the completion signal will block
+indefinitely on a capped recovery. Watch ``dhw_charge_per`` plateauing,
+or the compressor stopping, instead.
+
+**Do not read a capped cycle as a fault or as degraded capacity.** The
+appliance is doing what the schedule told it to. A recovery that ends at
+90 % charge with ``tou_status`` True is a normal outcome.
+
+**When measuring recovery duration, treat capped cycles separately.**
+They are not censored observations of a full recovery - they are
+complete observations of a different, shorter target. Pooling them with
+uncapped recoveries biases any duration estimate downward; discarding
+them biases it upward, because capped cycles are systematically shorter
+(median 161 minutes against 235 for cycles that ran to setpoint).
+
+**To force a full recovery,** set ``tou_override_status`` - none of the
+59 capped cycles had it set, and 27 of the cycles that ran to setpoint
+under an active TOU schedule did.

nwp500_python-9.4.0/docs/how-to/maintenance.rst

@@ -0,0 +1,139 @@
+==================
+Device Maintenance
+==================
+
+Maintenance commands cover firmware update information, the installer
+diagnostics counters, air filter service intervals and fault resets. All
+of them mirror what the NaviLink app sends; the CLI equivalents are noted
+with each one.
+
+.. contents:: On This Page
+   :local:
+   :depth: 2
+
+Before You Start
+================
+
+Some maintenance operations are gated on device capabilities. Request
+device features first so the client can inspect capability flags.
+
+.. code-block:: python
+
+   await mqtt.subscribe_device_feature(device, lambda feature: print(feature))
+   await mqtt.request_device_info(device)
+
+Installer Diagnostics
+=====================
+
+The NaviLink app's installer screen shows lifetime counters the device
+keeps: heat pump and element energy, days since installation, fault
+event counts, demand-response operation times, hot-water draw statistics
+and component run times and start counts. The gate is in the app, so a
+consumer account's unit answers the query.
+
+.. code-block:: python
+
+   from nwp500 import DeviceDiagnostics
+
+   def on_diagnostics(diag: DeviceDiagnostics) -> None:
+       ts, ta = diag.ts_data, diag.ta_data
+       print(f"Installed {ts.days_since_installation} days ago")
+       print(f"Heat pump: {ts.cumulated_pwr_hp} Wh over "
+             f"{ta.cumulated_op_time_comp} h, {ta.cumulated_op_num_comp} starts")
+       print(f"Condensate overflows: {ts.cumulated_occ_num_con_ovr_flow}")
+
+   await mqtt.subscribe_diagnostics(device, on_diagnostics)
+   await mqtt.request_diagnostics(device)
+
+The two energies are watt-hours and ``cumulated_op_time_*`` values are
+hours (both cross-checked against the energy query); the remaining
+counters have no documented unit. See
+:class:`~nwp500.models.DeviceDiagnostics` for every field.
+
+CLI: ``nwp-cli diagnostics`` (add ``--json`` for the raw model).
+
+Firmware Download Information
+=============================
+
+The device reports which firmware components it has downloaded for an
+over-the-air update. A unit with nothing pending reports one all-zero
+entry.
+
+.. code-block:: python
+
+   from nwp500 import FirmwareDownloadInfo
+
+   def on_firmware(info: FirmwareDownloadInfo) -> None:
+       for entry in info.download_sw_info:
+           print(entry.component_name, entry.sw_version, entry.status)
+
+   await mqtt.subscribe_firmware_download_info(device, on_firmware)
+   await mqtt.request_firmware_download_info(device)
+
+To apply a downloaded update, call
+:meth:`nwp500.mqtt.client.NavienMqttClient.commit_firmware_update` with an
+:class:`~nwp500.models.OtaCommitPayload` naming the component code and
+version from the entry above.
+
+.. warning::
+
+   Committing firmware reboots the device. Heating and MQTT connectivity
+   will be interrupted until the upgrade completes.
+
+.. code-block:: python
+
+   from nwp500 import OtaCommitPayload
+
+   payload = OtaCommitPayload(swCode=1, swVersion=1234)
+   await mqtt.commit_firmware_update(device, payload)
+
+CLI: ``nwp-cli firmware info``.
+
+Air Filter
+==========
+
+The air filter timer is reset after cleaning or replacing the filter. The
+service interval is set in evaporator-fan hours: ``0`` disables the alarm,
+otherwise 1000 to 10000 hours in 500-hour steps, which are the values the
+NaviLink app offers. The device reports the interval back as
+``DeviceStatus.air_filter_alarm_period``.
+
+.. code-block:: python
+
+   await mqtt.set_air_filter_life(device, 3000)
+   await mqtt.reset_air_filter(device)
+
+CLI: ``nwp-cli filter-life 3000`` and ``nwp-cli reset-filter``.
+
+Condenser Fault Reset
+=====================
+
+Clears a condenser fault. The NaviLink app exposes this on its status
+screen to installer accounts only; the gate is in the app. A consumer
+account's unit acknowledges the command; the clearing effect could not be
+observed because no fault was present.
+
+.. code-block:: python
+
+   await mqtt.reset_condenser_fault(device)
+
+CLI: ``nwp-cli reset-condenser-fault``.
+
+Commands the App Never Sends
+============================
+
+The NaviLink app's command enum also declares an OTA check, WiFi reconnect
+and reset, a freeze-protection temperature and a smart diagnostic trigger,
+but its request builder has no case for any of them, so no NaviLink client
+publishes those codes and their payloads are unknown. Earlier versions of
+this library sent made-up payloads for them; those methods were removed.
+The freeze-protection range and the smart diagnostic result remain
+readable from :class:`~nwp500.models.DeviceFeature` and
+:class:`~nwp500.models.DeviceStatus`.
+
+Related Documentation
+=====================
+
+* :doc:`../reference/python_api/mqtt_client` - Full MQTT client API reference
+* :doc:`schedule-operation` - Reservations, recirculation schedules, and intelligent scheduling
+* :doc:`diagnose-mqtt` - Connection troubleshooting and diagnostics

{nwp500_python-9.3.2 → nwp500_python-9.4.0}/docs/how-to/schedule-operation.rst

@@ -580,95 +580,62 @@ Important Notes
 Weekly Reservations
 ===================
 
-``update_weekly_reservation()`` configures a separate weekly reservation payload
-using :class:`~nwp500.models.WeeklyReservationSchedule`. This is useful when you
-want to send the whole weekly program as one typed object.
-
-.. code-block:: python
-
-   from nwp500 import (
-       WeeklyReservationEntry,
-       WeeklyReservationSchedule,
-   )
-   from nwp500.encoding import build_reservation_entry
-
-   morning = WeeklyReservationEntry.model_validate(
-       build_reservation_entry(
-           enabled=True,
-           days=["MO", "TU", "WE", "TH", "FR"],
-           hour=6,
-           minute=0,
-           mode_id=4,
-           temperature=60.0,
-       )
-   )
-
-   day = WeeklyReservationEntry.model_validate(
-       build_reservation_entry(
-           enabled=True,
-           days=["MO", "TU", "WE", "TH", "FR"],
-           hour=9,
-           minute=0,
-           mode_id=3,
-           temperature=50.0,
-       )
-   )
-
-   schedule = WeeklyReservationSchedule(
-       reservationUse=2,
-       reservation=[morning, day],
-   )
-
-   await mqtt.update_weekly_reservation(device, schedule)
-
-You can also subscribe to weekly reservation responses with
-:meth:`nwp500.mqtt.client.NavienMqttClient.subscribe_weekly_reservation_response`.
+The NaviLink app's "weekly" schedule screen is the reservation program
+above: it writes with ``update_reservations()`` on ``ctrl/rsv/rd`` and
+reads with ``request_reservations()``. There is no separate weekly
+command. (The app's enum declares a ``RESERVATION_WEEKLY`` code, but
+nothing sends it; the ``update_weekly_reservation()`` method that earlier
+library versions built on it was removed.)
 
 Recirculation Scheduling
 ========================
 
 Recirculation schedules are represented by
 :class:`~nwp500.models.RecirculationSchedule` and
-:class:`~nwp500.models.RecirculationScheduleEntry`.
+:class:`~nwp500.models.RecirculationScheduleEntry`. The app builds these
+entries with the same fields as a reservation entry: a day bitfield, a
+time, and ``mode`` as the entry's on/off toggle (``2`` pump on, ``1``
+pump off). The write goes to ``ctrl/recirc-rsv/rd`` and asks for the
+schedule back on ``recirc-rsv/rd``; the read is
+``request_recirculation_schedule()``. Both are gated on the
+``recirc_reservation_use`` capability, which a unit can report without
+having a recirculation pump fitted. Writes are limited to 20 entries with
+in-range fields.
 
 .. code-block:: python
 
    from nwp500 import RecirculationSchedule, RecirculationScheduleEntry
 
    schedule = RecirculationSchedule(
-       schedule=[
-           RecirculationScheduleEntry(
-               enable=2,
-               week=124,  # Mon-Fri
-               start_hour=6,
-               start_min=0,
-               end_hour=8,
-               end_min=30,
-               mode=2,
-           ),
-           RecirculationScheduleEntry(
-               enable=2,
-               week=130,  # Sat-Sun
-               start_hour=7,
-               start_min=0,
-               end_hour=9,
-               end_min=0,
-               mode=2,
-           ),
-       ]
+       reservationUse=2,
+       reservation=[
+           # Mon-Fri: pump on at 06:00, off at 08:30
+           RecirculationScheduleEntry(enable=2, week=124, hour=6, min=0, mode=2),
+           RecirculationScheduleEntry(enable=2, week=124, hour=8, min=30, mode=1),
+           # Sat-Sun: pump on at 07:00, off at 09:00
+           RecirculationScheduleEntry(enable=2, week=130, hour=7, min=0, mode=2),
+           RecirculationScheduleEntry(enable=2, week=130, hour=9, min=0, mode=1),
+       ],
    )
 
-   await mqtt.configure_recirculation_schedule(device, schedule)
-
-   def on_recirculation(schedule):
-       for entry in schedule.schedule:
-           print(entry.start_time, entry.end_time, entry.mode_name)
+   def on_recirculation(schedule: RecirculationSchedule) -> None:
+       print("enabled" if schedule.enabled else "disabled")
+       for entry in schedule.reservation:
+           print(entry.days, entry.time, "on" if entry.pump_on else "off")
 
    await mqtt.subscribe_recirculation_schedule_response(device, on_recirculation)
+   await mqtt.configure_recirculation_schedule(device, schedule)
+   await mqtt.request_recirculation_schedule(device)              # read back
+
+The ``mode``/``param`` semantics and the write echo are inferred from the
+app and have not been confirmed on a unit with recirculation fitted.
 
 Use :meth:`nwp500.mqtt.client.NavienMqttClient.set_recirculation_mode` to switch
 between always-on, button, schedule, and temperature modes.
 
+CLI: ``nwp-cli recirc-schedule get`` and
+``nwp-cli recirc-schedule set '<json array of entries>'``.
+
 Intelligent Scheduling
 ======================