Add ESPHome 2026.1 support and agent instructions

Author: Hovhannes Tumanyan

.github/copilot-instructions.md

@@ -0,0 +1,13 @@
+# Copilot Instructions (Navien ESPHome / RS-485)
+
+Follow the repository playbook in `AGENTS.md` (source of truth).
+
+Key rules:
+- Spaces only (2 spaces). No tabs.
+- Avoid STL and dynamic allocation: no `std::*`, no `malloc/free`, no `new/delete`. Prefer static/stack C-style buffers/structs.
+- Protocol changes require updates in `doc/` + at least one example frame and expected decoded output.
+- Do not provide speculative/unsafe hardware wiring advice; avoid unknown/high-voltage pins.
+
+How to validate changes:
+- Build/compile with ESPHome per README.
+- For protocol/entity changes: provide DEBUG logs and a trace sample if available.

.vscode/launch.json

@@ -0,0 +1,7 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": []
+}

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "chat.tools.terminal.autoApprove": {
+        "esphome": true
+    }
+}

AGENTS.md

@@ -0,0 +1,117 @@
+# AGENTS.md — Navien ESPHome Integration
+
+## What this repository is
+This repository provides:
+- An ESPHome external component for local control and telemetry of Navien water heaters via RS-485
+- Reverse-engineered protocol documentation, traces, and message decoding notes
+- Optional hardware reference materials for DIY controller builds
+
+Primary goal: reliable, local Home Assistant integration without proprietary cloud dependencies.
+
+The root README is the source of truth for end-user setup and supported configurations.
+
+## Scope & boundaries
+- Prefer **backwards-compatible** changes; avoid breaking existing YAML keys, entity names, or IDs.
+- Protocol changes must be documented under `doc/` with examples.
+- Do **not** add cloud-based features or proprietary APIs.
+- **Safety first**: never recommend wiring to unknown or high-voltage pins; explicitly warn when a pin is known to be ~14V or otherwise unsafe.
+
+## Repository layout
+- `esphome/` — ESPHome external component and example YAMLs
+- `doc/` — protocol reverse-engineering notes and field documentation
+- `trace/rs485/` — RS-485 captures used for validation
+- `hardware/` — PCB, connector, and harness reference designs
+- `src/` — implementation details (protocol parsing, entities)
+
+## Supported workflows
+
+### Build / compile
+Follow the workflow in the root README:
+- Install ESPHome (`pip install esphome`)
+- Copy secrets (`cp secrets.yaml.sample secrets.yaml`)
+- Compile: `esphome compile <config>.yml`
+- Flash/run: `esphome run <config>.yml`
+
+ESPHome versions can introduce breaking changes; follow README version guidance.
+
+### Runtime validation
+When modifying protocol parsing or entity behavior:
+- Enable DEBUG logging and capture at least one full request/response cycle
+- Verify:
+  - Stable RS-485 connection
+  - Sensors update correctly
+  - Controls (power, hot button, target temp) still work on known-good models
+
+### Protocol decode changes (required checklist)
+If protocol parsing changes:
+1. Update documentation in `doc/` (byte offsets, scaling, meaning)
+2. Include at least one example frame (raw bytes + decoded values)
+3. Document model-specific behavior (e.g., NPE vs NCB)
+4. Preserve unknown bytes or log them; do not silently drop data
+
+## C++ conventions & formatting
+
+### Indentation / whitespace (required)
+- **Spaces only. No tabs.**
+- Use **2 spaces** for indentation.
+- Strip trailing whitespace.
+- End all files with a newline.
+
+### Style
+- Favor readability over cleverness.
+- Keep functions short and single-purpose.
+- Use `const` where applicable; pass large objects by `const&`.
+- Prefer `enum class` for new enums.
+- Avoid macros unless required by ESPHome.
+
+### Memory & dependencies (embedded best practices)
+- **Avoid the C++ standard library** (`std::vector`, `std::map`, `std::string`, streams, etc.).
+- **Do not use dynamic allocation**:
+  - No `malloc` / `free`
+  - No `new` / `delete`
+- Prefer **statically allocated or stack-allocated C data structures**:
+  - Fixed-size arrays and ring buffers
+  - POD `struct`s with explicit sizes
+  - Preallocated buffers with strict bounds checks
+- If dynamic allocation is absolutely unavoidable:
+  - Justify it clearly in the PR
+  - Ensure it never occurs in `loop()` or hot paths
+  - Document ownership and lifetime explicitly
+
+### Safety & performance
+- Never block in hot paths (`loop()`, callbacks).
+- Avoid long delays or busy waits.
+- Minimize allocations and heavy string operations.
+- Treat all inbound RS-485 data as untrusted:
+  - Validate lengths before indexing
+  - Verify checksums/CRCs if available
+
+### Logging
+- Use ESPHome logging macros (`ESP_LOGD`, `ESP_LOGI`, `ESP_LOGW`).
+- Log unknown or unsupported frames at DEBUG with:
+  - Message/opcode (if known)
+  - Raw bytes (trimmed if large)
+- Avoid log spam in steady state; throttle repeated warnings.
+
+### Protocol parsing conventions
+- Centralize parsing logic; do not duplicate byte-offset logic.
+- Keep conversion math close to decode logic and comment units.
+- Isolate model-specific branching and document it.
+
+## Adding a new exposed metric (recommended flow)
+1. Identify the field in traces (`trace/rs485/`)
+2. Document it in `doc/` (offsets, scaling, examples)
+3. Implement decode + conversion
+4. Expose via ESPHome entity
+5. Update README or example YAML if user-visible
+
+## Communication & contributions
+- When handling issues/PRs:
+  - Ask for model info and PCB/front-panel photos when relevant
+  - Request RS-485 traces and ESPHome logs
+  - Avoid speculative electrical advice; call out unverified assumptions
+
+## What not to do
+- Do not recommend bypassing safety systems or modifying heater internals.
+- Do not introduce breaking renames without strong justification and migration notes.
+- Do not add “magic” auto-detection that can misconfigure pins or voltage assumptions.

