modbus_client.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/components/modbus/modbus.h"
#include "esphome/components/modbus/modbus_helpers.h"
#include "esphome/core/automation.h"
 
#include <span>
#include <vector>
 
namespace esphome::modbus_client {
 
template<typename... Ts> class ClientActionBase : public Action<Ts...>, public modbus::ModbusClientDevice {
 public:
  TEMPLATABLE_VALUE(uint8_t, target_address)  // the modbus device address
 
  Trigger<std::span<const uint8_t>> *get_sent_trigger() { return &this->sent_trigger_; }
  Trigger<std::span<const uint8_t>, modbus::ExceptionCode> *get_error_trigger() { return &this->error_trigger_; }
  Trigger<std::span<const uint8_t>> *get_no_response_trigger() { return &this->no_response_trigger_; }
  Trigger<std::span<const uint8_t>> *get_not_sent_trigger() { return &this->not_sent_trigger_; }
 
  using retry_func_t = bool (*)(std::span<const uint8_t>);
  void set_retry(retry_func_t f) { this->retry_func_ = f; }
 
  void on_sent(std::span<const uint8_t> request_pdu) override { this->sent_trigger_.trigger(request_pdu); }
  void on_not_sent(std::span<const uint8_t> request_pdu) override { this->not_sent_trigger_.trigger(request_pdu); }
  void on_error(std::span<const uint8_t> request_pdu, modbus::ExceptionCode exception_code) override {
    this->error_trigger_.trigger(request_pdu, exception_code);
  }
  bool on_no_response(std::span<const uint8_t> request_pdu) override {
    this->no_response_trigger_.trigger(request_pdu);
    if (this->retry_func_ != nullptr)
      return this->retry_func_(request_pdu);
    return false;
  }
  void play_complex(const Ts &...x) override {
    this->set_address(this->target_address_.value(x...));
    Action<Ts...>::play_complex(x...);
  }
 
 protected:
  void send_or_resolve_(std::span<const uint8_t> pdu, modbus::CommandOptions options = {}) {
    if (!this->queue_pdu(pdu, options))
      this->on_not_sent(pdu);
  }
 
  Trigger<std::span<const uint8_t>> sent_trigger_;
  Trigger<std::span<const uint8_t>, modbus::ExceptionCode> error_trigger_;
  Trigger<std::span<const uint8_t>> no_response_trigger_;
  Trigger<std::span<const uint8_t>> not_sent_trigger_;
  retry_func_t retry_func_{nullptr};
};
 
template<typename... Ts> class ReadCommandOptions {
 public:
  // Poll: re-queue after each success until downgraded (replay with false) or failed. The hub strips
  // it for mutating function codes at the door (see modbus::CommandOptions).
  TEMPLATABLE_VALUE(bool, continuous)
  TEMPLATABLE_VALUE(bool, allow_broadcast_read)
 
 protected:
  modbus::CommandOptions command_options_(const Ts &...x) const {
    return {.continuous = this->continuous_.value(x...),
            .allow_broadcast_read = this->allow_broadcast_read_.value(x...)};
  }
};
 
template<typename... Ts> class WriteCommandOptions {
 public:
  TEMPLATABLE_VALUE(bool, expect_broadcast_write_response)
 
 protected:
  void apply_write_command_options_(modbus::CommandOptions &options, const Ts &...x) const {
    options.expect_broadcast_write_response = this->expect_broadcast_write_response_.value(x...);
  }
  modbus::CommandOptions write_command_options_(const Ts &...x) const {
    modbus::CommandOptions options{};
    this->apply_write_command_options_(options, x...);
    return options;
  }
};
 
template<typename... Ts>
class ModbusClientSendAction : public ClientActionBase<Ts...>,
                               public ReadCommandOptions<Ts...>,
                               public WriteCommandOptions<Ts...> {
 public:
  TEMPLATABLE_VALUE(modbus::helpers::PduBuffer, pdu)
 
  Trigger<std::span<const uint8_t>, std::span<const uint8_t>> *get_response_trigger() {
    return &this->response_trigger_;
  }
 
  void play(const Ts &...x) override {
    modbus::CommandOptions options = this->command_options_(x...);
    this->apply_write_command_options_(options, x...);
    this->send_or_resolve_(this->pdu_.value(x...), options);
  }
 
  void on_response(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu) override {
    this->response_trigger_.trigger(request_pdu, response_pdu);
  }
 
 protected:
  Trigger<std::span<const uint8_t>, std::span<const uint8_t>> response_trigger_;
};
 
template<typename... Ts> class TypedClientActionBase : public ClientActionBase<Ts...> {
 public:
  Trigger<std::span<const uint8_t>, std::span<const uint8_t>> *get_custom_response_trigger() {
    return &this->custom_response_trigger_;
  }
  void set_custom_response_handled() { this->custom_response_handled_ = true; }
 
  void on_custom_response(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu,
                          modbus::ResponseStatus status) override {
    if (!this->custom_response_handled_) {
      modbus::ModbusClientDevice::on_custom_response(request_pdu, response_pdu, status);
      return;
    }
    this->custom_response_trigger_.trigger(request_pdu, response_pdu);
  }
 
 protected:
  Trigger<std::span<const uint8_t>, std::span<const uint8_t>> custom_response_trigger_;
  bool custom_response_handled_{false};
};
 
template<typename... Ts>
class ReadRegistersAction : public TypedClientActionBase<Ts...>, public ReadCommandOptions<Ts...> {
 public:
  explicit ReadRegistersAction(bool holding) : holding_(holding) {}
  TEMPLATABLE_VALUE(uint16_t, start_address)
  TEMPLATABLE_VALUE(uint16_t, count)
 
