nwp500-python 7.4.10__tar.gz → 8.0.0__tar.gz

{nwp500_python-7.4.10 → nwp500_python-8.0.0}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.13'
+          python-version: '3.14'
       
       - name: Install tox
         run: |
@@ -37,7 +37,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.13'
+          python-version: '3.14'
       
       - name: Install ruff
         run: |
@@ -52,7 +52,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.13', '3.14']
+        python-version: ['3.14']
     
     steps:
       - uses: actions/checkout@v4
@@ -87,7 +87,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.13'
+          python-version: '3.14'
       
       - name: Install build dependencies
         run: |

{nwp500_python-7.4.10 → nwp500_python-8.0.0}/.github/workflows/release.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.13'
+          python-version: '3.14'
       
       - name: Install dependencies
         run: |
@@ -53,7 +53,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.14'
       
       - name: Install build dependencies
         run: |
@@ -80,7 +80,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.14'
       
       - name: Extract changelog for this version
         id: changelog

{nwp500_python-7.4.10 → nwp500_python-8.0.0}/.readthedocs.yml

@@ -19,7 +19,7 @@ formats:
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.13"
+    python: "3.14"
 
 python:
   install:

{nwp500_python-7.4.10 → nwp500_python-8.0.0}/CHANGELOG.rst

@@ -2,6 +2,140 @@
 Changelog
 =========
 
