modbus_controller.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/core/component.h"
 
#include "esphome/components/modbus/modbus.h"
#include "esphome/components/modbus/modbus_helpers.h"
#include "esphome/core/helpers.h"
#include "esphome/core/automation.h"
 
#include <list>
#include <set>
#include <span>
#include <utility>
#include <vector>
 
namespace esphome::modbus_controller {
 
class ModbusController;
 
using modbus::EntityType;
using modbus::ExceptionCode;
using modbus::FunctionCode;
using modbus::helpers::SensorValueType;
 
// Remove before 2027.2.0 - deprecated names re-exported so external components keep their warning window
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
using modbus::ModbusExceptionCode;
using modbus::ModbusFunctionCode;
using modbus::ModbusRegisterType;
#pragma GCC diagnostic pop
 
// Remove before 2026.10.0 — these helpers have moved to modbus::helpers
ESPDEPRECATED("Use modbus::helpers::value_type_is_float() instead. Removed in 2026.10.0", "2026.4.0")
inline bool value_type_is_float(SensorValueType v) { return modbus::helpers::value_type_is_float(v); }
 
ESPDEPRECATED("Use modbus::helpers::modbus_register_read_function() instead. Removed in 2026.10.0", "2026.4.0")
inline FunctionCode modbus_register_read_function(modbus::EntityType reg_type) {
  return modbus::helpers::modbus_register_read_function(reg_type);
}
 
ESPDEPRECATED("Use modbus::helpers::modbus_register_write_function() instead. Removed in 2026.10.0", "2026.4.0")
inline FunctionCode modbus_register_write_function(modbus::EntityType reg_type) {
  return modbus::helpers::modbus_register_write_function(reg_type);
}
 
ESPDEPRECATED("Use modbus::helpers::c_to_hex() instead. Removed in 2026.10.0", "2026.4.0")
inline uint8_t c_to_hex(char c) { return modbus::helpers::c_to_hex(c); }
 
ESPDEPRECATED("Use modbus::helpers::byte_from_hex_str() instead. Removed in 2026.10.0", "2026.4.0")
inline uint8_t byte_from_hex_str(const std::string &value, uint8_t pos) {
  return modbus::helpers::byte_from_hex_str(value, pos);
}
 
ESPDEPRECATED("Use modbus::helpers::word_from_hex_str() instead. Removed in 2026.10.0", "2026.4.0")
inline uint16_t word_from_hex_str(const std::string &value, uint8_t pos) {
  return modbus::helpers::word_from_hex_str(value, pos);
}
 
ESPDEPRECATED("Use modbus::helpers::dword_from_hex_str() instead. Removed in 2026.10.0", "2026.4.0")
inline uint32_t dword_from_hex_str(const std::string &value, uint8_t pos) {
  return modbus::helpers::dword_from_hex_str(value, pos);
}
 
ESPDEPRECATED("Use modbus::helpers::qword_from_hex_str() instead. Removed in 2026.10.0", "2026.4.0")
inline uint64_t qword_from_hex_str(const std::string &value, uint8_t pos) {
  return modbus::helpers::qword_from_hex_str(value, pos);
}
 
template<typename T>
ESPDEPRECATED("Use modbus::helpers::get_data() instead. Removed in 2026.10.0", "2026.4.0")
T get_data(const std::vector<uint8_t> &data, size_t buffer_offset) {
  return modbus::helpers::get_data<T>(data, buffer_offset);
}
 
// Span overloads of the deprecated helpers below: read lambdas receive their payload as a
// std::span<const uint8_t> (previously a const std::vector<uint8_t> &), and a span does not convert to
// a vector, so existing lambdas calling these by name need an overload that accepts one. These carry
// this release's deprecation window, since the span forms only exist from it.
// payload_to_number() deliberately has no such overload: one of its arguments is a modbus::helpers
// type, so a span call already reaches the helper by argument-dependent lookup, and a forwarder here
// would only make that call ambiguous.
// Remove before 2027.2.0.
template<typename T>
ESPDEPRECATED("Use modbus::helpers::get_data() instead. Removed in 2027.2.0", "2026.8.0")
T get_data(std::span<const uint8_t> data, size_t buffer_offset) {
  return modbus::helpers::get_data<T>(data.data(), buffer_offset);
}
 
// Remove before 2027.2.0 (window restarted when the migration target changed to bit_from_packed())
ESPDEPRECATED("Use modbus::helpers::bit_from_packed() instead. Removed in 2027.2.0", "2026.4.0")
inline bool coil_from_vector(int coil, const std::vector<uint8_t> &data) {
  return modbus::helpers::bit_from_packed(coil, data);
}
 
// Remove before 2027.2.0
ESPDEPRECATED("Use modbus::helpers::bit_from_packed() instead. Removed in 2027.2.0", "2026.8.0")
inline bool coil_from_vector(int coil, std::span<const uint8_t> data) {
  return modbus::helpers::bit_from_packed(coil, data);
}
 
template<typename N>
ESPDEPRECATED("Use modbus::helpers::mask_and_shift_by_rightbit() instead. Removed in 2026.10.0", "2026.4.0")
N mask_and_shift_by_rightbit(N data, uint32_t mask) {
  return modbus::helpers::mask_and_shift_by_rightbit(data, mask);
}
 
ESPDEPRECATED("Use modbus::helpers::number_to_payload() instead. Removed in 2026.10.0", "2026.4.0")
inline void number_to_payload(std::vector<uint16_t> &data, int64_t value, SensorValueType value_type) {
  modbus::helpers::number_to_payload(data, value, value_type);
}
 
ESPDEPRECATED("Use modbus::helpers::payload_to_number() instead. Removed in 2026.10.0", "2026.4.0")
inline int64_t payload_to_number(const std::vector<uint8_t> &data, SensorValueType sensor_value_type, uint8_t offset,
                                 uint32_t bitmask) {
  return modbus::helpers::payload_to_number(std::span<const uint8_t>(data), sensor_value_type, offset, bitmask)
      .value_or(0);
}
 
ESPDEPRECATED("Use modbus::helpers::float_to_payload() instead. Removed in 2026.10.0", "2026.4.0")
inline std::vector<uint16_t> float_to_payload(float value, SensorValueType value_type) {
  std::vector<uint16_t> data;
  modbus::helpers::float_to_payload(data, value, value_type);
  return data;
}
 
class ModbusController;
 
enum class RangeReuse : uint8_t {
  AUTO = 0,    // join when adjacent and the position in the reply is exact (no non-standard response_size ahead)
  ALWAYS = 1,  // join unconditionally, reading across any address gap
  NEVER = 2,   // never join backward (later items may still extend this item's range)
};
 
class SensorItem {
 public:
  virtual void parse_and_publish(std::span<const uint8_t> data) = 0;
 