  Trigger<std::span<const uint16_t>> *get_response_trigger() { return &this->response_trigger_; }
 
  void play(const Ts &...x) override {
    const auto function_code =
        this->holding_ ? modbus::FunctionCode::READ_HOLDING_REGISTERS : modbus::FunctionCode::READ_INPUT_REGISTERS;
    this->send_or_resolve_(
        modbus::helpers::create_read_pdu(function_code, this->start_address_.value(x...), this->count_.value(x...)),
        this->command_options_(x...));
  }
  void on_read_registers(modbus::EntityType entity_type, uint16_t start_address, std::span<const uint16_t> registers,
                         modbus::ResponseStatus status) override {
    if (modbus::succeeded(status))
      this->response_trigger_.trigger(registers);
  }
 
 protected:
  Trigger<std::span<const uint16_t>> response_trigger_;
  bool holding_;
};
 
template<typename... Ts> class ReadBitsAction : public TypedClientActionBase<Ts...>, public ReadCommandOptions<Ts...> {
 public:
  explicit ReadBitsAction(bool coils) : coils_(coils) {}
  TEMPLATABLE_VALUE(uint16_t, start_address)
  TEMPLATABLE_VALUE(uint16_t, count)
 
  Trigger<modbus::PackedBits> *get_response_trigger() { return &this->response_trigger_; }
 
  void play(const Ts &...x) override {
    const auto function_code =
        this->coils_ ? modbus::FunctionCode::READ_COILS : modbus::FunctionCode::READ_DISCRETE_INPUTS;
    this->send_or_resolve_(
        modbus::helpers::create_read_pdu(function_code, this->start_address_.value(x...), this->count_.value(x...)),
        this->command_options_(x...));
  }
  void on_read_bits(modbus::EntityType entity_type, uint16_t start_address, modbus::PackedBits bits,
                    modbus::ResponseStatus status) override {
    if (modbus::succeeded(status))
      this->response_trigger_.trigger(bits);
  }
 
 protected:
  Trigger<modbus::PackedBits> response_trigger_;
  bool coils_;
};
 
template<typename... Ts>
class WriteSingleRegisterAction : public TypedClientActionBase<Ts...>, public WriteCommandOptions<Ts...> {
 public:
  TEMPLATABLE_VALUE(uint16_t, start_address)
  TEMPLATABLE_VALUE(uint16_t, value)
 
