23static constexpr uint16_t MODBUS_TX_BUFFER_SIZE = 128;
24static constexpr uint16_t MODBUS_TX_MAX_DELAY_US = 5000;
28static constexpr uint16_t MODBUS_FRAME_INLINE_SIZE = 8;
37 uint8_t *buf = this->data.
init(pdu_len + 3);
39 memcpy(buf + 1,
pdu, pdu_len);
40 auto crc =
crc16(buf, pdu_len + 1);
41 buf[pdu_len + 1] = crc >> 0;
42 buf[pdu_len + 2] = crc >> 8;
45 uint16_t
size()
const {
return static_cast<uint16_t
>(this->data.
size()); }
49 std::span<const uint8_t>
pdu()
const {
return std::span<const uint8_t>(this->data.
data() + 1, this->size() - 3u); }
56 void setup()
override;
63#ifdef MODBUS_ON_REQUEST_COUNT
69#ifdef MODBUS_ON_RESPONSE_COUNT
84 void clear_rx_buffer_(
const LogString *reason,
bool warn =
false,
size_t bytes_to_clear = 0);
104#ifdef MODBUS_ON_REQUEST_COUNT
107#ifdef MODBUS_ON_RESPONSE_COUNT
108 StaticCallbackManager<MODBUS_ON_RESPONSE_COUNT, void(uint8_t, std::span<const uint8_t>, std::span<const uint8_t>)>
144static_assert(
sizeof(CommandOptions) == 1,
"CommandOptions must stay one byte");
176 const uint8_t fc = this->frame.
pdu()[0];
185 this->device =
nullptr;
253 bool response(std::span<const uint8_t> response_pdu);
261 const auto own_pdu = this->frame.
pdu();
262 return own_pdu.size() == pdu.size() && this->frame.
address() ==
address &&
263 memcmp(own_pdu.data(), pdu.data(), pdu.size()) == 0;
271 void loop()
override;
284 ESPDEPRECATED(
"Use queue_pdu() instead - the call queues a request, it does not send one, and it "
285 "reports whether the request was accepted. Removed in 2027.2.0",
290 ESPDEPRECATED(
"Use queue_pdu(payload[0], <pdu bytes>, device) instead. Removed in 2027.2.0",
"2026.8.0")
368 uint16_t &start_address, uint16_t &
count);
376 std::span<const uint8_t> &packed_bytes);
383 std::span<uint8_t> response_buffer, uint16_t &response_len);
390 void send_response_(uint8_t
address, uint8_t function_code,
const uint8_t *payload, uint16_t payload_len);
392#ifdef MODBUS_ON_RESPONSE_COUNT
430 this->clear_tx_queue_for_device();
442 virtual void on_response(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu) {
443 this->dispatch_response_(request_pdu, response_pdu, std::nullopt);
449 this->dispatch_response_(request_pdu, {}, exception_code);
454#pragma GCC diagnostic push
455#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
456 this->on_modbus_not_sent();
457#pragma GCC diagnostic pop
460 virtual void on_sent(std::span<const uint8_t> request_pdu) {}
464#pragma GCC diagnostic push
465#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
466 return this->on_modbus_no_response();
467#pragma GCC diagnostic pop
473 std::span<const uint8_t> response_pdu) {
477 this->
on_error(request_pdu, exception_code);
485 ESPDEPRECATED(
"Override on_not_sent() instead. Removed in 2027.2.0",
"2026.8.0")
486 virtual
void on_modbus_not_sent() {}
488 ESPDEPRECATED(
"Override on_no_response() instead. Removed in 2027.2.0",
"2026.8.0")
489 virtual
bool on_modbus_no_response() {
return false; }
533 virtual void on_custom_response(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu,
535 ESPDEPRECATED(
"Use the typed read_*/write_* helpers or queue_pdu() instead. Removed in 2027.2.0",
"2026.8.0")
548 ESPDEPRECATED(
"Use queue_pdu() instead - the call queues a request, it does not send one, and it "
549 "reports whether the request was accepted. Removed in 2027.2.0",
551 void send_pdu(
std::span<const uint8_t> pdu) { this->queue_pdu(pdu); }
552 ESPDEPRECATED(
"Use queue_pdu() instead (the device address is prepended for you). Removed in 2027.2.0",
"2026.8.0")
556 this->parent_->queue_pdu(
payload[0], std::span<const uint8_t>(
payload).subspan(1),
this);
567 bool read_input_registers(uint16_t
start_address, uint16_t number_of_registers, CommandOptions
options = {}) {
568 return this->queue_pdu(
571 bool read_holding_registers(uint16_t
start_address, uint16_t number_of_registers, CommandOptions
options = {}) {
572 return this->queue_pdu(
575 bool read_coils(uint16_t
start_address, uint16_t number_of_coils, CommandOptions
options = {}) {
578 bool read_discrete_inputs(uint16_t
start_address, uint16_t number_of_inputs, CommandOptions
options = {}) {
579 return this->queue_pdu(
588 bool write_multiple_registers(uint16_t
start_address, std::span<const uint16_t> values, CommandOptions
options = {}) {
590 if (!values.empty() && values.size() <= helpers::MAX_FEW_REGISTERS)
596 bool write_multiple_coils(uint16_t
start_address, std::span<const bool> values, CommandOptions
options = {}) {
601 bool write_multiple_coils(uint16_t
start_address, PackedBits bits, CommandOptions
options = {}) {
607 bool read_write_multiple_registers(uint16_t read_start_address, uint16_t read_count, uint16_t write_start_address,
608 std::span<const uint16_t> write_values) {
610 write_start_address, write_values));
619 void dispatch_response_(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu,
630class ESPDEPRECATED(
"Subclass ModbusClientDevice and override on_response()/on_error() instead. Removed in 2027.2.0",
631 "2026.8.0") ModbusDevice :
public ModbusClientDevice {
633 using ModbusClientDevice::ModbusClientDevice;
634 virtual void on_modbus_data(
const std::vector<uint8_t> &data) {}
635 virtual void on_modbus_error(uint8_t function_code, uint8_t exception_code) {}
637 void on_response(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu)
override {
641 auto payload = !response_pdu.empty() && helpers::is_function_code_custom(response_pdu[0])
643 : helpers::server_pdu_payload(response_pdu);
644 this->on_modbus_data(std::vector<uint8_t>(payload.begin(), payload.end()));
646 void on_error(std::span<const uint8_t> request_pdu, ExceptionCode exception_code)
override {
647 this->on_modbus_error(request_pdu.empty() ? 0 : request_pdu[0],
static_cast<uint8_t
>(exception_code));
Small buffer optimization - stores data inline when small, heap-allocates for large data This avoids ...
uint8_t * init(size_t size)
Resize to size bytes of (uninitialized) storage and return a writable pointer to fill.
CallbackManager backed by StaticVector for compile-time-known callback counts.
Minimal static vector - saves memory by avoiding std::vector overhead.
virtual void on_response(std::span< const uint8_t > request_pdu, std::span< const uint8_t > response_pdu)
Low-level response hook: called with the request PDU this device sent and the response PDU received T...
virtual void on_write_multiple_coils(uint16_t start_address, PackedBits bits, ResponseStatus status)
ModbusClientDevice()=default
ModbusClientDevice & operator=(ModbusClientDevice &&)=delete
virtual void on_response(uint8_t address, std::span< const uint8_t > request_pdu, std::span< const uint8_t > response_pdu)
Overloads of the hooks above with the device address of the request first, taken from the request fra...
virtual void on_error(uint8_t address, std::span< const uint8_t > request_pdu, ExceptionCode exception_code)
virtual void on_read_holding_registers(uint16_t start_address, std::span< const uint16_t > registers, ResponseStatus status)
virtual void on_write_multiple_registers(uint16_t start_address, std::span< const uint16_t > registers, ResponseStatus status)
virtual void on_sent(std::span< const uint8_t > request_pdu)
Called when this device's frame is actually written to the wire.
ModbusClientDevice(const ModbusClientDevice &)=delete
virtual void on_write_single_register(uint16_t address, uint16_t value, ResponseStatus status)
Write acknowledgements.
uint16_t uint16_t uint8_t payload_len
virtual void on_read_bits(EntityType entity_type, uint16_t start_address, PackedBits bits, ResponseStatus status)
Coil/discrete-input reads are delivered as a PackedBits view (bit 0 = the bit at start_address,...
virtual void on_not_sent(uint8_t address, std::span< const uint8_t > request_pdu)
virtual bool on_no_response(uint8_t address, std::span< const uint8_t > request_pdu)
ModbusClientDevice & operator=(const ModbusClientDevice &)=delete
void set_parent(ModbusClientHub *parent)
ESPDEPRECATED("Use the typed read_*/write_* helpers or queue_pdu() instead. Removed in 2027.2.0", "2026.8.0") void send(uint8_t function
virtual bool on_no_response(std::span< const uint8_t > request_pdu)
Called when no matching, uninterrupted response arrived; return true to have the hub re-queue the fra...
virtual void on_custom_response(std::span< const uint8_t > request_pdu, std::span< const uint8_t > response_pdu, ResponseStatus status)
Catch-all for custom function codes and anything that is not a standard-conformant transaction (see d...
virtual void on_sent(uint8_t address, std::span< const uint8_t > request_pdu)
ModbusClientDevice(ModbusClientDevice &&)=delete
virtual void on_read_discrete_inputs(uint16_t start_address, PackedBits bits, ResponseStatus status)
uint16_t uint16_t number_of_entities
ESPDEPRECATED("Override on_no_response() instead. Removed in 2027.2.0", "2026.8.0") virtual bool on_modbus_no_response()
virtual void on_read_registers(EntityType entity_type, uint16_t start_address, std::span< const uint16_t > registers, ResponseStatus status)
High-level typed response callbacks, fired by the default on_response()/on_error() with arguments par...
virtual void on_error(std::span< const uint8_t > request_pdu, ExceptionCode exception_code)
Low-level error hook: called with the request PDU and the modbus exception code from the error respon...
ModbusClientDevice(ModbusClientHub *parent, uint8_t address)
virtual ~ModbusClientDevice()
void set_address(uint8_t address)
virtual void on_not_sent(std::span< const uint8_t > request_pdu)
Called when an accepted request was dropped before transmission by clear_tx_queue_for_address().
ModbusClientHub * parent_
virtual void on_read_coils(uint16_t start_address, PackedBits bits, ResponseStatus status)
virtual void on_write_single_coil(uint16_t address, bool value, ResponseStatus status)
bool custom_response_warned_
uint16_t uint16_t uint8_t const uint8_t * payload
virtual void on_read_input_registers(uint16_t start_address, std::span< const uint16_t > registers, ResponseStatus status)
ESPDEPRECATED("Override on_not_sent() instead. Removed in 2027.2.0", "2026.8.0") virtual void on_modbus_not_sent()
void clear_tx_queue_for_device(ModbusClientDevice *device)
void parse_modbus_frames() override
ModbusDeviceCommand * find_waiting_()
std::span< const uint8_t > pdu
uint32_t turnaround_delay_us_
void dump_config() override
ModbusClientHub()=default
bool waiting_for_response_
ESPDEPRECATED("Use queue_pdu() instead - the call queues a request, it does not send one, and it " "reports whether the request was accepted. Removed in 2027.2.0", "2026.8.0") void send_pdu(uint8_t address
ModbusDeviceCommand * select_next_ready_()
uint32_t send_wait_time_us_
int32_t tx_delay_remaining() override
std::deque< ModbusDeviceCommand > tx_buffer_
bool tx_blocked() override
std::span< const uint8_t > ModbusClientDevice * device
bool queue_pdu(uint8_t address, std::span< const uint8_t > pdu, ModbusClientDevice *device=nullptr, CommandOptions options={})
Queue a request.
void clear_tx_queue_for_address(uint8_t address)
void process_modbus_server_frame(uint8_t address, std::span< const uint8_t > pdu) override
void set_send_wait_time(uint16_t time_in_ms)
void set_turnaround_time(uint16_t time_in_ms)
void set_flow_control_pin(GPIOPin *flow_control_pin)
void add_on_response_callback(F &&callback)
Every response received (client) or sent or seen (server); PDUs valid during the call.
uint32_t long_rx_buffer_delay_us_
virtual void process_modbus_server_frame(uint8_t address, std::span< const uint8_t > pdu)=0
bool parse_modbus_server_frame_()
virtual void parse_modbus_frames()=0
bool send_frame_(const ModbusFrame &frame)
StaticCallbackManager< MODBUS_ON_RESPONSE_COUNT, void(uint8_t, std::span< const uint8_t >, std::span< const uint8_t >)> response_callback_
uint32_t last_modbus_byte_
GPIOPin * flow_control_pin_
uint32_t last_send_tx_offset_
virtual bool tx_blocked()
void clear_rx_buffer_(const LogString *reason, bool warn=false, size_t bytes_to_clear=0)
float get_setup_priority() const override
void add_on_request_callback(F &&callback)
Every request read (server, before a device answers) or sent (client, retries included); PDU valid in...
bool exceeded_rx_full_threshold_
virtual int32_t tx_delay_remaining()
uint16_t find_frame_end_by_crc_(uint16_t min_length) const
std::vector< uint8_t > rx_buffer_
uint32_t rx_detect_latency_us_
uint32_t last_receive_check_
StaticCallbackManager< MODBUS_ON_REQUEST_COUNT, void(uint8_t, std::span< const uint8_t >)> request_callback_
ModbusServerDevice & operator=(ModbusServerDevice &&)=delete
virtual ~ModbusServerDevice()=default
virtual ResponseStatus on_read_coils(uint16_t start_address, MutablePackedBits bits)
ModbusServerDevice(const ModbusServerDevice &)=delete
ModbusServerDevice & operator=(const ModbusServerDevice &)=delete
ModbusServerDevice()=default
void set_address(uint8_t address)
virtual ResponseStatus on_write_registers(uint16_t start_address, const RegisterValues ®isters)
virtual ResponseStatus on_read_bits(uint16_t start_address, MutablePackedBits bits)
Coil/discrete-input reads: set the requested bits (bit 0 = the coil at start_address) with bits....
virtual ResponseStatus on_read_holding_registers(uint16_t start_address, uint16_t number_of_registers, RegisterValues ®isters)
virtual ResponseStatus on_read_registers(uint16_t start_address, uint16_t number_of_registers, RegisterValues ®isters)
virtual ResponseStatus on_read_discrete_inputs(uint16_t start_address, MutablePackedBits bits)
virtual ResponseStatus on_write_coils(uint16_t start_address, PackedBits bits)
Coil writes deliver the values as a PackedBits view over the hub's receive buffer (only valid during ...
virtual ResponseStatus on_read_input_registers(uint16_t start_address, uint16_t number_of_registers, RegisterValues ®isters)
uint8_t get_address() const
ModbusServerDevice(ModbusServerDevice &&)=delete
std::vector< ModbusServerDevice * > devices_
ResponseStatus check_address_range_(uint16_t start_address, uint16_t count)
ResponseStatus parse_read_request_(std::span< const uint8_t > data, uint16_t max_entities, const LogString *entity_name, uint16_t &start_address, uint16_t &count)
void process_modbus_client_frame_(uint8_t address, uint8_t function_code, std::span< const uint8_t > data)
void parse_modbus_frames() override
void process_modbus_server_frame(uint8_t address, std::span< const uint8_t > pdu) override
ResponseStatus parse_write_multiple_coils_(std::span< const uint8_t > data, uint16_t &start_address, uint16_t &count, std::span< const uint8_t > &packed_bytes)
void process_broadcast_frame_(uint8_t function_code, std::span< const uint8_t > data)
ModbusServerHub()=default
uint16_t deferred_payload_len_
void register_device(ModbusServerDevice *device)
ModbusServerDevice * find_device_(uint8_t address)
bool send_reply_(const ModbusFrame &frame)
ResponseStatus parse_write_single_coil_(std::span< const uint8_t > data, uint16_t &start_address, bool &value)
bool build_or_reject_read_response_(uint8_t address, uint8_t function_code, ResponseStatus status, uint16_t number_of_registers, const RegisterValues ®isters, std::span< uint8_t > response_buffer, uint16_t &response_len)
void send_exception_(uint8_t address, uint8_t function_code, ExceptionCode exception_code)
void assemble_registers_(std::span< const uint8_t > values, RegisterValues ®isters)
void send_raw_(const uint8_t *payload, uint16_t len)
uint8_t request_[MAX_PDU_SIZE]
bool parse_modbus_client_frame_()
void dump_config() override
void send_response_(uint8_t address, uint8_t function_code, const uint8_t *payload, uint16_t payload_len)
ResponseStatus parse_write_multiple_(std::span< const uint8_t > data, uint16_t &start_address, RegisterValues ®isters)
bool rejected_(uint8_t address, uint8_t function_code, ResponseStatus status)
ResponseStatus parse_write_single_(std::span< const uint8_t > data, uint16_t &start_address, RegisterValues ®isters)
std::array< uint8_t, MAX_RAW_SIZE > deferred_payload_
uint8_t expecting_peer_response_
Mutable counterpart of PackedBits: set() writes bits in place (deliberately no proxy operator[]=).
Read-only view of Modbus-packed bits: bit 0 of byte 0 is the first bit (LSB first),...
PduBuffer create_write_coils_pdu(uint16_t start_address, PackedBits bits)
Create modbus write multiple coils command (function 0x0F) from bits packed as on the wire.
WriteFewRegistersPdu create_write_few_registers_pdu(uint16_t start_address, std::span< const uint16_t > values)
Create modbus write multiple registers command (function 0x10) on a right-sized stack buffer.
bool is_function_code_read_only(uint8_t function_code)
WriteSinglePdu create_write_single_coil_pdu(uint16_t address, bool value)
Create modbus write single coil command Function 0x05 Write Single Coil.
ReadPdu create_read_pdu(FunctionCode function_code, uint16_t start_address, uint16_t number_of_entities)
Create a modbus read request PDU.
bool is_function_code_write(uint8_t function_code)
WriteSinglePdu create_write_single_register_pdu(uint16_t start_address, uint16_t value)
Create modbus write single register command Function 0x06 Write Single Register.
PduBuffer create_client_pdu(FunctionCode function_code, uint16_t start_address, uint16_t number_of_entities, const uint8_t *values, size_t values_len)
Create a modbus client pdu for reading/writing single/multiple coils/register/inputs.
FunctionCode modbus_register_read_function(EntityType reg_type)
PduBuffer create_write_registers_pdu(uint16_t start_address, std::span< const uint16_t > values)
Create modbus write multiple registers command Function 0x10 Write Multiple Registers.
PduBuffer create_read_write_multiple_registers_pdu(uint16_t read_start_address, uint16_t read_count, uint16_t write_start_address, std::span< const uint16_t > write_values)
Create modbus read/write multiple registers command Function 0x17 Read/Write Multiple Registers Write...
std::optional< ExceptionCode > ResponseStatus
bool succeeded(ResponseStatus status)
True when a transaction carried no exception.
uint16_t crc16(const uint8_t *data, uint16_t len, uint16_t crc, uint16_t reverse_poly, bool refin, bool refout)
Calculate a CRC-16 checksum of data with size len.
bool expect_broadcast_write_response
bool allow_broadcast_read
bool response(std::span< const uint8_t > response_pdu)
void complete_broadcast()
CommandPriority priority() const
ModbusDeviceCommand(ModbusClientDevice *device, uint8_t address, std::span< const uint8_t > pdu, CommandOptions options={}, uint16_t seq=0)
void make_continuous(bool continuous)
bool error(ExceptionCode exception_code)
bool waiting_state() const
void requeue(uint16_t seq)
bool fire_and_forget() const
bool same_frame(uint8_t address, std::span< const uint8_t > pdu) const
True if this command carries the same wire frame (address + PDU) as the given one.
ModbusClientDevice * device
uint8_t max_pending() const
ModbusFrame(uint8_t address, const uint8_t *pdu, uint16_t pdu_len)
SmallInlineBuffer< MODBUS_FRAME_INLINE_SIZE > data
std::span< const uint8_t > pdu() const
A PDU is [function code][data...] without address or CRC.