  bool addresses_bits() const { return modbus::helpers::is_entity_type_binary(this->register_type); }
 
  uint16_t write_address() const {
    return this->range_start_address + (this->addresses_bits() ? this->offset : this->offset / 2);
  }
 
  void set_offset_from_start_address(uint8_t offset) {
    this->offset_from_start_address = offset;
    this->offset = offset;
  }
 
  void set_address(uint16_t address) {
    this->start_address = address;
    this->range_start_address = address;
  }
 
  void set_custom_pdu(std::initializer_list<uint8_t> pdu) { this->custom_pdu.set(pdu.begin(), pdu.size()); }
 
  virtual uint16_t entity_count() const {
    if (modbus::helpers::is_entity_type_binary(this->register_type)) {
      return 1;
    }
    if (this->sensor_value_type == SensorValueType::RAW && this->response_bytes > 0) {
      return (this->response_bytes + 1) / 2;
    }
    return modbus::helpers::register_width_for(this->sensor_value_type);
  }
 
  size_t virtual get_register_size() const {
    if (this->addresses_bits()) {
      return 1;
    } else {  // if CONF_RESPONSE_BYTES is used override the default
      return response_bytes > 0 ? response_bytes : this->entity_count() * 2;
    }
  }
  // Override register size for modbus devices not using 1 register for one dword
  void set_register_size(uint8_t register_size) { response_bytes = register_size; }
  modbus::EntityType register_type{modbus::EntityType::CUSTOM};
  SensorValueType sensor_value_type{SensorValueType::RAW};
  uint16_t start_address{0};
  uint32_t bitmask{0};
  uint8_t offset{0};
  uint8_t response_bytes{0};
  uint8_t offset_from_start_address{0};
  uint16_t range_start_address{0};
  SmallInlineBuffer<8> custom_pdu{};
  RangeReuse reuse_previous_range{RangeReuse::AUTO};
};
 
// ModbusController::create_polling_commands_ tries to optimize register range
// for this the sensors must be ordered by register_type, start_address and bitmask
class SensorItemsComparator {
 public:
  bool operator()(const SensorItem *lhs, const SensorItem *rhs) const {
    // first sort according to register type
    if (lhs->register_type != rhs->register_type) {
      return lhs->register_type < rhs->register_type;
    }
 
    // sort by start address
    if (lhs->start_address != rhs->start_address) {
      return lhs->start_address < rhs->start_address;
    }
 
    // at the same address: AUTO before ALWAYS before NEVER, so a NEVER item never starts the range
    // the others at that address are then forced to share (see RangeReuse)
    if (lhs->reuse_previous_range != rhs->reuse_previous_range) {
      return lhs->reuse_previous_range < rhs->reuse_previous_range;
    }
 
    // sort by the offset as configured (ensures update of sensors in ascending order). The resolved
    // `offset` is deliberately not used: ranges are built while iterating this set and assign it, and
    // a sort key that changed under the iteration would corrupt the set's ordering.
    if (lhs->offset_from_start_address != rhs->offset_from_start_address) {
      return lhs->offset_from_start_address < rhs->offset_from_start_address;
    }
 
    // The pointer to the sensor is used last to ensure that
    // multiple sensors with the same values can be added with a stable sort order.
    return lhs < rhs;
  }
};
 
using SensorSet = std::set<SensorItem *, SensorItemsComparator>;
 
struct RegisterRange {
  uint16_t start_address;
  modbus::EntityType register_type;
  uint16_t register_count;  // registers (or bits) the poll command reads; joins across gaps can exceed 255
  SensorSet sensors;        // all sensors of this range
  const SmallInlineBuffer<8> *custom_pdu{nullptr};
};
 
class ControllerDevice : protected modbus::ModbusClientDevice {
 public:
  // Public: only the owner can reach this instance, so reachability is the access gate.
  void set_controller(ModbusController *controller);
 
