{"id":27113388,"url":"https://github.com/dacarson/navienmanager","last_synced_at":"2026-02-28T08:32:58.328Z","repository":{"id":285495989,"uuid":"944713883","full_name":"dacarson/NavienManager","owner":"dacarson","description":"HomeKit and diagnostics for Navien Tankless Water Heater using ESP32 + RS485","archived":false,"fork":false,"pushed_at":"2025-04-10T03:59:36.000Z","size":310,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-10T04:39:12.631Z","etag":null,"topics":["esp32","homekit-accessory","homespan","navien","rs485"],"latest_commit_sha":null,"homepage":"","language":"C++","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/dacarson.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-07T20:50:06.000Z","updated_at":"2025-04-10T03:59:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"0f22b68d-602c-4227-9895-7c760f93873e","html_url":"https://github.com/dacarson/NavienManager","commit_stats":null,"previous_names":["dacarson/navienmanager"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dacarson/NavienManager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dacarson%2FNavienManager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dacarson%2FNavienManager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dacarson%2FNavienManager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dacarson%2FNavienManager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dacarson","download_url":"https://codeload.github.com/dacarson/NavienManager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dacarson%2FNavienManager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275399929,"owners_count":25457790,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-16T02:00:10.229Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["esp32","homekit-accessory","homespan","navien","rs485"],"created_at":"2025-04-07T02:51:58.538Z","updated_at":"2025-09-16T10:04:04.473Z","avatar_url":"https://github.com/dacarson.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Github License](https://img.shields.io/github/license/dacarson/NavienManager) ![Github Release](https://img.shields.io/github/v/release/dacarson/NavienManager?display_name=tag)\n\n# NavienManager\n HomeKit and diagnostics for Navien NPE-240A (though may work with others) using ESP32 + RS485\n\n## Why\nWhile the Navien Tankless Hot Water unit supports Wi-Fi via NaviLink, there are two important features it lacks:\n1. **Vacation Mode**  \nA way to automate vacation mode — either through a schedule with a defined start and end time, or by integrating with a system like HomeKit — is essential to me. Vacation mode prevents wasting gas on unnecessary recirculation. While I could manually turn the unit off before leaving and back on upon returning, automation allows me to “set it and forget it,” which is far more convenient and reliable.\n2. **Hot Water Now + Recirculation Schedule**  \nWith NaviLink, I can configure a fixed schedule for recirculation. However, this does not work with Navien’s “Hot Button.” You can have one or the other — not both. I wanted a way to trigger recirculation for a fixed period outside of the scheduled times. This allows me to avoid wasting water while waiting for it to get hot.\n\n## Description\n\nMy home is a HomeKit home, and I wanted to control the hot water unit through it. I decided to model the hot water unit as a thermostat. This allows me to say things like **“Hey Siri, turn on Hot Water Heater”** or create any number of scenes that activate recirculation. I’ve enabled two modes of operation:\n\n### Monitor Mode\nIn this mode, a NaviLink Wi-Fi box is attached and controls the Navien tankless hot water unit. Adjusting any HomeKit settings in this mode has no effect; they will simply revert to reflect the current state of the unit.\n\n- If the HomeKit thermostat shows **HEAT**, it means recirculation is currently running, or that a tap is open and the unit is actively heating water. The setpoint reflects the unit’s configured temperature.\n- If the thermostat shows **OFF**, the system is idle, and the setpoint is set to the minimum value. The adjustment of the setpoint is useful to show in the Eve app when the hot water unit is heating or not.\n\n### Control Mode (WIP - still validating)\nThe NaviLink box is not attached, allowing full control via HomeKit. In this mode, a schedule can be defined using the Eve app. The setpoint should be controlled via Apple’s Home app, as Eve does not support the full temperature range of a hot water unit. The temperature set in the Home app overrides any setpoint from the Eve schedule.\n\nThe thermostat states represent the same as Monitor mode. However, changing them now has an effect.\n\n- Switching to **HEAT** activates recirculation for 5 minutes, after which it returns to the schedule. If it is already running, it has no effect.\n- Switching to **OFF** turns off recirculation if it was running. The thermostat will return to schedule when the next scheduled event occurs.\n- If **Vacation Mode** is enabled via Automation in the Eve app, the hot water unit will be powered off and all schedules will be suspended.\n  \n## Features\nThe NavienManager has a number of features that came about as due process when working on a solution. I initially wanted to log the behaviour of the unit, which caused me to create a data broadcast component. Then I wanted to investigate the data that it was sending, which caused me to add Telnet support. Then as I was building out the HomeKit integration, I found that it didn't present all the information I wanted to see, so I built out a web interface. The core functionality for the RS-485 interface was built out by a team of people on [Home Assist](https://community.home-assistant.io/t/navien-esp32-navilink-interface/720567/170), with the foundation of the Navien C++ class by [htumanyan](https://github.com/htumanyan/navien)\n### HomeKit Integration and Eve App\n\nThe HomeKit integration is described in the [Description](#description) section above, but there are a few additional points worth noting:\n\n- You may see the setpoint fluctuate on the temperature graph. This is intentional and indicates when the unit is actively heating to the setpoint versus when it is idle. The lower setpoint represents the minimum temperature that the hot water unit can be set to.\n- The **Valve** graph shows the current operating load. When the valve is open, the unit is actively heating, and the graph reflects its current operating capacity.\n- The **Valve** metric is not shown by default in the Eve app. To enable it, edit the Thermostat page and manually add it as a visible characteristic.  \n  \u003cimg width=\"500\" alt=\"Eve thermostat screen\" src=\"https://github.com/user-attachments/assets/bdcb70b5-9ed8-47b2-a24c-a1740a0730ab\" /\u003e\n\n   \n### Web Server (via [HomeSpan](https://github.com/HomeSpan/HomeSpan))\n\nThe current status of the Navien unit can be viewed at any time by visiting its web page. The webpage is hosted at the IP address of the ESP32, e.g., `http://\u003cip-address\u003e/status`.\n\nAt the top of the status page is a green toggle button. Tapping it switches the units displayed on the screen between metric and imperial.\n\nThere are two schedulers shown:\n1. The built-in Navien scheduler, which does **not** support \"Hot Water Now\" functionality.\n2. A custom scheduler provided by this project, which **does** support \"Hot Water Now\" requests even while a schedule is running.\n\nIf both schedulers are active, the Navien scheduler takes precedence. In the image below, shows the system running in Monitor mode. Attempts to change the state of the hotwater unit are correctly failing.\n\n\u003cimg width=\"1488\" alt=\"Navien Status screen\" src=\"https://github.com/user-attachments/assets/fa161464-81c6-4bcd-b79f-f4b13bdf4a2d\" /\u003e\n\n\n### Telnet\n\nBecause the hot water unit is not in a convenient location for active development, I added Telnet capabilities to the ESP32. This allows a user to investigate and control the hot water unit remotely, as well as monitor its activity in real time. The Telnet functionality is broken into several categories:\n\n**General operation commands:**\n- `bye` — Disconnect\n- `wifi` — Print WiFi status\n- `fsStat` — Show file system status\n- `reboot` — Reboot the ESP32\n- `ping` — Test if Telnet commands are working\n\n**History and program state:**\n- `eraseHistory` — Erase all history entries\n- `erasePgm` — Erase all program state\n- `history` — Print history entries in CSV format (optional: specify number of entries)\n\n**Navien hot water monitoring:**\n- `gas` — Print current gas state as JSON\n- `water` — Print current water state as JSON\n- `trace` — Dump interactions (options: `gas`, `water`, `command`, `announce`)\n- `stop` — Stop tracing\n\n**Navien control commands:**\n- `control` — Check if control commands are available\n- `hotButton` — Send Hot Button command\n- `power` — Set or get power state (`on`/`off`)\n- `recirc` — Set or get recirculation state (`on`/`off`)\n- `setTemp` — Set or get temperature setpoint\n\n**Time operations:**\n- `time` — Print local and GMT time\n- `timezone` — Set or get the current timezone\n  \n### Data broadcast (UDP)\nTo continuously monitor and log the status of the Navien unit, the software broadcasts its status over the local network (not the internet) using UDP on port `2025`. Duplicate data is throttled to one broadcast every 5 seconds—if the same packet is observed again within that time, it is dropped. However, if the packet changes in any way, it will be broadcast immediately.  \nThis broadcasted data can be collected on another machine and used for logging. In the `Logging` folder, there is an example script that collects the broadcast data and logs it to InfluxDB. A Grafana template is also provided, which can be used in conjunction with InfluxDB to visualize the collected data.  \n\u003cimg width=\"1496\" alt=\"Grafana status\" src=\"https://github.com/user-attachments/assets/4846a6d5-f917-4f56-9773-adb856c933ff\" /\u003e\n\n\n## Setup\n### Hardware\n\nThis project requires an **ESP32** and an **RS-485 to serial interface**. Below are the components I personally used, along with why I chose them.\n\nI chose the **ESP32 D1 Mini** because I’ve used WeMos mini boards before, have a number of [shields](https://www.wemos.cc/en/latest/d1_mini_shield/index.html) for them, and find them easy to develop for using the Arduino SDK.\n\nFor the RS-485 interface, I found a **WeMos-compatible RS-485 shield** that works perfectly with the D1 Mini. It not only provides the required RS-485 connection, but also includes a **DC-DC converter** that can draw power from the Navien system.  \n*(Note: I’m not yet using this feature, as my Navien unit **does not** provide power on the NaviLink cable.)*\n\nTo tap into the communication line, I used a **breakout box**. My Navien unit already had a NaviLink module installed, so I wanted to begin by passively monitoring the traffic between the NaviLink and the Navien unit. Placing the breakout box inline allowed me to do just that.\nThe middle two lines on the breakout box are the two lines I connected to the RS-485 sheild. In the photo below, the Blue wire is attached to the B- terminal of the RS-485 shield, and the Purple wire is attached to the A+ terminal.\n\n\u003cimg width=\"500\" alt=\"RJ45 breakout box\" src=\"https://github.com/user-attachments/assets/d5f5c30d-4ed4-4dfe-a96a-0cd06035718e\" /\u003e\n\n#### 🧩 Parts List\n\n| Component | Description | Link |\n|----------|-------------|------|\n| **ESP32 D1 Mini** | Compact ESP32 Dev Board | [AliExpress](https://www.aliexpress.us/item/3256806227686284.html) |\n| **RS-485 CANBUS DCDC Shield** | RS-485 \u0026 Power Shield for D1 Mini | [Taaralabs](https://taaralabs.eu/rs485-canbus-dcdc-wemos-mini/) |\n| **RJ45 Ethernet Breakout Box** | RJ45 Tap for intercepting NaviLink connection | [Amazon](https://www.amazon.com/dp/B0CJM8BVWL) |\n\n---\n\n### Software\nThe code is broken up logically by functionality.\n1. NavienManager - Main startup file.\n2. Navien - Handles communication to the Navien Hot Water unit\n3. HomeSpanWeb - Contains all the web functions for HomeSpan to present a pretty web page\n4. DEV_Navien - HomeKit Themostat Service implementation\n5. FakeGatoScheduler - Handles the Eve specific Program Data, built on top of SchedulerBase, used in conjection with DEV_Navien\n6. SchedulerBase - generic baseclass to implement a day-of-week scheduler. \n7. FakeGatoHistoryService - HomeKit FakeGatoHistory Service implementation\n8. NavienBroadcaster - Receives callbacks from Navien of state changes and broadcasts over UDP\n9. TelnetCommands - Implements all the telnet commands.\n10. Logging - Folder contains the scripts listen for Navien broadcasts and write them to InfluxDB as well as Grafana templates\n\n\n## License\nThis library is licensed under [MIT License](https://opensource.org/license/mit/)\n\n## Acknowledgements\nCommunity members of [Home Assist](https://community.home-assistant.io/t/navien-esp32-navilink-interface/720567/170), who decoded the protocol and much of the packet data for the Navien NaviLink connection  \n[htumanya](https://github.com/htumanyan/navien) for the well-crafted base class for Navien  \n[simont77](https://github.com/simont77/fakegato-history) for decoding the Eve History logging interface   \n[HomeSpan](https://github.com/HomeSpan/HomeSpan) for the HomeKit accessory library for ESP32 devices\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdacarson%2Fnavienmanager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdacarson%2Fnavienmanager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdacarson%2Fnavienmanager/lists"}