ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
modbus.h
Go to the documentation of this file.
1#pragma once
2
6
9
10#include <array>
11#include <cstring>
12#include <memory>
13#include <span>
14#include <vector>
15#include <deque>
16#include <optional>
17#include <utility>
18
19namespace esphome::modbus {
20
21// Tx queue backstop: duplicates dedup into one entry, so only a runaway generator of distinct frames
22// (e.g. a loop writing a changing value) could grow the heap unboundedly.
23static constexpr uint16_t MODBUS_TX_BUFFER_SIZE = 128;
24static constexpr uint16_t MODBUS_TX_MAX_DELAY_US = 5000;
25
26// Typical frames -- reads and single-register/coil writes -- are exactly 8 bytes
27// (address + 5-byte PDU + 2-byte CRC).
28static constexpr uint16_t MODBUS_FRAME_INLINE_SIZE = 8;
29
31 // Small-buffer-optimized: typical frames fit inline, keeping high-frequency tx traffic off the
32 // heap; only large multi-register or custom frames spill to a single heap allocation.
34
35 // A frame is [address][PDU...][CRC lo][CRC hi]. These are the only places that need to know that layout
36 ModbusFrame(uint8_t address, const uint8_t *pdu, uint16_t pdu_len) {
37 uint8_t *buf = this->data.init(pdu_len + 3);
38 buf[0] = address;
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;
43 }
44
45 uint16_t size() const { return static_cast<uint16_t>(this->data.size()); }
46 uint8_t address() const { return this->data.data()[0]; }
49 std::span<const uint8_t> pdu() const { return std::span<const uint8_t>(this->data.data() + 1, this->size() - 3u); }
50};
51
52class Modbus : public uart::UARTDevice, public Component {
53 public:
54 Modbus() = default;
55
56 void setup() override;
57 void loop() override;
58
59 float get_setup_priority() const override;
60 virtual bool tx_blocked();
61
62 void set_flow_control_pin(GPIOPin *flow_control_pin) { this->flow_control_pin_ = flow_control_pin; }
63#ifdef MODBUS_ON_REQUEST_COUNT
65 template<typename F> void add_on_request_callback(F &&callback) {
66 this->request_callback_.add(std::forward<F>(callback));
67 }
68#endif
69#ifdef MODBUS_ON_RESPONSE_COUNT
72 template<typename F> void add_on_response_callback(F &&callback) {
73 this->response_callback_.add(std::forward<F>(callback));
74 }
75#endif
76
77 protected:
78 void receive_bytes_();
79 bool timeout_();
80 virtual int32_t tx_delay_remaining();
81 virtual void parse_modbus_frames() = 0;
83 virtual void process_modbus_server_frame(uint8_t address, std::span<const uint8_t> pdu) = 0;
84 void clear_rx_buffer_(const LogString *reason, bool warn = false, size_t bytes_to_clear = 0);
85 bool send_frame_(const ModbusFrame &frame);
86 uint16_t find_frame_end_by_crc_(uint16_t min_length) const;
87
88 // All timestamps and durations below are micros()-based
96 // Bits on the wire per character (start + data + optional parity + stop); 12 at most.
97 uint8_t bits_per_char_{11};
98 // Latched when a read reaches rx_full_threshold, cleared when the buffer drains.
100
102
103 std::vector<uint8_t> rx_buffer_;
104#ifdef MODBUS_ON_REQUEST_COUNT
105 StaticCallbackManager<MODBUS_ON_REQUEST_COUNT, void(uint8_t, std::span<const uint8_t>)> request_callback_;
106#endif
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>)>
110#endif
111};
112
115
116// Transmit ordering, highest first: writes before one-shot reads before continuous polls.
117enum class CommandPriority : uint8_t { CONTINUOUS = 0, READ, WRITE };
118
119// Per-entry lifecycle state. Waiting states (see waiting_state()) hold the bus; the sweep delivers owed
120// callbacks from a quiescent hub, and an entry is erased once pending == 0 && !waiting_state().
121enum class FrameState : uint8_t {
122 READY = 0,
123 WAITING,
126 TIMED_OUT, // on_no_response delivered at the send-wait timeout; awaiting reschedule/erase
127 INTERRUPTED, // unexpected frame arrived; ignores this transaction, waits out the timeout
128 WAITING_RETIRED, // retired while WAITING: a late response is still delivered as its usual terminal
129 INTERRUPTED_RETIRED, // retired while INTERRUPTED: still distrusts late frames, ends in on_no_response
130 RETIRED, // retired, off the wire
131};
132
133// Per-command send options. Append-only; pass via designated initializers ({.continuous = true}).
134// A new field reaches the queue with no plumbing but arrives inert until it defines three rules:
135// normalization in queue_pdu(), a merge rule for duplicate absorption, and teardown in
136// retire()/silent_retire(). Bit-packed: stored per entry, controller and writer entity, passed by value.
138 // A continuous poll lives in the queue until cancelled or failed; ignored for mutating codes.
139 bool continuous : 1 {false};
140 // Wait for the reply to a read sent to address 0, for a device that answers the broadcast address.
141 bool allow_broadcast_read : 1 {false};
143};
144static_assert(sizeof(CommandOptions) == 1, "CommandOptions must stay one byte");
145
149 // Place-in-line stamp (hub's free-running counter); selection takes the oldest for round-robin
150 // fairness within a class. Meant to wrap.
151 uint16_t seq{0};
153 // Accepted requests this entry stands for, capped at max_pending(); drains one terminal each.
154 // A continuous poll is a subscription: pending fixed at 1, removed only by cancellation or failure.
155 uint8_t pending{1};
156 // The entry's LIVE effective options, not a record of the caller's request
158
159 // Build a command from a PDU span (caller bounds it to MAX_PDU_SIZE) and pre-normalized options;
160 // fully initialized here.
161 ModbusDeviceCommand(ModbusClientDevice *device, uint8_t address, std::span<const uint8_t> pdu,
162 CommandOptions options = {}, uint16_t seq = 0)
163 : device(device), frame(address, pdu.data(), static_cast<uint16_t>(pdu.size())), seq(seq), options(options) {}
164
166 if (this->options.continuous)
168 if (helpers::is_function_code_write(this->frame.pdu()[0])) {
170 }
172 }
173
174 // Requests this entry can serve
175 uint8_t max_pending() const {
176 const uint8_t fc = this->frame.pdu()[0];
177 return (helpers::is_function_code_read_only(fc) && !this->options.continuous) ? 2 : 1;
178 }
179 // Device-scoped clear: detach with no callback. An entry still waiting for a response keeps its state as a
180 // reply-ignoring shell that resolves silently; any other goes RETIRED.
182 if (!this->waiting_state())
184 this->pending = 0;
185 this->device = nullptr;
186 }
187 bool fire_and_forget() const {
188 return this->frame.address() == BROADCAST_ADDRESS && !this->options.allow_broadcast_read &&
189 !this->options.expect_broadcast_write_response;
190 }
191 // Fire-and-forget completion for a broadcast (address 0): the frame was transmitted (on_sent already
192 // fired), but a broadcast is never answered (Modbus 4.1), so the entry retires with no terminal callback.
195 this->pending = 0;
196 }
197 // Re-ready for another transmission, restamped to the tail of its class
198 void requeue(uint16_t seq) {
199 this->state = FrameState::READY;
200 this->seq = seq;
201 }
202 // Re-task a frame that lives on: upgrade a one-shot to a continuous poll, or downgrade a poll back to
203 // a one-shot.
204 void make_continuous(bool continuous) {
205 if (continuous) {
206 this->options.continuous = true;
207 this->pending = 1;
208 } else {
209 this->increment_pending();
210 this->options.continuous = false;
211 }
212 }
213 // Address-scoped clear: keep pending and device so the sweep delivers one on_not_sent() per un-delivered
214 // request. An entry still waiting for a response keeps its in-flight request (whose usual terminal is
215 // still coming) and drains only its duplicates.
216 void retire() {
217 if (this->state == FrameState::WAITING) {
219 } else if (this->state == FrameState::INTERRUPTED) {
221 } else if (!this->waiting_state()) { // an already-retired shell stays put; off the wire -> RETIRED
223 }
224 // Only continuous ends with the clear; the delivery flags must survive for a granted retry.
225 this->options.continuous = false;
226 }
227
228 // True while the entry is still waiting for a response
229 bool waiting_state() const {
230 return this->state == FrameState::WAITING || this->state == FrameState::INTERRUPTED ||
232 }
233
235 if (this->pending > 0) {
236 this->pending--;
237 return true;
238 }
239 return false;
240 }
241
243 if (this->pending < this->max_pending()) {
244 this->pending++;
245 return true;
246 }
247 return false;
248 }
249
250 // Terminal/lifecycle methods: each owns its transition, callback, and pending accounting and
251 // returns whether a callback ran.
252 bool sent();
253 bool response(std::span<const uint8_t> response_pdu);
254 bool error(ExceptionCode exception_code);
255 bool interrupt();
256 bool timed_out();
257 bool notify_retired();
258
260 bool same_frame(uint8_t address, std::span<const uint8_t> pdu) const {
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;
264 }
265};
266
267class ModbusClientHub : public Modbus {
268 public:
269 ModbusClientHub() = default;
270 void dump_config() override;
271 void loop() override;
272 // Config arrives in milliseconds; stored internally in microseconds like all other timing.
273 void set_send_wait_time(uint16_t time_in_ms) { this->send_wait_time_us_ = time_in_ms * 1000UL; }
274 void set_turnaround_time(uint16_t time_in_ms) { this->turnaround_delay_us_ = time_in_ms * 1000UL; }
275 bool tx_buffer_empty();
276 bool tx_blocked() override;
280 bool queue_pdu(uint8_t address, std::span<const uint8_t> pdu, ModbusClientDevice *device = nullptr,
282 // Remove before 2027.2.0. Deliberately the void, no-options signature 2026.7.4 shipped: nothing
283 // external can rely on the later additions under this name.
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",
286 "2026.8.0")
287 void send_pdu(uint8_t address, std::span<const uint8_t> pdu, ModbusClientDevice *device = nullptr) {
288 this->queue_pdu(address, pdu, device);
289 }
290 ESPDEPRECATED("Use queue_pdu(payload[0], <pdu bytes>, device) instead. Removed in 2027.2.0", "2026.8.0")
291 void send_raw(const std::vector<uint8_t> &payload, ModbusClientDevice *device = nullptr);
292 // Clear all commands matching the given address; each unsent request resolves via on_not_sent(), but a
293 // frame on the wire still runs to its usual terminal.
295 // Clear all commands for a given device; no callbacks are delivered.
297
298 protected:
299 int32_t tx_delay_remaining() override;
300 void parse_modbus_frames() override;
301 void process_modbus_server_frame(uint8_t address, std::span<const uint8_t> pdu) override;
302 void send_next_frame_();
303 // Deliver owed callbacks from a quiescent hub and apply lifecycle bookkeeping; see FrameState.
304 void sweep_();
305 // The selection function: best READY entry (ordered by priority; FIFO by seq within each group), or nullptr.
307 // Locate the single entry waiting for a response (WAITING/INTERRUPTED/WAITING_RETIRED/INTERRUPTED_RETIRED).
309 // End the wait for a response on send-wait timeout (the loop() watchdog body); see FrameState.
310 void expire_waiting_();
311
314
315 // Set on transmit, cleared on the transaction-ending transition; send_next_frame_ won't select
316 // while it is set, so at most one frame is awaiting a response.
318
319 // Set whenever a transition leaves owed callbacks behind; quiet loop() passes skip the sweep.
320 bool sweep_needed_{false};
321 // Monotonic stamp source for ModbusDeviceCommand::seq.
322 uint16_t next_seq_{0};
323
324 // Plain append-order container; ordering lives in select_next_ready_(), lifecycle in FrameState.
325 std::deque<ModbusDeviceCommand> tx_buffer_;
326};
327
328// Transaction status: std::nullopt on success, otherwise a Modbus exception code
329using ResponseStatus = std::optional<ExceptionCode>;
330
332inline bool succeeded(ResponseStatus status) { return !status.has_value(); }
333
334// Register values exchanged with server handlers, in address order. Sized at the larger of the two protocol
335// maxima (read = 125 / 0x7D, write = 123 / 0x7B); the per-direction count limit is enforced by the hub, not by
336// the capacity of this type.
338
339class ModbusServerHub : public Modbus {
340 public:
341 ModbusServerHub() = default;
342 void dump_config() override;
343 void register_device(ModbusServerDevice *device) { this->devices_.push_back(device); }
344
345 protected:
346 void parse_modbus_frames() override;
348 void process_modbus_server_frame(uint8_t address, std::span<const uint8_t> pdu) override;
349 void process_modbus_client_frame_(uint8_t address, uint8_t function_code, std::span<const uint8_t> data);
350 // Dispatches a broadcast (address 0) write to every registered device; broadcasts are never answered.
351 void process_broadcast_frame_(uint8_t function_code, std::span<const uint8_t> data);
352 // Parses a WRITE_SINGLE_REGISTER / WRITE_MULTIPLE_REGISTERS PDU into start_address and the address order register
353 // values, validating the register count and address range. Shared by unicast and broadcast writes.
354 ResponseStatus parse_write_single_(std::span<const uint8_t> data, uint16_t &start_address, RegisterValues &registers);
355 ResponseStatus parse_write_multiple_(std::span<const uint8_t> data, uint16_t &start_address,
356 RegisterValues &registers);
357 // Assembles host-order registers from the big-endian bytes in values and appends them to registers.
358 void assemble_registers_(std::span<const uint8_t> values, RegisterValues &registers);
360 // Returns std::nullopt if [start_address, start_address + count) fits in a 16-bit address space, otherwise
361 // ILLEGAL_DATA_ADDRESS. The caller sends the exception reply if one is required. Shared by the
362 // register/coil/discrete-input handlers, which all use a 16-bit address space.
363 ResponseStatus check_address_range_(uint16_t start_address, uint16_t count);
364
365 // Parses read request data. max_entities is the protocol ceiling for the function code; entity_name labels
366 // the rejection log.
367 ResponseStatus parse_read_request_(std::span<const uint8_t> data, uint16_t max_entities, const LogString *entity_name,
368 uint16_t &start_address, uint16_t &count);
369
370 // Parses single-coil write data
371 ResponseStatus parse_write_single_coil_(std::span<const uint8_t> data, uint16_t &start_address, bool &value);
372
373 // Parses write-multiple-coil data into a packed-bit view pointing straight into the receive buffer, so the
374 // coil values are never copied.
375 ResponseStatus parse_write_multiple_coils_(std::span<const uint8_t> data, uint16_t &start_address, uint16_t &count,
376 std::span<const uint8_t> &packed_bytes);
377
378 // Builds the body of a register read response into response_buffer. Returns false once an exception has
379 // been sent: the one the handler reported via status, or SERVICE_DEVICE_FAILURE if it returned the wrong
380 // number of registers, the count exceeds the protocol read limit, or the body does not fit.
381 bool build_or_reject_read_response_(uint8_t address, uint8_t function_code, ResponseStatus status,
382 uint16_t number_of_registers, const RegisterValues &registers,
383 std::span<uint8_t> response_buffer, uint16_t &response_len);
384 void send_raw_(const uint8_t *payload, uint16_t len);
385 // Every reply of this hub goes on the wire here, so on_response sees each one once, exceptions included.
386 bool send_reply_(const ModbusFrame &frame);
387 // Sends and logs the exception reply when status holds one; returns true if the request was rejected.
388 bool rejected_(uint8_t address, uint8_t function_code, ResponseStatus status);
389 void send_exception_(uint8_t address, uint8_t function_code, ExceptionCode exception_code);
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
393 // The last request, for on_response with its reply from a device here or another one.
394 uint8_t request_len_{0};
395 uint8_t request_[MAX_PDU_SIZE];
396#endif
397 std::vector<ModbusServerDevice *> devices_;
398
399 // Holds the raw payload of a single reply deferred for sending when tx was blocked at send time.
400 // Only one server reply can be waiting at once, so a single fixed buffer avoids heap allocation.
401 std::array<uint8_t, MAX_RAW_SIZE> deferred_payload_;
403};
404
425 public:
429 if (this->parent_ != nullptr)
430 this->clear_tx_queue_for_device();
431 }
436 void set_parent(ModbusClientHub *parent) { this->parent_ = parent; }
437 void set_address(uint8_t address) { this->address_ = address; }
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);
444 }
448 virtual void on_error(std::span<const uint8_t> request_pdu, ExceptionCode exception_code) {
449 this->dispatch_response_(request_pdu, {}, exception_code);
450 }
453 virtual void on_not_sent(std::span<const uint8_t> request_pdu) {
454#pragma GCC diagnostic push
455#pragma GCC diagnostic ignored "-Wdeprecated-declarations"
456 this->on_modbus_not_sent();
457#pragma GCC diagnostic pop
458 }
460 virtual void on_sent(std::span<const uint8_t> request_pdu) {}
463 virtual bool on_no_response(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
468 }
472 virtual void on_response(uint8_t address, std::span<const uint8_t> request_pdu,
473 std::span<const uint8_t> response_pdu) {
474 this->on_response(request_pdu, response_pdu);
475 }
476 virtual void on_error(uint8_t address, std::span<const uint8_t> request_pdu, ExceptionCode exception_code) {
477 this->on_error(request_pdu, exception_code);
478 }
479 virtual void on_not_sent(uint8_t address, std::span<const uint8_t> request_pdu) { this->on_not_sent(request_pdu); }
480 virtual void on_sent(uint8_t address, std::span<const uint8_t> request_pdu) { this->on_sent(request_pdu); }
481 virtual bool on_no_response(uint8_t address, std::span<const uint8_t> request_pdu) {
482 return this->on_no_response(request_pdu);
483 }
484 // Remove before 2027.2.0
485 ESPDEPRECATED("Override on_not_sent() instead. Removed in 2027.2.0", "2026.8.0")
486 virtual void on_modbus_not_sent() {}
487 // Remove before 2027.2.0
488 ESPDEPRECATED("Override on_no_response() instead. Removed in 2027.2.0", "2026.8.0")
489 virtual bool on_modbus_no_response() { return false; }
490
495 virtual void on_read_registers(EntityType entity_type, uint16_t start_address, std::span<const uint16_t> registers,
496 ResponseStatus status) {}
497 virtual void on_read_holding_registers(uint16_t start_address, std::span<const uint16_t> registers,
498 ResponseStatus status) {
499 this->on_read_registers(EntityType::HOLDING, start_address, registers, status);
500 }
501 virtual void on_read_input_registers(uint16_t start_address, std::span<const uint16_t> registers,
502 ResponseStatus status) {
503 this->on_read_registers(EntityType::INPUT_REGISTER, start_address, registers, status);
504 }
508 virtual void on_read_bits(EntityType entity_type, uint16_t start_address, PackedBits bits, ResponseStatus status) {}
509 virtual void on_read_coils(uint16_t start_address, PackedBits bits, ResponseStatus status) {
510 this->on_read_bits(EntityType::COIL, start_address, bits, status);
511 }
512 virtual void on_read_discrete_inputs(uint16_t start_address, PackedBits bits, ResponseStatus status) {
513 this->on_read_bits(EntityType::DISCRETE_INPUT, start_address, bits, status);
514 }
524 virtual void on_write_single_register(uint16_t address, uint16_t value, ResponseStatus status) {}
525 virtual void on_write_single_coil(uint16_t address, bool value, ResponseStatus status) {}
526 virtual void on_write_multiple_registers(uint16_t start_address, std::span<const uint16_t> registers,
527 ResponseStatus status) {}
528 virtual void on_write_multiple_coils(uint16_t start_address, PackedBits bits, ResponseStatus status) {}
533 virtual void on_custom_response(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu,
534 ResponseStatus status);
535 ESPDEPRECATED("Use the typed read_*/write_* helpers or queue_pdu() instead. Removed in 2027.2.0", "2026.8.0")
536 void send(uint8_t function, uint16_t start_address, uint16_t number_of_entities, uint8_t payload_len = 0,
537 const uint8_t *payload = nullptr) {
538 this->parent_->queue_pdu(
539 this->address_,
541 this);
542 }
544 bool queue_pdu(std::span<const uint8_t> pdu, CommandOptions options = {}) {
545 return this->parent_->queue_pdu(this->address_, pdu, this, options);
546 }
547 // Remove before 2027.2.0. As on the hub, this is the signature 2026.7.4 shipped: void, no options.
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",
550 "2026.8.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")
553 void send_raw(const std::vector<uint8_t> &payload) {
554 if (payload.empty())
555 return; // too short to contain a PDU; refused at the door like any invalid send
556 this->parent_->queue_pdu(payload[0], std::span<const uint8_t>(payload).subspan(1), this);
557 }
558 // The typed request builders below all queue through queue_pdu() and share its return contract.
559 // Reads use the table-appropriate function code; an unreadable entity type maps to INVALID, which
560 // create_read_pdu() rejects into an empty PDU and queue_pdu() refuses with a false return.
561 bool read_entities(EntityType entity_type, uint16_t start_address, uint16_t number_of_entities,
562 CommandOptions options = {}) {
565 options);
566 }
567 bool read_input_registers(uint16_t start_address, uint16_t number_of_registers, CommandOptions options = {}) {
568 return this->queue_pdu(
570 }
571 bool read_holding_registers(uint16_t start_address, uint16_t number_of_registers, CommandOptions options = {}) {
572 return this->queue_pdu(
574 }
575 bool read_coils(uint16_t start_address, uint16_t number_of_coils, CommandOptions options = {}) {
576 return this->queue_pdu(helpers::create_read_pdu(FunctionCode::READ_COILS, start_address, number_of_coils), options);
577 }
578 bool read_discrete_inputs(uint16_t start_address, uint16_t number_of_inputs, CommandOptions options = {}) {
579 return this->queue_pdu(
581 }
582 bool write_single_register(uint16_t start_address, uint16_t value, CommandOptions options = {}) {
584 }
585 bool write_single_coil(uint16_t address, bool value, CommandOptions options = {}) {
587 }
588 bool write_multiple_registers(uint16_t start_address, std::span<const uint16_t> values, CommandOptions options = {}) {
589 // Empty goes to the full-size builder so the rejection log names this method's limit, not the small one's.
590 if (!values.empty() && values.size() <= helpers::MAX_FEW_REGISTERS)
591 return this->queue_pdu(helpers::create_write_few_registers_pdu(start_address, values), options);
592 return this->queue_pdu(helpers::create_write_registers_pdu(start_address, values), options);
593 }
596 bool write_multiple_coils(uint16_t start_address, std::span<const bool> values, CommandOptions options = {}) {
597 return this->queue_pdu(helpers::create_write_coils_pdu(start_address, values), options);
598 }
601 bool write_multiple_coils(uint16_t start_address, PackedBits bits, CommandOptions options = {}) {
602 return this->queue_pdu(helpers::create_write_coils_pdu(start_address, bits), options);
603 }
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) {
609 return this->queue_pdu(helpers::create_read_write_multiple_registers_pdu(read_start_address, read_count,
610 write_start_address, write_values));
611 }
612 inline void clear_tx_queue_for_address() { this->parent_->clear_tx_queue_for_address(this->address_); }
613 inline void clear_tx_queue_for_device() { this->parent_->clear_tx_queue_for_device(this); }
614
615 bool ready_for_immediate_send() { return this->parent_->tx_buffer_empty() && !this->parent_->tx_blocked(); }
616
617 protected:
619 void dispatch_response_(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu,
620 ResponseStatus status);
621
623 uint8_t address_{0};
624 bool custom_response_warned_{false}; // first unhandled custom response warns; repeats log at VERBOSE
625};
626
627// Compatibility shim adapting the span-based hooks back to the pre-2026.8 on_modbus_data()/
628// on_modbus_error() signatures (the owning-vector heap copy exists only on this deprecated path).
629// Remove before 2027.2.0 (window restarted when the plain alias became a behavior shim in 2026.8.0).
630class ESPDEPRECATED("Subclass ModbusClientDevice and override on_response()/on_error() instead. Removed in 2027.2.0",
631 "2026.8.0") ModbusDevice : public ModbusClientDevice {
632 public:
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) {}
636
637 void on_response(std::span<const uint8_t> request_pdu, std::span<const uint8_t> response_pdu) override {
638 // Custom (user-defined) function codes historically delivered the payload starting AT the function
639 // code byte (frame data_offset 1). server_pdu_payload() drops that byte, so pass the whole PDU for
640 // them - external components match the first byte against the code they sent (issue #17994).
641 auto payload = !response_pdu.empty() && helpers::is_function_code_custom(response_pdu[0])
642 ? response_pdu
643 : helpers::server_pdu_payload(response_pdu);
644 this->on_modbus_data(std::vector<uint8_t>(payload.begin(), payload.end()));
645 }
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));
648 }
649};
650
652 public:
653 virtual ~ModbusServerDevice() = default;
655 // Polymorphic base: non-copyable and non-movable to prevent slicing (Rule of Five).
660 void set_address(uint8_t address) { this->address_ = address; }
661 uint8_t get_address() const { return this->address_; }
662 virtual ResponseStatus on_read_registers(uint16_t start_address, uint16_t number_of_registers,
663 RegisterValues &registers) {
665 };
666 virtual ResponseStatus on_read_input_registers(uint16_t start_address, uint16_t number_of_registers,
667 RegisterValues &registers) {
668 return this->on_read_registers(start_address, number_of_registers, registers);
669 };
670 virtual ResponseStatus on_read_holding_registers(uint16_t start_address, uint16_t number_of_registers,
671 RegisterValues &registers) {
672 return this->on_read_registers(start_address, number_of_registers, registers);
673 };
674 virtual ResponseStatus on_write_registers(uint16_t start_address, const RegisterValues &registers) {
676 };
680 virtual ResponseStatus on_read_bits(uint16_t start_address, MutablePackedBits bits) {
682 };
683 virtual ResponseStatus on_read_coils(uint16_t start_address, MutablePackedBits bits) {
684 return this->on_read_bits(start_address, bits);
685 };
686 virtual ResponseStatus on_read_discrete_inputs(uint16_t start_address, MutablePackedBits bits) {
687 return this->on_read_bits(start_address, bits);
688 };
691 virtual ResponseStatus on_write_coils(uint16_t start_address, PackedBits bits) {
693 };
694
695 protected:
696 uint8_t address_{0};
697};
698
699} // namespace esphome::modbus
uint8_t status
Definition bl0942.h:8
Small buffer optimization - stores data inline when small, heap-allocates for large data This avoids ...
Definition helpers.h:224
uint8_t * init(size_t size)
Resize to size bytes of (uninitialized) storage and return a writable pointer to fill.
Definition helpers.h:272
size_t size() const
Definition helpers.h:291
CallbackManager backed by StaticVector for compile-time-known callback counts.
Definition helpers.h:2047
Minimal static vector - saves memory by avoiding std::vector overhead.
Definition helpers.h:304
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...
Definition modbus.h:442
virtual void on_write_multiple_coils(uint16_t start_address, PackedBits bits, ResponseStatus status)
Definition modbus.h:528
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...
Definition modbus.h:472
virtual void on_error(uint8_t address, std::span< const uint8_t > request_pdu, ExceptionCode exception_code)
Definition modbus.h:476
virtual void on_read_holding_registers(uint16_t start_address, std::span< const uint16_t > registers, ResponseStatus status)
Definition modbus.h:497
virtual void on_write_multiple_registers(uint16_t start_address, std::span< const uint16_t > registers, ResponseStatus status)
Definition modbus.h:526
virtual void on_sent(std::span< const uint8_t > request_pdu)
Called when this device's frame is actually written to the wire.
Definition modbus.h:460
ModbusClientDevice(const ModbusClientDevice &)=delete
virtual void on_write_single_register(uint16_t address, uint16_t value, ResponseStatus status)
Write acknowledgements.
Definition modbus.h:524
uint16_t uint16_t uint8_t payload_len
Definition modbus.h:536
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,...
Definition modbus.h:508
virtual void on_not_sent(uint8_t address, std::span< const uint8_t > request_pdu)
Definition modbus.h:479
virtual bool on_no_response(uint8_t address, std::span< const uint8_t > request_pdu)
Definition modbus.h:481
ModbusClientDevice & operator=(const ModbusClientDevice &)=delete
void set_parent(ModbusClientHub *parent)
Definition modbus.h:436
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...
Definition modbus.h:463
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...
Definition modbus.cpp:1439
virtual void on_sent(uint8_t address, std::span< const uint8_t > request_pdu)
Definition modbus.h:480
ModbusClientDevice(ModbusClientDevice &&)=delete
virtual void on_read_discrete_inputs(uint16_t start_address, PackedBits bits, ResponseStatus status)
Definition modbus.h:512
uint16_t uint16_t number_of_entities
Definition modbus.h:536
ESPDEPRECATED("Override on_no_response() instead. Removed in 2027.2.0", "2026.8.0") virtual bool on_modbus_no_response()
Definition modbus.h:488
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...
Definition modbus.h:495
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...
Definition modbus.h:448
ModbusClientDevice(ModbusClientHub *parent, uint8_t address)
Definition modbus.h:427
void set_address(uint8_t address)
Definition modbus.h:437
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().
Definition modbus.h:453
virtual void on_read_coils(uint16_t start_address, PackedBits bits, ResponseStatus status)
Definition modbus.h:509
virtual void on_write_single_coil(uint16_t address, bool value, ResponseStatus status)
Definition modbus.h:525
uint16_t uint16_t uint8_t const uint8_t * payload
Definition modbus.h:537
virtual void on_read_input_registers(uint16_t start_address, std::span< const uint16_t > registers, ResponseStatus status)
Definition modbus.h:501
ESPDEPRECATED("Override on_not_sent() instead. Removed in 2027.2.0", "2026.8.0") virtual void on_modbus_not_sent()
Definition modbus.h:485
void clear_tx_queue_for_device(ModbusClientDevice *device)
Definition modbus.cpp:1204
void parse_modbus_frames() override
Definition modbus.cpp:193
ModbusDeviceCommand * find_waiting_()
Definition modbus.cpp:947
std::span< const uint8_t > pdu
Definition modbus.h:287
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_()
Definition modbus.cpp:955
int32_t tx_delay_remaining() override
Definition modbus.cpp:140
std::deque< ModbusDeviceCommand > tx_buffer_
Definition modbus.h:325
std::span< const uint8_t > ModbusClientDevice * device
Definition modbus.h:287
bool queue_pdu(uint8_t address, std::span< const uint8_t > pdu, ModbusClientDevice *device=nullptr, CommandOptions options={})
Queue a request.
Definition modbus.cpp:1091
void clear_tx_queue_for_address(uint8_t address)
Definition modbus.cpp:1194
void process_modbus_server_frame(uint8_t address, std::span< const uint8_t > pdu) override
Definition modbus.cpp:351
void set_send_wait_time(uint16_t time_in_ms)
Definition modbus.h:273
void set_turnaround_time(uint16_t time_in_ms)
Definition modbus.h:274
void set_flow_control_pin(GPIOPin *flow_control_pin)
Definition modbus.h:62
void setup() override
Definition modbus.cpp:31
void add_on_response_callback(F &&callback)
Every response received (client) or sent or seen (server); PDUs valid during the call.
Definition modbus.h:72
uint32_t long_rx_buffer_delay_us_
Definition modbus.h:94
virtual void process_modbus_server_frame(uint8_t address, std::span< const uint8_t > pdu)=0
bool parse_modbus_server_frame_()
Definition modbus.cpp:269
virtual void parse_modbus_frames()=0
bool send_frame_(const ModbusFrame &frame)
Definition modbus.cpp:806
StaticCallbackManager< MODBUS_ON_RESPONSE_COUNT, void(uint8_t, std::span< const uint8_t >, std::span< const uint8_t >)> response_callback_
Definition modbus.h:109
uint32_t last_modbus_byte_
Definition modbus.h:89
GPIOPin * flow_control_pin_
Definition modbus.h:101
uint32_t last_send_tx_offset_
Definition modbus.h:92
virtual bool tx_blocked()
Definition modbus.cpp:148
void clear_rx_buffer_(const LogString *reason, bool warn=false, size_t bytes_to_clear=0)
Definition modbus.cpp:1270
void loop() override
Definition modbus.cpp:63
uint32_t frame_delay_us_
Definition modbus.h:93
float get_setup_priority() const override
Definition modbus.cpp:906
void add_on_request_callback(F &&callback)
Every request read (server, before a device answers) or sent (client, retries included); PDU valid in...
Definition modbus.h:65
bool exceeded_rx_full_threshold_
Definition modbus.h:99
virtual int32_t tx_delay_remaining()
Definition modbus.cpp:134
uint16_t find_frame_end_by_crc_(uint16_t min_length) const
Definition modbus.cpp:249
std::vector< uint8_t > rx_buffer_
Definition modbus.h:103
uint32_t rx_detect_latency_us_
Definition modbus.h:95
uint32_t last_receive_check_
Definition modbus.h:90
StaticCallbackManager< MODBUS_ON_REQUEST_COUNT, void(uint8_t, std::span< const uint8_t >)> request_callback_
Definition modbus.h:105
ModbusServerDevice & operator=(ModbusServerDevice &&)=delete
virtual ResponseStatus on_read_coils(uint16_t start_address, MutablePackedBits bits)
Definition modbus.h:683
ModbusServerDevice(const ModbusServerDevice &)=delete
ModbusServerDevice & operator=(const ModbusServerDevice &)=delete
void set_address(uint8_t address)
Definition modbus.h:660
virtual ResponseStatus on_write_registers(uint16_t start_address, const RegisterValues &registers)
Definition modbus.h:674
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....
Definition modbus.h:680
virtual ResponseStatus on_read_holding_registers(uint16_t start_address, uint16_t number_of_registers, RegisterValues &registers)
Definition modbus.h:670
virtual ResponseStatus on_read_registers(uint16_t start_address, uint16_t number_of_registers, RegisterValues &registers)
Definition modbus.h:662
virtual ResponseStatus on_read_discrete_inputs(uint16_t start_address, MutablePackedBits bits)
Definition modbus.h:686
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 ...
Definition modbus.h:691
virtual ResponseStatus on_read_input_registers(uint16_t start_address, uint16_t number_of_registers, RegisterValues &registers)
Definition modbus.h:666
ModbusServerDevice(ModbusServerDevice &&)=delete
std::vector< ModbusServerDevice * > devices_
Definition modbus.h:397
ResponseStatus check_address_range_(uint16_t start_address, uint16_t count)
Definition modbus.cpp:440
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)
Definition modbus.cpp:486
void process_modbus_client_frame_(uint8_t address, uint8_t function_code, std::span< const uint8_t > data)
Definition modbus.cpp:636
void parse_modbus_frames() override
Definition modbus.cpp:206
void process_modbus_server_frame(uint8_t address, std::span< const uint8_t > pdu) override
Definition modbus.cpp:407
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)
Definition modbus.cpp:513
void process_broadcast_frame_(uint8_t function_code, std::span< const uint8_t > data)
Definition modbus.cpp:538
void register_device(ModbusServerDevice *device)
Definition modbus.h:343
ModbusServerDevice * find_device_(uint8_t address)
Definition modbus.cpp:431
bool send_reply_(const ModbusFrame &frame)
Definition modbus.cpp:1259
ResponseStatus parse_write_single_coil_(std::span< const uint8_t > data, uint16_t &start_address, bool &value)
Definition modbus.cpp:500
bool build_or_reject_read_response_(uint8_t address, uint8_t function_code, ResponseStatus status, uint16_t number_of_registers, const RegisterValues &registers, std::span< uint8_t > response_buffer, uint16_t &response_len)
Definition modbus.cpp:593
void send_exception_(uint8_t address, uint8_t function_code, ExceptionCode exception_code)
Definition modbus.cpp:939
void assemble_registers_(std::span< const uint8_t > values, RegisterValues &registers)
Definition modbus.cpp:532
void send_raw_(const uint8_t *payload, uint16_t len)
Definition modbus.cpp:1224
uint8_t request_[MAX_PDU_SIZE]
Definition modbus.h:395
void send_response_(uint8_t address, uint8_t function_code, const uint8_t *payload, uint16_t payload_len)
Definition modbus.cpp:911
ResponseStatus parse_write_multiple_(std::span< const uint8_t > data, uint16_t &start_address, RegisterValues &registers)
Definition modbus.cpp:469
bool rejected_(uint8_t address, uint8_t function_code, ResponseStatus status)
Definition modbus.cpp:926
ResponseStatus parse_write_single_(std::span< const uint8_t > data, uint16_t &start_address, RegisterValues &registers)
Definition modbus.cpp:461
std::array< uint8_t, MAX_RAW_SIZE > deferred_payload_
Definition modbus.h:401
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),...
uint8_t options
unsigned count
Definition gif.cpp:51
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
Definition modbus.h:329
bool succeeded(ResponseStatus status)
True when a transaction carried no exception.
Definition modbus.h:332
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.
Definition helpers.cpp:95
uint32_t value
Definition hal.cpp:41
const void size_t len
Definition hal.h:68
uint16_t size
Definition helpers.cpp:34
STL namespace.
static void uint32_t
bool response(std::span< const uint8_t > response_pdu)
Definition modbus.cpp:990
CommandPriority priority() const
Definition modbus.h:165
ModbusDeviceCommand(ModbusClientDevice *device, uint8_t address, std::span< const uint8_t > pdu, CommandOptions options={}, uint16_t seq=0)
Definition modbus.h:161
void make_continuous(bool continuous)
Definition modbus.h:204
bool error(ExceptionCode exception_code)
Definition modbus.cpp:1001
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.
Definition modbus.h:260
ModbusClientDevice * device
Definition modbus.h:147
ModbusFrame(uint8_t address, const uint8_t *pdu, uint16_t pdu_len)
Definition modbus.h:36
uint8_t address() const
Definition modbus.h:46
SmallInlineBuffer< MODBUS_FRAME_INLINE_SIZE > data
Definition modbus.h:33
std::span< const uint8_t > pdu() const
A PDU is [function code][data...] without address or CRC.
Definition modbus.h:49
uint16_t size() const
Definition modbus.h:45