A single modbus command. More...

#include <modbus_controller.h>

Inheritance diagram for esphome::modbus_controller::ModbusCommandItem:

Public Member Functions
	ModbusCommandItem (ModbusController &controller, modbus::ModbusClientHub *parent, uint8_t address)
	Empty command with no controller connection (kept for source compatibility with value-type usage).

	ModbusCommandItem (ModbusController &controller, modbus::ModbusClientHub *parent, uint8_t address, RegisterRange &&range)
	Read command built from a range; the read PDU is rebuilt from these fields at send time.

	ModbusCommandItem (ModbusController &controller, modbus::ModbusClientHub parent, uint8_t address, SensorItem sensor)
	Custom polling command: the PDU bytes are referenced from the sensor (not copied); responses are dispatched to that sensor.

	ModbusCommandItem (const ModbusCommandItem &other)

	ModbusCommandItem (ModbusCommandItem &&other) noexcept

ModbusCommandItem &	operator= (ModbusCommandItem &&)=delete

void	on_response (std::span< const uint8_t > request_pdu, std::span< const uint8_t > response_pdu) override
	called when a modbus response was parsed without errors

void	on_error (std::span< const uint8_t > request_pdu, modbus::ExceptionCode exception_code) override
	called when a modbus error (exception) response was received

void	on_not_sent (std::span< const uint8_t > request_pdu) override
	called when the command could not be sent

void	on_sent (std::span< const uint8_t > request_pdu) override
	called when the command's frame is actually written to the wire; fires the on_command_sent trigger

bool	on_no_response (std::span< const uint8_t > request_pdu) override
	called on timeout; returns true to have the hub re-queue the frame for a retry

uint16_t	register_address () const

uint16_t	register_count () const

EntityType	register_type () const

bool	send ()
	Queue this command's frame on the hub.

Public Member Functions inherited from esphome::modbus::ModbusClientDevice
	ModbusClientDevice ()=default

	ModbusClientDevice (ModbusClientHub *parent, uint8_t address)

virtual	~ModbusClientDevice ()

	ModbusClientDevice (const ModbusClientDevice &)=delete

ModbusClientDevice &	operator= (const ModbusClientDevice &)=delete

	ModbusClientDevice (ModbusClientDevice &&)=delete

ModbusClientDevice &	operator= (ModbusClientDevice &&)=delete

void	set_parent (ModbusClientHub *parent)

void	set_address (uint8_t address)

	ESPDEPRECATED ("Override on_not_sent() instead. Removed in 2027.2.0", "2026.8.0") virtual void on_modbus_not_sent()

	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 parsed from the request and response PDUs.

virtual void	on_read_holding_registers (uint16_t start_address, std::span< const uint16_t > registers, ResponseStatus status)

virtual void	on_read_input_registers (uint16_t start_address, std::span< const uint16_t > registers, ResponseStatus status)

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, bits.size() = the count requested).

virtual void	on_read_coils (uint16_t start_address, PackedBits bits, ResponseStatus status)

virtual void	on_read_discrete_inputs (uint16_t start_address, PackedBits bits, ResponseStatus status)

virtual void	on_write_single_register (uint16_t address, uint16_t value, ResponseStatus status)
	Write acknowledgements.

virtual void	on_write_single_coil (uint16_t address, bool value, ResponseStatus status)

virtual void	on_write_multiple_registers (uint16_t start_address, std::span< const uint16_t > registers, ResponseStatus status)

virtual void	on_write_multiple_coils (uint16_t start_address, PackedBits bits, ResponseStatus status)

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 dispatch_response_()); on failure the response is empty and the exception code is in status.

	ESPDEPRECATED ("Use the typed read_/write_ helpers or queue_pdu() instead. Removed in 2027.2.0", "2026.8.0") void send(uint8_t function

Static Public Member Functions
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)
	factory methods

static ModbusCommandItem	create_write_multiple_command (ModbusController *modbusdevice, uint16_t start_address, uint16_t register_count, const std::vector< uint16_t > &values)
	Create modbus read command Function code 02-04.

static ModbusCommandItem	create_write_single_command (ModbusController *modbusdevice, uint16_t start_address, uint16_t value)
	Create modbus write multiple registers command Function 16 (10hex) Write Multiple Registers.

static ModbusCommandItem	create_write_single_coil (ModbusController *modbusdevice, uint16_t address, bool value)
	Create modbus write single registers command Function 05 (05hex) Write Single Coil.

