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

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

@@ -5,6 +5,105 @@ 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)
 ==========================
 

{nwp500_python-9.3.0/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.3.0
+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.3.0 → nwp500_python-9.3.1}/docs/how-to/optimize-tou.rst

@@ -339,28 +339,38 @@ Enables or disables TOU operation without changing the schedule.
 * ``device``: Device object
 * ``enabled``: ``True`` to enable TOU, ``False`` to disable
 
-MQTT: Request TOU Settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+REST: Read the Current TOU Schedule
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: python
 
-    async def request_tou_settings(
-        device: Device,
-        controller_serial_number: str
-    ) -> None
+    async def get_tou_info(
+        mac_address: str,
+        additional_value: str,
+        controller_id: str,
+        user_type: str = "O",
+    ) -> TOUInfo
 
-Requests the current TOU configuration from the device.
+Returns the stored TOU plan: rate name, utility, ZIP code, and the seasonal
+schedule with its pricing intervals.
 
 **Parameters:**
 
-* ``device``: Device object
-* ``controller_serial_number``: Controller serial number
+* ``mac_address``: Device MAC address
+* ``additional_value``: Additional device identifier
+* ``controller_id``: Controller serial number. Only the MQTT device-info
+  response publishes it (``DeviceFeature.controller_serial_number``); it is a
+  hardware property, so fetch it once and cache it. See Example 3.
+* ``user_type``: User type (default ``"O"``)
 
-The device will respond on the topic:
+.. note::
 
-.. code-block:: text
-
-    cmd/{deviceType}/{deviceId}/res/tou/rd
+   There is no MQTT read for the TOU schedule. ``ctrl/tou/rd`` with
+   ``CommandCode.TOU_RESERVATION`` is the *write* - it is what
+   :meth:`~nwp500.NavienMqttClient.configure_tou_schedule` publishes, and what
+   the vendor app publishes from its TOU editor. The device replies on
+   ``cmd/{deviceType}/{clientId}/res/tou/rd`` to confirm such a write; it does
+   not answer a request that carries no schedule. Read the plan over REST.
 
 Building TOU Periods
 --------------------
@@ -527,7 +537,7 @@ Configure two rate periods - off-peak and peak pricing:
             await mqtt_client.subscribe_device_feature(device, capture_feature)
             await mqtt_client.request_device_info(device)
             feature = await asyncio.wait_for(feature_future, timeout=15)
