A Home Assistant custom integration for Navien NWP500 Heat Pump Water Heaters. Connects to the Navien cloud API and subscribes to MQTT for real-time updates.

Table of Contents

• Features
• Installation
• Configuration
• Usage Guide
  • Operation Modes
  • Sensors & Entities
  • Reservation Scheduling
• Automation Examples
• Library Version
• License

Features

• Temperature & mode control — Set target temperature, switch operation modes, and toggle power.
• Live status — Current water temp, power draw, and device state updated via MQTT.
• Energy tracking — Live power draw as a sensor, lifetime heat pump and heating element energy sensors for the Energy dashboard, plus an on-demand report of the device's own daily or monthly history, split heat pump vs. resistive element.
• Lifetime counters — Compressor, fan, element and pump run times and start counts, and fault event counts, from the installer diagnostics the NaviLink app shows only to installers.
• Alerts — Error codes, leak detection, and freeze/scald warnings via binary sensors.
• Scheduling — Recurring mode and temperature changes via the reservation service.
• External control — Optional, and off unless you turn it on. Lets a scheduler of your own publish a plan: when to change the heater's temperature and mode. The plan is written into the heater's own schedule, so the heater keeps following it if Home Assistant is down. See docs/external-control.md.

Installation

HACS (Recommended)

This integration is in the default HACS index, so no custom repository is needed.

1. Open HACS in Home Assistant.
2. Search for "Navien NWP500".
3. Select it and choose Download.
4. Restart Home Assistant.

Not showing up in HACS?

If your HACS index is out of date, either refresh it (HACS > ⋮ > Update information) or add this repository manually:

1. Go to HACS > ⋮ > Custom repositories.
2. Add https://github.com/eman/ha_nwp500 with category Integration.
3. Search for "Navien NWP500" and download it.
4. Restart Home Assistant.

Manual

1. Copy custom_components/nwp500 to your config/custom_components/ directory.
2. Restart Home Assistant.

Or use this button

Configuration

1. Go to Settings > Devices & Services > Add Integration.
2. Search for "Navien NWP500".
3. Enter your NaviLink email and password.

Usage Guide

Operation Modes

Mode	HA Value	Description
Heat Pump	heat_pump	Heat pump only — most efficient.
Energy Saver	eco	Hybrid mode balancing efficiency and recovery time.
High Demand	high_demand	Heat pump + electric elements — fastest recovery.
Electric	electric	Electric elements only.

Sensors & Entities

Most sensors are disabled by default. Enable them from the device page in Home Assistant.

Category	Entities	Enabled by Default
Control	Water Heater entity	Yes
Temperature	Tank & DHW temperatures	Yes
Power	Current power & energy status	Yes
Status	Error codes & basic status	Yes
Energy	Lifetime heat pump & heating element energy	Yes
Diagnostics	Compressor temps, fan RPM, flow rates, refrigerant pressures	No
Lifetime	Run times, start counts, fault event counts, days installed	No
Internal	EEV steps, mixing rates, component status	No
Safety	Leak detection, freeze protection, scald warnings	No

Reservation Scheduling

Schedule recurring mode or temperature changes with the nwp500.set_reservation service.

service: nwp500.set_reservation
target:
  device_id: your_device_id
data:
  enabled: true
  days: [Monday, Tuesday, Wednesday, Thursday, Friday]
  hour: 6
  minute: 30
  mode: high_demand
  temperature: 140

Energy Usage Report

The device keeps its own daily energy totals, split between the heat pump and the electric heating elements. Ask for them on demand with nwp500.get_energy_usage; nothing is recorded, the report is returned to the caller. Omit year and months for the current month.

action: nwp500.get_energy_usage
target:
  device_id: your_device_id
data:
  year: 2026
  months: [7, 8]
response_variable: report

In the UI the months are a dropdown, so this is easier to reach from Developer Tools → Actions than from YAML; the report is shown there as the action's response.

The report carries the device's lifetime total (the device reports the same total whatever period is asked for), then a per-month total and a date-stamped day-by-day breakdown:

mac_address: AA:BB:CC:DD:EE:FF
total:
  heat_pump_wh: 41200
  heat_element_wh: 6800
  total_wh: 48000
  total_kwh: 48.0
  heat_pump_percent: 85.8
  heat_pump_hours: 412
  heat_element_hours: 23
months:
  - year: 2026
    month: 7
    total: {...}
    days:
      - day: 1
        date: "2026-07-01"
        heat_pump_wh: 1400
        heat_element_wh: 0
        total_kwh: 1.4
        heat_pump_percent: 100.0
        ...

heat_pump_percent is the share that came from the heat pump; the remainder is resistive element usage, which costs roughly three times as much per unit of heat.

Ask for whole years instead to get one total per month, the way the NaviLink app's usage screen does. years cannot be combined with year or months.

action: nwp500.get_energy_usage
target:
  device_id: your_device_id
data:
  years: [2025, 2026]
response_variable: report

mac_address: AA:BB:CC:DD:EE:FF
lifetime_total: {...}
years:
  - year: 2026
    total: {...}
    months:
      - month: 1
        date: "2026-01"
        heat_pump_wh: 41200
        ...

Maintenance Services

• nwp500.reset_air_filter restarts the air filter timer after cleaning.
• nwp500.set_air_filter_life sets the interval the air filter alarm counts toward: 0 (alarm off) or 1000-10000 evaporator-fan hours in steps of 500, the same choices the NaviLink app offers.
• nwp500.reset_condenser_fault clears a condenser fault once its cause has been dealt with. The app shows this only to installer accounts.
• nwp500.set_vacation_duration changes the vacation day count without entering vacation mode; nwp500.set_vacation_days enters it.

Automation Examples

Solar Energy Dump

Switch to High Demand when you have surplus solar power.

alias: "Water Heater - Solar Boost"
trigger:
  - platform: numeric_state
    entity_id: sensor.solar_export_power
    above: 1000
action:
  - service: water_heater.set_operation_mode
    target:
      entity_id: water_heater.navien_nwp500
    data:
      operation_mode: "high_demand"
  - service: water_heater.set_temperature
    target:
      entity_id: water_heater.navien_nwp500
    data:
      temperature: 140

Leak Detection Alert

Enable binary_sensor.navien_nwp500_water_leak_detected from the device page first.

alias: "Water Heater - Leak Alert"
trigger:
  - platform: state
    entity_id: binary_sensor.navien_nwp500_water_leak_detected
    to: "on"
action:
  - service: notify.mobile_app_phone
    data:
      message: "CRITICAL: Water leak detected at Water Heater!"
      data:
        push:
          sound:
            name: default
            critical: 1
            volume: 1.0

Vacation Mode

alias: "Water Heater - Away Mode"
trigger:
  - platform: state
    entity_id: group.family
    to: "not_home"
action:
  - service: water_heater.set_operation_mode
    target:
      entity_id: water_heater.navien_nwp500
    data:
      operation_mode: "eco"

Library Version

Uses nwp500-python v9.4.3. See CHANGELOG.md for version history.

License

Released under the MIT License.