Merge pull request #81 from eman/docs-update

documentation updates

Author: eman

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 <https://nwp500-python.readthedocs.io/>`_ for all available fields.
 
 Documentation
 =============
 
 Full docs: https://nwp500-python.readthedocs.io/
 
+Home Assistant Integration
+==========================
+
+Use this library with Home Assistant: `ha_nwp500 <https://github.com/eman/ha_nwp500>`_
+
 Data Models
 ===========
 

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
 -------------------------

docs/guides/advanced_features_explained.rst

@@ -1,24 +1,24 @@
-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
 ==========================
 
 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
 ------------------------
 

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.

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
 =========