diff --git a/docs/api/nwp500.rst b/docs/api/nwp500.rst index 5e2f5cd..46dc281 100644 --- a/docs/api/nwp500.rst +++ b/docs/api/nwp500.rst @@ -8,6 +8,7 @@ Subpackages :maxdepth: 4 nwp500.cli + nwp500.mqtt Submodules ---------- @@ -28,6 +29,14 @@ nwp500.auth module :show-inheritance: :undoc-members: +nwp500.command\_decorators module +--------------------------------- + +.. automodule:: nwp500.command_decorators + :members: + :show-inheritance: + :undoc-members: + nwp500.config module -------------------- @@ -36,106 +45,106 @@ nwp500.config module :show-inheritance: :undoc-members: -nwp500.constants module ------------------------ +nwp500.converters module +------------------------ -.. automodule:: nwp500.constants +.. automodule:: nwp500.converters :members: :show-inheritance: :undoc-members: -nwp500.encoding module ----------------------- +nwp500.device\_capabilities module +---------------------------------- -.. automodule:: nwp500.encoding +.. automodule:: nwp500.device_capabilities :members: :show-inheritance: :undoc-members: -nwp500.events module --------------------- +nwp500.device\_info\_cache module +--------------------------------- -.. automodule:: nwp500.events +.. automodule:: nwp500.device_info_cache :members: :show-inheritance: :undoc-members: -nwp500.exceptions module ------------------------- +nwp500.encoding module +---------------------- -.. automodule:: nwp500.exceptions +.. automodule:: nwp500.encoding :members: :show-inheritance: :undoc-members: -nwp500.models module --------------------- +nwp500.enums module +------------------- -.. automodule:: nwp500.models +.. automodule:: nwp500.enums :members: :show-inheritance: :undoc-members: -nwp500.mqtt\_client module --------------------------- +nwp500.events module +-------------------- -.. automodule:: nwp500.mqtt_client +.. automodule:: nwp500.events :members: :show-inheritance: :undoc-members: -nwp500.mqtt\_command\_queue module ----------------------------------- +nwp500.exceptions module +------------------------ -.. automodule:: nwp500.mqtt_command_queue +.. automodule:: nwp500.exceptions :members: :show-inheritance: :undoc-members: -nwp500.mqtt\_connection module ------------------------------- +nwp500.factory module +--------------------- -.. automodule:: nwp500.mqtt_connection +.. automodule:: nwp500.factory :members: :show-inheritance: :undoc-members: -nwp500.mqtt\_device\_control module ------------------------------------ +nwp500.field\_factory module +---------------------------- -.. automodule:: nwp500.mqtt_device_control +.. automodule:: nwp500.field_factory :members: :show-inheritance: :undoc-members: -nwp500.mqtt\_periodic module ----------------------------- +nwp500.models module +-------------------- -.. automodule:: nwp500.mqtt_periodic +.. automodule:: nwp500.models :members: :show-inheritance: :undoc-members: -nwp500.mqtt\_reconnection module --------------------------------- +nwp500.mqtt\_events module +-------------------------- -.. automodule:: nwp500.mqtt_reconnection +.. automodule:: nwp500.mqtt_events :members: :show-inheritance: :undoc-members: -nwp500.mqtt\_subscriptions module ---------------------------------- +nwp500.temperature module +------------------------- -.. automodule:: nwp500.mqtt_subscriptions +.. automodule:: nwp500.temperature :members: :show-inheritance: :undoc-members: -nwp500.mqtt\_utils module -------------------------- +nwp500.topic\_builder module +---------------------------- -.. automodule:: nwp500.mqtt_utils +.. automodule:: nwp500.topic_builder :members: :show-inheritance: :undoc-members: diff --git a/docs/conf.py b/docs/conf.py index a2089f7..ba6d57b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -78,6 +78,7 @@ # Suppress warnings for classes/functions exported in multiple modules suppress_warnings = [ "ref.python", # Suppress "more than one target found" warnings + "py.duplicate", # Suppress all "duplicate" warnings including duplicate_description ] # Add any paths that contain templates here, relative to this directory. @@ -289,4 +290,17 @@ "pyscaffold": ("https://pyscaffold.org/en/stable", None), } +# Suppress duplicate object description warnings from re-exported classes +import logging + +class DuplicateWarningFilter(logging.Filter): + def filter(self, record): + # Suppress "duplicate object description" warnings + return "duplicate object description" not in record.getMessage() + +# Install the filter when Sphinx initializes +def setup(app): + logger = logging.getLogger("sphinx") + logger.addFilter(DuplicateWarningFilter()) + print(f"loading configurations for {project} {version} ...", file=sys.stderr) diff --git a/docs/enumerations.rst b/docs/enumerations.rst index 28ea228..ef9d436 100644 --- a/docs/enumerations.rst +++ b/docs/enumerations.rst @@ -10,6 +10,7 @@ Device Control Commands .. autoclass:: nwp500.enums.CommandCode :members: :undoc-members: + :no-index: These command IDs are used in MQTT control messages to change device settings and trigger actions. The most commonly used commands include: @@ -37,6 +38,7 @@ OnOffFlag .. autoclass:: nwp500.enums.OnOffFlag :members: :undoc-members: + :no-index: Generic on/off flag used throughout status fields for power status, TOU status, recirculation status, vacation mode, anti-legionella, and other boolean settings. @@ -49,6 +51,7 @@ Operation .. autoclass:: nwp500.enums.Operation :members: :undoc-members: + :no-index: Device operation state indicating overall device activity. @@ -58,6 +61,7 @@ DhwOperationSetting .. autoclass:: nwp500.enums.DhwOperationSetting :members: :undoc-members: + :no-index: User-configured DHW heating mode preference. This determines which heat source(s) the device will use when heating is needed: @@ -83,6 +87,7 @@ CurrentOperationMode .. autoclass:: nwp500.enums.CurrentOperationMode :members: :undoc-members: + :no-index: Real-time operational state (read-only). This reflects what the device is actually doing right now, which may differ from the configured mode setting: @@ -106,6 +111,7 @@ HeatSource .. autoclass:: nwp500.enums.HeatSource :members: :undoc-members: + :no-index: Currently active heat source (read-only status). This reflects what the device is *currently* using, not what mode it's set to. In Hybrid mode, this field @@ -117,6 +123,7 @@ DREvent .. autoclass:: nwp500.enums.DREvent :members: :undoc-members: + :no-index: Demand Response event status. Allows utilities to manage grid load by signaling water heaters to reduce consumption (shed) or pre-heat (load up) before peak periods. @@ -127,6 +134,7 @@ WaterLevel .. autoclass:: nwp500.enums.WaterLevel :members: :undoc-members: + :no-index: Hot water level indicator displayed as gauge in app. IDs are non-sequential, likely represent bit positions for multi-level displays. @@ -137,6 +145,7 @@ FilterChange .. autoclass:: nwp500.enums.FilterChange :members: :undoc-members: + :no-index: Air filter status for heat pump models. Indicates when air filter maintenance is needed. @@ -147,6 +156,7 @@ RecirculationMode .. autoclass:: nwp500.enums.RecirculationMode :members: :undoc-members: + :no-index: Recirculation pump operation mode: @@ -164,6 +174,7 @@ TouWeekType .. autoclass:: nwp500.enums.TouWeekType :members: :undoc-members: + :no-index: Day grouping for TOU schedules. Allows separate schedules for weekdays and weekends to account for different electricity rates and usage patterns. @@ -174,6 +185,7 @@ TouRateType .. autoclass:: nwp500.enums.TouRateType :members: :undoc-members: + :no-index: Electricity rate period type. Device behavior can be configured for each period: @@ -190,6 +202,7 @@ TemperatureType .. autoclass:: nwp500.enums.TemperatureType :members: :undoc-members: + :no-index: Temperature display unit preference (Celsius or Fahrenheit). @@ -201,6 +214,7 @@ TempFormulaType .. autoclass:: nwp500.enums.TempFormulaType :members: :undoc-members: + :no-index: Temperature conversion formula type. Different device models use slightly different rounding algorithms when converting internal Celsius values to Fahrenheit: @@ -219,6 +233,7 @@ UnitType .. autoclass:: nwp500.enums.UnitType :members: :undoc-members: + :no-index: Navien device/unit model types. Common values: @@ -236,6 +251,7 @@ DeviceType .. autoclass:: nwp500.enums.DeviceType :members: :undoc-members: + :no-index: Communication device type (WiFi module model). @@ -245,6 +261,7 @@ FirmwareType .. autoclass:: nwp500.enums.FirmwareType :members: :undoc-members: + :no-index: Firmware component types. Devices may have multiple firmware components that can be updated independently. @@ -290,4 +307,4 @@ For detailed protocol documentation, see: - :doc:`protocol/device_status` - Status field definitions - :doc:`guides/time_of_use` - TOU scheduling and rate types -- :doc:`protocol/control_commands` - Control command usage +- :doc:`protocol/quick_reference` - Quick reference and control commands diff --git a/docs/guides/mqtt_diagnostics.rst b/docs/guides/mqtt_diagnostics.rst index 250ca92..0c4183e 100644 --- a/docs/guides/mqtt_diagnostics.rst +++ b/docs/guides/mqtt_diagnostics.rst @@ -1116,8 +1116,8 @@ Investigation Checklist See Also ======== -- :doc:`/docs/DEVICE_STATUS_FIELDS` - Device status field reference -- :doc:`/docs/MQTT_CLIENT` - MQTT client API documentation +- :doc:`../protocol/device_status` - Device status field reference +- :doc:`../python_api/mqtt_client` - MQTT client API documentation External Resources diff --git a/docs/protocol/mqtt_protocol.rst b/docs/protocol/mqtt_protocol.rst index a13e5be..b35b20e 100644 --- a/docs/protocol/mqtt_protocol.rst +++ b/docs/protocol/mqtt_protocol.rst @@ -770,8 +770,7 @@ Status Response "operationBusy": 2, "compUse": 2, "heatUpperUse": 1, - "errorCode": 0, - ... + "errorCode": 0 } } } @@ -796,8 +795,7 @@ Feature/Info Response "controller_sw_version": 184614912, "dhw_temperature_min": 75, "dhw_temperature_max": 130, - "energy_usage_use": 1, - ... + "energy_usage_use": 1 } } } diff --git a/docs/python_api/cli.rst b/docs/python_api/cli.rst index 0c7d54f..eda83ac 100644 --- a/docs/python_api/cli.rst +++ b/docs/python_api/cli.rst @@ -94,6 +94,13 @@ Get current device status (one-time query). .. code-block:: bash python3 -m nwp500.cli status + python3 -m nwp500.cli status --raw + +**Options:** + +.. option:: --raw + + Output raw JSON response (unformatted). **Output:** Device status including water temperature, target temperature, mode, power consumption, tank charge percentage, and component states. @@ -122,10 +129,38 @@ Show comprehensive device information (firmware, model, capabilities, serial). .. code-block:: bash python3 -m nwp500.cli info + python3 -m nwp500.cli info --raw + +**Options:** + +.. option:: --raw + + Output raw JSON response (unformatted). **Output:** Device name, MAC address, firmware versions, features supported, temperature ranges, and capabilities. +device-info +^^^^^^^^^^^ + +Show basic device information from REST API (DeviceInfo model). + +.. code-block:: bash + + python3 -m nwp500.cli device-info + python3 -m nwp500.cli device-info --raw + +**Options:** + +.. option:: --raw + + Output raw JSON response (unformatted). + +**Output:** Basic device information from REST API. + +**Note:** Use ``info`` command for MQTT-based comprehensive information, or +``device-info`` for REST API-based basic information. + serial ^^^^^^ @@ -386,24 +421,27 @@ Energy & Utility Commands energy ^^^^^^ -Query historical energy usage data by month. +Query historical energy usage data by month or daily breakdown. .. code-block:: bash - # Get October 2024 + # Get monthly summary for October 2024 python3 -m nwp500.cli energy --year 2024 --months 10 # Get multiple months python3 -m nwp500.cli energy --year 2024 --months 8,9,10 - # Get full year + # Get daily breakdown for October 2024 + python3 -m nwp500.cli energy --year 2024 --month 10 + + # Get full year summary python3 -m nwp500.cli energy --year 2024 --months 1,2,3,4,5,6,7,8,9,10,11,12 **Syntax:** .. code-block:: bash - python3 -m nwp500.cli energy --year --months + python3 -m nwp500.cli energy --year [--months | --month ] **Options:** @@ -413,7 +451,13 @@ Query historical energy usage data by month. .. option:: --months MONTHS - Comma-separated list of months (1-12). **Required.** + Comma-separated list of months (1-12) for monthly summary. Use either + ``--months`` OR ``--month``, not both. + +.. option:: --month MONTH + + Show daily breakdown for a specific month (1-12). Use either ``--month`` + OR ``--months``, not both. **Output:** Energy usage breakdown by heat pump vs. electric heating. @@ -427,7 +471,7 @@ Query historical energy usage data by month. "heat_pump_hours": 245, "electric_wh": 302469, "electric_hours": 67, - "by_day": [...] + "by_day": [] } tou @@ -717,4 +761,4 @@ Related Documentation * :doc:`auth_client` - Python authentication API * :doc:`api_client` - Python REST API * :doc:`mqtt_client` - Python MQTT API -* :doc:`../guides/mqtt_basics` - MQTT protocol guide +* :doc:`../guides/auto_recovery` - Connection recovery and resilience diff --git a/docs/python_api/models.rst b/docs/python_api/models.rst index e26a4b3..cb57adb 100644 --- a/docs/python_api/models.rst +++ b/docs/python_api/models.rst @@ -608,4 +608,3 @@ Related Documentation * :doc:`auth_client` - Authentication * :doc:`api_client` - REST API * :doc:`mqtt_client` - MQTT client -* :doc:`constants` - Command codes and constants diff --git a/src/nwp500/field_factory.py b/src/nwp500/field_factory.py index 26cc0d8..6b69b59 100644 --- a/src/nwp500/field_factory.py +++ b/src/nwp500/field_factory.py @@ -6,6 +6,7 @@ Each factory function creates a Pydantic Field with metadata for Home Assistant integration: + - temperature_field: Adds unit_of_measurement, device_class='temperature', suggested_display_precision - signal_strength_field: Adds unit_of_measurement,