 protected:
  ControllerDevice() = default;  // WriterEntity's member is wired later via set_controller()
  explicit ControllerDevice(ModbusController *controller) { this->set_controller(controller); }
 
  void on_response(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu) override;
  void on_error(std::span<const uint8_t> request_pdu, modbus::ExceptionCode exception_code) override;
  void on_sent(std::span<const uint8_t> request_pdu) override;
  void on_not_sent(std::span<const uint8_t> request_pdu) override;
  bool on_no_response(std::span<const uint8_t> request_pdu) override;
 
  void notify_online_(std::span<const uint8_t> request_pdu);
 
  bool dispatched_ : 1 {false};
  bool write_buffer_deprecated_warned_ : 1 {false};
  modbus::CommandOptions write_options_{};
  ModbusController *controller_{nullptr};
};
 
class WriterDevice final : public ControllerDevice {
 public:
  using modbus::ModbusClientDevice::clear_tx_queue_for_device;
  using modbus::ModbusClientDevice::queue_pdu;
  using modbus::ModbusClientDevice::write_multiple_coils;
  using modbus::ModbusClientDevice::write_multiple_registers;
  using modbus::ModbusClientDevice::write_single_coil;
  using modbus::ModbusClientDevice::write_single_register;
 
  bool send_raw_frame_deprecated(std::span<const uint8_t> frame);
 
  bool dispatched() const { return this->dispatched_; }
  void set_dispatched() { this->dispatched_ = true; }
  void clear_dispatched() { this->dispatched_ = false; }
  modbus::CommandOptions write_options() const { return this->write_options_; }
  void set_write_options(modbus::CommandOptions options) { this->write_options_ = options; }
  void warn_write_buffer_deprecated(const LogString *platform, uint16_t address);
 