  Trigger<> *get_response_trigger() { return &this->response_trigger_; }
 
  void play(const Ts &...x) override {
    this->send_or_resolve_(
        modbus::helpers::create_write_single_register_pdu(this->start_address_.value(x...), this->value_.value(x...)),
        this->write_command_options_(x...));
  }
  void on_write_single_register(uint16_t address, uint16_t value, modbus::ResponseStatus status) override {
    if (modbus::succeeded(status))
      this->response_trigger_.trigger();
  }
 
 protected:
  Trigger<> response_trigger_;
};
 
template<typename... Ts>
class WriteSingleCoilAction : public TypedClientActionBase<Ts...>, public WriteCommandOptions<Ts...> {
 public:
  TEMPLATABLE_VALUE(uint16_t, start_address)
  TEMPLATABLE_VALUE(bool, value)
 
  Trigger<> *get_response_trigger() { return &this->response_trigger_; }
 
  void play(const Ts &...x) override {
    this->send_or_resolve_(
        modbus::helpers::create_write_single_coil_pdu(this->start_address_.value(x...), this->value_.value(x...)),
        this->write_command_options_(x...));
  }
  void on_write_single_coil(uint16_t address, bool value, modbus::ResponseStatus status) override {
    if (modbus::succeeded(status))
      this->response_trigger_.trigger();
  }
 
 protected:
  Trigger<> response_trigger_;
};
 
template<typename... Ts>
class WriteMultipleRegistersAction : public TypedClientActionBase<Ts...>, public WriteCommandOptions<Ts...> {
 public:
  TEMPLATABLE_VALUE(uint16_t, start_address)
 
  
  void set_values_static(const uint16_t *values, size_t len) {
    this->values_.data = values;
    this->len_ = static_cast<ssize_t>(len);
  }
  void set_values_template(std::vector<uint16_t> (*func)(Ts...)) {
    this->values_.func = func;
    this->len_ = -1;  // sentinel: template mode
  }
 
  Trigger<> *get_response_trigger() { return &this->response_trigger_; }
 
  void play(const Ts &...x) override {
    const uint16_t start = this->start_address_.value(x...);
    // An empty or over-long set rejects into an empty PDU inside the builder, which logs the reason;
    // the empty PDU then resolves via on_not_sent like any refused send.
    if (this->len_ >= 0) {
      this->send_or_resolve_(modbus::helpers::create_write_registers_pdu(
                                 start, std::span<const uint16_t>(this->values_.data, static_cast<size_t>(this->len_))),
                             this->write_command_options_(x...));
      return;
    }
    const std::vector<uint16_t> values = this->values_.func(x...);
    this->send_or_resolve_(modbus::helpers::create_write_registers_pdu(start, std::span<const uint16_t>(values)),
                           this->write_command_options_(x...));
  }
  void on_write_multiple_registers(uint16_t start_address, std::span<const uint16_t> registers,
                                   modbus::ResponseStatus status) override {
    if (modbus::succeeded(status))
      this->response_trigger_.trigger();
  }
 
 protected:
  Trigger<> response_trigger_;
  ssize_t len_{-1};  // -1 = template mode, >= 0 = static mode with this many registers
  union Values {
    std::vector<uint16_t> (*func)(Ts...);
    const uint16_t *data;
  } values_;
};
 
template<typename... Ts>
class WriteMultipleCoilsAction : public TypedClientActionBase<Ts...>, public WriteCommandOptions<Ts...> {
 public:
  TEMPLATABLE_VALUE(uint16_t, start_address)
 
  
  void set_values_static(const uint8_t *packed, size_t count) {
    this->values_.packed = packed;
    this->count_ = static_cast<ssize_t>(count);
  }
  void set_values_template(std::vector<bool> (*func)(Ts...)) {
    this->values_.func = func;
    this->count_ = -1;  // sentinel: template mode
  }
 