static ModbusCommandItem	create_write_multiple_coils (ModbusController *modbusdevice, uint16_t start_address, const std::vector< bool > &values)
	Create modbus write multiple registers command Function 15 (0Fhex) Write Multiple Coils.

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)
	Create custom modbus command.

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)
	Create custom modbus command.

Data Fields
SensorSet	sensors

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
	Write data bytes for the command (register/coil values), or the raw frame of a one-shot custom command; reads leave it empty.

bool	pending_removal {false}

Data Fields inherited from esphome::modbus::ModbusClientDevice
uint16_t	start_address

uint16_t uint16_t	number_of_entities

uint16_t uint16_t uint8_t	payload_len = 0

uint16_t uint16_t uint8_t const uint8_t *	payload

ModbusClientHub *	parent_ {nullptr}

uint8_t	address_ {0}

bool	custom_response_warned_ {false}

Protected Member Functions
void	set_command_ (FunctionCode function_code, EntityType register_type, uint16_t start_address, uint16_t register_count)

Protected Attributes
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}
	Custom polling commands reference the PDU bytes owned by their SensorItem instead of copying them.

ModbusController *	controller_ {nullptr}

Detailed Description

A single modbus command.

Each command is its own ModbusClientDevice: it sends its frame to the hub and the hub routes the response back to this object's on_modbus_* callbacks, so the controller no longer has to match responses to a FIFO queue.

Definition at line 240 of file modbus_controller.h.

Constructor & Destructor Documentation

◆ ModbusCommandItem() [1/5]

esphome::modbus_controller::ModbusCommandItem::ModbusCommandItem	(	ModbusController &	controller,
		modbus::ModbusClientHub *	parent,
		uint8_t	address )

inline

Empty command with no controller connection (kept for source compatibility with value-type usage).

Definition at line 243 of file modbus_controller.h.

◆ ModbusCommandItem() [2/5]

esphome::modbus_controller::ModbusCommandItem::ModbusCommandItem	(	ModbusController &	controller,
		modbus::ModbusClientHub *	parent,
		uint8_t	address,
		RegisterRange &&	range )

Read command built from a range; the read PDU is rebuilt from these fields at send time.

Definition at line 13 of file modbus_controller.cpp.

◆ ModbusCommandItem() [3/5]

esphome::modbus_controller::ModbusCommandItem::ModbusCommandItem	(	ModbusController &	controller,
		modbus::ModbusClientHub *	parent,
		uint8_t	address,
		SensorItem *	sensor )

Custom polling command: the PDU bytes are referenced from the sensor (not copied); responses are dispatched to that sensor.

Definition at line 24 of file modbus_controller.cpp.

◆ ModbusCommandItem() [4/5]

esphome::modbus_controller::ModbusCommandItem::ModbusCommandItem ( const ModbusCommandItem & other )

Definition at line 40 of file modbus_controller.cpp.

◆ ModbusCommandItem() [5/5]

esphome::modbus_controller::ModbusCommandItem::ModbusCommandItem ( ModbusCommandItem && other )

noexcept

Definition at line 55 of file modbus_controller.cpp.

Member Function Documentation

◆ create_custom_command() [1/2]

ModbusCommandItem esphome::modbus_controller::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 )

static

Create custom modbus command.

Parameters

modbusdevice	pointer to the device to execute the command
values	word vector of data to be sent to the device. The complete payload must be provided with the exception of the crc codes
handler	function called when the response is received. Default is just logging a response

Returns: ModbusCommandItem with the prepared command

Definition at line 491 of file modbus_controller.cpp.

◆ create_custom_command() [2/2]

ModbusCommandItem esphome::modbus_controller::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

Create custom modbus command.

Parameters

modbusdevice	pointer to the device to execute the command
values	byte vector of data to be sent to the device. The complete payload must be provided with the exception of the crc codes
handler	function called when the response is received. Default is just logging a response

Returns: ModbusCommandItem with the prepared command

Definition at line 474 of file modbus_controller.cpp.

◆ create_read_command()

ModbusCommandItem esphome::modbus_controller::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

factory methods

Create modbus read command Function code 02-04

Parameters

modbusdevice	pointer to the device to execute the command
function_code	modbus function code for the read command
start_address	modbus address of the first register to read
register_count	number of registers to read
handler	function called when the response is received

Returns: ModbusCommandItem with the prepared command

Definition at line 398 of file modbus_controller.cpp.

◆ create_write_multiple_coils()

