Navien Hot Water heater - Navilink

To anyone who experiences the above, just let NaviLink run for a few days and delete / readd the integration - it will start working!

@nikshriv, can’t wait for you to integrate the ability to enable / disable the recirculation schedule. I think this would be a fantastic addition, so that we can just have one button on the HA dashboard that allows us to start it.

While NaviLink works, it has a terrible interface. If you incorporate schedule on / off, we can simply set the schedule to be on 24/7, then enable / disable the schedule as needed. Personally, I would create an automation that turns on the schedule, waits for 2-3 minutes (that’s how long it takes for mine to re-circulate hot water), then stops it. Would be super useful before using hot water, so that none is wasted!

Never mind the above. Now that I looked through the code, I realized my mistake :slight_smile:
Instructions to follow for newbies below…

Alright, whoever struggles with this integration and wants to make it work amazingly well, here is what you need to do:

  1. Install NaviLink and let it run for a few days
  2. On your Navien water heater, go to the menu and set it up for Hot Button (manual), even if you don’t have a Hot Button accessory
  3. Open up NaviLink and make sure it shows Hot Button on the bottom instead of something like Weekly Schedule
  4. Install the above integration through HACS (look up how to do this online, it is pretty easy!). I personally set up polling to 60 seconds not to overwhelm my HA install, but you can choose all the way down to 15 seconds. Once the integration is installed, because you set it up as “Hot Button”, it will add another entity called switch.device_name_hot_button. If you set it up for schedule or some other mode, this entity will not be set up.
  5. Now that the Hot Button entity is set up, you can add a button to your dashboard. I set up mine as a large button, so that my family members can walk up to a wall-mounted display and tap the button to start the recirculation pump.

The integration works beautifully. Hopefully @nikshriv will set up a good manual for those who struggle with this integration. I don’t mind it at all if he copy-pastes the above to the README file - I think it will help others who just want to get this thing working.

Thank you very much for the integration!!!

1 Like

Lately mine has been generating errors in my logs. I don’t have the logs right now but I believe it was something related to connectivity. I am having issues with my Unifi AP firmware so at first I chalked it up to that but I believe it started after a recent update of this integration…


This error originated from a custom integration.

Logger: custom_components.navien_water_heater.navien_api
Source: custom_components/navien_water_heater/
Integration: Navien NaviLink Water Heater Integration (documentation)
First occurred: 12:54:36 (3 occurrences)
Last logged: 20:34:37

Connection reset by Navien server, reconnecting...

I have seen connectivity issues with the Navien SmartControl service from time to time as well. You can see the same issue with their mobile app. There isn’t much we can do from a programmatic standpoint other than reconnect to the service and try the command again when this happens.

Where do you see disconnections in their app?

I do have some ongoing issue with my Unifi APs kicking off some devices but I thought it was limited to our phones and ecobee thermostats… maybe it includes the NaviLink device too.

Aha! I stand corrected… The connectivity issues I had experienced earlier were while using a previous Wi-Fi setup (in an area with somewhat poor signal level) and I had always attributed this issue to a connectivity issue between the interface library (pyNavienSmartControl in this case) and Navien’s backend, but it seems to do this if the NaviLink is disconnected from the network. As a test, I blocked the NaviLink device on my wireless network and tried to pull a status summary. The library is able to authenticate with the Navien REST API, but is unable to connect to the binary protocol backend and throws the same type of error. This lends support to your theory that it may be related to NaviLink Wi-Fi link issues.

My current Wi-Fi setup also uses multiple Unifi APs (and Ecobees), and thus far I haven’t been having any issues with device connectivity. My only suggestions on that front if you are using multiple APs, is to set a logical minimum RSSI for the 2.4GHz radio, disable Fast Roaming and enable BSS Transition.

All my IoT stuff has its own SSID on 2.4GHz with all advanced features turned off for increased compatibility. My issues started when I replaced 2 of my 5 APs with U6-LR APs… they use a different chipset / firmware and I am guessing Unifi has some issue they are struggling to fix. To complicate matters both my ecobee thermostats kicked the bucket soon after so I replaced them with new ones which happened to have Alexa in them… and since they do, I get the annoying “I’m having issues right now” message and found that their network config was when they gave that error. I did configure one statically but the same thing happens… I am now inclined to think that the Navilink is also getting booted for the same unknown reason.

I’m not sure if it helps, but I have a mix of U6-Pro and U6-IW (all Qualcomm chipset). From posts on the Unifi forums and chatter in Discord, it definitely seems the Mediatek chipset APs had a lot of issues earlier on (during EA, and the earlier days of GA), but this seems to have bee mostly sorted out now. You likely want to follow up on the forums or Discord as they can likely provide more assistance on this.

1 Like

Hi all. I have a HCB-240/130H combi-boiler with NaviLink. I added the hass_navien_water_heater custom component and it is connected and functional in HA. While it is displaying water heater relevant metrics, it isn’t returning the extra “boiler” sensor metrics. Is anyone aware of a custom component for the combi-boiler in addition to the water heater? I’d absolutely be willing to test. Thanks, all!


Thanks for the great instructions. I haven’t been able to get the Hot button to show up in the integration and I’m wondering if you have any suggestions. I was using the Navilink app to run the recirculation on a schedule, but I find the app finicky and I’d like to control the recirculation from HA, either based on schedule in HA or possibly a motion sensors or light switches.

I went to the navilink menu and but don’t see anything obvious for Hot Button initiation. I’ve googled the Hot Button installation instructions and they speak of P-012 setting but nothing else. Is there something I can being doing on HA to get this Hot Button to show up on the integration?


Your water heater needs to be configured properly for the hot button to show up. This depends primarily on if the water heater recirculation settings are set for internal or external recirculation. You can change those settings by using the menu button on the water heater and selecting recirculation settings. Then you will need to select external recirculation, and then select Hot Button. You will then need to uninstall and reinstall the integration. Once you do so, the Hot Button entity will be created.

I was forced to update my username and password today for the new Navien app. Instead of my standard username, I had to use an email address. After making these changes and deleting and re-adding the integration, I was no longer able to login. Anyone else seeing this behavior?

Same here. I have not had time to look into it yet.

Here’s what I’ve tried so far. Removed the integration completely and re-downloaded and installed the integration. Able to get to the NaviLink Credentials screen, but neither my old username nor new email based username work.

Unfortunately, navien completely changed the backend of the app. It now uses AWS IOT platform so the integration will need to be completely rewritten. I’ll update you when I figure out how to get this working.

1 Like

Hi @nikshriv. I recently installed a combi-boiler (NFC-250/175H) from Navien and have Navilink set up. I’m happy to help support with testing or collecting test data from my system if helpful to the project (my system has both a water heater and boiler so I imagine can help cover both cases). Thank you for the work on this!

1 Like

Yep, it looks like some major updates have finally been made… There was a pretty serious security vulnerability with the previous protocol implementation that I hope has been addressed, but haven’t dug into it yet.

@nikshriv Thank You for your work on this. I’d be happy to help in anyway I can as well.

Is the app or Navilink any better now since the migration?

Seems more responsive and stable, but the basic functionality is the same. Setup on the old app was pretty bad. I did not have to re-add my Navilink, so I cannot comment on if setup was improved.

1 Like