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/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;
 
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_data(const std::vector<uint8_t> &data) { custom_data = data; }
  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 : register_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 register_count{0};
  uint8_t response_bytes{0};
  uint8_t offset_from_start_address{0};
  uint16_t range_start_address{0};
  uint16_t skip_updates{0};
  std::vector<uint8_t> custom_data{};
  bool force_new_range{false};
};
 
// 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;
    }
 
    // ensure that sensor with force_new_range set are before the others
    if (lhs->force_new_range != rhs->force_new_range) {
      return lhs->force_new_range > rhs->force_new_range;
    }
 
    // sort by start address
    if (lhs->start_address != rhs->start_address) {
      return lhs->start_address < rhs->start_address;
    }
 
    // 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;
  uint8_t register_count;
  uint16_t skip_updates;  // the config value
  SensorSet sensors;      // all sensors of this range
};
 
class 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)
  uint16_t skip_updates{0};
  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();
 
 
  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 std::vector<uint8_t> *custom_data_{nullptr};
  ModbusController *controller_{nullptr};
};
 
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:
  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;
 
  // The controller is not itself a modbus device - its commands and writer entities send as their own
  // devices. It only owns the hub + address so those senders can be built against them.
  void set_parent(modbus::ModbusClientHub *hub) { this->hub_ = hub; }
  void set_address(uint8_t address) { this->address_ = address; }
 
  modbus::ModbusClientHub *hub() const { return this->hub_; }
  uint8_t device_address() const { return this->address_; }
 
  void queue_command(ModbusCommandItem command);
  void unqueue_command(const ModbusCommandItem *command);
  void add_sensor_item(SensorItem *item) { sensorset_.insert(item); }
  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_; }
 
 protected:
  void create_polling_commands_();
  void create_polling_command_(RegisterRange &&range) {
    // A custom range polls the first sensor's custom_data (a ready-made raw frame); it needs the
    // sensor constructor so the command references those bytes and decodes the real function code.
    // The response still dispatches to every sensor in the range.
    if (range.register_type == EntityType::CUSTOM && !range.sensors.empty()) {
      auto &cmd = this->polling_command_items_.emplace_back(*this, this->hub_, this->address_, *range.sensors.begin());
      cmd.sensors = std::move(range.sensors);
      cmd.skip_updates = range.skip_updates;  // the range's merged rate, not the first sensor's
    } else {
      this->polling_command_items_.emplace_back(*this, this->hub_, this->address_, std::move(range));
    }
  }
  void update_range_(ModbusCommandItem &cmd);
  modbus::ModbusClientHub *hub_{nullptr};
  uint8_t address_{0};
  SensorSet sensorset_;
  std::vector<ModbusCommandItem> polling_command_items_{};
  std::list<std::unique_ptr<ModbusCommandItem>> one_shot_command_items_;
  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};
  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