ModbusCommandItem esphome::modbus_controller::ModbusCommandItem::create_write_multiple_coils	(	ModbusController *	modbusdevice,
		uint16_t	start_address,
		const std::vector< bool > &	values )

static

Create modbus write multiple registers command Function 15 (0Fhex) Write Multiple Coils.

Parameters

modbusdevice	pointer to the device to execute the command
start_address	modbus address of the first register to read
value	bool vector of values to be written to the registers

Returns: ModbusCommandItem with the prepared command

Definition at line 438 of file modbus_controller.cpp.

◆ create_write_multiple_command()

ModbusCommandItem esphome::modbus_controller::ModbusCommandItem::create_write_multiple_command	(	ModbusController *	modbusdevice,
		uint16_t	start_address,
		uint16_t	register_count,
		const std::vector< uint16_t > &	values )

static

Create modbus read command Function code 02-04.

Parameters

modbusdevice	pointer to the device to execute the command
function_code	modbus function code for the read command
start_address	modbus address of the first register to read
register_count	number of registers to read
handler	function called when the response is received

Returns: ModbusCommandItem with the prepared command

Definition at line 408 of file modbus_controller.cpp.

◆ create_write_single_coil()

ModbusCommandItem esphome::modbus_controller::ModbusCommandItem::create_write_single_coil	(	ModbusController *	modbusdevice,
		uint16_t	address,
		bool	value )

static

Create modbus write single registers command Function 05 (05hex) Write Single Coil.

Parameters

modbusdevice	pointer to the device to execute the command
start_address	modbus address of the first register to read
value	uint16_t data to be written to the registers

Returns: ModbusCommandItem with the prepared command

Definition at line 425 of file modbus_controller.cpp.

◆ create_write_single_command()

ModbusCommandItem esphome::modbus_controller::ModbusCommandItem::create_write_single_command	(	ModbusController *	modbusdevice,
		uint16_t	start_address,
		uint16_t	value )

static

Create modbus write multiple registers command Function 16 (10hex) Write Multiple Registers.

Parameters

modbusdevice	pointer to the device to execute the command
start_address	modbus address of the first register to read
register_count	number of registers to read
value	uint16_t single register value to write

Returns: ModbusCommandItem with the prepared command

Definition at line 459 of file modbus_controller.cpp.

◆ on_error()

void esphome::modbus_controller::ModbusCommandItem::on_error	(	std::span< const uint8_t >	request_pdu,
		modbus::ExceptionCode	exception_code )

overridevirtual

called when a modbus error (exception) response was received

Reimplemented from esphome::modbus::ModbusClientDevice.

Definition at line 88 of file modbus_controller.cpp.

◆ on_no_response()

bool esphome::modbus_controller::ModbusCommandItem::on_no_response ( std::span< const uint8_t > request_pdu )

overridevirtual

called on timeout; returns true to have the hub re-queue the frame for a retry

Reimplemented from esphome::modbus::ModbusClientDevice.

Definition at line 130 of file modbus_controller.cpp.

◆ on_not_sent()

void esphome::modbus_controller::ModbusCommandItem::on_not_sent ( std::span< const uint8_t > request_pdu )

overridevirtual

called when the command could not be sent

Reimplemented from esphome::modbus::ModbusClientDevice.

Definition at line 99 of file modbus_controller.cpp.

◆ on_response()

void esphome::modbus_controller::ModbusCommandItem::on_response	(	std::span< const uint8_t >	request_pdu,
		std::span< const uint8_t >	response_pdu )

overridevirtual

called when a modbus response was parsed without errors

Reimplemented from esphome::modbus::ModbusClientDevice.

Definition at line 71 of file modbus_controller.cpp.

◆ on_sent()

void esphome::modbus_controller::ModbusCommandItem::on_sent ( std::span< const uint8_t > request_pdu )

overridevirtual

called when the command's frame is actually written to the wire; fires the on_command_sent trigger

Reimplemented from esphome::modbus::ModbusClientDevice.

Definition at line 111 of file modbus_controller.cpp.

◆ operator=()

ModbusCommandItem & esphome::modbus_controller::ModbusCommandItem::operator= ( ModbusCommandItem && )

delete

◆ register_address()

uint16_t esphome::modbus_controller::ModbusCommandItem::register_address ( ) const

inline

Definition at line 283 of file modbus_controller.h.

◆ register_count()

uint16_t esphome::modbus_controller::ModbusCommandItem::register_count ( ) const

