nwp500-python 6.1.1__tar.gz → 7.0.1__tar.gz

{nwp500_python-6.1.1 → nwp500_python-7.0.1}/.github/workflows/ci.yml

@@ -33,7 +33,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.13', '3.14']
     
     steps:
       - uses: actions/checkout@v4

{nwp500_python-6.1.1 → nwp500_python-7.0.1}/.github/workflows/release.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.10'
+          python-version: '3.13'
       
       - name: Install dependencies
         run: |

{nwp500_python-6.1.1 → nwp500_python-7.0.1}/CHANGELOG.rst

@@ -2,6 +2,123 @@
 Changelog
 =========
 
+Version 7.0.1 (2025-12-18)
+==========================
+
+Fixed
+-----
+- Minor bug fixes and improvements
+
+Version 7.0.0 (2025-12-17)
+==========================
+
+**BREAKING CHANGES**: 
+- Minimum Python version raised to 3.13
+- Enumerations refactored for type safety and consistency
+
+Removed
+-------
+- **Python 3.9-3.12 Support**: Minimum Python version is now 3.13
+  
+  Home Assistant has deprecated Python 3.12 support, making Python 3.13 the de facto minimum for this ecosystem.
+  
+  Python 3.13 features and improvements:
+  
+  - **Experimental free-threaded mode** (PEP 703): Optional GIL removal for true parallelism
+  - **JIT compiler** (PEP 744): Just-in-time compilation for performance improvements
+  - **Better error messages**: Enhanced suggestions for NameError, AttributeError, and import errors
+  - **Type system enhancements**: TypeVars with defaults (PEP 696), @deprecated decorator (PEP 702), ReadOnly TypedDict (PEP 705)
+  - **Performance**: ~5-10% faster overall, optimized dictionary/set operations, better function calls
+  - PEP 695: New type parameter syntax for generics
+  - PEP 701: f-string improvements
+  - Built-in ``datetime.UTC`` constant
+  
+  If you need Python 3.12 support, use version 6.1.x of this library.
+
+- **CommandCode moved**: Import from ``nwp500.enums`` instead of ``nwp500.constants``
+  
+  .. code-block:: python
+  
+     # OLD (removed)
+     from nwp500.constants import CommandCode
+     
+     # NEW
+     from nwp500.enums import CommandCode
+     # OR
+     from nwp500 import CommandCode  # Still works
+
+Added
+-----
+
+- **Python 3.12+ Optimizations**: Leverage latest Python features
+  
+  - PEP 695: New type parameter syntax (``def func[T](...)`` instead of ``TypeVar``)
+  - Use ``datetime.UTC`` constant instead of ``datetime.timezone.utc``
+  - Native union syntax (``X | Y`` instead of ``Union[X, Y]``)
+  - Cleaner generic type annotations throughout codebase
+
+- **Enumerations Module (``src/nwp500/enums.py``)**: Comprehensive type-safe enums for device control and status
+  
+  - Status value enums: ``OnOffFlag``, ``Operation``, ``DhwOperationSetting``, ``CurrentOperationMode``, ``HeatSource``, ``DREvent``, ``WaterLevel``, ``FilterChange``, ``RecirculationMode``
+  - Time of Use enums: ``TouWeekType``, ``TouRateType``
+  - Device capability enums: ``CapabilityFlag``, ``TemperatureType``, ``DeviceType``
+  - Device control command enum: ``CommandCode`` (all MQTT command codes)
+  - Error code enum: ``ErrorCode`` with complete error code mappings
+  - Human-readable text mappings for all enums (e.g., ``DHW_OPERATION_SETTING_TEXT``, ``ERROR_CODE_TEXT``)
+  - Exported from main package: ``from nwp500 import OnOffFlag, ErrorCode, CommandCode``
+  - Comprehensive documentation in ``docs/enumerations.rst``
+  - Example usage in ``examples/error_code_demo.py``
+
+Changed
+-------
+
+- **Command Code Constants**: Migrated from ``constants.py`` to ``CommandCode`` enum in ``enums.py``
+  
+  - ``ANTI_LEGIONELLA_ENABLE`` → ``CommandCode.ANTI_LEGIONELLA_ON``
+  - ``ANTI_LEGIONELLA_DISABLE`` → ``CommandCode.ANTI_LEGIONELLA_OFF``
+  - ``TOU_ENABLE`` → ``CommandCode.TOU_ON``
+  - ``TOU_DISABLE`` → ``CommandCode.TOU_OFF``
+  - ``TOU_SETTINGS`` → ``CommandCode.TOU_RESERVATION``
+  - All command constants now use consistent naming in ``CommandCode`` enum
+
+- **Model Enumerations**: Updated type annotations for clarity and type safety
+  
+  - ``TemperatureUnit`` → ``TemperatureType`` (matches device protocol field names)
+  - All capability flags (e.g., ``power_use``, ``dhw_use``) now use ``CapabilityFlag`` type
+  - ``MqttRequest.device_type`` now accepts ``Union[DeviceType, int]`` for flexibility
+
+- **Model Serialization**: Enums automatically serialize to human-readable names
+  
+  - `model_dump()` converts enums to names (e.g., `DhwOperationSetting.HEAT_PUMP` → `"HEAT_PUMP"`)
+  - CLI and other consumers benefit from automatic enum name serialization
+  - Text mappings available for custom formatting (e.g., `DHW_OPERATION_TEXT[enum]` → "Heat Pump Only")
+
+- **Documentation**: Comprehensive updates across protocol and API documentation
+  
+  - ``docs/guides/time_of_use.rst``: Clarified TOU override status behavior (1=OFF/override active, 2=ON/normal operation)
+  - ``docs/protocol/data_conversions.rst``: Updated TOU field descriptions with correct enum values
+  - ``docs/protocol/device_features.rst``: Added capability flag pattern explanation (2=supported, 1=not supported)
+  - ``docs/protocol/mqtt_protocol.rst``: Updated command code references to use new enum names
+  - ``docs/python_api/models.rst``: Updated model field type annotations
+
+- **Examples**: Updated to use new enums for type-safe device control
+  
+  - ``examples/anti_legionella_example.py``: Uses ``CommandCode`` enum
+  - ``examples/device_feature_callback.py``: Uses capability enums
+  - ``examples/event_emitter_demo.py``: Uses status enums
+  - ``examples/mqtt_diagnostics_example.py``: Uses command enums
+
+- **CLI Code Cleanup**: Refactored JSON formatting to use shared utility function
+  
+  - Extracted repeated `json.dumps()` calls to `format_json_output()` helper
+  - Cleaner code with consistent formatting across all commands
+
+Fixed
+-----
+
+- **Temperature Conversion Test**: Corrected ``test_device_status_div10`` to use ``HalfCelsiusToF`` conversion (100 → 122°F, not 50.0)
+- **Documentation**: Fixed references to non-existent ``OperationMode`` enum - replaced with correct ``DhwOperationSetting`` and ``CurrentOperationMode`` enums
+
 Version 6.1.1 (2025-12-08)
 ==========================
 
@@ -238,7 +355,7 @@ Quick Example
 
    # OLD boolean and enum handling
    is_heating = converted["currentHeatUse"] == 2
-   mode = CurrentOperationMode(converted["operationMode"]) if converted["operationMode"] in (0,32,64,96) else CurrentOperationMode.STANDBY
+   mode = OperationMode(converted["operationMode"]) if converted["operationMode"] in (0,32,64,96) else OperationMode.STANDBY
 
    # NEW simplified
    is_heating = status.current_heat_use

{nwp500_python-6.1.1/src/nwp500_python.egg-info → nwp500_python-7.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 6.1.1
+Version: 7.0.1
 Summary: A library for controlling Navien NWP500 Water Heaters via NaviLink
 Home-page: https://github.com/eman/nwp500-python
 Author: Emmanuel Levijarvi
@@ -13,17 +13,13 @@ Platform: any
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3 :: Only
-Requires-Python: >=3.9
+Requires-Python: >=3.13
 Description-Content-Type: text/x-rst; charset=UTF-8
 License-File: LICENSE.txt
 Requires-Dist: aiohttp>=3.8.0
-Requires-Dist: awsiotsdk>=1.26.0
+Requires-Dist: awsiotsdk>=1.27.0
 Requires-Dist: pydantic>=2.0.0
 Provides-Extra: testing
 Requires-Dist: setuptools; extra == "testing"
@@ -215,12 +211,10 @@ The library includes type-safe data models with automatic unit conversions:
 Requirements
 ============
 
-* Python 3.9+
+* Python 3.13+
 * aiohttp >= 3.8.0
-* websockets >= 10.0
-* cryptography >= 3.4.0
 * pydantic >= 2.0.0
-* awsiotsdk >= 1.21.0
+* awsiotsdk >= 1.27.0
 
 License
 =======

{nwp500_python-6.1.1 → nwp500_python-7.0.1}/README.rst

@@ -175,12 +175,10 @@ The library includes type-safe data models with automatic unit conversions:
 Requirements
 ============
 
-* Python 3.9+
+* Python 3.13+
 * aiohttp >= 3.8.0
-* websockets >= 10.0
-* cryptography >= 3.4.0
 * pydantic >= 2.0.0
-* awsiotsdk >= 1.21.0
+* awsiotsdk >= 1.27.0
 
 License
 =======

{nwp500_python-6.1.1 → nwp500_python-7.0.1}/docs/development/history.rst

@@ -18,7 +18,7 @@ providing:
 - Automatic reconnection with exponential backoff
 - Command queuing for reliable communication
 - Historical energy usage data (EMS API)
-- Modern Python 3.9+ codebase with native type hints
+- Modern Python 3.13+ codebase with native type hints
 
 Current Status
 --------------
@@ -38,7 +38,7 @@ The library is feature-complete with:
 - Comprehensive documentation
 - Working examples for all features
 - Unit tests with good coverage
-- Python 3.9+ with modern type hints
+- Python 3.13+ with modern type hints
 
 Implementation Milestones
 -------------------------

nwp500_python-7.0.1/docs/enumerations.rst

@@ -0,0 +1,293 @@
+Enumerations Reference
+======================
+
+This document provides a comprehensive reference for all enumerations used in
+the Navien NWP500 protocol.
+
+Device Control Commands
+-----------------------
+
+.. autoclass:: nwp500.enums.CommandCode
+   :members:
+   :undoc-members:
+
+These command IDs are used in MQTT control messages to change device settings
+and trigger actions. The most commonly used commands include:
+
+- **Power Control**: ``POWER_ON``, ``POWER_OFF``
+- **Temperature**: ``DHW_TEMPERATURE``
+- **Operation Mode**: ``DHW_MODE``
+- **TOU**: ``TOU_ON``, ``TOU_OFF``
+- **Maintenance**: ``AIR_FILTER_RESET``, ``ANTI_LEGIONELLA_ON``
+
+Example usage::
+
+    from nwp500 import CommandCode
+    
+    # Send temperature command
+    command = CommandCode.DHW_TEMPERATURE
+    params = [120]  # 60°C in half-degree units
+
+Status Value Enumerations
+--------------------------
+
+OnOffFlag
+~~~~~~~~~
+
+.. autoclass:: nwp500.enums.OnOffFlag
+   :members:
+   :undoc-members:
+
+Generic on/off flag used throughout status fields for power status, TOU status,
+recirculation status, vacation mode, anti-legionella, and other boolean settings.
+
+**Note**: Device uses ``1=OFF, 2=ON`` (not standard 0/1 boolean).
+
+Operation
+~~~~~~~~~
+
+.. autoclass:: nwp500.enums.Operation
+   :members:
+   :undoc-members:
+
+Device operation state indicating overall device activity.
+
+DhwOperationSetting
+~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: nwp500.enums.DhwOperationSetting
+   :members:
+   :undoc-members:
+
+User-configured DHW heating mode preference. This determines which heat source(s)
+the device will use when heating is needed:
+
+- **HEAT_PUMP**: Most efficient but slower heating
+- **ELECTRIC**: Fastest but uses most energy
+- **ENERGY_SAVER**: Hybrid mode - balanced efficiency
+- **HIGH_DEMAND**: Hybrid mode - maximum heating capacity
+- **VACATION**: Energy-saving mode for extended absences
+- **POWER_OFF**: Device powered off
+
+Example::
+
+    from nwp500 import DhwOperationSetting
+    from nwp500.enums import DHW_OPERATION_SETTING_TEXT
+    
+    mode = DhwOperationSetting.ENERGY_SAVER
+    print(f"Current mode: {DHW_OPERATION_SETTING_TEXT[mode]}")  # "Hybrid: Efficiency"
+
+CurrentOperationMode
+~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: nwp500.enums.CurrentOperationMode
+   :members:
+   :undoc-members:
+
+Real-time operational state (read-only). This reflects what the device is actually
+doing right now, which may differ from the configured mode setting:
+
+- **STANDBY**: Device idle, not actively heating
+- **HEAT_PUMP_MODE**: Heat pump actively running
+- **HYBRID_EFFICIENCY_MODE**: Actively heating in Energy Saver mode
+- **HYBRID_BOOST_MODE**: Actively heating in High Demand mode
+
+Example::
+
+    from nwp500 import CurrentOperationMode
+    from nwp500.enums import CURRENT_OPERATION_MODE_TEXT
+    
+    mode = CurrentOperationMode.HEAT_PUMP_MODE
+    print(f"Device state: {CURRENT_OPERATION_MODE_TEXT[mode]}")  # "Heat Pump"
+
+HeatSource
+~~~~~~~~~~
+
+.. autoclass:: nwp500.enums.HeatSource
+   :members:
+   :undoc-members:
+
+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
+shows which heat source(s) are active at any moment.
+
+DREvent
+~~~~~~~
+
+.. autoclass:: nwp500.enums.DREvent
+   :members:
+   :undoc-members:
+
+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.
+
+WaterLevel
+~~~~~~~~~~
+
+.. autoclass:: nwp500.enums.WaterLevel
+   :members:
+   :undoc-members:
+
+Hot water level indicator displayed as gauge in app. IDs are non-sequential,
+likely represent bit positions for multi-level displays.
+
+FilterChange
+~~~~~~~~~~~~
+
+.. autoclass:: nwp500.enums.FilterChange
+   :members:
+   :undoc-members:
+
+Air filter status for heat pump models. Indicates when air filter maintenance
+is needed.
+
+RecirculationMode
+~~~~~~~~~~~~~~~~~
+
+.. autoclass:: nwp500.enums.RecirculationMode
+   :members:
+   :undoc-members:
+
+Recirculation pump operation mode:
+
+- **ALWAYS**: Pump continuously runs
+- **BUTTON**: Manual activation only (hot button)
+- **SCHEDULE**: Runs on configured schedule
+- **TEMPERATURE**: Activates when pipe temp drops below setpoint
+
+Time of Use (TOU) Enumerations
+-------------------------------
+
+TouWeekType
+~~~~~~~~~~~
+
+.. autoclass:: nwp500.enums.TouWeekType
+   :members:
+   :undoc-members:
+
+Day grouping for TOU schedules. Allows separate schedules for weekdays and
+weekends to account for different electricity rates and usage patterns.
+
+TouRateType
+~~~~~~~~~~~
+
+.. autoclass:: nwp500.enums.TouRateType
+   :members:
+   :undoc-members:
+
+Electricity rate period type. Device behavior can be configured for each period:
+
+- **OFF_PEAK**: Lowest rates - device heats aggressively
+- **MID_PEAK**: Medium rates - device heats normally
+- **ON_PEAK**: Highest rates - device minimizes heating
+
+Temperature and Unit Enumerations
+----------------------------------
+
+TemperatureType
+~~~~~~~~~~~~~~~
+
+.. autoclass:: nwp500.enums.TemperatureType
+   :members:
+   :undoc-members:
+
+Temperature display unit preference (Celsius or Fahrenheit).
+
+**Alias**: ``TemperatureUnit`` in models.py for backward compatibility.
+
+TempFormulaType
+~~~~~~~~~~~~~~~
+
+.. autoclass:: nwp500.enums.TempFormulaType
+   :members:
+   :undoc-members:
+
+Temperature conversion formula type. Different device models use slightly different
+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.
+
+Device Type Enumerations
+-------------------------
+
+UnitType
+~~~~~~~~
+
+.. autoclass:: nwp500.enums.UnitType
+   :members:
+   :undoc-members:
+
+Navien device/unit model types. Common values:
+
+- **NPF** (513): Heat pump water heater (primary model for this library)
+- **NPE**: Tankless water heater
+- **NCB**: Condensing boiler
+- **NPN**: Condensing water heater
+
+Values with ``CAS_`` prefix indicate cascading systems where multiple units
+work together.
+
+DeviceType
+~~~~~~~~~~
+
+.. autoclass:: nwp500.enums.DeviceType
+   :members:
+   :undoc-members:
+
+Communication device type (WiFi module model).
+
+FirmwareType
+~~~~~~~~~~~~
+
+.. autoclass:: nwp500.enums.FirmwareType
+   :members:
+   :undoc-members:
+
+Firmware component types. Devices may have multiple firmware components that
+can be updated independently.
+
+Display Text Helpers
+--------------------
+
+The enums module also provides dictionaries for converting enum values to
+user-friendly display text:
+
+.. code-block:: python
+
+   from nwp500.enums import (
+       DHW_OPERATION_SETTING_TEXT,
+       CURRENT_OPERATION_MODE_TEXT,
+       HEAT_SOURCE_TEXT,
+       DR_EVENT_TEXT,
+       RECIRC_MODE_TEXT,
+       TOU_RATE_TEXT,
+       FILTER_STATUS_TEXT,
+       ERROR_CODE_TEXT,
+   )
+   
+   # Usage examples
+   from nwp500 import DhwOperationSetting, CurrentOperationMode, ErrorCode
+   
+   # User-configured mode
+   mode = DhwOperationSetting.ENERGY_SAVER
+   print(DHW_OPERATION_SETTING_TEXT[mode])  # "Hybrid: Efficiency"
+   
+   # Current operational state
+   state = CurrentOperationMode.HEAT_PUMP_MODE
+   print(CURRENT_OPERATION_MODE_TEXT[state])  # "Heat Pump"
+   
+   # Error codes
+   error = ErrorCode.E407_DHW_TEMP_SENSOR
+   print(ERROR_CODE_TEXT[error])  # "Abnormal DHW Temperature Sensor"
+
+Related Documentation
+---------------------
+
+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

{nwp500_python-6.1.1 → nwp500_python-7.0.1}/docs/guides/time_of_use.rst

@@ -914,11 +914,11 @@ The device status includes TOU-related fields:
 
     {
       "touStatus": 1,
-      "touOverrideStatus": 0
+      "touOverrideStatus": 2
     }
 
-* ``touStatus``: ``1`` if TOU scheduling is active, ``0`` if inactive
-* ``touOverrideStatus``: ``1`` if user has temporarily overridden TOU schedule
+* ``touStatus``: ``1`` if TOU scheduling is enabled/active, ``0`` if disabled/inactive
+* ``touOverrideStatus``: ``2`` (ON) = TOU schedule is operating normally, ``1`` (OFF) = user has overridden TOU to force immediate heating
 
 See :doc:`../protocol/device_status` for more details.
 

{nwp500_python-6.1.1 → nwp500_python-7.0.1}/docs/index.rst

@@ -101,6 +101,7 @@ Documentation Index
    python_api/api_client
    python_api/mqtt_client
    python_api/models
+   enumerations
    python_api/constants
    python_api/events
    python_api/exceptions

{nwp500_python-6.1.1 → nwp500_python-7.0.1}/docs/installation.rst

@@ -5,7 +5,7 @@ Installation
 Requirements
 ============
 
-* Python 3.9 or higher
+* Python 3.13 or higher
 * pip (Python package installer)
 * Navien Smart Control account
 
@@ -51,7 +51,7 @@ Core Dependencies
 The library requires:
 
 * ``aiohttp>=3.8.0`` - Async HTTP client for REST API
-* ``awsiotsdk>=1.20.0`` - AWS IoT SDK for MQTT
+* ``awsiotsdk>=1.27.0`` - AWS IoT SDK for MQTT
 * ``pydantic>=2.0.0`` - Data validation and models
 
 Optional Dependencies
@@ -128,7 +128,7 @@ The MQTT client requires the AWS IoT SDK:
 
 .. code-block:: bash
 
-   pip install awsiotsdk>=1.20.0
+   pip install awsiotsdk>=1.27.0
 
 Upgrading
 =========

{nwp500_python-6.1.1 → nwp500_python-7.0.1}/docs/protocol/data_conversions.rst

@@ -487,7 +487,7 @@ Vacation and Scheduling Fields
    * - ``touStatus``
      - None (direct value)
      - See values below
-     - **Time-of-Use (TOU) schedule status**. 0=inactive, 1=active. Controls heating based on electricity rate periods.
+     - **Time-of-Use (TOU) schedule status**. 0 = inactive/disabled, 1 = active/enabled. Controls heating based on electricity rate periods.
    * - ``drEventStatus``
      - None (direct value)
      - Bitfield
@@ -499,7 +499,7 @@ Vacation and Scheduling Fields
    * - ``touOverrideStatus``
      - None (direct value)
      - See explanation
-     - **User temporary override of TOU schedule**. Similar to DR override - user can override schedule temporarily.
+     - **TOU schedule operation status**. 1 (OFF) = user has overridden TOU to force immediate heating (override lasts up to 72 hours), 2 (ON) = TOU schedule is operating normally.
 
 Network and Diagnostic Fields
 -----------------------------