esphome/components/navien/navien.cpp

@@ -4,60 +4,82 @@
 #include "esphome.h"
 #include "esphome/core/log.h"
 #include "navien.h"
-#include "navien_link_esp.h"
 
 namespace esphome {
 namespace navien {
 
   static const char *TAG = "navien.sensor";
 
-  // NavienBase implementation
-  void NavienBase::set_link(NavienLinkEsp *link, uint8_t src) {
-    this->link_ = link;
-    this->src_ = src;
-    if (link != nullptr) {
-      link->add_visitor(this, src);
-    }
+namespace {
+class NavienEspUartAdapter : public NavienUartI {
+ public:
+  void set_uart(esphome::uart::UARTComponent *uart) { uart_ = uart; }
+  int available() override { return uart_ ? uart_->available() : 0; }
+  uint8_t peek_byte(uint8_t *byte) override {
+    if (!uart_) return 0;
+    return uart_->peek_byte(byte) ? 1 : 0;
   }
-
-  void NavienBase::send_turn_on_cmd() {
-    if (this->link_ != nullptr) {
-      this->link_->send_turn_on_cmd();
-    }
+  uint8_t read_byte(uint8_t *byte) override {
+    if (!uart_) return 0;
+    return uart_->read_byte(byte) ? 1 : 0;
   }
-
-  void NavienBase::send_turn_off_cmd() {
-    if (this->link_ != nullptr) {
-      this->link_->send_turn_off_cmd();
-    }
+  bool read_array(uint8_t *data, uint8_t len) override {
+    if (!uart_) return false;
+    return uart_->read_array(data, len);
   }
-
-  void NavienBase::send_hot_button_cmd() {
-    if (this->link_ != nullptr) {
-      this->link_->send_hot_button_cmd();
-    }
+  void write_array(const uint8_t *data, uint8_t len) override {
+    if (!uart_) return;
+    uart_->write_array(data, len);
   }
 
-  void NavienBase::send_set_temp_cmd(float temp) {
-    if (this->link_ != nullptr) {
-      this->link_->send_set_temp_cmd(temp);
-    }
-  }
+ private:
+  esphome::uart::UARTComponent *uart_ = nullptr;
+};
 
-  void NavienBase::send_scheduled_recirculation_on_cmd() {
-    if (this->link_ != nullptr) {
-      this->link_->send_scheduled_recirculation_on_cmd();
-    }
-  }
+NavienEspUartAdapter global_uart_adapter;
+}  // namespace
 
-  void NavienBase::send_scheduled_recirculation_off_cmd() {
-    if (this->link_ != nullptr) {
-      this->link_->send_scheduled_recirculation_off_cmd();
-    }
+NavienBase::NavienBase() : navien_link_(nullptr), uart_(nullptr), src_(0), is_rt(false) {}
+
+void NavienBase::setup() {
+  if (!uart_) {
+    ESP_LOGE(TAG, "UART interface not set");
+    return;
   }
+  global_uart_adapter.set_uart(uart_);
+  navien_link_ = NavienLink::get_instance(&global_uart_adapter);
+  if (navien_link_ != nullptr) {
+    navien_link_->add_visitor(this, src_);
+  } else {
+    ESP_LOGE(TAG, "Failed to acquire NavienLink singleton");
+  }
+}
+
+  // NavienBase implementation
+// NavienLinkEsp removed. set_link now uses NavienLink.
+
+void NavienBase::send_turn_on_cmd() {
+  if (navien_link_) navien_link_->send_turn_on_cmd();
+}
+void NavienBase::send_turn_off_cmd() {
+  if (navien_link_) navien_link_->send_turn_off_cmd();
+}
+void NavienBase::send_hot_button_cmd() {
+  if (navien_link_) navien_link_->send_hot_button_cmd();
+}
+void NavienBase::send_set_temp_cmd(float temp) {
+  if (navien_link_) navien_link_->send_set_temp_cmd(temp);
+}
+void NavienBase::send_scheduled_recirculation_on_cmd() {
+  if (navien_link_) navien_link_->send_scheduled_recirculation_on_cmd();
+}
+void NavienBase::send_scheduled_recirculation_off_cmd() {
+  if (navien_link_) navien_link_->send_scheduled_recirculation_off_cmd();
+}
 
   // Navien implementation
   void Navien::setup() {
+    NavienBase::setup();
     this->state.power = POWER_OFF;
   }
 
@@ -324,6 +346,11 @@ namespace navien {
   void Navien::update() {
     ESP_LOGV(TAG, "Conn Status: received: %d, updated: %d", this->received_cnt, this->updated_cnt);
 
+    // Call receive on navien_link_ to process UART data
+    if (navien_link_) {
+      navien_link_->receive();
+    }
+
     // here we track how many packets were received
     // since the last update
     // if Navien is connected and we receive packets, the
@@ -344,7 +371,7 @@ namespace navien {
       this->conn_status_sensor->publish_state(this->is_connected);
 
     if (this->other_navilink_installed_sensor != nullptr)
-      this->other_navilink_installed_sensor->publish_state(this->link_->is_other_navilink_installed());
+      this->other_navilink_installed_sensor->publish_state(this->navien_link_->is_other_navilink_installed());
 
     update_water_sensors();
     update_gas_sensors();

esphome/components/navien/navien.h

@@ -17,10 +17,12 @@
 #include "esphome/components/switch/switch.h"
 //#endif
 #include "esphome/components/uart/uart.h"
+#include "navien_link.h"
+#include "navien_proto.h"
 #include "esphome/components/climate/climate.h"
 #include "esphome/components/text_sensor/text_sensor.h"
 
-#include "navien_link_esp.h"
+// #include "navien_link_esp.h" // No longer needed
 
 #ifndef USE_SWITCH
 namespace switch_ {
@@ -143,23 +145,16 @@ namespace navien {
 
 
   // Forward declaration
-  class NavienLinkEsp;
 
   class NavienBase : public NavienLinkVisitorI {
   public:
-    NavienBase() : link_(nullptr), src_(0), is_rt(false) {}
+    NavienBase();
 
-    /**
-     * Set the link to the NavienLinkEsp singleton instance.
-     * This also registers this instance as a visitor to receive callbacks.
-     * @param link - pointer to the NavienLinkEsp singleton
-     * @param src - source index (0-15) used to identify this visitor
-     */
-    void set_link(NavienLinkEsp *link, uint8_t src = 0);
+    virtual void setup();
+
+    void set_uart(esphome::uart::UARTComponent* uart) { uart_ = uart; }
+    void set_src(uint8_t src) { src_ = src; }
 
-    /**
-     * Send commands to Navien unit (forwarded to link)
-     */
     void send_turn_on_cmd();
     void send_turn_off_cmd();
     void send_hot_button_cmd();
@@ -261,7 +256,8 @@ namespace navien {
     switch_::Switch *allow_recirc_switch = nullptr;
     climate::Climate *climate = nullptr;
 
-    NavienLinkEsp *link_;
+    NavienLink *navien_link_;
+    esphome::uart::UARTComponent* uart_;
     uint8_t src_;
     bool is_rt;
   };
@@ -272,6 +268,7 @@ namespace navien {
       updated_cnt = 0;
       received_cnt = 0;
       is_connected = false;
+      navien_link_ = nullptr;
     }
 
     virtual float get_setup_priority() const { return setup_priority::HARDWARE; }