Navien.h

/*
Copyright (c) 2024 Hovhannes Tumanyan (htumanyan)
Copyright (c) 2025 David Carson (dacarson)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
*/

#include <cstddef>
#include <cstdint>
#include <array>
#include <HardwareSerial.h>

#ifndef Navien_h
#define Navien_h

/* Navien RS424 / NaviLink interface
** Usage:
* The class inherits from HardwareSerial, so it needs to be constructed with
* a Serial port number, and when it is told to begin(), Serial IO pin numbers
* need to be provided.
*     Navien navienSerial(2);  // Serial Port 2
*
*     #define RXD2 16 // Second serial port on WeMos D1 Mini ESP32 board
*     #define TXD2 17 
*     navienSerial.begin(RXD2, TXD2);
*
* To be notified of observed data, you need to register for the respective
* callback. Note that only the structure for the current callback should be
* considered valid. With Gas Packer callback, only state.gas structure 
* should be examined. 
* Callback functions must be defined as:
*   void onStatePacket(Navien::NAVIEN_STATE *state) {}
* For example:
*     navienSerial.onGasPacket(onGasPacket);
*     navienSerial.onWaterPacket(onWaterPacket);
*     navienSerial.onCommandPacket(onCommandPacket);
*     navienSerial.onAnnouncePacket(onAnnouncePacket);
* For errors, the callback function is defined as:
*   void onError(const char *function, const char *errorMessage) {}
* To register call:
*     navienSerial.onError(onError);
*
* Then in the loop, make sure to call the loop function of navien so that
* it can process any packets.
*     void loop() {
*       navienSerial.loop();
*     }
*
** Basic class operation:
* Observer operation.
* In the loop() function, the class builds up a recieve packet, PACKET_BUFFER
* until it is either a full packet (defined by the packet length in the header)
* or it is too large for the buffer. 
* Once a full packet is recieved, it determines the type of packet, and then
* parses it into the correct NAVIEN_STATE object.
* If a Callback is defined for the packet type, it is called with the 
* recieved packet. The raw packet is also available while in the callback
* function.
*
* Publisher operation.
* Sending commands is only available if a NaviLink device is not detected. If
* one is detected, commands are not sent as it may confuse the state of the 
* hot water unit and the NaviLink unit.
* Calling any of the control functions, the hot water unit state will be 
* adjusted.
*/

class Navien : public HardwareSerial {
public:
  typedef struct {
    /**
   * Unknown value, but could be the protocol version (very likely)
   */
    uint8_t packet_marker;

    /**
   * Unknown value, but could be the protocol version (very likely)
   */
    uint8_t unknown_0x05;

    /**
   * Direction of the packet. Not unlikely to be "recipient address" essentially.
   * Needs to be captured in multi-unit installation to see if it is simply a direction or a version.
   *
   * Navien to control device - 0x50, PACKET_DIRECTION_STATUS
   * Control Device to Navien - 0x0F, PACKET_DIRECTION_CONTROL
   */
    uint8_t direction;

    /**
   * There are two known packet types with somewhat overlapping
   * data but also with unique data points in each
   * [0x50 - 0x57] - water flow and temperature data from unit [0-7] - PACKET_TYPE_WATER_MIN/PACKET_TYPE_WATER_MAX
   * 0x0F - gas flow and also water temperature - PACKET_TYPE_GAS
   */
    uint8_t packet_type;

    /**
   * Unknown value. Observed to be 0x90 for navien-device direction
   * and 0x10 in device-to-navien (control packets).
   */
    uint8_t unknown_0x90;

    /**
   * Length of the packet including the header and checksum, i.e. total number of bytes
   * in the packet, including everything
   */
    uint8_t len;
  } HEADER;

  static const uint8_t HDR_SIZE = sizeof(HEADER);
  static const uint8_t PACKET_MARKER = 0xF7;
  // Default send command header
  static const uint8_t COMMAND_HEADER[];
  // Periodic NaviLink announce (control → heater) when no NaviLink detected on bus
  static const uint8_t ANNOUNCE_PACKET[];

enum PacketDirection {
  PACKET_DIRECTION_CONTROL = 0x0F,
  PACKET_DIRECTION_STATUS = 0x50
};

enum PacketType {
  PACKET_TYPE_WATER_MIN = 0x50,
  PACKET_TYPE_WATER_MAX = 0x57,
  PACKET_TYPE_GAS = 0x0F
};

enum StatusCmdType {
  CMD_TYPE_WATER = 0x42,
  CMD_TYPE_GAS = 0x45,
  CMD_TYPE_CMD = 0x4F,
  CMD_TYPE_ANNOUNCE = 0x4A
};

enum ControlPacketType {
  CONTROL_ANNOUNCE = 0x4A,
  CONTROL_COMMAND = 0x4F
};

enum CommandActionSystemPower {
  SYSTEM_POWER_ON = 0x0A,
  SYSTEM_POWER_OFF = 0x0B
};

enum CommandActionHotButton {
  HOT_BUTTON_DOWN = 0x1,
  RECIRCULATION_ON = 0x8,
  RECIRCULATION_OFF = 0x10
};

  static const uint16_t CHECKSUM_SEED_4B = 0x4b;
  static const uint16_t CHECKSUM_SEED_62 = 0x62;

  // RS485 collision avoidance timing constants
  // At 19200 baud, 8N1 format: 10 bits/byte = 0.52ms per byte
  // Typical packets: Water ~48 bytes (~25ms), Gas ~55 bytes (~29ms), Command ~20 bytes (~10ms)
  // We wait for silence to ensure we're between packets, not mid-transmission
  static constexpr unsigned long BUS_SILENCE_MS = 50;  // Wait 50ms after last byte received
  static constexpr unsigned long PACKET_GAP_MS = 30;   // Wait 30ms after last complete packet


  typedef struct {
    uint8_t cmd_type;  // Always 0x42 Water
    uint8_t unknown_07; // 0x00
    uint8_t flow_state;  // 8 0x20 if Consumption is Active 0x08 if recirculating_running
    uint8_t system_power;  // 9
    uint8_t system_stage;  // 10 system operating stage
    uint8_t set_temp;      // 11
    uint8_t outlet_temp;   // 12
    uint8_t inlet_temp;    // 13
    uint8_t unknown_14; // 0x00
    uint8_t unknown_15; // 0x00
    uint8_t unknown_16; // 0x00
    uint8_t operating_capacity;  // 17
    uint8_t water_flow;          // 18
    uint8_t unknown_19; // 0x00
    uint8_t unknown_20; // 0xA0
    uint8_t unknown_21; // 0xBE
    uint8_t unknown_22; // 0x00
    uint8_t unknown_23; // 0x20
    uint8_t system_status;  // 24
    uint8_t unknown_25; // 0x00
    uint8_t unknown_26; // 0x00
    uint8_t system_active;  // 27 0x00 = no, 0x01 = yes
    uint8_t operation_time_lo;  // 28 operation time in hours (lo byte)
    uint8_t operation_time_hi;  // 29 operation time in hours (hi byte)
    uint8_t unknown_30; // 0x00
    uint8_t unknown_31; // 0x01
    uint8_t unknown_32; // 0x00
    uint8_t recirculation_enabled;  // 33
    uint8_t unknown_34; // 0x00
    uint8_t unknown_35; // 0x00
    uint8_t unknown_36; // 0x00
    uint8_t unknown_37; // 0x00
    uint8_t unknown_38; // 0x00
    uint8_t unknown_39; // 0x00
  } WATER_DATA;

  typedef struct {
    uint8_t cmd_type; // Always 0x45 Gas
    uint8_t unknown_07; // 0x00
    uint8_t unknown_08; // 0x0B
    uint8_t unknown_09; // 0x01
    uint8_t controller_version_lo;  // 10
    uint8_t controller_version_hi;  // 11
    uint8_t panel_version_lo;  // 12
    uint8_t panel_version_hi;  // 13
    uint8_t set_temp;     // 14
    uint8_t outlet_temp;  // 15
    uint8_t inlet_temp;   // 16
    uint8_t unknown_17; // 0x00
    uint8_t unknown_18; // 0x00
    uint8_t target_burner_power_lo;  // 19 target burner power in kcal (lo byte)
    uint8_t target_burner_power_hi;  // 20 target burner power in kcal (hi byte)
    uint8_t unknown_21; // 0x01
    uint8_t current_gas_lo;     // 22 current burner power in kcal (lo byte)
    uint8_t current_gas_hi;     // 23 current burner power in kcal (hi byte)
    uint8_t cumulative_gas_lo;  // 24 total gas usage in m3 x0.1 (byte 0)
    uint8_t cumulative_gas_hi;  // 25 total gas usage in m3 x0.1 (byte 1)
    uint8_t cumulative_gas_b2;  // 26 total gas usage in m3 x0.1 (byte 2)
    uint8_t cumulative_gas_b3;  // 27 total gas usage in m3 x0.1 (byte 3)
    uint8_t elapsed_install_days_lo;  // 28 elapsed time since install in days (lo byte)
    uint8_t elapsed_install_days_hi;  // 29 elapsed time since install in days (hi byte)
    uint8_t cumulative_domestic_usage_cnt_lo; // 30 Domestic Usage Counter in 10 usage increments
    uint8_t cumulative_domestic_usage_cnt_hi; // 31
    uint8_t cumulative_water_usage_lo;  // 32 total water usage in L x0.1 (byte 0)
    uint8_t cumulative_water_usage_hi;  // 33 total water usage in L x0.1 (byte 1)
    uint8_t cumulative_water_usage_b2;  // 34 total water usage in L x0.1 (byte 2)
    uint8_t cumulative_water_usage_b3;  // 35 total water usage in L x0.1 (byte 3)
    uint8_t total_operating_time_lo;    // 36 total operation time in hours (byte 0)
    uint8_t total_operating_time_hi;    // 37 total operation time in hours (byte 1)
    uint8_t total_operating_time_b2;    // 38 total operation time in hours (byte 2)
    uint8_t total_operating_time_b3;    // 39 total operation time in hours (byte 3)
    uint8_t unknown_40; // 0x00
    uint8_t unknown_41; // 0x00
    uint8_t unknown_42; // 0xAA
    uint8_t unknown_43; // 0x48
    uint8_t unknown_44; // 0x00
    uint8_t unknown_45; // 0x00
    uint8_t recirculation_enabled;  // 46 0x00 = no, 0x01 = yes
    uint8_t unknown_47; // 0x00
    // length is 42, ie 0 - 41
  } GAS_DATA;

  typedef struct {
    uint8_t cmd_type; // Always 4F Command
    uint8_t unknown_07;    // 00
    uint8_t system_power;  // 08 0a == On, 0b == Off
    uint8_t set_temp;         // 09 5E == 117F
    uint8_t unknown_10;       // 0x00
    uint8_t hot_button_recirculation;  // 11 CommandActionHotButton
    uint8_t cmd_data;         // 12 Seems to vary
    uint8_t unknown_13;       // 0x00
    uint8_t unknown_14;       // 0x00
    uint8_t unknown_15;       // 0x00
    uint8_t unknown_16;       // 0x00
    uint8_t unknown_17;       // 0x00
    // cmd_type (4F) length is
  } CMD_DATA;

  typedef struct {
    uint8_t cmd_type; // Always 4A Announce
    uint8_t unknown_07;  // 0x00
    uint8_t unknown_08;  // 0x01
    // cmd_type (4A) length is 9, ie 0 - 8
  } ANNOUNCE_DATA;

  typedef union {
    struct {
      HEADER hdr;
      union {
        GAS_DATA gas;
        WATER_DATA water;
        CMD_DATA cmd;
        ANNOUNCE_DATA announce;
      };
    };
    uint8_t raw_data[128];
  } PACKET_BUFFER;