-            controller_serial = feature.controllerSerialNumber
+            controller_serial = feature.controller_serial_number
             
             # Define off-peak period (midnight to 2 PM, weekdays)
             off_peak = build_tou_period(
@@ -651,58 +661,63 @@ Configure different rates for summer and winter:
 Example 3: Retrieve Current TOU Settings
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Query the device for its current TOU configuration:
+The stored TOU plan is read over the REST API. The read itself needs no MQTT
+connection, but it is keyed by the controller serial number, and the only
+place that is published is the MQTT device-info response. The serial is a
+hardware property that never changes, so fetch it once, keep it, and every
+later read is pure REST:
 
 .. code-block:: python
 
-    from nwp500.encoding import decode_week_bitfield, decode_price
+    import asyncio
+    from nwp500 import NavienAPIClient, NavienAuthClient, NavienMqttClient
+    from nwp500.encoding import decode_price, decode_week_bitfield
+
+    async def get_controller_serial(auth_client, device) -> str:
+        """One-time lookup: the controller serial is only published over MQTT."""
+        mqtt_client = NavienMqttClient(auth_client)
+        await mqtt_client.connect()
+        try:
+            feature_future = asyncio.Future()
+
+            def capture_feature(feature):
+                if not feature_future.done():
+                    feature_future.set_result(feature)
+
+            await mqtt_client.subscribe_device_feature(device, capture_feature)
+            await mqtt_client.request_device_info(device)
+            feature = await asyncio.wait_for(feature_future, timeout=15)
+            return feature.controller_serial_number
+        finally:
+            await mqtt_client.disconnect()
 
-    async def check_tou_settings():
+    async def check_tou_settings(controller_serial: str | None = None):
         async with NavienAuthClient("user@example.com", "password") as auth_client:
             api_client = NavienAPIClient(auth_client=auth_client)
             device = await api_client.get_first_device()
-            
-            mqtt_client = NavienMqttClient(auth_client)
-            await mqtt_client.connect()
-            
-            # ... get controller_serial (same as Example 1) ...
-            
-            # Set up response handler
-            response_topic = f"cmd/{device.device_info.device_type}/{mqtt_client.config.client_id}/res/tou/rd"
-            
-            def on_tou_response(topic: str, message: dict):
-                response = message.get("response", {})
-                enabled = response.get("reservationUse")
-                periods = response.get("reservation", [])
-                
-                print(f"TOU Enabled: {enabled}")
-                print(f"Number of periods: {len(periods)}")
-                
-                for i, period in enumerate(periods, 1):
-                    days = decode_week_bitfield(period.get("week", 0))
-                    price_min = decode_price(
-                        period.get("priceMin", 0),
-                        period.get("decimalPoint", 0)
-                    )
-                    price_max = decode_price(
-                        period.get("priceMax", 0),
-                        period.get("decimalPoint", 0)
-                    )
-                    
+
+            if controller_serial is None:
+                controller_serial = await get_controller_serial(auth_client, device)
+
+            tou_info = await api_client.get_tou_info(
+                mac_address=device.device_info.mac_address,
+                additional_value=device.device_info.additional_value,
+                controller_id=controller_serial,
+            )
+
+            print(f"Plan: {tou_info.name} ({tou_info.utility})")
+
+            # TOUSchedule.intervals holds the raw interval dicts
+            for season in tou_info.schedule:
+                for i, interval in enumerate(season.intervals, 1):
+                    days = decode_week_bitfield(interval["week"])
+                    dp = interval["decimalPoint"]
                     print(f"\nPeriod {i}:")
                     print(f"  Days: {', '.join(days)}")
-                    print(f"  Time: {period['startHour']:02d}:{period['startMinute']:02d} "
-                          f"- {period['endHour']:02d}:{period['endMinute']:02d}")
-                    print(f"  Price: ${price_min:.5f} - ${price_max:.5f}/kWh")
-            
-            await mqtt_client.subscribe(response_topic, on_tou_response)
-            
-            # Request current settings
-            await mqtt_client.request_tou_settings(device, controller_serial)
-            
-            # Wait for response
-            await asyncio.sleep(5)
-            await mqtt_client.disconnect()
+                    print(f"  Time: {interval['startHour']:02d}:{interval['startMinute']:02d} "
+                          f"- {interval['endHour']:02d}:{interval['endMinute']:02d}")
+                    print(f"  Price: ${decode_price(interval['priceMin'], dp):.5f} "
+                          f"- ${decode_price(interval['priceMax'], dp):.5f}/kWh")
 
     asyncio.run(check_tou_settings())
 

{nwp500_python-9.3.0 → nwp500_python-9.3.1}/docs/openapi.yaml

@@ -195,6 +195,14 @@ paths:
                             connected:
                               type: integer
                               example: 2
+                            modelTypeCode:
+                              type: integer
+                              nullable: true
+                              example: null
+                            installerId:
+                              type: string
+                              nullable: true
+                              example: null
                         location:
                           type: object
                           properties:
@@ -206,7 +214,29 @@ paths:
                               example: "Anytown"
                             address:
                               type: string
-                              example: "123 Main Street" 
+                              example: "123 Main Street"
+                        error:
+                          type: object
+                          description: Last recorded device fault.
+                          properties:
+                            errorCode:
+                              type: integer
+                              example: 0
+                            errorOccuredTime:
+                              type: string
+                              nullable: true
+                              example: "2025-12-07T11:58:02"
+                        descaling:
+                          type: object
+                          properties:
+                            descalingStartTime:
+                              type: string
+                              nullable: true
+                              example: null
+                            descalingEndTime:
+                              type: string
+                              nullable: true
+                              example: null
   /device/info:
     post:
       summary: Device Info

{nwp500_python-9.3.0 → nwp500_python-9.3.1}/docs/reference/python_api/models.rst

@@ -60,6 +60,10 @@ Complete device representation with info and location.
 
    * ``device_info`` (DeviceInfo) - Device identification and status
    * ``location`` (Location) - Physical location information
+   * ``error`` (DeviceErrorSummary, optional) - Last recorded fault. Returned by
+     ``/device/list`` only; ``None`` on a device fetched through ``/device/info``.
+   * ``descaling`` (DescalingInfo, optional) - Descaling window, if one is
+     scheduled or recorded
 
    **Example:**
 
@@ -80,6 +84,52 @@ Complete device representation with info and location.
           print(f"Location: {loc.city}, {loc.state}")
           print(f"Coords: {loc.latitude}, {loc.longitude}")
 
+DeviceErrorSummary
+------------------
+
+The device's last recorded fault, as reported by the REST API. Unlike
+``DeviceStatus.error_code`` this is readable without an MQTT connection, and
+remains readable while the device is offline.
+
+.. py:class:: DeviceErrorSummary
+
+   **Fields:**
+
+   * ``error_code`` (ErrorCode | int) - ``ErrorCode.NO_ERROR`` when there is no
+     recorded fault. A code the enum does not know is kept as a plain int rather
+     than failing the whole response.
+   * ``error_occurred_time`` (str, optional) - When the fault was recorded, as an
+     ISO-8601 string. Sent by the API under the misspelled key ``errorOccuredTime``.
+
+   **Example:**
+
+   .. code-block:: python
+
+      devices = await api.list_devices()
+
+      for device in devices:
+          if device.error and device.error.error_code != ErrorCode.NO_ERROR:
+              code = device.error.error_code
+              # A code the enum knows arrives as an ErrorCode; anything else
+              # falls back to a plain int, which has no .name.
+              label = code.name if isinstance(code, ErrorCode) else f"code {code}"
+              print(f"{device.device_info.device_name}: {label}"
+                    f" at {device.error.error_occurred_time}")
+
+DescalingInfo
+-------------
+
+Descaling window reported by the REST API.
+
+.. py:class:: DescalingInfo
+
+   **Fields:**
+
+   * ``descaling_start_time`` (str, optional) - Start of the descaling window
+   * ``descaling_end_time`` (str, optional) - End of the descaling window
+
+   Both are ``None`` on a device with no descaling scheduled or recorded.
+
 DeviceInfo
 ----------
 
@@ -99,6 +149,8 @@ Device identification and connection information.
    * ``device_name`` (str) - User-assigned device name
    * ``connected`` (int) - Connection status (2 = online, 0 = offline)
    * ``install_type`` (str, optional) - Installation type
+   * ``model_type_code`` (int, optional) - Model type code
+   * ``installer_id`` (str, optional) - Installer identifier
 
    **Example:**
 

{nwp500_python-9.3.0 → nwp500_python-9.3.1}/docs/reference/python_api/mqtt_client.rst

@@ -582,24 +582,17 @@ configure_tou_schedule()
 
    **Capability Required:** ``program_reservation_use``
 
-request_tou_settings()
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. py:method:: request_tou_settings(device, controller_serial_number)
-
-   Request the current TOU schedule.
-
 subscribe_tou_response()
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
 .. py:method:: subscribe_tou_response(device, callback)
 
-   Subscribe to parsed TOU schedule responses.
+   Subscribe to parsed TOU schedule write confirmations.
 
    The callback is invoked with a :class:`~nwp500.models.TOUReservationSchedule`
-   whenever the device responds to a :meth:`request_tou_settings` read or a
-   :meth:`configure_tou_schedule` write (both use the ``tou/rd`` response
-   topic).
+   when the device confirms a :meth:`configure_tou_schedule` write on the
+   ``tou/rd`` response topic. The device has no MQTT read for its TOU schedule;
+   to read the stored plan, use :meth:`~nwp500.NavienAPIClient.get_tou_info`.
 
    :param callback: Called with the parsed TOU schedule on each response.
    :type callback: Callable[[TOUReservationSchedule], None]

{nwp500_python-9.3.0 → nwp500_python-9.3.1}/examples/advanced/firmware_payload_capture.py

@@ -8,7 +8,6 @@ updates by diffing captures taken before and after an update.
 
 Specifically captures:
   - Weekly reservations (rsv/rd)
-  - Time-of-Use schedule (tou/rd)
   - Device info (firmware versions, capabilities)
   - Device status (current operating state)
   - All other response/event topics (via wildcards)
@@ -37,7 +36,6 @@ from pathlib import Path
 from typing import Any
 
 from nwp500 import NavienAPIClient, NavienAuthClient, NavienMqttClient
-from nwp500.exceptions import Nwp500Error
 from nwp500.models import DeviceFeature
 from nwp500.mqtt.utils import redact, redact_topic
 from nwp500.topic_builder import MqttTopicBuilder
@@ -113,17 +111,30 @@ async def main() -> None:
 
         # --- Wildcard subscriptions to catch everything ---
 
-        # All response messages back to this client
+        # Everything under the device's own command path. The device
+        # acknowledges control and query commands on
+        # cmd/{type}/navilink-{mac}/{client_id}/res, which is where the status
+        # and device-info responses arrive, so a capture without this
+        # subscription misses them entirely. It also picks up the published
+        # requests themselves and the traffic of other clients on the same
+        # device (a Home Assistant integration, the vendor app), which is
+        # exactly what a capture wants. Query results that the device routes
+        # back to a client-keyed topic - reservations, energy usage - arrive
+        # under res_wildcard below instead.
+        cmd_wildcard = MqttTopicBuilder.command_topic(device_type, mac, "#")
+        # Query results routed back to this client specifically
         res_wildcard = MqttTopicBuilder.response_topic(device_type, client_id, "#")
         # All event messages pushed by the device
         evt_wildcard = MqttTopicBuilder.event_topic(device_type, mac, "#")
 
         print(
-            f"\nSubscribing to:\n  {redact_topic(res_wildcard)}\n"
+            f"\nSubscribing to:\n  {redact_topic(cmd_wildcard)}\n"
+            f"  {redact_topic(res_wildcard)}\n"
             f"  {redact_topic(evt_wildcard)}\n"
         )
         print("Captured topics:")
 
+        await mqtt_client.subscribe(cmd_wildcard, capture.record)
         await mqtt_client.subscribe(res_wildcard, capture.record)
         await mqtt_client.subscribe(evt_wildcard, capture.record)
 
@@ -156,16 +167,9 @@ async def main() -> None:
         await mqtt_client.request_reservations(device)
         await asyncio.sleep(5)
 
-        # --- Step 4: request TOU schedule (requires controller serial number) ---
-        if device_feature and device_feature.program_reservation_use:
-            serial = device_feature.controller_serial_number
-            if serial:
-                print("Requesting TOU schedule...")
-                try:
-                    await mqtt_client.request_tou_settings(device, serial)
-                    await asyncio.sleep(5)
-                except Nwp500Error as exc:
-                    print(f"  TOU request failed: {exc}")
+        # No TOU step: the device has no MQTT read for its TOU schedule.
+        # ctrl/tou/rd carries the *write*, which a capture tool must not send.
+        # Read the schedule over REST instead (api_client.get_tou_info).
 
         # --- Step 5: wait a bit more to catch any late-arriving messages ---
         print("\nWaiting for any remaining messages...")

{nwp500_python-9.3.0 → nwp500_python-9.3.1}/examples/advanced/tou_schedule.py

@@ -119,10 +119,10 @@ async def main() -> None:
             enabled=True,
         )
 