  Trigger<> *get_response_trigger() { return &this->response_trigger_; }
 
  void play(const Ts &...x) override {
    const uint16_t start = this->start_address_.value(x...);
    if (this->count_ >= 0) {
      const auto count = static_cast<uint16_t>(this->count_);
      this->send_or_resolve_(
          modbus::helpers::create_write_coils_pdu(
              start, modbus::PackedBits(std::span<const uint8_t>(this->values_.packed, modbus::packed_bit_bytes(count)),
                                        count)),
          this->write_command_options_(x...));
      return;
    }
    // The builder packs and bound-checks; an over-long set is rejected and logged there.
    this->send_or_resolve_(modbus::helpers::create_write_coils_pdu(start, this->values_.func(x...)),
                           this->write_command_options_(x...));
  }
  void on_write_multiple_coils(uint16_t start_address, modbus::PackedBits bits,
                               modbus::ResponseStatus status) override {
    if (modbus::succeeded(status))
      this->response_trigger_.trigger();
  }
 
 protected:
  Trigger<> response_trigger_;
  ssize_t count_{-1};  // -1 = template mode, >= 0 = static mode with this many coils
  union Values {
    std::vector<bool> (*func)(Ts...);
    const uint8_t *packed;
  } values_;
};
 
template<typename... Ts>
class ReadWriteMultipleRegistersAction : public TypedClientActionBase<Ts...>, public ReadCommandOptions<Ts...> {
 public:
  TEMPLATABLE_VALUE(uint16_t, read_address)
  TEMPLATABLE_VALUE(uint16_t, read_count)
  TEMPLATABLE_VALUE(uint16_t, write_address)
 
  void set_values_static(const uint16_t *values, size_t len) {
    this->values_.data = values;
    this->len_ = static_cast<ssize_t>(len);
  }
  void set_values_template(std::vector<uint16_t> (*func)(Ts...)) {
    this->values_.func = func;
    this->len_ = -1;  // sentinel: template mode
  }
 
  Trigger<std::span<const uint16_t>> *get_response_trigger() { return &this->response_trigger_; }
 
  void play(const Ts &...x) override {
    const uint16_t read_start = this->read_address_.value(x...);
    const uint16_t read_count = this->read_count_.value(x...);
    const uint16_t write_start = this->write_address_.value(x...);
    // An out-of-range read/write count builds an empty PDU (the builder logs why), resolving via on_not_sent.
    if (this->len_ >= 0) {
      this->send_or_resolve_(modbus::helpers::create_read_write_multiple_registers_pdu(
                                 read_start, read_count, write_start,
                                 std::span<const uint16_t>(this->values_.data, static_cast<size_t>(this->len_))),
                             this->command_options_(x...));
      return;
    }
    const std::vector<uint16_t> values = this->values_.func(x...);
    this->send_or_resolve_(modbus::helpers::create_read_write_multiple_registers_pdu(
                               read_start, read_count, write_start, std::span<const uint16_t>(values)),
                           this->command_options_(x...));
  }
  // The 0x17 response carries only the read block, so the hub dispatch delivers it as a holding-register read.
  void on_read_registers(modbus::EntityType entity_type, uint16_t start_address, std::span<const uint16_t> registers,
                         modbus::ResponseStatus status) override {
    if (modbus::succeeded(status))
      this->response_trigger_.trigger(registers);
  }
 
 protected:
  Trigger<std::span<const uint16_t>> response_trigger_;
  ssize_t len_{-1};  // -1 = template mode, >= 0 = static mode with this many write registers
  union Values {
    std::vector<uint16_t> (*func)(Ts...);
    const uint16_t *data;
  } values_;
};
 
}  // namespace esphome::modbus_client