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, plus an on-demand report of the device's own daily history, split heat pump vs. resistive element. There is no cumulative consumption sensor: the device records the totals itself and reports them when asked.
• Alerts — Error codes, leak detection, and freeze/scald warnings via binary sensors.
• Scheduling — Recurring mode and temperature changes via the reservation service.

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
Diagnostics	Compressor temps, fan RPM, flow rates, refrigerant pressures	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 a total for everything requested, 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.

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.3.2. See CHANGELOG.md for version history.

License

Released under the MIT License.