 protected:
  // Only the write side forwards to the typed callbacks (for item->queue_pdu() replies): a poll parses
  // its own response, and dispatching its errors would trip the base unhandled-custom-response warning.
  void on_response(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu) override;
  void on_error(std::span<const uint8_t> request_pdu, modbus::ExceptionCode exception_code) override;
};
 
class WriterEntity {
 public:
  bool dispatched() const { return this->device_.dispatched(); }
  void set_write_options(modbus::CommandOptions options) { this->device_.set_write_options(options); }
  bool write_single_register(uint16_t address, uint16_t value) {
    this->device_.set_dispatched();
    return this->device_.write_single_register(address, value, this->device_.write_options());
  }
  bool write_single_coil(uint16_t address, bool value) {
    this->device_.set_dispatched();
    return this->device_.write_single_coil(address, value, this->device_.write_options());
  }
  bool write_multiple_registers(uint16_t address, std::span<const uint16_t> values) {
    this->device_.set_dispatched();
    return this->device_.write_multiple_registers(address, values, this->device_.write_options());
  }
  bool write_multiple_coils(uint16_t address, std::span<const bool> values) {
    this->device_.set_dispatched();
    return this->device_.write_multiple_coils(address, values, this->device_.write_options());
  }
  bool write_multiple_coils(uint16_t address, modbus::PackedBits bits) {
    this->device_.set_dispatched();
    return this->device_.write_multiple_coils(address, bits, this->device_.write_options());
  }
  bool queue_pdu(std::span<const uint8_t> pdu) { return this->queue_pdu(pdu, this->device_.write_options()); }
  bool queue_pdu(std::span<const uint8_t> pdu, modbus::CommandOptions options) {
    this->device_.set_dispatched();
    return this->device_.queue_pdu(pdu, options);
  }
  void clear_tx_queue_for_device() { this->device_.clear_tx_queue_for_device(); }
 
 protected:
  bool send_raw_frame_deprecated_(std::span<const uint8_t> frame) {
    this->device_.set_dispatched();
    return this->device_.send_raw_frame_deprecated(frame);
  }
  void set_controller_(ModbusController *controller) { this->device_.set_controller(controller); }
  void clear_dispatched_() { this->device_.clear_dispatched(); }
  void warn_write_buffer_deprecated_(const LogString *platform, uint16_t address) {
    this->device_.warn_write_buffer_deprecated(platform, address);
  }
 
 private:
  // Private so a derived entity cannot reach the device except through the recording forwarders above.
  WriterDevice device_;
};
 
class PollingDevice final : public ControllerDevice {
 public:
  PollingDevice(ModbusController &controller, RegisterRange &&range);
 
  bool queue(modbus::CommandOptions options = {});
 
  uint16_t register_address() const { return this->range_.start_address; }
  uint16_t register_count() const { return this->range_.register_count; }
  EntityType register_type() const { return this->range_.register_type; }
 
 protected:
  void on_response(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu) override;
 