+Unreleased (8.x)
+================
+
+Bug Fixes
+---------
+- **Fix MQTT reconnection after unexpected AWS hangup**: The
+  ``on_connection_resumed`` callback was missing the ``connection`` parameter
+  required by the AWS IoT SDK callback signature. The SDK calls
+  ``on_connection_resumed(connection, return_code, session_present, **kwargs)``,
+  but the handler only accepted ``(return_code, session_present)``. The
+  mismatched signature caused the callback to fail silently (exception swallowed
+  by the AWS CRT C layer), so ``self._connected`` was never restored to ``True``
+  after an ``AWS_ERROR_MQTT_UNEXPECTED_HANGUP``. As a result, the
+  ``connection_resumed`` event was never emitted, the reconnection loop ran
+  indefinitely, and device sensors became permanently unavailable until a manual
+  restart. (`#85 <https://github.com/eman/nwp500-python/issues/85>`_)
+
+Features
+--------
+- **Multi-device support enhancements**: Improved support for accounts with multiple
+  Navilink devices by injecting device identity into models and events.
+
+  - Added ``mac_address`` field to ``DeviceStatus`` and ``DeviceFeature`` models.
+  - Added ``device_mac`` attribute to all device-specific MQTT events (temperature
+    changes, mode changes, power updates, errors, etc.).
+  - Updated ``DeviceStateTracker`` and ``MqttSubscriptionManager`` to propagate
+    device identity correctly.
+
+**BREAKING CHANGES**: ``.on()`` event handler callbacks now receive a single typed
+event dataclass instead of positional arguments. ``MqttDeviceController`` is no longer
+accessible as ``.control`` on ``NavienMqttClient``; all control methods are now
+available directly on the client.
+
+Breaking Changes
+----------------
+- **Typed event payloads**: All ``.on()`` event handler callbacks now receive a single
+  typed event dataclass instance. The dataclasses are exported from
+  ``nwp500.mqtt_events``.
+
+  .. code-block:: python
+
+     # OLD (removed)
+     mqtt.on("temperature_changed", lambda old, new: print(old, new))
+     mqtt.on("connection_resumed", lambda rc, sp: print(rc, sp))
+
+     # NEW
+     mqtt.on("temperature_changed", lambda e: print(e.old_temperature, e.new_temperature))
+     mqtt.on("connection_resumed", lambda e: print(e.return_code, e.session_present))
+
+- **``MqttDeviceController`` no longer public**: ``NavienMqttClient`` no longer exposes
+  a ``.control`` attribute. All control methods are now available directly on the
+  client.
+
+  .. code-block:: python
+
+     # OLD (removed)
+     await mqtt.control.set_temperature(device, 50)
+
+     # NEW
+     await mqtt.set_temperature(device, 50)
+
+Migration Guide (from 7.x.x)
+----------------------------
+The following steps are recommended for a smooth migration, particularly for complex
+integrations like Home Assistant:
+
+1.  **Update Event Listeners**: Locate all ``mqtt.on()`` or ``mqtt.once()`` calls.
+    Update the callback signatures to accept a single argument (the event object) and
+    update the body to access fields via the object (e.g., ``event.new_temperature``
+    instead of ``new_val``).
+2.  **Refactor Control Calls**: Remove ``.control`` from all device command invocations.
+    Instead of ``await mqtt.control.set_power(...)``, use ``await mqtt.set_power(...)``.
+3.  **Handle Unit Conversions**: If your integration previously performed its own
+    conversions or relied on the library's eager conversion, note that
+    ``DeviceStatus`` fields like ``dhw_temperature`` are now properties. They return
+    values based on the global unit system context (``us_customary`` by default).
+
+    *   **Home Assistant Tip**: To ensure your state tracking is immune to unit system
+        toggles within the library, use the new ``*_raw`` fields (e.g.,
+        ``status.dhw_temperature_raw``) for comparison logic, and use the properties
+        only for display or when a converted value is explicitly needed.
+4.  **Remove ``from_dict()`` Calls**: The ``from_dict()`` method has been removed
+    from all models. Use ``model_validate()`` instead.
+
+    *   **Note**: ``AuthenticationResponse.model_validate()`` now automatically handles
+        the ``"data": { ... }`` wrapper found in raw API responses.
+5.  **Subpackage Imports**: While top-level imports from ``nwp500.models`` are
+    preserved, if you were importing from the internal ``nwp500.models`` module file
+    directly, you must update your imports to point to the new structured files
+    (e.g., ``nwp500.models.status``).
+
+Added
+-----
+- **New control methods**: Nine previously unimplemented ``CommandCode`` values now have
+  full implementations: ``check_firmware``, ``commit_firmware``, ``reconnect_wifi``,
+  ``reset_wifi``, ``set_freeze_protection_temperature``, ``run_smart_diagnostic``,
+  ``enable_intelligent_reservation``, ``disable_intelligent_reservation``, and
+  ``set_water_program_reservation``.
+- **Typed subscription methods**: ``subscribe_reservation``,
+  ``subscribe_weekly_reservation``, and ``subscribe_recirculation`` return typed
+  responses directly without requiring raw MQTT event handlers.
+- **New protocol models**: ``WeeklyReservationSchedule``, ``WeeklyReservationEntry``,
+  ``RecirculationSchedule``, ``RecirculationScheduleEntry``, and ``OtaCommitPayload``.
+- **``DeviceStateTracker``**: State change detection extracted into a dedicated class
+  in ``nwp500.mqtt.state_tracker`` with per-device tracking keyed by MAC address.
+- **``MQTT_PROTOCOL_VERSION`` constant**: Protocol version is now a named constant in
+  ``nwp500.config`` rather than a hardcoded integer in the command payload builder.
+- **``response_ack_topic()``**: New method on ``MqttTopicBuilder`` for control command
+  acknowledgement topics.
+
+Changed
+-------
+- **Unit conversion redesign**: Temperature, flow rate, and volume fields in
+  ``DeviceStatus`` and ``DeviceFeature`` now store raw device values as ``*_raw: int``
+  fields and expose converted values via lazy computed properties. Conversion happens at
+  access time rather than during Pydantic deserialization, preserving the original
+  device value in all cases.
+- **Models split into subpackage**: ``nwp500.models`` is now a package
+  (``nwp500/models/``) with modules for status, schedule, TOU, and MQTT models. Public
+  imports from ``nwp500.models`` are unchanged.
+- **Topic building centralised**: All MQTT topic construction now goes through
+  ``MqttTopicBuilder``. Hardcoded topic strings removed from ``control.py``,
+  ``reservations.py``, and ``cli/handlers.py``.
+- **``set_vacation_days`` delegates to ``set_dhw_mode``**: The method now calls
+  ``set_dhw_mode(device, DhwOperationSetting.VACATION, vacation_days=days)`` directly.
+- **Per-device state tracking**: ``_previous_status`` changed from a single
+  ``DeviceStatus | None`` to a ``dict[str, DeviceStatus]`` keyed by MAC address,
+  preventing spurious state-change events when multiple devices are connected.
+- **Unit system stored as instance variable**: ``NavienAPIClient``,
+  ``NavienMqttClient``, and ``NavienAuthClient`` no longer call ``set_unit_system()``
+  as a constructor side-effect.
+- **``NavienBaseModel`` consolidated**: Duplicate definitions in ``auth.py`` and
+  ``models.py`` merged into a single definition in ``nwp500._base``.
+
 Version 7.4.10 (2026-04-13)
 ===========================
 
