{"id":42051999,"url":"https://github.com/eman/nwp500-python","last_synced_at":"2026-02-18T01:06:24.420Z","repository":{"id":318709119,"uuid":"1073237436","full_name":"eman/nwp500-python","owner":"eman","description":"Python module for interacting with Navien NWP500 water heaters","archived":false,"fork":false,"pushed_at":"2026-02-13T06:49:24.000Z","size":1743,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-13T12:25:27.016Z","etag":null,"topics":["heat-pump","navien","nwp500","water-heater"],"latest_commit_sha":null,"homepage":"https://nwp500-python.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eman.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGELOG.rst","contributing":"CONTRIBUTING.rst","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.rst","dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-09T20:11:48.000Z","updated_at":"2026-02-13T06:49:27.000Z","dependencies_parsed_at":"2026-01-16T03:01:53.426Z","dependency_job_id":null,"html_url":"https://github.com/eman/nwp500-python","commit_stats":null,"previous_names":["eman/nwp500-python"],"tags_count":51,"template":false,"template_full_name":null,"purl":"pkg:github/eman/nwp500-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eman%2Fnwp500-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eman%2Fnwp500-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eman%2Fnwp500-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eman%2Fnwp500-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eman","download_url":"https://codeload.github.com/eman/nwp500-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eman%2Fnwp500-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29565018,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T00:47:08.760Z","status":"ssl_error","status_checked_at":"2026-02-18T00:45:26.718Z","response_time":100,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["heat-pump","navien","nwp500","water-heater"],"created_at":"2026-01-26T07:02:45.124Z","updated_at":"2026-02-18T01:06:24.414Z","avatar_url":"https://github.com/eman.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"=============\nnwp500-python\n=============\n\nPython library for Navien NWP500 Heat Pump Water Heater\n========================================================\n\nA 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.\n\n**Documentation:** https://nwp500-python.readthedocs.io/\n\n**Source Code:** https://github.com/eman/nwp500-python\n\nFeatures\n========\n* Monitor status (temperature, power, charge %)\n* Set target water temperature\n* Change operation mode\n* Optional scheduling (reservations)\n* Optional time-of-use settings\n* Periodic high-temp cycle info\n* Access detailed status fields\n\n* Async friendly\n\nQuick Start\n===========\n\nInstallation\n------------\n\nBasic Installation (Library Only)\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nFor using the library as a Python package without the CLI:\n\n.. code-block:: bash\n\n    pip install nwp500-python\n\nThis installs the core library with support for API and MQTT clients. No CLI framework is required.\n\nInstallation with CLI Support\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nTo use the command-line interface with rich formatting and colors:\n\n.. code-block:: bash\n\n    pip install nwp500-python[cli]\n\nThis includes both the ``click`` CLI framework and the ``rich`` formatting library for enhanced terminal output with formatted tables, progress bars, and colored output.\n\nBasic Usage\n-----------\n\n.. code-block:: python\n\n    from nwp500 import NavienAuthClient, NavienAPIClient\n\n    # Authentication happens automatically when entering the context\n    async with NavienAuthClient(\"your_email@example.com\", \"your_password\") as auth_client:\n        # Create API client\n        api_client = NavienAPIClient(auth_client=auth_client)\n        \n        # Get device data\n        devices = await api_client.list_devices()\n        device = devices[0] if devices else None\n        \n        if device:\n            # Access status information\n            status = device.status\n            print(f\"Water Temperature: {status.dhw_temperature}\")\n            print(f\"Tank Charge: {status.dhw_charge_per}%\")\n            print(f\"Power Consumption: {status.current_inst_power}W\")\n            \n            # Set temperature\n            await api_client.set_device_temperature(device, 130)\n            \n            # Change operation mode\n            await api_client.set_device_mode(device, \"heat_pump\")\n\nFor more detailed authentication information, see the `Authentication \u0026 Session Management \u003chttps://nwp500-python.readthedocs.io/en/latest/guides/authentication.html\u003e`_ guide.\n\nMQTT Real-Time Monitoring\n--------------------------\n\nMonitor your device in real-time using MQTT:\n\n.. code-block:: python\n\n    from nwp500 import NavienAuthClient, NavienMqttClient\n\n    async with NavienAuthClient(\"your_email@example.com\", \"your_password\") as auth_client:\n        # Create MQTT client\n        mqtt_client = NavienMqttClient(auth_client=auth_client)\n        await mqtt_client.connect()\n        \n        # Subscribe to device status updates\n        def on_status(status):\n            print(f\"Temperature: {status.dhw_temperature}°F\")\n            print(f\"Mode: {status.operation_mode}\")\n        \n        device = (await api_client.list_devices())[0]\n        await mqtt_client.subscribe_device_status(device, on_status)\n        \n        # Keep the connection alive\n        await mqtt_client.wait()\n\n\nCommand Line Interface\n======================\n\nThe library includes a command line interface for monitoring and controlling your Navien water heater.\n\n**Installation Requirement:** The CLI requires the ``cli`` extra:\n\n.. code-block:: bash\n\n    pip install nwp500-python[cli]\n\nQuick Reference\n---------------\n\n.. code-block:: bash\n\n    # Set credentials via environment variables\n    export NAVIEN_EMAIL=\"your_email@example.com\"\n    export NAVIEN_PASSWORD=\"your_password\"\n\n    # Get current device status\n    python3 -m nwp500.cli status\n\n    # Get device information and firmware (via MQTT - DeviceFeature)\n    python3 -m nwp500.cli info\n\n    # Get basic device info from REST API (DeviceInfo)\n    python3 -m nwp500.cli device-info\n\n    # Get controller serial number\n    python3 -m nwp500.cli serial\n\n    # Turn device on/off\n    python3 -m nwp500.cli power on\n    python3 -m nwp500.cli power off\n\n    # Set operation mode\n    python3 -m nwp500.cli mode heat-pump\n    python3 -m nwp500.cli mode energy-saver\n    python3 -m nwp500.cli mode high-demand\n    python3 -m nwp500.cli mode electric\n    python3 -m nwp500.cli mode vacation\n    python3 -m nwp500.cli mode standby\n\n    # Set target temperature\n    python3 -m nwp500.cli temp 140\n\n    # Set vacation days\n    python3 -m nwp500.cli vacation 7\n\n    # Trigger instant hot water\n    python3 -m nwp500.cli hot-button\n\n    # Set recirculation pump mode (1-4)\n    python3 -m nwp500.cli recirc 2\n\n    # Reset air filter timer\n    python3 -m nwp500.cli reset-filter\n\n    # Enable water program mode\n    python3 -m nwp500.cli water-program\n\n    # View and update schedules\n    python3 -m nwp500.cli reservations get\n    python3 -m nwp500.cli reservations set '[{\"hour\": 6, \"min\": 0, ...}]'\n\n    # Time-of-use settings\n    python3 -m nwp500.cli tou get\n    python3 -m nwp500.cli tou set on\n\n    # Energy usage data\n    python3 -m nwp500.cli energy --year 2024 --months 10,11,12\n\n    # Demand response\n    python3 -m nwp500.cli dr enable\n    python3 -m nwp500.cli dr disable\n\n    # Real-time monitoring (logs to CSV)\n    python3 -m nwp500.cli monitor\n    python3 -m nwp500.cli monitor -o my_data.csv\n\n**Global Options:**\n\n* ``--email EMAIL``: Navien account email (or use ``NAVIEN_EMAIL`` env var)\n* ``--password PASSWORD``: Navien account password (or use ``NAVIEN_PASSWORD`` env var)\n* ``-v, --verbose``: Enable debug logging\n* ``--version``: Show version and exit\n\n**Available Commands:**\n\n* ``status``: Show current device status (temperature, mode, power)\n* ``info``: Show device information (firmware, capabilities)\n* ``serial``: Get controller serial number\n* ``power on|off``: Turn device on or off\n* ``mode MODE``: Set operation mode (heat-pump, electric, energy-saver, high-demand, vacation, standby)\n* ``temp TEMPERATURE``: Set target water temperature in °F\n* ``vacation DAYS``: Enable vacation mode for N days\n* ``recirc MODE``: Set recirculation pump (1=always, 2=button, 3=schedule, 4=temperature)\n* ``hot-button``: Trigger instant hot water\n* ``reset-filter``: Reset air filter maintenance timer\n* ``water-program``: Enable water program reservation mode\n* ``reservations get|set``: View or update schedule\n* ``tou get|set STATE``: View or configure time-of-use settings\n* ``energy``: Query historical energy usage (requires ``--year`` and ``--months``)\n* ``dr enable|disable``: Enable or disable demand response\n* ``monitor``: Monitor device status in real-time (logs to CSV with ``-o`` option)\n\nDevice Status Fields\n====================\n\nThe library provides access to comprehensive device status information:\n\n**Temperature Sensors**\n    * Water temperature (current and target)\n    * Tank upper/lower temperatures\n    * Ambient temperature\n    * Discharge, suction, and evaporator temperatures\n    * Inlet temperature\n\n**System Status**\n    * Operation mode (Heat Pump, Energy Saver, High Demand, Electric, Vacation)\n    * Compressor status\n    * Heat pump and electric heater status\n    * Evaporator fan status\n    * Tank charge percentage\n\n**Power \u0026 Energy**\n    * Current power consumption (Watts)\n    * Total energy capacity (Wh)\n    * Available energy capacity (Wh)\n\n**Diagnostics**\n    * WiFi signal strength\n    * Error codes\n    * Fault status\n    * Cumulative operation time\n    * Flow rates\n\nDocumentation\n=============\n\nFull docs: https://nwp500-python.readthedocs.io/\n\nData Models\n===========\n\nThe library includes type-safe data models with automatic unit conversions:\n\n* **DeviceStatus**: Complete device status with 70+ fields\n* **DeviceFeature**: Device capabilities, firmware versions, and configuration limits\n* **OperationMode**: Enumeration of available operation modes\n* **TemperatureUnit**: Celsius/Fahrenheit handling\n\nRequirements\n============\n\n* Python 3.13+\n* aiohttp \u003e= 3.8.0\n* pydantic \u003e= 2.0.0\n* awsiotsdk \u003e= 1.27.0\n\nLicense\n=======\n\nThis project is licensed under the MIT License.\n\nAuthor\n======\n\nEmmanuel Levijarvi \u003cemansl@gmail.com\u003e\n\nAcknowledgments\n===============\n\nThis project has been set up using PyScaffold 4.6. For details and usage\ninformation on PyScaffold see https://pyscaffold.org/.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feman%2Fnwp500-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feman%2Fnwp500-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feman%2Fnwp500-python/lists"}