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

nwp500/__init__.py

@@ -77,13 +77,19 @@ from nwp500.models import (
     ConvertedTOUPlan,
     DescalingInfo,
     Device,
+    DeviceDiagnostics,
     DeviceErrorSummary,
     DeviceFeature,
     DeviceInfo,
     DeviceStatus,
+    DiagnosticsComponentCounters,
+    DiagnosticsDhwUsage,
+    DiagnosticsEventCounters,
     EnergyUsageDay,
     EnergyUsageResponse,
     EnergyUsageTotal,
+    FirmwareDownloadEntry,
+    FirmwareDownloadInfo,
     FirmwareInfo,
     Location,
     MonthlyEnergyData,
@@ -98,8 +104,6 @@ from nwp500.models import (
     TOUPeriod,
     TOUReservationSchedule,
     TOUSchedule,
-    WeeklyReservationEntry,
-    WeeklyReservationSchedule,
     fahrenheit_to_half_celsius,
     preferred_to_half_celsius,
     reservation_param_to_preferred,
@@ -154,11 +158,15 @@ __all__ = [
     "FirmwareInfo",
     "ReservationEntry",
     "ReservationSchedule",
-    "WeeklyReservationEntry",
-    "WeeklyReservationSchedule",
     "RecirculationScheduleEntry",
     "RecirculationSchedule",
     "OtaCommitPayload",
+    "DeviceDiagnostics",
+    "DiagnosticsEventCounters",
+    "DiagnosticsDhwUsage",
+    "DiagnosticsComponentCounters",
+    "FirmwareDownloadEntry",
+    "FirmwareDownloadInfo",
     "TOUSchedule",
     "TOUInfo",
     "TOUPeriod",

nwp500/cli/__main__.py

@@ -28,6 +28,7 @@ from nwp500.exceptions import (
     TokenRefreshError,
     ValidationError,
 )
+from nwp500.mqtt.control import MAX_ENERGY_YEAR, MIN_ENERGY_YEAR
 from nwp500.unit_system import UnitSystemType
 
 from . import handlers
@@ -69,6 +70,28 @@ async def _detect_unit_system(
         return "us_customary"
 
 
+def _parse_filter_hours(
+    ctx: click.Context, param: click.Parameter, value: int
+) -> int:
+    """Reject filter intervals the device does not accept, before connecting."""
+    if value != 0 and not (1000 <= value <= 10000 and value % 500 == 0):
+        raise click.BadParameter(
+            f"{value} is not accepted; use 0 or 1000-10000 in steps of 500"
+        )
+    return value
+
+
+def _parse_recirc_schedule(
+    ctx: click.Context, param: click.Parameter, value: str
+) -> str:
+    """Validate the recirculation schedule JSON before connecting."""
+    try:
+        handlers.parse_recirculation_schedule_json(value, enabled=True)
+    except ValueError as e:
+        raise click.BadParameter(str(e)) from None
+    return value
+
+
 def async_command(f: Any) -> Any:
     """Decorator to run click commands asynchronously with device connection."""
 
@@ -275,6 +298,94 @@ async def reset_filter(mqtt: NavienMqttClient, device: Any) -> None:
     await handlers.handle_reset_air_filter_request(mqtt, device)
 
 
+@cli.command()  # type: ignore[attr-defined]
+@click.argument("hours", type=int, callback=_parse_filter_hours)
+@async_command
+async def filter_life(mqtt: NavienMqttClient, device: Any, hours: int) -> None:
+    """Set the air filter service interval in fan hours.
+
+    HOURS is 0 to disable the alarm, or 1000-10000 in steps of 500 (the
+    values the NaviLink app offers).
+    """
+    await handlers.handle_set_air_filter_life_request(mqtt, device, hours)
+
+
+@cli.command()  # type: ignore[attr-defined]
+@click.option("--json", "output_json", is_flag=True, help="Output raw JSON")
+@async_command
+async def diagnostics(
+    mqtt: NavienMqttClient, device: Any, output_json: bool = False
+) -> None:
+    """Show the installer diagnostics counters.
+
+    Lifetime energy and fault counters, hot-water draw statistics and
+    component run times, as shown on the NaviLink app's installer screen.
+    """
+    await handlers.handle_diagnostics_request(mqtt, device, output_json)
+
+
+@cli.command()  # type: ignore[attr-defined]
+@async_command
+async def reset_condenser_fault(mqtt: NavienMqttClient, device: Any) -> None:
+    """Clear a condenser fault (installer-level in the NaviLink app)."""
+    await handlers.handle_reset_condenser_fault_request(mqtt, device)
+
+
+@cli.group()  # type: ignore[attr-defined]
+def firmware() -> None:
+    """Firmware update information."""
+    pass
+
+
+@firmware.command("info")  # type: ignore[attr-defined]
+@click.option("--json", "output_json", is_flag=True, help="Output raw JSON")
+@async_command
+async def firmware_info(
+    mqtt: NavienMqttClient, device: Any, output_json: bool = False
+) -> None:
+    """Show downloadable firmware (OTA) information."""
+    await handlers.handle_firmware_download_info_request(
+        mqtt, device, output_json
+    )
+
+
+@cli.group()  # type: ignore[attr-defined]
+def recirc_schedule() -> None:
+    """Manage the recirculation pump schedule."""
+    pass
+
+
+@recirc_schedule.command("get")  # type: ignore[attr-defined]
+@click.option("--json", "output_json", is_flag=True, help="Output raw JSON")
+@async_command
+async def recirc_schedule_get(
+    mqtt: NavienMqttClient, device: Any, output_json: bool = False
+) -> None:
+    """Read the recirculation pump schedule from the device."""
+    await handlers.handle_get_recirculation_schedule_request(
+        mqtt, device, output_json
+    )
+
+
+@recirc_schedule.command("set")  # type: ignore[attr-defined]
+@click.argument("json_str", metavar="JSON", callback=_parse_recirc_schedule)
+@click.option("--disabled", is_flag=True, help="Write the schedule disabled")
+@async_command
+async def recirc_schedule_set(
+    mqtt: NavienMqttClient, device: Any, json_str: str, disabled: bool
+) -> None:
+    """Write the recirculation pump schedule.
+
+    JSON is an array of up to 20 entries, for example Monday-Friday
+    at 06:00: {"enable": 2, "week": 124, "hour": 6, "min": 0, "mode": 2}.
+    week is the day bitfield (Sun=128, Mon=64 ... Sat=2), mode 2 switches
+    the pump on and 1 off.
+    """
+    await handlers.handle_set_recirculation_schedule_request(
+        mqtt, device, json_str, enabled=not disabled
+    )
+
+
 @cli.command()  # type: ignore[attr-defined]
 @async_command
 async def water_program(mqtt: NavienMqttClient, device: Any) -> None:
@@ -327,6 +438,20 @@ async def vacation(mqtt: NavienMqttClient, device: Any, days: int) -> None:
     await handlers.handle_set_vacation_days_request(mqtt, device, days)
 
 
+@cli.command()  # type: ignore[attr-defined]
+@click.argument("days", type=click.IntRange(1, 30))
+@async_command
+async def vacation_duration(
+    mqtt: NavienMqttClient, device: Any, days: int
+) -> None:
+    """Set the vacation day count without entering vacation mode.
+
+    Sends the app's goout-day command. Use ``vacation`` to enter vacation
+    mode for a number of days.
+    """
+    await handlers.handle_set_vacation_duration_request(mqtt, device, days)
+
+
 @cli.command()  # type: ignore[attr-defined]
 @click.argument(
     "mode_val", type=click.Choice(["1", "2", "3", "4"]), metavar="MODE"
@@ -667,8 +792,37 @@ def _parse_months(
     return months
 
 
+def _parse_years(
+    ctx: click.Context, param: click.Parameter, value: str | None
+) -> list[int] | None:
+    """Parse ``--years`` at parse time, so bad input is a usage error.
+
+    Years must fall in the range the library accepts; duplicates are
+    dropped, keeping the first occurrence.
+    """
+    if value is None:
+        return None
+    years: list[int] = []
+    for raw in value.split(","):
+        try:
+            year = int(raw.strip())
+        except ValueError:
+            raise click.BadParameter(
+                f"{raw.strip()!r} is not a year; expected a comma-separated "
+                "list like 2025,2026"
+            ) from None
+        if not MIN_ENERGY_YEAR <= year <= MAX_ENERGY_YEAR:
+            raise click.BadParameter(
+                f"{year} is not in the range "
+                f"{MIN_ENERGY_YEAR}-{MAX_ENERGY_YEAR}"
+            )
+        if year not in years:
+            years.append(year)
+    return years
+
+
 class _EnergySelection(click.Command):
-    """Rejects an unusable --month/--months combination during parsing.
+    """Rejects an unusable --month/--months/--years 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``,
@@ -681,23 +835,48 @@ class _EnergySelection(click.Command):
     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:
+        years, year = ctx.params.get("years"), ctx.params.get("year")
+        chosen = [
+            name
+            for name, value in (
+                ("--month", month),
+                ("--months", months),
+                ("--years", years),
+            )
+            if value is not None
+        ]
+        if len(chosen) > 1:
             raise click.UsageError(
-                "Use either --month (daily breakdown) or --months "
-                "(monthly summary), not both",
+                "Use only one of --month (daily breakdown), --months "
+                "(monthly summary) or --years (per-month for whole years), "
+                f"not {' and '.join(chosen)}",
                 ctx=ctx,
             )
-        if month is None and months is None:
+        if not chosen:
             raise click.UsageError(
-                "Either --months (for monthly summary) or --month "
-                "(for daily breakdown) is required",
+                "One of --months (monthly summary), --month (daily "
+                "breakdown) or --years (whole years) is required",
                 ctx=ctx,
             )
+        if years is not None and year is not None:
+            raise click.UsageError(
+                "--years already names the years; do not pass --year",
+                ctx=ctx,
+            )
+        if years is None and year is None:
+            raise click.UsageError(
+                "--year is required with --month or --months", 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(
+    "--year",
+    type=click.IntRange(MIN_ENERGY_YEAR, MAX_ENERGY_YEAR),
+    required=False,
+    help="Year to query",
+)
 @click.option(
     "--months",
     required=False,
@@ -710,28 +889,38 @@ class _EnergySelection(click.Command):
     required=False,
     help="Show daily breakdown for a specific month (1-12)",
 )
+@click.option(
+    "--years",
+    required=False,
+    callback=_parse_years,
+    help="Comma-separated years for a per-month breakdown (e.g. 2025,2026)",
+)
 @async_command
 async def energy(
     mqtt: NavienMqttClient,
     device: Any,
-    year: int,
+    year: int | None,
     months: list[int] | None,
     month: int | None,
+    years: list[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.
+    Use --year with --months for a monthly summary or --month for a daily
+    breakdown, or --years alone for a per-month breakdown of whole years
+    (the device's monthly query). 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
+    # _EnergySelection rejected every combination but these during
     # parsing, so exactly one of the options is set here.
-    if month is not None:
+    if years is not None:
+        await handlers.handle_get_energy_monthly_request(mqtt, device, years)
+    elif month is not None and year is not None:
         await handlers.handle_get_energy_request(
             mqtt, device, year, [month], daily=True
         )
-    elif months is not None:
+    elif months is not None and year is not None:
         await handlers.handle_get_energy_request(
             mqtt, device, year, months, daily=False
         )

nwp500/cli/handlers.py

@@ -21,7 +21,12 @@ from nwp500.exceptions import (
     RangeValidationError,
     ValidationError,
 )
-from nwp500.models import ReservationSchedule
+from nwp500.models import (
+    RecirculationSchedule,
+    RecirculationScheduleEntry,
+    ReservationSchedule,
+)
+from nwp500.mqtt.control import validate_recirculation_schedule
 from nwp500.mqtt.utils import get_response_data, redact_serial
 from nwp500.reservations import (
     add_reservation,
@@ -35,8 +40,12 @@ from nwp500.unit_system import get_unit_system
 from .output_formatters import (
     print_device_info,
     print_device_status,
+    print_diagnostics,
     print_energy_usage,
+    print_firmware_download_info,
     print_json,
+    print_recirculation_schedule,
+    print_yearly_energy_usage,
 )
 from .rich_output import get_formatter
 
@@ -897,6 +906,238 @@ async def handle_get_energy_request(
         _logger.error(f"Error getting energy data: {e}")
 
 
+async def handle_get_energy_monthly_request(
+    mqtt: NavienMqttClient, device: Device, years: list[int]
+) -> None:
+    """Request per-month energy usage for whole years and print each year."""
+    try:
+        res: Any = await _wait_for_response(
+            mqtt.subscribe_energy_usage_monthly,
+            device,
+            lambda: mqtt.request_energy_usage_monthly(device, years),
+            action_name="monthly energy usage",
+            timeout=15,
+        )
+        print_yearly_energy_usage(
+            cast(EnergyUsageResponse, res), list(dict.fromkeys(years))
+        )
+    except TimeoutError:
+        _print_no_answer("monthly energy usage")
+    except (ValidationError, Nwp500Error) as e:
+        _logger.error(f"Error getting energy data: {e}")
+        _formatter.print_error(str(e), title="Monthly Energy Usage")
+    except Exception as e:
+        _logger.error(f"Error getting energy data: {e}")
+
+
+async def handle_diagnostics_request(
+    mqtt: NavienMqttClient, device: Device, output_json: bool = False
+) -> None:
+    """Request the installer diagnostics counters and print them."""
+    try:
+        diagnostics: Any = await _wait_for_response(
+            mqtt.subscribe_diagnostics,
+            device,
+            lambda: mqtt.request_diagnostics(device),
+            action_name="diagnostics",
+            timeout=15,
+        )
+        if output_json:
+            print_json(diagnostics.model_dump())
+        else:
+            print_diagnostics(diagnostics)
+    except TimeoutError:
+        _print_no_answer("diagnostics")
+    except Nwp500Error as e:
+        _logger.error(f"Error getting diagnostics: {e}")
+        _formatter.print_error(str(e), title="Diagnostics")
+    except Exception as e:
+        _logger.error(f"Error getting diagnostics: {e}")
+
+
+async def handle_firmware_download_info_request(
+    mqtt: NavienMqttClient, device: Device, output_json: bool = False
+) -> None:
+    """Request the firmware download (OTA) information and print it."""
+    try:
+        info: Any = await _wait_for_response(
+            mqtt.subscribe_firmware_download_info,
+            device,
+            lambda: mqtt.request_firmware_download_info(device),
+            action_name="firmware download info",
+        )
+        if output_json:
+            print_json(info.model_dump())
+        else:
+            print_firmware_download_info(info)
+    except TimeoutError:
+        _print_no_answer("firmware download info")
+    except Nwp500Error as e:
+        _logger.error(f"Error getting firmware download info: {e}")
+        _formatter.print_error(str(e), title="Firmware Download Info")
+    except Exception as e:
+        _logger.error(f"Error getting firmware download info: {e}")
+
+
+async def handle_get_recirculation_schedule_request(
+    mqtt: NavienMqttClient, device: Device, output_json: bool = False
+) -> None:
+    """Request the recirculation pump schedule and print it."""
+    try:
+        schedule: Any = await _wait_for_response(
+            mqtt.subscribe_recirculation_schedule_response,
+            device,
+            lambda: mqtt.request_recirculation_schedule(device),
+            action_name="recirculation schedule",
+        )
+        if output_json:
+            print_json(schedule.model_dump())
+        else:
+            print_recirculation_schedule(schedule)
+    except TimeoutError:
+        _print_no_answer("recirculation schedule")
+    except (DeviceError, Nwp500Error) as e:
+        _logger.error(f"Error getting recirculation schedule: {e}")
+        _formatter.print_error(str(e), title="Recirculation Schedule")
+    except Exception as e:
+        _logger.error(f"Error getting recirculation schedule: {e}")
+
+
+RECIRCULATION_ENTRY_KEYS = frozenset(
+    {"enable", "week", "hour", "min", "mode", "param"}
+)
+
+
+def parse_recirculation_schedule_json(
+    schedule_json: str, enabled: bool
+) -> RecirculationSchedule:
+    """Parse and validate a CLI recirculation schedule.
+
+    ``schedule_json`` is a JSON array of objects with ``enable`` (2/1),
+    ``week`` (day bitfield), ``hour``, ``min`` and ``mode`` (2 = pump on,
+    1 = pump off); ``param`` may be given but must be ``-1``. Unknown keys
+    are rejected rather than ignored, so an entry in another format cannot
+    silently become an all-default entry.
+
+    Raises:
+        ValueError: With a user-facing message on malformed input.
+    """
+    try:
+        entries = json.loads(schedule_json)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"not valid JSON: {e.msg}") from None
+    if not isinstance(entries, list):
+        raise ValueError("schedule must be a JSON array of entries")
+    parsed: list[RecirculationScheduleEntry] = []
+    for index, raw in enumerate(cast(list[Any], entries), start=1):
+        if not isinstance(raw, dict):
+            raise ValueError(f"entry {index} must be a JSON object")
+        entry = cast(dict[str, Any], raw)
+        unknown = sorted(set(entry) - RECIRCULATION_ENTRY_KEYS)
+        if unknown:
+            raise ValueError(
+                f"entry {index} has unknown keys {', '.join(unknown)}; "
+                "expected enable, week, hour, min, mode, param"
+            )
+        for key in ("week", "hour", "min"):
+            if key not in entry:
+                raise ValueError(f"entry {index} is missing {key!r}")
+        for key, value in entry.items():
+            if not isinstance(value, int) or isinstance(value, bool):
+                raise ValueError(f"entry {index}: {key} must be an integer")
+        # Checked before model_validate, which maps a read-back's 255 to -1.
+        if entry.get("param", -1) != -1:
+            raise ValueError(f"entry {index}: param must be -1 if given")
+        parsed.append(RecirculationScheduleEntry.model_validate(entry))
+    schedule = RecirculationSchedule(
+        reservationUse=2 if enabled else 1, reservation=parsed
+    )
+    try:
+        validate_recirculation_schedule(schedule)
+    except ValidationError as e:
+        raise ValueError(str(e)) from None
+    return schedule
+
+
+async def handle_set_recirculation_schedule_request(
+    mqtt: NavienMqttClient,
+    device: Device,
+    schedule_json: str,
+    enabled: bool,
+    timeout: float = 10.0,
+) -> None:
+    """Write the recirculation pump schedule and confirm it from the echo.
+
+    See :func:`parse_recirculation_schedule_json` for the input format.
+    The write asks for the schedule back on ``recirc-rsv/rd``. Success is
+    reported only when a reply's canonical form matches what was written,
+    so a stale reply (from an earlier write or a concurrent read) or a
+    schedule the device stored differently is not mistaken for
+    confirmation. The echo has not been observed on a unit with
+    recirculation, so no reply at all is reported as sent but unconfirmed
+    rather than as a failure.
+    """
+    try:
+        schedule = parse_recirculation_schedule_json(schedule_json, enabled)
+    except ValueError as e:
+        _logger.error(f"Invalid schedule: {e}")
+        _formatter.print_error(str(e), title="Invalid Schedule")
+        return
+
+    expected = schedule.canonical()
+    confirmed: asyncio.Future[RecirculationSchedule] = (
+        asyncio.get_running_loop().create_future()
+    )
+    last_seen: list[RecirculationSchedule] = []
+
+    def on_schedule(reply: RecirculationSchedule) -> None:
+        last_seen.append(reply)
+        if not confirmed.done() and reply.canonical() == expected:
+            confirmed.set_result(reply)
+
+    try:
+        await mqtt.subscribe_recirculation_schedule_response(
+            device, on_schedule
+        )
+        try:
+            await mqtt.configure_recirculation_schedule(device, schedule)
+            stored = await asyncio.wait_for(confirmed, timeout=timeout)
+            _formatter.print_success("Recirculation schedule updated")
+            print_recirculation_schedule(stored)
+        except TimeoutError:
+            if last_seen:
+                _formatter.print_error(
+                    "The device replied with a schedule that does not match "
+                    "the one written. It may have rejected or changed it; "
+                    "the last schedule it reported is shown below.",
+                    title="Recirculation Schedule Not Confirmed",
+                )
+                print_recirculation_schedule(last_seen[-1])
+            else:
+                _formatter.print_info(
+                    "Recirculation schedule sent, but the device did not "
+                    "echo it back. Run 'recirc-schedule get' to check what "
+                    "it stored."
+                )
+        finally:
+            await mqtt.unsubscribe_recirculation_schedule_response(
+                device, on_schedule
+            )
+    except (ValidationError, DeviceError, Nwp500Error) as e:
+        _logger.error(f"Error updating recirculation schedule: {e}")
+        _formatter.print_error(str(e), title="Recirculation Schedule")
+    except Exception as e:
+        _logger.error(f"Error updating recirculation schedule: {e}")
+
+
+def _print_no_answer(what: str) -> None:
+    """Report a query the device did not answer in time."""
+    _formatter.print_error(
+        f"The device did not answer the {what} request in time.",
+        title="No Response",
+    )
+
+
 async def handle_reset_air_filter_request(
     mqtt: NavienMqttClient, device: Device
 ) -> None:
@@ -910,6 +1151,34 @@ async def handle_reset_air_filter_request(
     )
 
 
+async def handle_set_air_filter_life_request(
+    mqtt: NavienMqttClient, device: Device, hours: int
+) -> None:
+    """Set the air filter service interval."""
+    await _handle_command_with_status_feedback(
+        mqtt,
+        device,
+        lambda: mqtt.set_air_filter_life(device, hours),
+        "setting air filter life",
+        f"Air filter life set to {hours} hours"
+        if hours
+        else "Air filter alarm disabled",
+    )
+
+
+async def handle_reset_condenser_fault_request(
+    mqtt: NavienMqttClient, device: Device
+) -> None:
+    """Clear a condenser fault."""
+    await _handle_command_with_status_feedback(
+        mqtt,
+        device,
+        lambda: mqtt.reset_condenser_fault(device),
+        "resetting condenser fault",
+        "Condenser fault reset sent",
+    )
+
+
 async def handle_set_vacation_days_request(
     mqtt: NavienMqttClient, device: Device, days: int
 ) -> None:
@@ -923,6 +1192,19 @@ async def handle_set_vacation_days_request(
     )
 
 
+async def handle_set_vacation_duration_request(
+    mqtt: NavienMqttClient, device: Device, days: int
+) -> None:
+    """Set the vacation day count without entering vacation mode."""
+    await _handle_command_with_status_feedback(
+        mqtt,
+        device,
+        lambda: mqtt.set_vacation_duration(device, days),
+        "setting vacation duration",
+        f"Vacation duration set to {days} days",
+    )
+
+
 async def handle_set_recirculation_mode_request(
     mqtt: NavienMqttClient, device: Device, mode: int
 ) -> None: