nwp500-python 1.0.2__tar.gz → 1.0.4__tar.gz

{nwp500_python-1.0.2/src/nwp500_python.egg-info → nwp500_python-1.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nwp500-python
-Version: 1.0.2
+Version: 1.0.4
 Summary: Add a short description here!
 Home-page: https://github.com/pyscaffold/pyscaffold/
 Author: Emmanuel Levijarvi
@@ -96,6 +96,59 @@ Basic Usage
             # Change operation mode
             await api_client.set_device_mode(device, "heat_pump")
 
+Command Line Interface
+======================
+
+The library includes a command line interface for quick monitoring and device information retrieval:
+
+.. code-block:: bash
+
+    # Set credentials via environment variables
+    export NAVIEN_EMAIL="your_email@example.com"
+    export NAVIEN_PASSWORD="your_password"
+
+    # Get current device status (one-time)
+    python -m nwp500.cli --status
+
+    # Get device information
+    python -m nwp500.cli --device-info
+
+    # Get device feature/capability information  
+    python -m nwp500.cli --device-feature
+
+    # Set operation mode and see response
+    python -m nwp500.cli --set-mode energy-saver
+
+    # Set DHW target temperature and see response
+    python -m nwp500.cli --set-dhw-temp 140
+
+    # Set temperature and then get updated status
+    python -m nwp500.cli --set-dhw-temp 140 --status
+
+    # Set mode and then get updated status
+    python -m nwp500.cli --set-mode energy-saver --status
+
+    # Just get current status (one-time)
+    python -m nwp500.cli --status
+
+    # Monitor continuously (default - writes to CSV)
+    python -m nwp500.cli --monitor
+
+    # Monitor with custom output file
+    python -m nwp500.cli --monitor --output my_data.csv
+
+**Available CLI Options:**
+
+* ``--status``: Print current device status as JSON. Can be combined with control commands to see updated status.
+* ``--device-info``: Print comprehensive device information (firmware, model, capabilities) via MQTT as JSON and exit  
+* ``--device-feature``: Print device capabilities and feature settings via MQTT as JSON and exit
+* ``--set-mode MODE``: Set operation mode and display response. Valid modes: heat-pump, energy-saver, high-demand, electric, vacation, standby
+* ``--set-dhw-temp TEMP``: Set DHW (Domestic Hot Water) target temperature in Fahrenheit (115-150°F) and display response
+* ``--monitor``: Continuously monitor status every 30 seconds and log to CSV (default)
+* ``-o, --output``: Specify CSV output filename for monitoring mode
+* ``--email``: Override email (alternative to environment variable)
+* ``--password``: Override password (alternative to environment variable)
+
 Device Status Fields
 ====================
 
@@ -182,12 +235,14 @@ Documentation
 Comprehensive documentation is available in the ``docs/`` directory:
 
 * `Device Status Fields`_ - Complete field reference with units and conversions
+* `Device Feature Fields`_ - Device capabilities and firmware information reference
 * `MQTT Messages`_ - MQTT protocol documentation
 * `MQTT Client`_ - MQTT client usage guide
 * `Authentication`_ - Authentication module documentation
 
 .. _MQTT Protocol Documentation: docs/MQTT_MESSAGES.rst
 .. _Device Status Fields: docs/DEVICE_STATUS_FIELDS.rst
+.. _Device Feature Fields: docs/DEVICE_FEATURE_FIELDS.rst
 .. _MQTT Messages: docs/MQTT_MESSAGES.rst
 .. _MQTT Client: docs/MQTT_CLIENT.rst
 .. _Authentication: docs/AUTHENTICATION.rst
@@ -198,6 +253,7 @@ Data Models
 The library includes type-safe data models with automatic unit conversions:
 
 * **DeviceStatus**: Complete device status with 70+ fields
+* **DeviceFeature**: Device capabilities, firmware versions, and configuration limits
 * **OperationMode**: Enumeration of available operation modes
 * **TemperatureUnit**: Celsius/Fahrenheit handling
 * **MqttRequest/MqttCommand**: MQTT message structures

{nwp500_python-1.0.2 → nwp500_python-1.0.4}/README.rst

@@ -59,6 +59,59 @@ Basic Usage
             # Change operation mode
             await api_client.set_device_mode(device, "heat_pump")
 
+Command Line Interface
+======================
+
+The library includes a command line interface for quick monitoring and device information retrieval:
+
+.. code-block:: bash
+
+    # Set credentials via environment variables
+    export NAVIEN_EMAIL="your_email@example.com"
+    export NAVIEN_PASSWORD="your_password"
+
+    # Get current device status (one-time)
+    python -m nwp500.cli --status
+
+    # Get device information
+    python -m nwp500.cli --device-info
+
+    # Get device feature/capability information  
+    python -m nwp500.cli --device-feature
+
+    # Set operation mode and see response
+    python -m nwp500.cli --set-mode energy-saver
+
+    # Set DHW target temperature and see response
+    python -m nwp500.cli --set-dhw-temp 140
+
+    # Set temperature and then get updated status
+    python -m nwp500.cli --set-dhw-temp 140 --status
+
+    # Set mode and then get updated status
+    python -m nwp500.cli --set-mode energy-saver --status
+
+    # Just get current status (one-time)
+    python -m nwp500.cli --status
+
+    # Monitor continuously (default - writes to CSV)
+    python -m nwp500.cli --monitor
+
+    # Monitor with custom output file
+    python -m nwp500.cli --monitor --output my_data.csv
+
+**Available CLI Options:**
+
+* ``--status``: Print current device status as JSON. Can be combined with control commands to see updated status.
+* ``--device-info``: Print comprehensive device information (firmware, model, capabilities) via MQTT as JSON and exit  
+* ``--device-feature``: Print device capabilities and feature settings via MQTT as JSON and exit
+* ``--set-mode MODE``: Set operation mode and display response. Valid modes: heat-pump, energy-saver, high-demand, electric, vacation, standby
+* ``--set-dhw-temp TEMP``: Set DHW (Domestic Hot Water) target temperature in Fahrenheit (115-150°F) and display response
+* ``--monitor``: Continuously monitor status every 30 seconds and log to CSV (default)
+* ``-o, --output``: Specify CSV output filename for monitoring mode
+* ``--email``: Override email (alternative to environment variable)
+* ``--password``: Override password (alternative to environment variable)
+
 Device Status Fields
 ====================
 
@@ -145,12 +198,14 @@ Documentation
 Comprehensive documentation is available in the ``docs/`` directory:
 
 * `Device Status Fields`_ - Complete field reference with units and conversions
+* `Device Feature Fields`_ - Device capabilities and firmware information reference
 * `MQTT Messages`_ - MQTT protocol documentation
 * `MQTT Client`_ - MQTT client usage guide
 * `Authentication`_ - Authentication module documentation
 
 .. _MQTT Protocol Documentation: docs/MQTT_MESSAGES.rst
 .. _Device Status Fields: docs/DEVICE_STATUS_FIELDS.rst
+.. _Device Feature Fields: docs/DEVICE_FEATURE_FIELDS.rst
 .. _MQTT Messages: docs/MQTT_MESSAGES.rst
 .. _MQTT Client: docs/MQTT_CLIENT.rst
 .. _Authentication: docs/AUTHENTICATION.rst
@@ -161,6 +216,7 @@ Data Models
 The library includes type-safe data models with automatic unit conversions:
 
 * **DeviceStatus**: Complete device status with 70+ fields
+* **DeviceFeature**: Device capabilities, firmware versions, and configuration limits
 * **OperationMode**: Enumeration of available operation modes
 * **TemperatureUnit**: Celsius/Fahrenheit handling
 * **MqttRequest/MqttCommand**: MQTT message structures

nwp500_python-1.0.4/docs/DEVICE_FEATURE_FIELDS.rst

@@ -0,0 +1,366 @@
+Device Feature Fields
+=====================
+
+This document lists the fields found in the ``DeviceFeature`` object returned by MQTT device info requests.
+
+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.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 8 8 49 20
+
+   * - Field Name
+     - Type
+     - Units
+     - Description
+     - Conversion Formula
+   * - ``countryCode``
+     - int
+     - None
+     - Country/region code where device is certified for operation (1=USA, complies with FCC Part 15 Class B, NSF/ANSI 372)
+     - None
+   * - ``modelTypeCode``
+     - int
+     - None
+     - Model type identifier: NWP500 series electric heat pump water heater model variant
+     - None
+   * - ``controlTypeCode``
+     - int
+     - None
+     - Control system type: Advanced digital control with LCD display and WiFi connectivity
+     - None
+   * - ``volumeCode``
+     - int
+     - Gallons
+     - Tank nominal capacity: 50, 65, or 80 gallons (NWP500-50/65/80 models)
+     - None
+   * - ``controllerSwVersion``
+     - int
+     - None
+     - Main controller firmware version - controls heat pump, heating elements, and system logic
+     - None
+   * - ``panelSwVersion``
+     - int
+     - None
+     - Front panel display firmware version - manages LCD display and user interface
+     - None
+   * - ``wifiSwVersion``
+     - int
+     - None
+     - WiFi module firmware version - handles NaviLink app connectivity and cloud communication
+     - None
+   * - ``controllerSwCode``
+     - int
+     - None
+     - Controller firmware variant/branch identifier for support and compatibility
+     - None
+   * - ``panelSwCode``
+     - int
+     - None
+     - Panel firmware variant/branch identifier for display features and UI capabilities
+     - None
+   * - ``wifiSwCode``
+     - int
+     - None
+     - WiFi firmware variant/branch identifier for communication protocol version
+     - None
+   * - ``controllerSerialNumber``
+     - str
+     - None
+     - Unique serial number of the main controller board for warranty and service identification
+     - None
+   * - ``powerUse``
+     - int
+     - Boolean
+     - Power control capability (1=supported) - can be turned on/off via controls (always 1 for NWP500)
+     - None
+   * - ``holidayUse``
+     - int
+     - Boolean
+     - Vacation mode support (1=supported) - energy-saving mode for 0-99 days with minimal operations
+     - None
+   * - ``programReservationUse``
+     - int
+     - Boolean
+     - Scheduled operation support (1=supported) - programmable heating schedules and timers
+     - None
+   * - ``dhwUse``
+     - int
+     - Boolean
+     - Domestic hot water functionality (1=available) - primary function of water heater (always 1)
+     - None
+   * - ``dhwTemperatureSettingUse``
+     - int
+     - Boolean
+     - Temperature adjustment capability (1=supported) - user can modify target temperature
+     - None
+   * - ``dhwTemperatureMin``
+     - int
+     - °F
+     - Minimum DHW temperature setting: 95°F (35°C) - safety and efficiency lower limit
+     - ``raw + 20``
+   * - ``dhwTemperatureMax``
+     - int
+     - °F
+     - Maximum DHW temperature setting: 150°F (65.5°C) - scald protection upper limit
+     - ``raw + 20``
+   * - ``smartDiagnosticUse``
+     - int
+     - Boolean
+     - Self-diagnostic capability (1=available) - 10-minute startup diagnostic, error code system
+     - None
+   * - ``wifiRssiUse``
+     - int
+     - Boolean
+     - WiFi signal monitoring (1=supported) - reports signal strength in dBm for connectivity diagnostics
+     - None
+   * - ``temperatureType``
+     - TemperatureUnit
+     - Enum
+     - Default temperature unit preference (CELSIUS=1, FAHRENHEIT=2) - factory set to Fahrenheit for USA
+     - Enum
+   * - ``tempFormulaType``
+     - int
+     - None
+     - Temperature calculation method identifier for internal sensor calibration and conversions
+     - None
+   * - ``energyUsageUse``
+     - int
+     - Boolean
+     - Energy monitoring support (1=available) - tracks kWh consumption for heat pump and electric elements
+     - None
+   * - ``freezeProtectionUse``
+     - int
+     - Boolean
+     - Freeze protection capability (1=available) - automatic heating when tank drops below threshold
+     - None
+   * - ``freezeProtectionTempMin``
+     - int
+     - °F
+     - Minimum freeze protection threshold: 43°F (6°C) - factory default activation temperature
+     - ``raw + 20``
+   * - ``freezeProtectionTempMax``
+     - int
+     - °F
+     - Maximum freeze protection threshold: typically 65°F - user-adjustable upper limit
+     - ``raw + 20``
+   * - ``mixingValueUse``
+     - int
+     - Boolean
+     - Thermostatic mixing valve support (1=available) - for temperature limiting at point of use
+     - None
+   * - ``drSettingUse``
+     - int
+     - Boolean
+     - Demand Response support (1=available) - CTA-2045 compliance for utility load management
+     - None
+   * - ``antiLegionellaSettingUse``
+     - int
+     - Boolean
+     - Anti-Legionella function (1=available) - periodic heating to 140°F (60°C) to prevent bacteria
+     - None
+   * - ``hpwhUse``
+     - int
+     - Boolean
+     - Heat Pump Water Heater mode (1=supported) - primary efficient heating method using refrigeration cycle
+     - None
+   * - ``dhwRefillUse``
+     - int
+     - Boolean
+     - Tank refill detection (1=supported) - monitors for "dry fire" conditions during refill
+     - None
+   * - ``ecoUse``
+     - int
+     - Boolean
+     - ECO safety switch (1=available) - Energy Cut Off high-temperature limit protection
+     - None
+   * - ``electricUse``
+     - int
+     - Boolean
+     - Electric-only mode (1=supported) - heating element only operation for maximum recovery speed
+     - None
+   * - ``heatpumpUse``
+     - int
+     - Boolean
+     - Heat pump only mode (1=supported) - most efficient operation using only refrigeration cycle
+     - None
+   * - ``energySaverUse``
+     - int
+     - Boolean
+     - Energy Saver mode (1=supported) - hybrid efficiency mode balancing speed and efficiency (default)
+     - None
+   * - ``highDemandUse``
+     - int
+     - Boolean
+     - High Demand mode (1=supported) - hybrid boost mode prioritizing fast recovery over efficiency
+     - None
+
+Operation Mode Support Matrix
+-----------------------------
+
+The NWP500 supports five primary operation modes as indicated by the capability flags:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 15 15 15 55
+
+   * - Mode ID
+     - Mode Name
+     - Capability Flag
+     - Description & Performance Characteristics
+   * - 1
+     - Heat Pump Only
+     - ``heatpumpUse``
+     - **Most Efficient** - Uses only the heat pump compressor and evaporator. Longest recovery time but highest energy efficiency. Performance varies with ambient temperature and humidity.
+   * - 2
+     - Energy Saver (Default)
+     - ``energySaverUse``
+     - **Balanced Efficiency** - Hybrid mode combining heat pump with backup electric elements. Factory default setting balances efficiency with reasonable recovery time.
+   * - 3
+     - High Demand
+     - ``highDemandUse``
+     - **Fastest Recovery** - Hybrid mode prioritizing speed over efficiency. Uses heat pump plus more frequent electric element operation for maximum hot water supply.
+   * - 4
+     - Electric Only
+     - ``electricUse``
+     - **Emergency/Service Mode** - Uses only 3,755W heating elements (upper and lower, not simultaneously). Least efficient but operates in all conditions. Auto-reverts after 72 hours.
+   * - 5
+     - Vacation
+     - ``holidayUse``
+     - **Maximum Energy Savings** - Suspends normal heating for 0-99 days. Only freeze protection and anti-seize operations continue. Heating resumes 9 hours before vacation end.
+
+Hardware Specifications from Manual Cross-Reference
+---------------------------------------------------
+
+The device feature data corresponds to these official NWP500 specifications:
+
+**Electrical System**
+   * Input: 208-240V AC, 60Hz, 1-Phase
+   * Current Draw: 208V (25.9A) / 240V (28.8A) 
+   * Circuit Protection: 30A breaker required
+   * Heating Elements: 3,755W @ 208V or 5,000W @ 240V (upper and lower)
+   * Heat Pump Compressor: 11.6A
+   * Evaporator Fan: 0.22A
+
+**Physical Models**
+   * NWP500-50: 50 gallon, Ø21.7" × 63" (229 lbs)
+   * NWP500-65: 65 gallon, Ø25" × 63" (265 lbs) 
+   * NWP500-80: 80 gallon, Ø25" × 71.6" (282 lbs)
+
+**Safety & Compliance Features**
+   * FCC ID: P53-EMC3290 (Class B digital device)
+   * IC: 23507-EMC3290 (Industry Canada RSS-210)
+   * NSF/ANSI 372 certified (lead-free wetted surfaces <0.25%)
+   * Temperature & Pressure relief valve (150 psi)
+   * ECO (Energy Cut Off) high-limit safety switch
+
+**Smart Features & Connectivity**
+   * NaviLink WiFi app connectivity
+   * Self-diagnostic system with error codes
+   * CTA-2045 Demand Response module support
+   * Anti-Legionella periodic disinfection (1-30 day intervals)
+   * Programmable operation schedules
+
+Firmware Version Interpretation
+-------------------------------
+
+The device returns three separate firmware components for comprehensive system identification:
+
+**Main Controller (``controllerSwVersion``, ``controllerSwCode``)**
+   * Manages heat pump compressor, heating elements, temperature sensors
+   * Controls operation mode logic and safety interlocks
+   * Handles diagnostic routines and error detection
+   * Serial number provided for warranty tracking
+
+**Display Panel (``panelSwVersion``, ``panelSwCode``)** 
+   * User interface and LCD display management
+   * Button input processing and menu navigation
+   * Status indicator control and user feedback
+
+**WiFi Module (``wifiSwVersion``, ``wifiSwCode``)**
+   * NaviLink cloud connectivity and app communication
+   * Wireless network management and security
+   * Remote monitoring and control capabilities
+
+Temperature Range Validation
+----------------------------
+
+The reported temperature ranges align with official specifications and use the same conversion patterns as DeviceStatus fields:
+
+* **DHW Range**: 95°F to 150°F (factory default: 120°F for safety) - uses ``raw + 20`` conversion
+* **Freeze Protection**: Activates at 43°F, prevents tank freezing - uses ``raw + 20`` conversion
+* **Anti-Legionella**: Heats to 140°F at programmed intervals (requires mixing valve)
+* **Scald Protection**: Built-in limits with recommendation for thermostatic mixing valves
+
+**Conversion Pattern Consistency**: Temperature fields in DeviceFeature use the same ``raw + 20`` 
+conversion formula as corresponding fields in DeviceStatus, ensuring consistent temperature 
+handling across all device data structures.
+
+Usage Example
+-------------
+
+.. code-block:: python
+
+   import asyncio
+   from nwp500 import NavienAuthClient, NavienMqttClient, NavienAPIClient
+
+   async def analyze_device_capabilities():
+       async with NavienAuthClient("email@example.com", "password") as auth_client:
+           # Get device list
+           api_client = NavienAPIClient(auth_client)
+           devices = await api_client.list_devices()
+           device = devices[0]
+           
+           # Connect MQTT and request device features
+           mqtt_client = NavienMqttClient(auth_client)
+           await mqtt_client.connect()
+           
+           # Set up callback to analyze device capabilities
+           def analyze_features(feature):
+               print(f"=== Device Capability Analysis ===")
+               print(f"Model: NWP500-{feature.volumeCode} ({feature.volumeCode} gallon)")
+               print(f"Controller FW: v{feature.controllerSwVersion} (Code: {feature.controllerSwCode})")
+               print(f"Panel FW: v{feature.panelSwVersion} (Code: {feature.panelSwCode})")
+               print(f"WiFi FW: v{feature.wifiSwVersion} (Code: {feature.wifiSwCode})")
+               print(f"Serial: {feature.controllerSerialNumber}")
+               
+               print(f"\n=== Temperature Capabilities ===")
+               print(f"DHW Range: {feature.dhwTemperatureMin}°F - {feature.dhwTemperatureMax}°F")
+               print(f"Freeze Protection: {feature.freezeProtectionTempMin}°F - {feature.freezeProtectionTempMax}°F")
+               print(f"Default Unit: {feature.temperatureType.name}")
+               
+               print(f"\n=== Supported Operation Modes ===")
+               modes = []
+               if feature.heatpumpUse: modes.append("Heat Pump Only")
+               if feature.energySaverUse: modes.append("Energy Saver (Default)")
+               if feature.highDemandUse: modes.append("High Demand") 
+               if feature.electricUse: modes.append("Electric Only")
+               if feature.holidayUse: modes.append("Vacation Mode")
+               print(f"Available: {', '.join(modes)}")
+               
+               print(f"\n=== Smart Features ===")
+               features = []
+               if feature.smartDiagnosticUse: features.append("Self-Diagnostics")
+               if feature.wifiRssiUse: features.append("WiFi Monitoring")
+               if feature.energyUsageUse: features.append("Energy Tracking")
+               if feature.antiLegionellaSettingUse: features.append("Anti-Legionella")
+               if feature.drSettingUse: features.append("Demand Response")
+               if feature.mixingValueUse: features.append("Mixing Valve Support")
+               print(f"Available: {', '.join(features)}")
+           
+           await mqtt_client.subscribe_device_feature(device, analyze_features)
+           await mqtt_client.request_device_info(device)
+           
+           # Wait for response
+           await asyncio.sleep(5)
+           await mqtt_client.disconnect()
+
+   asyncio.run(analyze_device_capabilities())
+
+See Also
+--------
+
+* :doc:`DEVICE_STATUS_FIELDS` - Real-time device status field reference
+* :doc:`MQTT_CLIENT` - MQTT client usage guide for device communication
+* :doc:`API_CLIENT` - REST API client for device management
+* :doc:`ERROR_CODES` - Complete error code reference for diagnostics

{nwp500_python-1.0.2 → nwp500_python-1.0.4}/docs/DEVICE_STATUS_FIELDS.rst

@@ -117,12 +117,12 @@ This document lists the fields found in the ``status`` object of device status m
      - integer
      - °F
      - Temperature of the upper part of the tank.
-     - ``raw + 20``
+     - ``(raw / 10) * 9/5 + 32`` (decicelsius to Fahrenheit)
    * - ``tankLowerTemperature``
      - integer
      - °F
      - Temperature of the lower part of the tank.
-     - ``raw + 20``
+     - ``(raw / 10) * 9/5 + 32`` (decicelsius to Fahrenheit)
    * - ``dischargeTemperature``
      - integer
      - °F
@@ -142,7 +142,7 @@ This document lists the fields found in the ``status`` object of device status m
      - integer
      - °F
      - Ambient air temperature measured at the heat pump air intake.
-     - ``(raw * 9/5) + 32``
+     - ``(raw / 22.4) * 9/5 + 32``
    * - ``targetSuperHeat``
      - integer
      - °F

{nwp500_python-1.0.2 → nwp500_python-1.0.4}/docs/index.rst

@@ -322,6 +322,7 @@ Documentation
 
    API Reference (OpenAPI) <API_REFERENCE>
    Device Status Fields <DEVICE_STATUS_FIELDS>
+   Device Feature Fields <DEVICE_FEATURE_FIELDS>
    Error Codes <ERROR_CODES>
    MQTT Messages <MQTT_MESSAGES>
 

nwp500_python-1.0.4/examples/set_dhw_temperature_example.py

@@ -0,0 +1,120 @@
+#!/usr/bin/env python3
+"""
+Example: Setting DHW target temperature via MQTT and displaying response.
+
+This demonstrates how to programmatically change the water heater DHW
+(Domestic Hot Water) target temperature and receive confirmation of the change.
+"""
+
+import asyncio
+import logging
+from nwp500 import NavienAuthClient, NavienAPIClient, NavienMqttClient
+
+# Set up logging to see the temperature change process
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+async def set_dhw_temperature_example():
+    """Example of setting DHW target temperature programmatically."""
+
+    # Use environment variables or replace with your credentials
+    email = "your_email@example.com"
+    password = "your_password"
+
+    async with NavienAuthClient(email, password) as auth_client:
+        # Get device information
+        api_client = NavienAPIClient(auth_client)
+        devices = await api_client.list_devices()
+
+        if not devices:
+            logger.error("No devices found")
+            return
+
+        device = devices[0]
+        logger.info(f"Found device: {device.device_info.device_name}")
+
+        # Connect MQTT client
+        mqtt_client = NavienMqttClient(auth_client)
+        await mqtt_client.connect()
+        logger.info("MQTT client connected")
+
+        try:
+            # Get current status first
+            logger.info("Getting current device status...")
+            current_status = None
+
+            def on_current_status(status):
+                nonlocal current_status
+                current_status = status
+                logger.info(
+                    f"Current DHW target temperature: {status.dhwTargetTemperatureSetting}°F"
+                )
+                logger.info(f"Current DHW temperature: {status.dhwTemperature}°F")
+
+            await mqtt_client.subscribe_device_status(device, on_current_status)
+            await mqtt_client.request_device_status(device)
+            await asyncio.sleep(3)  # Wait for current status
+
+            # Set new target temperature to 140°F
+            target_temperature = 140
+            logger.info(f"Setting DHW target temperature to {target_temperature}°F...")
+
+            # Set up callback to capture temperature change response
+            temp_changed = False
+
+            def on_temp_change_response(status):
+                nonlocal temp_changed
+                logger.info("Temperature change response received!")
+                logger.info(
+                    f"New target temperature: {status.dhwTargetTemperatureSetting}°F"
+                )
+                logger.info(f"Current DHW temperature: {status.dhwTemperature}°F")
+                logger.info(f"Operation mode: {status.operationMode.name}")
+                logger.info(f"Tank charge: {status.dhwChargePer}%")
+                temp_changed = True
+
+            await mqtt_client.subscribe_device_status(device, on_temp_change_response)
+
+            # Send temperature change command using display temperature value
+            await mqtt_client.set_dhw_temperature_display(device, target_temperature)
+
+            # Wait for confirmation
+            for i in range(15):  # Wait up to 15 seconds
+                if temp_changed:
+                    logger.info("Temperature change confirmed!")
+                    break
+                await asyncio.sleep(1)
+            else:
+                logger.warning("Timeout waiting for temperature change confirmation")
+
+        finally:
+            await mqtt_client.disconnect()
+            logger.info("Disconnected from MQTT")
+
+
+if __name__ == "__main__":
+    print("=== DHW Temperature Change Example ===")
+    print("This example demonstrates:")
+    print("1. Connecting to device via MQTT")
+    print("2. Getting current DHW target temperature")
+    print("3. Setting new DHW target temperature to 140°F")
+    print("4. Receiving and displaying the response")
+    print()
+
+    # Note: This requires valid credentials
+    print(
+        "Note: Update email/password or set NAVIEN_EMAIL/NAVIEN_PASSWORD environment variables"
+    )
+    print()
+
+    # Uncomment to run (requires valid credentials)
+    # asyncio.run(set_dhw_temperature_example())
+
+    print("CLI equivalent commands:")
+    print("  python -m nwp500.cli --set-dhw-temp 140")
+    print("  python -m nwp500.cli --set-dhw-temp 130")
+    print("  python -m nwp500.cli --set-dhw-temp 150")
+    print()
+    print("Valid temperature range: 115-150°F")
+    print("Note: The device may cap temperatures at 150°F maximum")