  RegisterRange range_;
};
 
// The deprecated class references other deprecated names. Remove before 2027.3.0.
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
class ESPDEPRECATED(
    "One-shot writes go through the entity write helpers (WriterDevice) or the modbus_client actions, and "
    "polling runs through PollingDevice. Removed in 2027.3.0",
    "2026.9.0") ModbusCommandItem : public modbus::ModbusClientDevice {
 public:
  ModbusCommandItem(ModbusController &controller, modbus::ModbusClientHub *parent, uint8_t address)
      : modbus::ModbusClientDevice(parent, address), controller_(&controller) {}
  ModbusCommandItem(ModbusController &controller, modbus::ModbusClientHub *parent, uint8_t address,
                    RegisterRange &&range);
  ModbusCommandItem(ModbusController &controller, modbus::ModbusClientHub *parent, uint8_t address, SensorItem *sensor);
 
  // The base deletes copy/move (its destructor unregisters the device from the hub queue), but command
  // items are stored in value containers, so copy/move CONSTRUCTION is re-provided (copy only for the
  // queue_command() path). Assignment stays deleted: the item's address-in-memory is its hub identity.
  ModbusCommandItem(const ModbusCommandItem &other);
  ModbusCommandItem(ModbusCommandItem &&other) noexcept;
  ModbusCommandItem &operator=(ModbusCommandItem &&) = delete;
 
  SensorSet sensors;  // sensors served by this command (empty for factory/write commands)
  std::function<void(EntityType register_type, uint16_t start_address, std::span<const uint8_t> data)> on_data_func;
  SmallInlineBuffer<8> payload;
  // Set by unqueue_command() when this one-shot has completed. The controller erases flagged items at a
  // safe point (update()/queue_command()), never from inside the command's own callback.
  bool pending_removal{false};
 
  void on_response(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu) override;
  void on_error(std::span<const uint8_t> request_pdu, modbus::ExceptionCode exception_code) override;
  void on_not_sent(std::span<const uint8_t> request_pdu) override;
  void on_sent(std::span<const uint8_t> request_pdu) override;
  bool on_no_response(std::span<const uint8_t> request_pdu) override;
 
  uint16_t register_address() const { return this->start_address_; }
  uint16_t register_count() const { return this->register_count_; }
  EntityType register_type() const { return this->register_type_; }
 
  bool send(modbus::CommandOptions options = {});
 
 
  static ModbusCommandItem create_read_command(
      ModbusController *modbusdevice, EntityType register_type, uint16_t start_address, uint16_t register_count,
      std::function<void(EntityType register_type, uint16_t start_address, std::span<const uint8_t> data)> &&handler);
  static ModbusCommandItem create_write_multiple_command(ModbusController *modbusdevice, uint16_t start_address,
                                                         uint16_t register_count, const std::vector<uint16_t> &values);
  static ModbusCommandItem create_write_single_command(ModbusController *modbusdevice, uint16_t start_address,
                                                       uint16_t value);
  static ModbusCommandItem create_write_single_coil(ModbusController *modbusdevice, uint16_t address, bool value);
 
  static ModbusCommandItem create_write_multiple_coils(ModbusController *modbusdevice, uint16_t start_address,
                                                       const std::vector<bool> &values);
  static ModbusCommandItem create_custom_command(
      ModbusController *modbusdevice, const std::vector<uint8_t> &values,
      std::function<void(EntityType register_type, uint16_t start_address, std::span<const uint8_t> data)> &&handler =
          nullptr);
 
  static ModbusCommandItem create_custom_command(
      ModbusController *modbusdevice, const std::vector<uint16_t> &values,
      std::function<void(EntityType register_type, uint16_t start_address, std::span<const uint8_t> data)> &&handler =
          nullptr);
 
 protected:
  void set_command_(FunctionCode function_code, EntityType register_type, uint16_t start_address,
                    uint16_t register_count) {
    this->function_code_ = function_code;
    this->register_type_ = register_type;
    this->start_address_ = start_address;
    this->register_count_ = register_count;
  }
  EntityType register_type_{EntityType::CUSTOM};
  uint16_t start_address_{0};
  uint16_t register_count_{0};
  FunctionCode function_code_{FunctionCode::CUSTOM};
  const SmallInlineBuffer<8> *custom_pdu_{nullptr};
  ModbusController *controller_{nullptr};
};
#pragma GCC diagnostic pop
 
inline bool offline_retry_due(uint16_t update_counter, uint16_t module_offline_at, uint16_t offline_skip_updates) {
  return static_cast<uint16_t>(update_counter + 1 - module_offline_at) % (offline_skip_updates + 1) == 0;
}
 
class ModbusController final : public PollingComponent {
 public:
  // The controller is not itself a modbus device - its commands and writer entities send as their own
  // devices, built against this hub + address.
  ModbusController(modbus::ModbusClientHub *hub, uint8_t address) : hub_(hub), address_(address) {}
 
  void dump_config() override;
  // No loop() override: the hub owns transmit/receive timing and each command routes its own
  // response, so the controller never joins the looping components at all.
  void setup() override;
  void update() override;
 