@@ -205,7 +339,7 @@ Breaking Changes
   .. code-block:: python
 
      # OLD (hardcoded 95-150°F)
-     await mqtt.control.set_dhw_temperature(device, temperature_f=140.0)
+     await mqtt.set_dhw_temperature(device, temperature_f=140.0)
      entry = build_reservation_entry(
          enabled=True,
          days=["Monday"],
@@ -217,7 +351,7 @@ Breaking Changes
 
      # NEW (device-provided limits, unit-aware)
      # Temperature value automatically uses user's preferred unit
-     await mqtt.control.set_dhw_temperature(device, 140.0)
+     await mqtt.set_dhw_temperature(device, 140.0)
      
      # Device features provide min/max in user's preferred unit
      features = await device_info_cache.get(device.device_info.mac_address)

{nwp500_python-7.4.10 → nwp500_python-8.0.0}/CONTRIBUTING.rst

@@ -135,7 +135,7 @@ Follow a clear exception hierarchy with consistent naming:
   .. code-block:: python
 
       try:
-          await mqtt_client.control.set_temperature(device, 150)
+          await mqtt_client.set_temperature(device, 150)
       except MqttNotConnectedError:
           # Handle specific case: not connected
           print("Connect to device first")

nwp500_python-8.0.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.4
+Name: nwp500-python
+Version: 8.0.0
+Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
+Home-page: https://github.com/eman/nwp500-python
+Author: Emmanuel Levijarvi
+Author-email: emansl@gmail.com
+License: MIT
+Project-URL: Documentation, https://nwp500-python.readthedocs.io/en/latest/
+Project-URL: Source, https://github.com/eman/nwp500-python
+Project-URL: Tracker, https://github.com/eman/nwp500-python/issues
+Platform: any
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.14
+Description-Content-Type: text/x-rst; charset=UTF-8
+License-File: LICENSE.txt
+Requires-Dist: aiohttp>=3.13.5
+Requires-Dist: awsiotsdk>=1.29.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: cli
+Requires-Dist: click>=8.3.0; extra == "cli"
+Requires-Dist: rich>=14.3.0; extra == "cli"
+Provides-Extra: testing
+Requires-Dist: setuptools; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: pytest-asyncio; extra == "testing"
+Requires-Dist: hypothesis; extra == "testing"
+Provides-Extra: dev
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: pyright>=1.1.0; extra == "dev"
+Requires-Dist: setuptools; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: hypothesis; extra == "dev"
+Dynamic: license-file
+
+=============
+nwp500-python
+=============
+
+|PyPI-v| |Python-versions| |CI-status| |Docs-status| |Code-style| |License|
+
+Python library for Navien NWP500 Heat Pump Water Heater
+========================================================
+
+A complete Python library for monitoring and controlling the Navien NWP500 Heat Pump Water Heater through the Navilink cloud service.
+
+* **Documentation:** https://nwp500-python.readthedocs.io/
+* **Source:** https://github.com/eman/nwp500-python
+
+Features
+========
+* **Complete Interface:** Full support for both REST API and real-time MQTT (AWS IoT).
+* **Monitoring:** Real-time tracking of temperature, power usage, tank charge, and component status.
+* **Control:** Remote control of target temperatures, operation modes, and vacation settings.
+* **Advanced Features:** Native support for reservations, time-of-use (TOU) optimization, and anti-legionella cycles.
+* **Type-Safe:** Built with Pydantic for robust data validation and unit handling.
+* **Async/Await:** Modern asyncio-based implementation for high-performance integration.
+
+Getting Started
+===============
+
+.. code-block:: bash
+
+    pip install nwp500-python
+
+Quick Example
+-------------
+
+.. code-block:: python
+
+    from nwp500 import NavienAuthClient, NavienAPIClient
+
+    async with NavienAuthClient("email@example.com", "password") as auth:
+        api = NavienAPIClient(auth)
+        devices = await api.list_devices()
+        
+        if devices:
+            device = devices[0]
+            print(f"Temperature: {device.status.dhw_temperature}°F")
+            await api.set_device_temperature(device, 130)
+
+Documentation
+=============
+
+The documentation follows the `Diátaxis <https://diataxis.fr/>`_ framework:
+
+* `Tutorials <https://nwp500-python.readthedocs.io/en/latest/tutorials/getting-started.html>`_: Start here if you're new to the library.
+* `How-to Guides <https://nwp500-python.readthedocs.io/en/latest/how-to/index.html>`_: Practical step-by-step recipes for specific tasks.
+* `Reference <https://nwp500-python.readthedocs.io/en/latest/reference/index.html>`_: Technical descriptions of the API, models, and protocol.
+* `Explanation <https://nwp500-python.readthedocs.io/en/latest/explanation/index.html>`_: Understanding-oriented deep dives into the library's design and advanced features.
+
+Contributing
+============
+
+We welcome contributions! Please see our `Contributing Guide <https://nwp500-python.readthedocs.io/en/latest/project/contributing.html>`_ for more details.
+
+License
+=======
+
+This project is licensed under the MIT License. See the `LICENSE.txt <https://github.com/eman/nwp500-python/blob/main/LICENSE.txt>`_ file for details.
+
+.. |PyPI-v| image:: https://img.shields.io/pypi/v/nwp500-python.svg
+   :target: https://pypi.org/project/nwp500-python/
+.. |Python-versions| image:: https://img.shields.io/pypi/pyversions/nwp500-python.svg
+   :target: https://pypi.org/project/nwp500-python/
+.. |CI-status| image:: https://github.com/eman/nwp500-python/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/eman/nwp500-python/actions/workflows/ci.yml
+.. |Docs-status| image:: https://readthedocs.org/projects/nwp500-python/badge/?version=latest
+   :target: https://nwp500-python.readthedocs.io/en/latest/?badge=latest
+.. |Code-style| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+   :target: https://github.com/astral-sh/ruff
+.. |License| image:: https://img.shields.io/pypi/l/nwp500-python.svg
+   :target: https://opensource.org/licenses/MIT

nwp500_python-8.0.0/README.rst

@@ -0,0 +1,78 @@
+=============
+nwp500-python
+=============
+
+|PyPI-v| |Python-versions| |CI-status| |Docs-status| |Code-style| |License|
+
+Python library for Navien NWP500 Heat Pump Water Heater
+========================================================
+
+A complete Python library for monitoring and controlling the Navien NWP500 Heat Pump Water Heater through the Navilink cloud service.
+
+* **Documentation:** https://nwp500-python.readthedocs.io/
+* **Source:** https://github.com/eman/nwp500-python
+
+Features
+========
+* **Complete Interface:** Full support for both REST API and real-time MQTT (AWS IoT).
+* **Monitoring:** Real-time tracking of temperature, power usage, tank charge, and component status.
+* **Control:** Remote control of target temperatures, operation modes, and vacation settings.
+* **Advanced Features:** Native support for reservations, time-of-use (TOU) optimization, and anti-legionella cycles.
+* **Type-Safe:** Built with Pydantic for robust data validation and unit handling.
+* **Async/Await:** Modern asyncio-based implementation for high-performance integration.
+
+Getting Started
+===============
+
+.. code-block:: bash
+
+    pip install nwp500-python
+
+Quick Example
+-------------
+
+.. code-block:: python
+
+    from nwp500 import NavienAuthClient, NavienAPIClient
+
+    async with NavienAuthClient("email@example.com", "password") as auth:
+        api = NavienAPIClient(auth)
+        devices = await api.list_devices()
+        
+        if devices:
+            device = devices[0]
+            print(f"Temperature: {device.status.dhw_temperature}°F")
+            await api.set_device_temperature(device, 130)
+
+Documentation
+=============
+
+The documentation follows the `Diátaxis <https://diataxis.fr/>`_ framework:
+
+* `Tutorials <https://nwp500-python.readthedocs.io/en/latest/tutorials/getting-started.html>`_: Start here if you're new to the library.
+* `How-to Guides <https://nwp500-python.readthedocs.io/en/latest/how-to/index.html>`_: Practical step-by-step recipes for specific tasks.
+* `Reference <https://nwp500-python.readthedocs.io/en/latest/reference/index.html>`_: Technical descriptions of the API, models, and protocol.
+* `Explanation <https://nwp500-python.readthedocs.io/en/latest/explanation/index.html>`_: Understanding-oriented deep dives into the library's design and advanced features.
+
+Contributing
+============
+
+We welcome contributions! Please see our `Contributing Guide <https://nwp500-python.readthedocs.io/en/latest/project/contributing.html>`_ for more details.
+
+License
+=======
+
+This project is licensed under the MIT License. See the `LICENSE.txt <https://github.com/eman/nwp500-python/blob/main/LICENSE.txt>`_ file for details.
+
+.. |PyPI-v| image:: https://img.shields.io/pypi/v/nwp500-python.svg
+   :target: https://pypi.org/project/nwp500-python/
+.. |Python-versions| image:: https://img.shields.io/pypi/pyversions/nwp500-python.svg
+   :target: https://pypi.org/project/nwp500-python/
+.. |CI-status| image:: https://github.com/eman/nwp500-python/actions/workflows/ci.yml/badge.svg
+   :target: https://github.com/eman/nwp500-python/actions/workflows/ci.yml
+.. |Docs-status| image:: https://readthedocs.org/projects/nwp500-python/badge/?version=latest
+   :target: https://nwp500-python.readthedocs.io/en/latest/?badge=latest
+.. |Code-style| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+   :target: https://github.com/astral-sh/ruff
+.. |License| image:: https://img.shields.io/pypi/l/nwp500-python.svg
+   :target: https://opensource.org/licenses/MIT

{nwp500_python-7.4.10 → nwp500_python-8.0.0}/docs/conf.py

@@ -33,7 +33,7 @@ try:  # for Sphinx >= 1.7
 except ImportError:
     from sphinx import apidoc
 
-output_dir = os.path.join(__location__, "api")
+output_dir = os.path.join(__location__, "reference", "api")
 module_dir = os.path.join(__location__, "../src/nwp500")
 try:
     shutil.rmtree(output_dir)

nwp500_python-7.4.10/docs/guides/advanced_features_explained.rst → nwp500_python-8.0.0/docs/explanation/advanced-features.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
 ------------------------
@@ -109,7 +109,7 @@ The ``outsideTemperature`` field is transmitted in the device status update. Pyt
 .. code-block:: python
 
     # From device status updates
-    status = await mqtt_client.control.request_device_status()
+    status = await mqtt_client.request_device_status()
     
     # Access ambient temperature data
     outdoor_temp = status.outside_temperature  # Raw integer value
@@ -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
 ------------------------
 
@@ -389,7 +383,7 @@ Monitoring Stratification from Python
     async def monitor_stratification(mqtt_client: NavienMQTTClient, device_id: str):
         """Monitor tank stratification quality"""
         
-        status = await mqtt_client.control.request_device_status(device_id)
+        status = await mqtt_client.request_device_status(device_id)
         
         upper_temp = status.tank_upper_temperature  # float in °F
         lower_temp = status.tank_lower_temperature  # float in °F
@@ -470,7 +464,7 @@ The NWP500 uses **half-degrees Celsius** encoding for temperature fields.
 
 **Related Documentation**:
 
-See :doc:`../protocol/data_conversions` for complete field conversion reference and formula applications.
+See :doc:`../reference/protocol/data_conversions` for complete field conversion reference and formula applications.
 
 Summary and Recommendations
 ============================
@@ -497,7 +491,7 @@ Summary and Recommendations
 See Also
 --------
 
-* :doc:`../protocol/data_conversions` - Temperature field conversions (HalfCelsiusToF, DeciCelsiusToF)
-* :doc:`../protocol/device_status` - Complete device status field reference
-* :doc:`scheduling` - Scheduling and automation guide
-* :doc:`../python_api/models` - DeviceStatus model field definitions
+* :doc:`../reference/protocol/data_conversions` - Temperature field conversions (HalfCelsiusToF, DeciCelsiusToF)
+* :doc:`../reference/protocol/device_status` - Complete device status field reference
+* :doc:`../how-to/schedule-operation` - Scheduling and automation guide
+* :doc:`../reference/python_api/models` - DeviceStatus model field definitions

nwp500_python-8.0.0/docs/explanation/architecture.rst

@@ -0,0 +1,81 @@
+============
+Architecture
+============
+
+This document explains the high-level architecture of the ``nwp500-python`` library and how it interacts with the Navien Smart Control cloud platform.
+
+System Overview
+===============
+
+The library acts as a bridge between your Python application and the Navien NWP500 Heat Pump Water Heater. Communication happens through two primary channels:
+
+1. **REST API**: Used for authentication, account management, and listing devices.
+2. **MQTT (AWS IoT)**: Used for real-time monitoring and control of the device.
+
+Component Diagram
+=================
+
+.. code-block:: text
+
+    +-------------------+       +------------------------+
+    |                   |       |                        |
+    |  Your Application |       |  Navien Smart Control  |
+    |                   |       |         (Cloud)        |
+    +---------+---------+       +-----------+------------+
+              |                             |
+              |       +-------------+       |
+              +------>| Auth Client |<------+ (Sign-in/Tokens)
+              |       +-------------+       |
+              |                             |
+              |       +-------------+       |
+              +------>| API Client  |<------+ (REST API)
+              |       +-------------+       |
+              |                             |
+              |       +-------------+       |
+              +------>| MQTT Client |<------+ (AWS IoT Core)
+                      +-------------+
+
+Core Components
+===============
+
+Authentication Client
+---------------------
+
+The ``NavienAuthClient`` is responsible for managing credentials and tokens. It performs the initial sign-in to obtain:
+* A JWT access token for REST API requests.
+* AWS IoT credentials (identity ID, session token, etc.) for MQTT connection.
+
+REST API Client
+---------------
+
+The ``NavienAPIClient`` provides methods for "heavy" or infrequent operations, such as:
+* Retrieving the list of devices.
+* Getting detailed device information.
+* Accessing historical energy data.
+
+MQTT Client
+-----------
+
+The ``NavienMqttClient`` is the heart of real-time interaction. It maintains a persistent connection to AWS IoT Core and handles:
+* Subscribing to device status updates.
+* Publishing control commands (e.g., setting temperature).
+* Parsing incoming hex-encoded payloads into structured data models.
+
+Data Models
+===========
+
+The library uses **Pydantic** for all data models. This ensures:
+* **Type Safety**: All fields have explicit types.
+* **Validation**: Incoming data is validated against expected formats.
+* **Unit Handling**: Temperatures and other units are automatically converted to appropriate scales (e.g., Fahrenheit).
+
+Event System
+============
+
+The library implements an asynchronous event system. You can subscribe to various events (e.g., status updates, connection changes) and provide callback functions that will be executed when those events occur.
+
+See Also
+========
+
+* :doc:`advanced-features` - Deep dive into TOU, reservations, and more.
+* :doc:`../reference/protocol/mqtt_protocol` - Low-level details of the MQTT messaging.

nwp500_python-8.0.0/docs/explanation/index.rst

@@ -0,0 +1,11 @@
+===========
+Explanation
+===========
+
+Understanding-oriented deep dives into the library's design and advanced features.
+
+.. toctree::
+   :maxdepth: 1
+
+   advanced-features
+   architecture

nwp500_python-7.4.10/docs/guides/auto_recovery.rst → nwp500_python-8.0.0/docs/how-to/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.