inline

Definition at line 284 of file modbus_controller.h.

◆ register_type()

EntityType esphome::modbus_controller::ModbusCommandItem::register_type ( ) const

inline

Definition at line 285 of file modbus_controller.h.

◆ send()

bool esphome::modbus_controller::ModbusCommandItem::send ( )

Queue this command's frame on the hub.

Returns false when refused, in which case no callback ever comes. The item is the hub device, so it must stay alive until its terminal callback; a destroyed item's pending frame is silently retired.

Definition at line 512 of file modbus_controller.cpp.

◆ set_command_()

void esphome::modbus_controller::ModbusCommandItem::set_command_	(	FunctionCode	function_code,
		EntityType	register_type,
		uint16_t	start_address,
		uint16_t	register_count )

inlineprotected

Definition at line 369 of file modbus_controller.h.

Field Documentation

◆ controller_

ModbusController* esphome::modbus_controller::ModbusCommandItem::controller_ {nullptr}

protected

Definition at line 382 of file modbus_controller.h.

◆ custom_data_

const std::vector<uint8_t>* esphome::modbus_controller::ModbusCommandItem::custom_data_ {nullptr}

protected

Custom polling commands reference the PDU bytes owned by their SensorItem instead of copying them.

Definition at line 381 of file modbus_controller.h.

◆ function_code_

FunctionCode esphome::modbus_controller::ModbusCommandItem::function_code_ {FunctionCode::CUSTOM}

protected

Definition at line 379 of file modbus_controller.h.

◆ on_data_func

std::function<void(EntityType register_type, uint16_t start_address, std::span<const uint8_t> data)> esphome::modbus_controller::ModbusCommandItem::on_data_func

Definition at line 261 of file modbus_controller.h.

◆ payload

SmallInlineBuffer<8> esphome::modbus_controller::ModbusCommandItem::payload

Write data bytes for the command (register/coil values), or the raw frame of a one-shot custom command; reads leave it empty.

Small-buffer optimized: fixed-size commands (single-register/coil writes) fit in the 8-byte inline buffer with no heap; only large multi-register or custom frames spill to a single one-time heap allocation. This keeps runtime one-shot writes off the heap without reserving a max-size buffer per command item.

Definition at line 267 of file modbus_controller.h.

◆ pending_removal

bool esphome::modbus_controller::ModbusCommandItem::pending_removal {false}

Definition at line 270 of file modbus_controller.h.

◆ register_count_

uint16_t esphome::modbus_controller::ModbusCommandItem::register_count_ {0}

protected

Definition at line 378 of file modbus_controller.h.

◆ register_type_

EntityType esphome::modbus_controller::ModbusCommandItem::register_type_ {EntityType::CUSTOM}

protected

Definition at line 376 of file modbus_controller.h.

◆ sensors

SensorSet esphome::modbus_controller::ModbusCommandItem::sensors

Definition at line 259 of file modbus_controller.h.

◆ skip_updates

uint16_t esphome::modbus_controller::ModbusCommandItem::skip_updates {0}

Definition at line 260 of file modbus_controller.h.

◆ start_address_

uint16_t esphome::modbus_controller::ModbusCommandItem::start_address_ {0}

protected

Definition at line 377 of file modbus_controller.h.

The documentation for this class was generated from the following files:

esphome/components/modbus_controller/modbus_controller.h
esphome/components/modbus_controller/modbus_controller.cpp

Public Member Functions

Static Public Member Functions

Data Fields

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ModbusCommandItem() [1/5]

◆ ModbusCommandItem() [2/5]

◆ ModbusCommandItem() [3/5]

◆ ModbusCommandItem() [4/5]

◆ ModbusCommandItem() [5/5]

Member Function Documentation

◆ create_custom_command() [1/2]

◆ create_custom_command() [2/2]

◆ create_read_command()

◆ create_write_multiple_coils()

◆ create_write_multiple_command()

◆ create_write_single_coil()

◆ create_write_single_command()

◆ on_error()

◆ on_no_response()

◆ on_not_sent()

◆ on_response()

◆ on_sent()

◆ operator=()

◆ register_address()

◆ register_count()

◆ register_type()

◆ send()

◆ set_command_()

Field Documentation

◆ controller_

◆ custom_data_

◆ function_code_

◆ on_data_func

◆ payload

◆ pending_removal

◆ register_count_

◆ register_type_

◆ sensors

◆ skip_updates

◆ start_address_