  modbus::ModbusClientHub *hub() const { return this->hub_; }
  uint8_t device_address() const { return this->address_; }
 
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
  ESPDEPRECATED("Use the entity write helpers or the modbus_client actions instead. Removed in 2027.3.0", "2026.9.0")
  void queue_command(ModbusCommandItem command);
  ESPDEPRECATED("Serves only ModbusCommandItem's own callbacks. Removed in 2027.3.0", "2026.9.0")
  void unqueue_command(const ModbusCommandItem *command);
#pragma GCC diagnostic pop
  void add_sensor_item(SensorItem *item) { sensorset_.insert(item); }
  ESPDEPRECATED("Write acknowledgements are handled by the writing entity's own device. Removed in 2027.3.0",
                "2026.9.0")
  void on_write_register_response(EntityType register_type, uint16_t start_address, std::span<const uint8_t> data);
  void set_online(bool online, int function_code, int register_address);
  void command_sent(int function_code, int register_address) {
    this->command_sent_callback_.call(function_code, register_address);
  }
  void increment_non_response_count() { this->cmd_non_responses_++; }
  bool can_send() { return this->cmd_non_responses_ <= this->max_cmd_retries_; }
  void set_offline_skip_updates(uint16_t offline_skip_updates) { this->offline_skip_updates_ = offline_skip_updates; }
  bool get_module_offline() { return module_offline_; }
  template<typename F> void add_on_command_sent_callback(F &&callback) {
    this->command_sent_callback_.add(std::forward<F>(callback));
  }
  template<typename F> void add_on_online_callback(F &&callback) {
    this->online_callback_.add(std::forward<F>(callback));
  }
  template<typename F> void add_on_offline_callback(F &&callback) {
    this->offline_callback_.add(std::forward<F>(callback));
  }
  void set_max_cmd_retries(uint8_t max_cmd_retries) { this->max_cmd_retries_ = max_cmd_retries; }
  uint8_t get_max_cmd_retries() { return this->max_cmd_retries_; }
  void set_read_options(modbus::CommandOptions options) { this->read_options_ = options; }
  const modbus::CommandOptions &read_options() const { return this->read_options_; }
 
 protected:
  void create_polling_commands_();
  modbus::ModbusClientHub *hub_{nullptr};
  uint8_t address_{0};
  SensorSet sensorset_;
  FixedVector<PollingDevice> polling_devices_;
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
  std::list<std::unique_ptr<ModbusCommandItem>> one_shot_command_items_;
#pragma GCC diagnostic pop
  void sweep_completed_one_shots_();
  bool module_offline_{false};
  uint16_t module_offline_at_{0};
  uint16_t update_counter_{0};
  uint8_t cmd_non_responses_{0};
  uint16_t offline_skip_updates_{0};
  uint8_t max_cmd_retries_{4};
  modbus::CommandOptions read_options_{};
  CallbackManager<void(int, int)> command_sent_callback_{};
  CallbackManager<void(int, int)> online_callback_{};
  CallbackManager<void(int, int)> offline_callback_{};
};
 
inline float payload_to_float(std::span<const uint8_t> data, const SensorItem &item, uint8_t offset) {
  int64_t number = modbus::helpers::payload_to_number(data, item.sensor_value_type, offset, item.bitmask).value_or(0);
 
  float float_value;
  if (modbus::helpers::value_type_is_float(item.sensor_value_type)) {
    float_value = bit_cast<float>(static_cast<uint32_t>(number));
  } else {
    float_value = static_cast<float>(number);
  }
 
  return float_value;
}
 
// Remove before 2027.2.0 (window opened when this helper gained an explicit offset). item.offset is
// the item's resolved position within its range's response, so this decodes the same bytes as passing
// that offset explicitly.
ESPDEPRECATED("Pass the offset explicitly: payload_to_float(data, item, item.offset). Removed in 2027.2.0", "2026.8.0")
inline float payload_to_float(std::span<const uint8_t> data, const SensorItem &item) {
  return payload_to_float(data, item, item.offset);
}
 
}  // namespace esphome::modbus_controller