  static const uint8_t commandHeader[];

  // When units are connected in a cascade, I have seen additional
  // water packets, one for each unit. There can be up to 8 units
  // connected together.
  #define MAX_DEVICES 8

  // Parsed known values from the respective packets
  // Structure is updated before calling the callback functions.
  typedef struct {
    bool system_power;
    float set_temp; // degree C
    float outlet_temp; // degree C
    float inlet_temp; // degree C
    float flow_lpm; // Water flow velocity, via Recirculation or Tap being on
    bool recirculation_active; // Recirculation mode is current ON
    bool recirculation_running; // Recirculation pump is currently running
    bool display_metric; // True == degree C; False == degree F
    bool internal_recirculation; // Unit configured for internal recirculation
    bool external_recirculation; // Unit configured for external recirculation
    float operating_capacity; // Percentage 0.0 - 100.0 %
    bool consumption_active; // Tap is turned on
    uint8_t flow_state;
    uint8_t system_stage;  // Raw system operating stage value

    // system_stage high-level groups (upper nibble)
    bool stage_idle;          // 0x1x
    bool stage_starting;      // 0x2x
    bool stage_active;        // 0x3x
    bool stage_shutting_down; // 0x4x

    // system_stage specific sub-states
    bool stage_standby;           // 0x14
    bool stage_demand;            // 0x20
    bool stage_pre_purge;         // 0x29
    bool stage_ignition;          // 0x2B
    bool stage_flame_on;          // 0x2C
    bool stage_ramp_up;           // 0x2D
    bool stage_active_combustion; // 0x33
    bool stage_water_adjustment;  // 0x34
    bool stage_flame_off;         // 0x3C
    bool stage_post_purge_1;      // 0x46 post-purge 1/2 (15s)
    bool stage_post_purge_2;      // 0x47 post-purge 2/2 (15s)
    bool stage_dhw_wait;          // 0x49 dhw-wait (150s)

    bool system_active;       // System is actively running
    uint16_t operation_time;  // hours
    uint8_t device_number;
  } NAVIEN_STATE_WATER;

  typedef struct {
    float set_temp;  // degree C
    float outlet_temp; // degree C
    float inlet_temp; // degree C
    float controller_version;
    float panel_version;
    float accumulated_gas_usage;    // m^3 (ccf = m^3 / 2.832, Therms = m^3 / 2.832 * 1.02845 )
    float accumulated_water_usage;  // L (gal = L / 3.78541)
    uint16_t current_gas_usage;     // kcal (btu == kcal * 3.965667)
    uint16_t target_gas_usage;      // kcal (btu == kcal * 3.965667)
    uint32_t total_operating_time;  // minutes
    uint16_t elapsed_install_days;  // days since install
    uint32_t accumulated_domestic_usage_cnt;  // Counter for domestic usage, increments every 10 usages
    bool recirculation_enabled;     // recirculation is configured/enabled
  } NAVIEN_STATE_GAS;

  typedef struct {
    bool power_command; // Observe the power on command
    bool power_on; // Power On command, True == turn On; False == turn OFF

    bool set_temp_command; // Observe the Set Temperature command
    float set_temp; // Set the Set Temperature to this value in deg. C

    bool hot_button_command; // Send Hot Button command

    bool recirculation_command; // Observe the recirculation command
    bool recirculation_on; // Recirculation command, True == turn On; False == turn OFF

    uint8_t cmd_data;
  } NAVIEN_STATE_COMMAND;

  typedef struct {
    bool navilink_present; // Navilink unit is present controlling the Navien
  } NAVIEN_STATE_ANNOUNCE;

  typedef struct {

    NAVIEN_STATE_WATER water[MAX_DEVICES];
    uint8_t max_water_devices_seen = 0;  // Count of unique water device IDs seen

    NAVIEN_STATE_GAS gas;
    NAVIEN_STATE_COMMAND command;
    NAVIEN_STATE_ANNOUNCE announce;

  } NAVIEN_STATE;