-        print("Requesting current TOU settings for confirmation...")
-        await mqtt_client.request_tou_settings(device, controller_serial)
-
-        print("Waiting up to 15 seconds for TOU responses...")
+        # The device has no MQTT read for its TOU schedule; the write above
+        # is confirmed on the same tou/rd topic. To read the stored schedule
+        # back, use the REST API: api_client.get_tou_info(...).
+        print("Waiting up to 15 seconds for the TOU write confirmation...")
         await asyncio.sleep(15)
 
         print("Toggling TOU off for quick test...")

{nwp500_python-9.3.0 → nwp500_python-9.3.1}/src/nwp500/__init__.py

@@ -75,7 +75,9 @@ from nwp500.factory import (
 )
 from nwp500.models import (
     ConvertedTOUPlan,
+    DescalingInfo,
     Device,
+    DeviceErrorSummary,
     DeviceFeature,
     DeviceInfo,
     DeviceStatus,
@@ -147,6 +149,8 @@ __all__ = [
     "DeviceInfo",
     "Location",
     "Device",
+    "DeviceErrorSummary",
+    "DescalingInfo",
     "FirmwareInfo",
     "ReservationEntry",
     "ReservationSchedule",

{nwp500_python-9.3.0 → nwp500_python-9.3.1}/src/nwp500/cli/__main__.py

@@ -143,6 +143,11 @@ def async_command(f: Any) -> Any:
                         await mqtt.disconnect()
                     return 0
 
+            except click.ClickException:
+                # A usage/config error a command raised deliberately. Let
+                # Click report it as itself; the catch-all below would
+                # otherwise log it as an "Unexpected Error" with a traceback.
+                raise
             except (
                 InvalidCredentialsError,
                 AuthenticationError,
@@ -639,14 +644,69 @@ async def tou_apply(
         _logger.error("API client not available")
 
 
-@cli.command()  # type: ignore[attr-defined]
+def _parse_months(
+    ctx: click.Context, param: click.Parameter, value: str | None
+) -> list[int] | None:
+    """Parse ``--months`` at parse time, so bad input is a usage error."""
+    if value is None:
+        return None
+    months = []
+    for raw in value.split(","):
+        try:
+            month = int(raw.strip())
+        except ValueError:
+            raise click.BadParameter(
+                f"{raw.strip()!r} is not a month number; expected a "
+                "comma-separated list like 1,2,3"
+            ) from None
+        if not 1 <= month <= 12:
+            raise click.BadParameter(f"{month} is not in the range 1-12")
+        months.append(month)
+    if not months:
+        raise click.BadParameter("at least one month is required")
+    return months
+
+
+class _EnergySelection(click.Command):
+    """Rejects an unusable --month/--months combination during parsing.
+
+    Cross-option checks have no natural home in a per-option callback, and
+    the command body is the wrong place: it runs inside ``async_command``,
+    after authentication and the MQTT connect, so a usage error there would
+    surface only to users whose credentials already work - and then as an
+    "Unexpected Error" traceback, because the wrapper's catch-all swallows
+    ``ClickException``.
+    """
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        rest = super().parse_args(ctx, args)
+        month, months = ctx.params.get("month"), ctx.params.get("months")
+        if month is not None and months is not None:
+            raise click.UsageError(
+                "Use either --month (daily breakdown) or --months "
+                "(monthly summary), not both",
+                ctx=ctx,
+            )
+        if month is None and months is None:
+            raise click.UsageError(
+                "Either --months (for monthly summary) or --month "
+                "(for daily breakdown) is required",
+                ctx=ctx,
+            )
+        return rest
+
+
+@cli.command(cls=_EnergySelection)  # type: ignore[attr-defined]
 @click.option("--year", type=int, required=True, help="Year to query")
 @click.option(
-    "--months", required=False, help="Comma-separated months (e.g. 1,2,3)"
+    "--months",
+    required=False,
+    callback=_parse_months,
+    help="Comma-separated months for a monthly summary (e.g. 1,2,3)",
 )
 @click.option(
     "--month",
-    type=int,
+    type=click.IntRange(1, 12),
     required=False,
     help="Show daily breakdown for a specific month (1-12)",
 )
@@ -655,26 +715,25 @@ async def energy(
     mqtt: NavienMqttClient,
     device: Any,
     year: int,
-    months: str | None,
+    months: list[int] | None,
     month: int | None,
 ) -> None:
     """Query historical energy usage.
 
     Use either --months for monthly summary or --month for daily breakdown.
+    Which option was passed decides the view, not how many months it names:
+    ``--months 5`` is a one-month summary, ``--month 5`` is a daily
+    breakdown of that month.
     """
+    # _EnergySelection rejected every combination but these two during
+    # parsing, so exactly one of the options is set here.
     if month is not None:
-        # Daily breakdown for a single month
-        if month < 1 or month > 12:
-            raise click.ClickException("Month must be between 1 and 12")
-        await handlers.handle_get_energy_request(mqtt, device, year, [month])
+        await handlers.handle_get_energy_request(
+            mqtt, device, year, [month], daily=True
+        )
     elif months is not None:
-        # Monthly summary
-        month_list = [int(m.strip()) for m in months.split(",")]
-        await handlers.handle_get_energy_request(mqtt, device, year, month_list)
-    else:
-        raise click.ClickException(
-            "Either --months (for monthly summary) or --month "
-            "(for daily breakdown) required"
+        await handlers.handle_get_energy_request(
+            mqtt, device, year, months, daily=False
         )