From 819e54b9c9676164ca0a859ce6a59a5e7a87416b Mon Sep 17 00:00:00 2001 From: Emmanuel Levijarvi Date: Wed, 22 Apr 2026 12:26:52 -0700 Subject: [PATCH] documentation updates --- README.rst | 47 +---- docs/enumerations.rst | 5 +- docs/guides/advanced_features_explained.rst | 18 +- docs/guides/auto_recovery.rst | 4 +- docs/guides/command_queue.rst | 11 +- docs/guides/energy_monitoring.rst | 220 ++++++++++---------- docs/guides/event_system.rst | 4 +- docs/guides/home_assistant_integration.rst | 7 +- docs/guides/mqtt_diagnostics.rst | 6 +- docs/guides/time_of_use.rst | 10 +- docs/guides/unit_conversion.rst | 2 +- docs/index.rst | 61 +----- docs/protocol/data_conversions.rst | 6 +- docs/protocol/device_features.rst | 4 +- docs/protocol/device_status.rst | 2 +- docs/protocol/error_codes.rst | 2 +- docs/protocol/quick_reference.rst | 2 +- docs/python_api/cli.rst | 4 +- docs/python_api/device_control.rst | 2 +- docs/python_api/exceptions.rst | 2 +- docs/python_api/models.rst | 4 +- 21 files changed, 168 insertions(+), 255 deletions(-) diff --git a/README.rst b/README.rst index ab57c14..11981a2 100644 --- a/README.rst +++ b/README.rst @@ -5,7 +5,7 @@ nwp500-python Python library for Navien NWP500 Heat Pump Water Heater ======================================================== -A Python library for monitoring and controlling the Navien NWP500 Heat Pump Water Heater through the Navilink cloud service. This library provides comprehensive access to device status, temperature control, operation mode management, and real-time monitoring capabilities. +A Python library for monitoring and controlling the Navien NWP500 Heat Pump Water Heater through the Navilink cloud service. **Documentation:** https://nwp500-python.readthedocs.io/ @@ -32,25 +32,21 @@ Installation Basic Installation (Library Only) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -For using the library as a Python package without the CLI: +For using the library as a Python package: .. code-block:: bash pip install nwp500-python -This installs the core library with support for API and MQTT clients. No CLI framework is required. - Installation with CLI Support ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To use the command-line interface with rich formatting and colors: +To use the CLI with rich formatting and colors: .. code-block:: bash pip install nwp500-python[cli] -This includes both the ``click`` CLI framework and the ``rich`` formatting library for enhanced terminal output with formatted tables, progress bars, and colored output. - Basic Usage ----------- @@ -111,9 +107,9 @@ Monitor your device in real-time using MQTT: Command Line Interface ====================== -The library includes a command line interface for monitoring and controlling your Navien water heater. +Monitor and control your Navien water heater from the terminal. -**Installation Requirement:** The CLI requires the ``cli`` extra: +**Installation Requirement:** .. code-block:: bash @@ -218,39 +214,18 @@ Quick Reference Device Status Fields ==================== -The library provides access to comprehensive device status information: - -**Temperature Sensors** - * Water temperature (current and target) - * Tank upper/lower temperatures - * Ambient temperature - * Discharge, suction, and evaporator temperatures - * Inlet temperature - -**System Status** - * Operation mode (Heat Pump, Energy Saver, High Demand, Electric, Vacation) - * Compressor status - * Heat pump and electric heater status - * Evaporator fan status - * Tank charge percentage - -**Power & Energy** - * Current power consumption (Watts) - * Total energy capacity (Wh) - * Available energy capacity (Wh) - -**Diagnostics** - * WiFi signal strength - * Error codes - * Fault status - * Cumulative operation time - * Flow rates +The library provides access to comprehensive device status information. See the `full documentation `_ for all available fields. Documentation ============= Full docs: https://nwp500-python.readthedocs.io/ +Home Assistant Integration +========================== + +Use this library with Home Assistant: `ha_nwp500 `_ + Data Models =========== diff --git a/docs/enumerations.rst b/docs/enumerations.rst index ef9d436..cd4afc2 100644 --- a/docs/enumerations.rst +++ b/docs/enumerations.rst @@ -1,8 +1,7 @@ Enumerations Reference ====================== -This document provides a comprehensive reference for all enumerations used in -the Navien NWP500 protocol. +This document lists all enumerations used in the Navien NWP500 protocol. Device Control Commands ----------------------- @@ -222,7 +221,7 @@ rounding algorithms when converting internal Celsius values to Fahrenheit: - **ASYMMETRIC** (Type 0): Special rounding based on raw value remainder - **STANDARD** (Type 1): Simple round to nearest integer -This ensures the mobile app matches the device's built-in display exactly. +This keeps the mobile app display in sync with the device's built-in display. Device Type Enumerations ------------------------- diff --git a/docs/guides/advanced_features_explained.rst b/docs/guides/advanced_features_explained.rst index ddb5990..8b86dea 100644 --- a/docs/guides/advanced_features_explained.rst +++ b/docs/guides/advanced_features_explained.rst @@ -1,16 +1,16 @@ -Advanced Features Explained: Weather-Responsive Heating, Demand Response, and Tank Stratification -================================================================================================== +Weather Response, Demand Response, and Tank Stratification +=========================================================== -This document provides comprehensive technical documentation for three advanced NWP500 features. +This document covers three advanced NWP500 features. Overview of Advanced Features ----------------------------- -The NWP500 heat pump water heater implements sophisticated algorithms for grid integration, environmental responsiveness, and efficiency optimization: +The NWP500 heat pump water heater implements algorithms for grid integration, environmental responsiveness, and efficiency optimization: 1. **Weather-Responsive Heating** - Adjusts heating strategy based on ambient temperature conditions 2. **Demand Response Integration** - Responds to grid signals for demand/response events (CTA-2045) -3. **Tank Stratification Optimization** - Uses dual temperature sensors for enhanced heating efficiency +3. **Tank Stratification Optimization** - Uses dual temperature sensors for improved heating efficiency Weather-Responsive Heating ========================== @@ -18,7 +18,7 @@ Weather-Responsive Heating Feature Overview ---------------- -The device continuously monitors ambient air temperature to optimize heat pump performance and adjust heating strategies. This enables the system to maintain comfort while adapting to seasonal conditions automatically. +The device continuously monitors ambient air temperature to optimize heat pump performance and adjust heating strategies based on seasonal conditions. Technical Implementation ------------------------ @@ -230,12 +230,6 @@ Implementation in Device Firmware 3. **Grid Stability**: Participate in demand response events, earn utility incentives 4. **Cost Reduction**: Shift heating to low-price periods automatically -Utility Integration Requirements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To use demand response with your NWP500: - - Tank Temperature Sensors ------------------------ diff --git a/docs/guides/auto_recovery.rst b/docs/guides/auto_recovery.rst index e0949f0..b81dc8f 100644 --- a/docs/guides/auto_recovery.rst +++ b/docs/guides/auto_recovery.rst @@ -127,7 +127,7 @@ Refresh authentication tokens before retrying (handles token expiry). await mqtt_client.subscribe_device_status(device, on_status) await mqtt_client.start_periodic_requests(device) -**Pros:** Handles token expiry, more robust +**Pros:** Handles token expiry, more reliable **Cons:** More complex, need to manage client lifecycle @@ -453,4 +453,4 @@ For production use, **use Strategy 4 (Exponential Backoff)** via the ``Resilient * Subscription restoration * Configurable limits and delays -This ensures your application stays connected even during extended network outages. +Your application will stay connected even through extended network outages. diff --git a/docs/guides/command_queue.rst b/docs/guides/command_queue.rst index f243925..9d215e1 100644 --- a/docs/guides/command_queue.rst +++ b/docs/guides/command_queue.rst @@ -54,15 +54,12 @@ Queue Management **Internal Components:** -- ``QueuedCommand`` dataclass - Stores command details (topic, payload, QoS, timestamp) -- ``_command_queue`` - Deque with maximum length for efficient FIFO operations -- ``_queue_command()`` - Internal method to add commands to queue -- ``_send_queued_commands()`` - Internal method to process queue on reconnection +Internally, the queue uses a fixed-length deque for O(1) operations and FIFO ordering. You do not need to interact with these components directly. Integration with Reconnection ------------------------------ -The command queue integrates seamlessly with the existing automatic reconnection feature: +The command queue works with the existing automatic reconnection feature: 1. Connection is lost 2. Commands sent during disconnection are queued @@ -231,7 +228,7 @@ Benefits ======== 1. **No Lost Commands** - Commands sent during disconnection are preserved -2. **Automatic Recovery** - Works seamlessly with auto-reconnection +2. **Automatic Recovery** - Works with auto-reconnection 3. **Transparent** - Works automatically without user intervention 4. **Configurable** - Adjust queue size or disable if needed 5. **Monitorable** - Query queue status at any time @@ -247,7 +244,7 @@ The command queue feature is designed with reliability and ease of use in mind: - **Enabled by default** - Most users want commands preserved during network issues - **Automatic operation** - No manual queue management required - **Configurable** - Can be disabled or tuned for specific use cases -- **Integrated** - Works seamlessly with automatic reconnection +- **Integrated** - Works with automatic reconnection Use Cases ========= diff --git a/docs/guides/energy_monitoring.rst b/docs/guides/energy_monitoring.rst index b7ffaac..eb097b5 100644 --- a/docs/guides/energy_monitoring.rst +++ b/docs/guides/energy_monitoring.rst @@ -7,7 +7,7 @@ from Navien NWP500 water heaters. Overview -------- -The NWP500 provides comprehensive energy monitoring through real-time +The NWP500 provides energy monitoring data through real-time status updates via MQTT. All energy-related data is available through the ``DeviceStatus`` object returned by the ``subscribe_device_status()`` callback. @@ -29,7 +29,7 @@ The most important metric for energy monitoring: power_watts = status.current_inst_power print(f"Current Power: {power_watts} W") -| **Field:** ``currentInstPower`` +| **Field:** ``current_inst_power`` | **Type:** ``float`` | **Units:** Watts (W) | **Description:** Total instantaneous power consumption of the entire @@ -52,9 +52,11 @@ Know which heating components are currently active: if status.heat_lower_use: print("Lower electric heater is running") -| **Fields:** - ``compUse`` (bool): Heat pump compressor status - - ``heatUpperUse`` (bool): Upper electric heating element status -| - ``heatLowerUse`` (bool): Lower electric heating element status +**Fields:** + +- ``comp_use`` (bool): Heat pump compressor active +- ``heat_upper_use`` (bool): Upper electric heating element active +- ``heat_lower_use`` (bool): Lower electric heating element active Cumulative Usage Statistics --------------------------- @@ -73,11 +75,11 @@ Track total runtime for each heating component: print(f"Upper Heater Runtime: {heater1_hours:.1f} hours") print(f"Lower Heater Runtime: {heater2_hours:.1f} hours") -**Fields:** - ``compRunningMinuteTotal`` (int): Total heat pump -compressor runtime in minutes - ``heater1RunningMinuteTotal`` (int): -Total upper electric heater runtime in minutes - -``heater2RunningMinuteTotal`` (int): Total lower electric heater runtime -in minutes +**Fields:** + +- ``comp_running_minute_total`` (int): Total heat pump compressor runtime in minutes +- ``heater1_running_minute_total`` (int): Total upper electric heater runtime in minutes +- ``heater2_running_minute_total`` (int): Total lower electric heater runtime in minutes Historical Energy Usage ----------------------- @@ -106,7 +108,7 @@ Request detailed daily energy usage data for specific months: # Request multiple months await mqtt_client.control.request_energy_usage(device, year=2025, months=[7, 8, 9]) -**Key Methods:** +**Methods:** - ``request_energy_usage(device, year, months)``: Request historical data - ``subscribe_energy_usage(device, callback)``: Subscribe to energy usage responses @@ -134,7 +136,7 @@ Monitor available stored energy: elif capacity > 80: print("High energy - tank is hot") -| **Field:** ``availableEnergyCapacity`` +| **Field:** ``available_energy_capacity`` | **Type:** ``int`` | **Units:** Percentage (0-100) | **Description:** Available energy in the tank as a percentage, @@ -155,10 +157,12 @@ Water Temperature print(f"Water Temperature: {current_temp}°F (Target: {target_temp}°F)") -**Fields:** - ``dhwTemperature`` (float): Current water -temperature - ``dhwTemperatureSetting`` (int): Target temperature -setting - ``dhwTemperatureMin`` (int): Minimum allowed temperature - -``dhwTemperatureMax`` (int): Maximum allowed temperature +**Fields:** + +- ``dhw_temperature`` (float): Current water temperature +- ``dhw_temperature_setting`` (int): Target temperature setting +- ``dhw_temperature_min`` (int): Minimum allowed temperature +- ``dhw_temperature_max`` (int): Maximum allowed temperature Component Temperatures ~~~~~~~~~~~~~~~~~~~~~~ @@ -187,74 +191,64 @@ Complete Energy Monitoring Example return kwh * cost_per_kwh async def monitor_energy(): - # Authenticate and get device async with NavienAuthClient("email@example.com", "password") as auth_client: - api_client = NavienAPIClient(auth_client=auth_client) device = await api_client.get_first_device() - - # Create MQTT client - mqtt_client = NavienMqttClient(auth_client) - await mqtt_client.connect() - - # Energy monitoring callback - def on_status(status: DeviceStatus): - print("\n" + "="*50) - print("ENERGY MONITORING") - print("="*50) - # Real-time power - print(f"\nCurrent Power: {status.current_inst_power} W") + # Create MQTT client inside the auth context + mqtt_client = NavienMqttClient(auth_client) + await mqtt_client.connect() - # Active components - components = [] - if status.comp_use: - components.append("Heat Pump") - if status.heat_upper_use: - components.append("Upper Heater") - if status.heat_lower_use: - components.append("Lower Heater") + # Energy monitoring callback + def on_status(status: DeviceStatus): + print("\n" + "="*50) + print("ENERGY MONITORING") + print("="*50) + + # Real-time power + print(f"\nCurrent Power: {status.current_inst_power} W") + + # Active components + components = [] + if status.comp_use: + components.append("Heat Pump") + if status.heat_upper_use: + components.append("Upper Heater") + if status.heat_lower_use: + components.append("Lower Heater") + + if components: + print(f"Active: {', '.join(components)}") + else: + print("Active: None (Standby)") + + # Cumulative runtime + print(f"\nCumulative Runtime:") + print(f" Heat Pump: {status.comp_running_minute_total / 60:.1f} hours") + print(f" Upper Heater: {status.heater1_running_minute_total / 60:.1f} hours") + print(f" Lower Heater: {status.heater2_running_minute_total / 60:.1f} hours") + + # Energy capacity and temperature + print(f"\nEnergy Capacity: {status.available_energy_capacity}%") + print(f"Water Temp: {status.dhw_temperature}°F " + f"(Target: {status.dhw_temperature_setting}°F)") + + # Estimated hourly cost (if running continuously at current power) + if status.current_inst_power > 0: + hourly_cost = calculate_power_cost(status.current_inst_power, 1.0) + print(f"\nEstimated Cost (if sustained): ${hourly_cost:.3f}/hour") - if components: - print(f"Active: {', '.join(components)}") - else: - print("Active: None (Standby)") + # Subscribe to device status + await mqtt_client.subscribe_device_status(device, on_status) - # Cumulative runtime - print(f"\nCumulative Runtime:") - print(f" Heat Pump: {status.comp_running_minute_total / 60:.1f} hours") - print(f" Upper Heater: {status.heater1_running_minute_total / 60:.1f} hours") - print(f" Lower Heater: {status.heater2_running_minute_total / 60:.1f} hours") + # Request initial status + await mqtt_client.control.request_device_status(device) - # Energy capacity and temperature - print(f"\nEnergy Capacity: {status.available_energy_capacity}%") - print(f"Water Temp: {status.dhw_temperature}°F " - f"(Target: {status.dhw_temperature_setting}°F)") + # Monitor for 5 minutes + print("Monitoring energy consumption for 5 minutes...") + await asyncio.sleep(300) - # Estimated hourly cost (if running continuously at current power) - if status.current_inst_power > 0: - hourly_cost = calculate_power_cost(status.current_inst_power, 1.0) - print(f"\nEstimated Cost (if sustained): ${hourly_cost:.3f}/hour") - - # Subscribe to device status - await mqtt_client.subscribe_device_status( - device.device_info.mac_address, - on_status - ) - - # Request initial status - await mqtt_client.control.request_device_status( - device.device_info.mac_address, - device.device_info.device_type, - device.device_info.additional_value - ) - - # Monitor for 5 minutes - print("Monitoring energy consumption for 5 minutes...") - await asyncio.sleep(300) - - # Cleanup - await mqtt_client.disconnect() + await mqtt_client.disconnect() if __name__ == "__main__": asyncio.run(monitor_energy()) @@ -268,58 +262,58 @@ Power Consumption +----------------------+------------+--------------+---------------------------+ | Field | Type | Units | Description | +======================+============+==============+===========================+ -| ``currentInstPower`` | float | W | Total instantaneous power | -| | | | consumption | -+----------------------+------------+--------------+---------------------------+ -| ``compUse`` | bool | - | Heat pump compressor | -| | | | active | -+----------------------+------------+--------------+---------------------------+ -| ``heatUpperUse`` | bool | - | Upper electric heater | -| | | | active | -+----------------------+------------+--------------+---------------------------+ -| ``heatLowerUse`` | bool | - | Lower electric heater | -| | | | active | -+----------------------+------------+--------------+---------------------------+ +| ``current_inst_power`` | float | W | Total instantaneous power | +| | | | consumption | ++------------------------+-----------+--------------+---------------------------+ +| ``comp_use`` | bool | - | Heat pump compressor | +| | | | active | ++------------------------+-----------+--------------+---------------------------+ +| ``heat_upper_use`` | bool | - | Upper electric heater | +| | | | active | ++------------------------+-----------+--------------+---------------------------+ +| ``heat_lower_use`` | bool | - | Lower electric heater | +| | | | active | ++------------------------+-----------+--------------+---------------------------+ Cumulative Usage ~~~~~~~~~~~~~~~~ -+-------------------------------+------------+--------------+---------------------------+ -| Field | Type | Units | Description | -+===============================+============+==============+===========================+ -| ``compRunningMinuteTotal`` | int | minutes | Total heat pump runtime | -+-------------------------------+------------+--------------+---------------------------+ -| ``heater1RunningMinuteTotal`` | int | minutes | Total upper heater | -| | | | runtime | -+-------------------------------+------------+--------------+---------------------------+ -| ``heater2RunningMinuteTotal`` | int | minutes | Total lower heater | -| | | | runtime | -+-------------------------------+------------+--------------+---------------------------+ ++--------------------------------+------------+--------------+---------------------------+ +| Field | Type | Units | Description | ++================================+============+==============+===========================+ +| ``comp_running_minute_total`` | int | minutes | Total heat pump runtime | ++--------------------------------+------------+--------------+---------------------------+ +| ``heater1_running_minute_total`` | int | minutes | Total upper heater | +| | | | runtime | ++--------------------------------+------------+--------------+---------------------------+ +| ``heater2_running_minute_total`` | int | minutes | Total lower heater | +| | | | runtime | ++--------------------------------+------------+--------------+---------------------------+ .. _energy-capacity-1: Energy Capacity ~~~~~~~~~~~~~~~ -============================= ==== ===== ========================= -Field Type Units Description -============================= ==== ===== ========================= -``availableEnergyCapacity`` int % Available energy (0-100%) -============================= ==== ===== ========================= +=============================== ==== ===== ========================= +Field Type Units Description +=============================== ==== ===== ========================= +``available_energy_capacity`` int % Available energy (0-100%) +=============================== ==== ===== ========================= Temperature ~~~~~~~~~~~ -============================= ===== ===== ================================= -Field Type Units Description -============================= ===== ===== ================================= -``dhwTemperature`` float °F Current water temperature -``dhwTemperatureSetting`` int °F Target temperature setting -``compTemp`` float °F Heat pump compressor temperature -``dhwTankUpperTemp`` float °F Upper tank temperature -``dhwTankLowerTemp`` float °F Lower tank temperature -``dhwHeatexOutTemp`` float °F Heat exchanger outlet temperature -============================= ===== ===== ================================= +============================== ===== ===== ================================= +Field Type Units Description +============================== ===== ===== ================================= +``dhw_temperature`` float °F Current water temperature +``dhw_temperature_setting`` int °F Target temperature setting +``comp_temp`` float °F Heat pump compressor temperature +``dhw_tank_upper_temp`` float °F Upper tank temperature +``dhw_tank_lower_temp`` float °F Lower tank temperature +``dhw_heatex_out_temp`` float °F Heat exchanger outlet temperature +============================== ===== ===== ================================= Notes ----- diff --git a/docs/guides/event_system.rst b/docs/guides/event_system.rst index 0a1a421..0977155 100644 --- a/docs/guides/event_system.rst +++ b/docs/guides/event_system.rst @@ -98,8 +98,8 @@ Event Registry -------------- The :class:`nwp500.mqtt_events.MqttClientEvents` class provides type-safe event -constants and programmatic discovery. This ensures your callbacks use valid event -names and enables IDE autocomplete: +constants and programmatic discovery, so your callbacks use valid event +names and get IDE autocomplete: .. code-block:: python diff --git a/docs/guides/home_assistant_integration.rst b/docs/guides/home_assistant_integration.rst index 4ff8f19..22e608b 100644 --- a/docs/guides/home_assistant_integration.rst +++ b/docs/guides/home_assistant_integration.rst @@ -7,9 +7,9 @@ This guide provides best practices for integrating the nwp500-python library wit Overview ======== -The nwp500-python library automatically converts device values to the user's preferred temperature unit (Celsius or Fahrenheit) based on the device's ``temperature_type`` setting. This guide shows how Home Assistant integrations should handle these dynamic units to provide a seamless user experience. +The nwp500-python library automatically converts device values to the user's preferred temperature unit (Celsius or Fahrenheit) based on the device's ``temperature_type`` setting. This guide shows how Home Assistant integrations should handle these dynamic units. -Key Concepts +Concepts ============ **Dynamic Unit Conversion** @@ -152,8 +152,7 @@ Here's a complete example showing how to implement dynamic units in a Home Assis def native_unit_of_measurement(self) -> str | None: """Return dynamic unit based on device temperature preference. - This ensures Home Assistant displays the correct unit symbol - (°C or °F) based on the device's current setting. + Reflects the device's current temperature_type setting (°C or °F). """ if not self._status: return self.entity_description.native_unit_of_measurement diff --git a/docs/guides/mqtt_diagnostics.rst b/docs/guides/mqtt_diagnostics.rst index 0c4183e..1a95cc9 100644 --- a/docs/guides/mqtt_diagnostics.rst +++ b/docs/guides/mqtt_diagnostics.rst @@ -9,7 +9,7 @@ MQTT Connection Drops Investigation & Diagnostics Guide Overview ======== -This guide provides a comprehensive toolkit for investigating and resolving AWS +This guide covers tools for investigating and resolving AWS MQTT connection drops (``AWS_ERROR_MQTT_UNEXPECTED_HANGUP``). It helps identify whether drops are caused by network/environmental issues, AWS server-side limits, or client-side configuration problems. @@ -104,7 +104,7 @@ The ``MqttDiagnosticsCollector`` class provides telemetry: metrics = diagnostics.get_metrics() diagnostics.print_summary() -Key Classes +Classes ----------- **MqttDiagnosticsCollector** @@ -912,7 +912,7 @@ Implement Home Assistant's native diagnostics protocol to expose your data: # Redact sensitive info (credentials, tokens, etc.) return async_redact_data(data, REDACT_FIELDS) -This allows users to view diagnostics directly in Home Assistant UI: +Users can view diagnostics directly in the Home Assistant UI: **Settings → System → Diagnostics** for your integration. Periodic Export Schedule diff --git a/docs/guides/time_of_use.rst b/docs/guides/time_of_use.rst index fe7fbd5..fd5ac97 100644 --- a/docs/guides/time_of_use.rst +++ b/docs/guides/time_of_use.rst @@ -14,12 +14,12 @@ Time of Use pricing enables: * **Seasonal support**: Different schedules for different months of the year * **Weekday/weekend support**: Separate schedules for weekdays and weekends -The system uses utility rate data from OpenEI to automatically configure optimal heating schedules based on your location and utility provider. +The system uses utility rate data from OpenEI to configure heating schedules based on your location and utility provider. OpenEI API Integration ---------------------- -The Navien mobile app queries the OpenEI Utility Rates API to retrieve current electricity rate information for the user's location. This allows the app to present available rate plans and configure TOU schedules automatically. +The Navien mobile app queries the OpenEI Utility Rates API to retrieve current electricity rate information for the user's location, then presents available rate plans and configures TOU schedules. API Endpoint ~~~~~~~~~~~~ @@ -120,7 +120,7 @@ The API returns a JSON response with an array of utility rate plans: ] } -Key Response Fields +Response Fields """"""""""""""""""" .. list-table:: @@ -736,7 +736,7 @@ Example 5: Apply Rate Plan from OpenEI ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use the ``OpenEIClient`` and ``convert_tou()``/``update_tou()`` methods to -browse, convert, and apply a rate plan from OpenEI — the same workflow the +browse, convert, and apply a rate plan from OpenEI. This is the same workflow the Navien mobile app uses: .. code-block:: python @@ -796,7 +796,7 @@ Navien mobile app uses: asyncio.run(apply_openei_rate_plan()) -**Key Points:** +**Notes:** * Set the ``OPENEI_API_KEY`` environment variable before running * Get a free key at https://openei.org/services/api/signup/ diff --git a/docs/guides/unit_conversion.rst b/docs/guides/unit_conversion.rst index 5de0720..245e600 100644 --- a/docs/guides/unit_conversion.rst +++ b/docs/guides/unit_conversion.rst @@ -2,7 +2,7 @@ Dynamic Unit Conversion ======================= -The nwp500-python library implements a sophisticated dynamic unit conversion system that automatically converts all temperature, flow rate, and volume measurements between metric (Celsius, LPM, Liters) and imperial (Fahrenheit, GPM, Gallons) units based on the device's configured ``temperature_type`` setting. +The library automatically converts temperature, flow rate, and volume values to the user's preferred unit system (metric or imperial) based on the device's configured ``temperature_type`` setting. Overview ======== diff --git a/docs/index.rst b/docs/index.rst index db0cc33..0d5da5d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,7 +19,7 @@ This library provides a complete Python interface to Navien NWP500 heat pump water heaters through the Navien Smart Control cloud platform. It supports both REST API and real-time MQTT communication. -**Key Features:** +**Features:** * **REST API Client** - Complete implementation of Navien Smart Control API @@ -34,53 +34,8 @@ supports both REST API and real-time MQTT communication. Quick Start =========== -Installation ------------- - -.. code-block:: bash - - pip install nwp500-python - -Basic Example -------------- - -.. code-block:: python - - import asyncio - from nwp500 import NavienAuthClient, NavienAPIClient, NavienMqttClient - - async def main(): - # Authenticate (credentials from env vars or direct) - async with NavienAuthClient( - "email@example.com", - "password" - ) as auth: - - # Get device list via REST API - api = NavienAPIClient(auth) - device = await api.get_first_device() - print(f"Device: {device.device_info.device_name}") - - # Connect to MQTT for real-time control - mqtt = NavienMqttClient(auth) - await mqtt.connect() - - # Monitor device status - def on_status(status): - print(f"Temp: {status.dhw_temperature}°F") - print(f"Power: {status.current_inst_power}W") - - await mqtt.subscribe_device_status(device, on_status) - await mqtt.control.request_device_status(device) - - # Control device - await mqtt.control.set_power(device, power_on=True) - await mqtt.control.set_dhw_temperature(device, 120.0) - - await asyncio.sleep(30) - await mqtt.disconnect() - - asyncio.run(main()) +Install with ``pip install nwp500-python``, then see the :doc:`quickstart` guide +to connect and control your device in minutes. Documentation Index =================== @@ -119,15 +74,15 @@ Documentation Index :maxdepth: 1 :caption: User Guides - guides/unit_conversion guides/authentication - guides/home_assistant_integration - guides/scheduling - guides/energy_monitoring - guides/time_of_use guides/event_system guides/command_queue guides/auto_recovery + guides/scheduling + guides/energy_monitoring + guides/time_of_use + guides/unit_conversion + guides/home_assistant_integration guides/mqtt_diagnostics guides/advanced_features_explained diff --git a/docs/protocol/data_conversions.rst b/docs/protocol/data_conversions.rst index baf0017..f53053d 100644 --- a/docs/protocol/data_conversions.rst +++ b/docs/protocol/data_conversions.rst @@ -1,7 +1,7 @@ Data Conversions and Units Reference ==================================== -This document provides comprehensive details on all data conversions applied to device status messages, field units, and the meaning of various data structures. +This document covers all data conversions applied to device status messages, field units, and the meaning of various data structures. .. warning:: This document describes the underlying protocol details. Most users should use the @@ -41,7 +41,7 @@ The device uses several encoding schemes to minimize transmission overhead: - Applied to differential temperature settings (heat pump and element hysteresis) - Formula: ``displayed_value_celsius = raw_value / 10.0``, ``displayed_value_fahrenheit = (raw_value / 10.0) * 9/5`` (NO +32 offset) - Purpose: Represents temperature DIFFERENCES/DELTAS, not absolute temperatures - - Key difference from absolute temperature conversion: No +32 offset applied when converting to Fahrenheit + - Unlike absolute temperature conversion, no +32 offset is applied when converting to Fahrenheit - Example: Raw 5 → 0.5°C delta → 0.9°F delta (NOT 32.9°F) - Used for: Heat pump on/off differential, heating element on/off differential @@ -653,7 +653,7 @@ The ``temp_formula_type`` field indicates which temperature conversion formula t **Type 1: STANDARD** (most devices) - Standard rounding: ``round(fahrenheit)`` -Both formulas convert from half-degrees Celsius to Fahrenheit based on the raw encoded temperature value. This ensures temperature display matches the device's built-in LCD. +Both formulas convert from half-degrees Celsius to Fahrenheit based on the raw encoded temperature value, matching the device's built-in LCD display. See Also -------- diff --git a/docs/protocol/device_features.rst b/docs/protocol/device_features.rst index 842cde4..fc04155 100644 --- a/docs/protocol/device_features.rst +++ b/docs/protocol/device_features.rst @@ -17,7 +17,7 @@ This document lists the fields found in the ``feature`` object (also known as This is the standard Navien protocol pattern for boolean-like values, not traditional 0/1 booleans. The Python library automatically converts these to Python ``bool`` (True/False). -The DeviceFeature data contains comprehensive device capabilities, configuration, and firmware information received via MQTT when calling ``request_device_info()``. This data is much more detailed than the basic device information available through the REST API and corresponds to the actual device specifications and capabilities as documented in the official Navien NWP500 Installation and User manuals. +The DeviceFeature data contains device capabilities, configuration, and firmware information received via MQTT when calling ``request_device_info()``. This data is much more detailed than the basic device information available through the REST API and corresponds to the actual device specifications and capabilities as documented in the official Navien NWP500 Installation and User manuals. .. list-table:: :header-rows: 1 @@ -278,7 +278,7 @@ The device feature data corresponds to these official NWP500 specifications: Firmware Version Interpretation ------------------------------- -The device returns three separate firmware components for comprehensive system identification: +The device returns three separate firmware components for full system identification: **Main Controller (``controllerSwVersion``, ``controllerSwCode``)** * Manages heat pump compressor, heating elements, temperature sensors diff --git a/docs/protocol/device_status.rst b/docs/protocol/device_status.rst index 0941823..2b9789f 100644 --- a/docs/protocol/device_status.rst +++ b/docs/protocol/device_status.rst @@ -572,7 +572,7 @@ Field Definitions * Meaning: "This is what I'm doing right now" * **Note**: This field shows ``STANDBY`` (0) both when device is powered off AND when it's on but not heating. Check ``dhwOperationSetting`` to determine if device is actually powered off (value 6). -Key Relationship +Relationship ^^^^^^^^^^^^^^^^ The relationship between these fields can be summarized as: diff --git a/docs/protocol/error_codes.rst b/docs/protocol/error_codes.rst index c5ed665..45fbf43 100644 --- a/docs/protocol/error_codes.rst +++ b/docs/protocol/error_codes.rst @@ -1,7 +1,7 @@ Error Codes =========== -This document provides a comprehensive reference for NWP500 heat pump water heater error codes. +This document lists error codes for the NWP500 heat pump water heater. .. warning:: This document describes the underlying protocol details. Most users should use the diff --git a/docs/protocol/quick_reference.rst b/docs/protocol/quick_reference.rst index cca69f8..8d68d04 100644 --- a/docs/protocol/quick_reference.rst +++ b/docs/protocol/quick_reference.rst @@ -43,7 +43,7 @@ This likely stems from legacy firmware design where: When parsed via ``DeviceStatus``, this becomes ``status.power == True``. -Key Enum Values +Enum Values --------------- CurrentOperationMode diff --git a/docs/python_api/cli.rst b/docs/python_api/cli.rst index 4f3719a..9d3e853 100644 --- a/docs/python_api/cli.rst +++ b/docs/python_api/cli.rst @@ -124,7 +124,7 @@ power consumption, tank charge percentage, and component states. info ^^^^ -Show comprehensive device information (firmware, model, capabilities, serial). +Show full device information (firmware, model, capabilities, serial). .. code-block:: bash @@ -158,7 +158,7 @@ Show basic device information from REST API (DeviceInfo model). **Output:** Basic device information from REST API. -**Note:** Use ``info`` command for MQTT-based comprehensive information, or +**Note:** Use ``info`` for MQTT-based full device information, or ``device-info`` for REST API-based basic information. serial diff --git a/docs/python_api/device_control.rst b/docs/python_api/device_control.rst index fb864ae..3721536 100644 --- a/docs/python_api/device_control.rst +++ b/docs/python_api/device_control.rst @@ -1044,7 +1044,7 @@ Best Practices logger.warning(f"Feature not supported: {e.feature}") # Fallback to alternative command -4. **Use try/except for robust error handling:** +4. **Use try/except for error handling:** .. code-block:: python diff --git a/docs/python_api/exceptions.rst b/docs/python_api/exceptions.rst index 6086a2e..725815d 100644 --- a/docs/python_api/exceptions.rst +++ b/docs/python_api/exceptions.rst @@ -4,7 +4,7 @@ Exceptions **New in v5.0:** Complete exception architecture with enterprise-grade error handling. -The nwp500 library provides a comprehensive exception hierarchy for robust error handling. +The nwp500 library provides a structured exception hierarchy for error handling. All custom exceptions inherit from a base class and provide structured error information. Exception Hierarchy diff --git a/docs/python_api/models.rst b/docs/python_api/models.rst index cb57adb..8697d84 100644 --- a/docs/python_api/models.rst +++ b/docs/python_api/models.rst @@ -185,7 +185,7 @@ Complete real-time device status with 100+ fields. .. py:class:: DeviceStatus - **Key Temperature Fields:** + **Temperature Fields:** * ``dhw_temperature`` (float) - Current water temperature (°F or °C) * ``dhw_temperature_setting`` (float) - Target temperature setting @@ -199,7 +199,7 @@ Complete real-time device status with 100+ fields. .. note:: Temperature values from the device are automatically converted from their raw (scaled Celsius) representation to Fahrenheit or Celsius based on the device's settings. The library handles these conversions transparently. - **Key Power/Energy Fields:** + **Power/Energy Fields:** * ``current_inst_power`` (float) - Current power consumption (Watts) * ``total_energy_capacity`` (float) - Total energy capacity (%)