  typedef enum {
    INITIAL,
    MARKER_FOUND,
    HEADER_PARSED
  } READ_STATE;

  // Navien 240A has temperature range for domestic hot water (DHW) of 37degC to 60degC
  static constexpr float TEMPERATURE_MIN = 37.0f;
  static constexpr float TEMPERATURE_MAX = 60.0f;

  typedef void (*NavienWaterCallback)(NAVIEN_STATE_WATER *water);
  typedef void (*NavienGasCallback)(NAVIEN_STATE_GAS *gas);
  typedef void (*PacketCallbackFunction)(NAVIEN_STATE *state);
  typedef void (*ErrorCallbackFunction)(const char* functionName, const char* error);

public:
  Navien(uint8_t uart_nr)
    : HardwareSerial(uart_nr), navilink_present(false), test_mode(true), recv_state(INITIAL) {}
  
  /* Navien is 19200 baud, 8 bit, no parity, 1 stop bit */
  void begin(int8_t rxPin, int8_t txPin) { HardwareSerial::begin(19200, SERIAL_8N1, rxPin, txPin); }

  // Call this in the loop function
  void loop();

  // Set the callback functions, called when packet is processed
  void onGasPacket(NavienGasCallback f) {
    on_gas_packet_cb = f;
  }
  void onWaterPacket(NavienWaterCallback f) {
    on_water_packet_cb = f;
  }
  void onCommandPacket(PacketCallbackFunction f) {
    on_command_packet_cb = f;
  }

  void onAnnouncePacket(PacketCallbackFunction f) {
    on_announce_packet_cb = f;
  }

  // Set the error callback function
  void onError(ErrorCallbackFunction f) {
    on_error_cb = f;
  }

  // Get the current state
  const NAVIEN_STATE *currentState() {
    return &state;
  }

  // Only valid while inside a packet callback function
  const PACKET_BUFFER *rawPacketData() {
    return &recv_buffer;
  }

// Control functions
// These are only available if there is no NaviLink control unit attached

  // Control available: no remote NaviLink, and (test mode or we've sent at least one announce on the bus)
  bool controlAvailable() {
    return !navilink_present && (test_mode || last_periodic_announce_time != 0);
  }

  // Turn on or off the unit
  // Return number of bytes sent, -1 on failure
  int power(bool on);

  // Change the set point. Value specified in degC, 
  // rounded to nearest 0.5 degree
  // Return number of bytes sent, -1 on failure
  int setTemp(float temp_degC);

  // Press the hot button
  // Return number of bytes sent, -1 on failure
  int hotButton();

  // Turn on or off Recirculation
  // Return number of bytes sent, -1 on failure
  int recirculation(bool on);


protected:
  // Debug helper to print hex buffers
  static void print_buffer(const uint8_t *data, size_t length, ErrorCallbackFunction on_error_cb);

  // Can I send a command now - avoid collisions on RS485 line
  bool can_send(int curr_available);
  void maybe_send_periodic_announce();
  /** Enqueue without policy checks (periodic announce, TX retries). */
  int enqueue_send_cmd(const PACKET_BUFFER& pkt);
  /** User-facing queue: defers CONTROL_COMMAND until we've transmitted an announce. */
  int queue_send_cmd(const PACKET_BUFFER& pkt);

  // Generate the cmd_data field for the command packet
  uint8_t generateCmdData();

  // Write the send_buffer command
  // Returns number of bytes sent, or -1 for failure
  int send_cmd();

  static float t2c(uint8_t);         // Temperature to degC
  static float flow2lpm(uint8_t f);  // Flow to LPM

  /**
   * 
   */
  static uint8_t checksum(const uint8_t *buffer, uint8_t len, uint16_t seed);

  // Callback functions that will be called when packets are received
  NavienGasCallback on_gas_packet_cb = NULL;
  NavienWaterCallback on_water_packet_cb = NULL;
  PacketCallbackFunction on_command_packet_cb = NULL;
  PacketCallbackFunction on_announce_packet_cb = NULL;

  // General error callback function to call if an error is encountered.
  ErrorCallbackFunction on_error_cb = NULL;
  

protected:
  bool seek_to_marker();


  /**
   * Data extraction routines.
   * Copy the raw data from PACKET_BUFFER to internal representation
   * in this->state where it is stored and reported upon "update" calls.
   */

  // Common entry point that is always called upon receipt of a valid packet
  // calls parse_water/gas depending on the paket type
  void parse_packet();

  // Called when we observe a control packet.
  // from_local_send: true when we generated/transmitted this packet locally.
  void parse_control_packet(bool from_local_send = false);

  // Called when we receive a status packet from Navien device
  void parse_status_packet();

  // Called when the direction is from Navien to reporting device
  // and type field is PACKET_TYPE_WATER
  void parse_water();

  // Called when the direction is from Navien to reporting device
  // and the type field is PACKET_TYPE_GAS
  void parse_gas();

  // Called when the direction reporting device to Navien
  // and the cmd_type field is CONTROL_ANNOUNCE.
  // from_local_send: true after we transmit an announce (do not treat as remote NaviLink).
  void parse_announce(bool from_local_send = false);

  // Called when the direction reporting device to Navien
  // and the cmd_type field is CONTROL_COMMAND.
  // from_local_send: true after we transmit a command.
  void parse_command(bool from_local_send = false);

protected:
  // Keeps track of the state machine and iterates through
  // initialized -> marker found -> header parsed -> data parsed -> initialized
  READ_STATE recv_state;

  // Data received off the wire
  PACKET_BUFFER recv_buffer;


  // Use an array to build a list of commands to be sent
  // They will be sent when the wire is clear
  static constexpr size_t QUEUE_CAPACITY = 5;
  std::array<PACKET_BUFFER, QUEUE_CAPACITY> send_array;
  size_t send_queue_head = 0;
  size_t send_queue_tail = 0;
  size_t send_queue_count = 0;

  // Data, extracted from gas and water packers and stored
  NAVIEN_STATE state;

  // Control available
  bool navilink_present;
  // If we see 10 water packets and no announce packet
  // reset navilink to not being present
  int water_packets_since_announce;

  // Track timing for collision avoidance
  unsigned long last_packet_complete_time = 0;

  // Track recently transmitted control packet to suppress local RS485 echo.
  PACKET_BUFFER last_sent_control_packet{};
  size_t last_sent_control_packet_len = 0;
  unsigned long last_sent_control_packet_time = 0;
  /** Match last TX bytes; window must cover slow loop() + RS485 turnaround. */
  static constexpr unsigned long LOCAL_ECHO_FILTER_WINDOW_MS = 900;
  /** Our periodic announce is fixed; suppress late echo even if we TX'd another cmd since. */
  static constexpr unsigned long OWN_ANNOUNCE_ECHO_SUPPRESS_MS = 5000;
  /** Same raw announce can reach parse_announce twice (local TX path + RS485 echo). */
  static constexpr unsigned long ANNOUNCE_CALLBACK_DEDUPE_MS = 500;
  uint8_t last_announced_raw[16]{};
  uint8_t last_announced_raw_len = 0;
  unsigned long last_announce_callback_ms = 0;

  // Rate limiting for commands - minimum 2 seconds between any commands
  unsigned long last_command_sent_time = 0;
  static constexpr unsigned long MIN_COMMAND_INTERVAL_MS = 2000;

  unsigned long last_periodic_announce_time = 0;
  static constexpr unsigned long PERIODIC_ANNOUNCE_INTERVAL_MS = 5000;
  /** True while a periodic announce is queued or being retried by send_cmd(). */
  bool periodic_announce_pending = false;

  // Assume running in test mode *until* we see a packet
  bool test_mode;
};

#endif  // Navien_h