Modbus controller class. More...

#include <modbus_controller.h>

Inheritance diagram for esphome::modbus_controller::ModbusController:

Public Member Functions
	ModbusController (modbus::ModbusClientHub *hub, uint8_t address)

void	dump_config () override

void	setup () override

void	update () override

modbus::ModbusClientHub *	hub () const
	The hub and modbus address this controller talks to.

uint8_t	device_address () const

	ESPDEPRECATED ("Use the entity write helpers or the modbus_client actions instead. Removed in 2027.3.0", "2026.9.0") void queue_command(ModbusCommandItem command)
	Queues a one-shot modbus command (writes, custom commands); taken by value, so std::move to avoid a copy.

	ESPDEPRECATED ("Serves only ModbusCommandItem's own callbacks. Removed in 2027.3.0", "2026.9.0") void unqueue_command(const ModbusCommandItem *command)
	Flags a finished one-shot command for removal.

void	add_sensor_item (SensorItem *item)
	Registers a sensor with the controller. Called by esphomes code generator.

	ESPDEPRECATED ("Write acknowledgements are handled by the writing entity's own device. Removed in 2027.3.0", "2026.9.0") void on_write_register_response(EntityType register_type
	Handles a write command acknowledgement (used by write command on_data_func handlers).

void	set_online (bool online, int function_code, int register_address)
	Update the online/offline state after a response or a run of timeouts, firing the callbacks.

void	command_sent (int function_code, int register_address)
	Fire the on_command_sent trigger (called when a command's frame reaches the wire).

void	increment_non_response_count ()
	A command timed out; bump the consecutive-timeout counter used by can_send()/offline detection.

bool	can_send ()
	Whether more retries are allowed before the device is considered offline.

void	set_offline_skip_updates (uint16_t offline_skip_updates)
	called by esphome generated code to set the offline_skip_updates

bool	get_module_offline ()
	get if the module is offline, didn't respond the last command

template<typename F >
void	add_on_command_sent_callback (F &&callback)
	Set callback for commands.

template<typename F >
void	add_on_online_callback (F &&callback)
	Set callback for online changes.

template<typename F >
void	add_on_offline_callback (F &&callback)
	Set callback for offline changes.

void	set_max_cmd_retries (uint8_t max_cmd_retries)
	called by esphome generated code to set the max_cmd_retries.

uint8_t	get_max_cmd_retries ()
	get how many times a command will be (re)sent if no response is received

void	set_read_options (modbus::CommandOptions options)
	called by esphome generated code with the read-side command options applied to every poll

const modbus::CommandOptions &	read_options () const
	the read-side command options applied to every poll

Public Member Functions inherited from esphome::PollingComponent
	PollingComponent ()

	PollingComponent (uint32_t update_interval)
	Initialize this polling component with the given update interval in ms.

void	set_update_interval (uint32_t update_interval)
	Manually set the update interval in ms for this polling object.

void	call_setup () override

virtual uint32_t	get_update_interval () const
	Get the update interval in ms of this sensor.

void	start_poller ()

void	stop_poller ()

Public Member Functions inherited from esphome::Component
virtual void	loop ()
	This method will be called repeatedly.

virtual float	get_setup_priority () const
	priority of setup().

float	get_actual_setup_priority () const

void	set_setup_priority (float priority)

void	call ()

virtual void	on_shutdown ()

virtual void	on_safe_shutdown ()

virtual bool	teardown ()
	Called during teardown to allow component to gracefully finish operations.

virtual void	on_powerdown ()
	Called after teardown is complete to power down hardware.

uint8_t	get_component_state () const

void	reset_to_construction_state ()
	Reset this component back to the construction state to allow setup to run again.

bool	is_in_loop_state () const
	Check if this component has completed setup and is in the loop state.

bool	is_idle () const
	Check if this component is idle.

void	mark_failed ()
	Mark this component as failed.

void	mark_failed (const LogString *message)

void	disable_loop ()
	Disable this component's loop.

void	enable_loop ()
	Enable this component's loop.

void	enable_loop_soon_any_context ()
	Thread and ISR-safe version of enable_loop() that can be called from any context.

bool	is_failed () const

bool	is_ready () const

virtual bool	can_proceed ()

bool	status_has_warning () const

bool	status_has_error () const

void	status_set_warning ()

void	status_set_warning (const char *message)

void	status_set_warning (const LogString *message)

bool	status_comm_result (bool ok)
	Clears the warning when `ok`, else sets it with `message` (default "Communication failed"); returns `ok`.

bool	status_comm_result (bool ok, const LogString *message)

void	status_set_error ()

void	status_set_error (const LogString *message)

void	status_clear_warning ()

void	status_clear_error ()

	ESPDEPRECATED ("Use status_momentary_warning() without a name. Removed in 2027.5.0", "2026.11.0") void status_momentary_warning(const char *name

void	status_momentary_warning (uint32_t length=5000)
	Set warning status flag and clear it after `length` ms.

void	status_momentary_warning (const LogString *message, uint32_t length=5000)

	ESPDEPRECATED ("Use status_momentary_error() without a name. Removed in 2027.5.0", "2026.11.0") void status_momentary_error(const char *name

void	status_momentary_error (uint32_t length=5000)
	Set error status flag and clear it after `length` ms.

void	status_momentary_error (const LogString *message, uint32_t length=5000)

bool	has_overridden_loop () const

const LogString *	get_component_log_str () const ESPHOME_ALWAYS_INLINE
	Get the integration where this component was declared as a LogString for logging.

bool	should_warn_of_blocking (uint32_t blocking_time, uint32_t &threshold_ms_out)

Data Fields
uint16_t	start_address

uint16_t std::span< const uint8_t >	data

Data Fields inherited from esphome::Component
uint32_t	length = 5000)

Protected Member Functions
void	create_polling_commands_ ()
	Group the registered sensors into contiguous ranges and create one PollingDevice per range.

void	sweep_completed_one_shots_ ()
	Erases one-shot commands flagged by unqueue_command().

Protected Member Functions inherited from esphome::Component
friend	void::setup ()

friend	void::original_setup ()

void	set_component_source_ (uint8_t index)
	Set where this component was loaded from for some debug messages.

void	call_dump_config_ ()

void	enable_loop_slow_path_ ()

void	set_component_state_ (uint8_t state)
	Helper to set component state (clears state bits and sets new state)

bool	set_status_flag_ (uint8_t flag)
	Helper to set a status LED flag on both this component and the app.

bool	set_error_flag_ (const LogString *message)
	Set the error flag and log it; true when it was not set before.

void	set_interval (const char *name, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a const char* name.

void	set_interval (uint32_t id, uint32_t interval, std::function< void()> &&f)
	Set an interval function with a numeric ID (zero heap allocation).

void	set_interval (InternalSchedulerID id, uint32_t interval, std::function< void()> &&f)

void	set_interval (uint32_t interval, std::function< void()> &&f)

bool	cancel_interval (const char *name)
	Cancel an interval function.

bool	cancel_interval (uint32_t id)

bool	cancel_interval (InternalSchedulerID id)

void	set_timeout (const char *name, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a const char* name.

void	set_timeout (uint32_t id, uint32_t timeout, std::function< void()> &&f)
	Set a timeout function with a numeric ID (zero heap allocation).

void	set_timeout (InternalSchedulerID id, uint32_t timeout, std::function< void()> &&f)

void	set_timeout (uint32_t timeout, std::function< void()> &&f)

bool	cancel_timeout (const char *name)
	Cancel a timeout function.

bool	cancel_timeout (uint32_t id)

bool	cancel_timeout (InternalSchedulerID id)

void	defer (const char *name, std::function< void()> &&f)
	Defer a callback to the next loop() call with a const char* name.

void	defer (std::function< void()> &&f)
	Defer a callback to the next loop() call.

void	defer (uint32_t id, std::function< void()> &&f)
	Defer a callback with a numeric ID (zero heap allocation)

bool	cancel_defer (const char *name)
	Cancel a defer callback using the specified name, name must not be empty.

bool	cancel_defer (uint32_t id)

void	status_clear_warning_slow_path_ ()

void	status_clear_error_slow_path_ ()

Protected Attributes
modbus::ModbusClientHub *	hub_ {nullptr}
	The hub this controller's commands/entities send through, and the modbus address they target.

uint8_t	address_ {0}

SensorSet	sensorset_
	Collection of all sensors for this component.

FixedVector< PollingDevice >	polling_devices_
	One persistent PollingDevice per register range.

std::list< std::unique_ptr< ModbusCommandItem > >	one_shot_command_items_
	Dynamically queued one-shot commands (writes, custom commands).

bool	module_offline_ {false}
	if module didn't respond the last command

uint16_t	module_offline_at_ {0}
	update_counter_ value at which the module went offline (for offline_skip_updates timing)

uint16_t	update_counter_ {0}
	counts update() cycles; drives the offline-retry cadence

uint8_t	cmd_non_responses_ {0}
	consecutive non-responses; drives can_send() and offline detection

uint16_t	offline_skip_updates_ {0}
	how many updates to skip if module is offline

uint8_t	max_cmd_retries_ {4}
	How many times we will retry a command if we get no response.

modbus::CommandOptions	read_options_ {}
	read-side command options applied to every poll

CallbackManager< void(int, int)>	command_sent_callback_ {}
	Command sent callback.

CallbackManager< void(int, int)>	online_callback_ {}
	Server online callback.

CallbackManager< void(int, int)>	offline_callback_ {}
	Server offline callback.

Protected Attributes inherited from esphome::PollingComponent
uint32_t	update_interval_

Protected Attributes inherited from esphome::Component
uint8_t	component_source_index_ {0}
	Index into component source PROGMEM lookup table (0 = not set)

uint8_t	warn_if_blocking_over_ {WARN_IF_BLOCKING_OVER_CS}
	Warn threshold in centiseconds (max 2550ms)

uint8_t	component_state_ {0x00}
	State of this component - each bit has a purpose: Bits 0-2: Component state (0x00=CONSTRUCTION, 0x01=SETUP, 0x02=LOOP, 0x03=FAILED, 0x04=LOOP_DONE) Bit 3: STATUS_LED_WARNING Bit 4: STATUS_LED_ERROR Bit 5: Has overridden loop() (set at registration time) Bits 6-7: Unused - reserved for future expansion.

volatile bool	pending_enable_loop_ {false}
	ISR-safe flag for enable_loop_soon_any_context.

ComponentRuntimeStats	runtime_stats_

Detailed Description

Modbus controller class.

Each instance handles the modbus commuinication for all sensors with the same modbus address

all sensor items (sensors, switches, binarysensor ...) are parsed in modbus address ranges. when esphome calls ModbusController::Update the commands for each range are created and sent Responses for the commands are dispatched to the modbus sensor items.

Definition at line 496 of file modbus_controller.h.

Constructor & Destructor Documentation

◆ ModbusController()

esphome::modbus_controller::ModbusController::ModbusController	(	modbus::ModbusClientHub *	hub,
		uint8_t	address )

inline

Definition at line 500 of file modbus_controller.h.

Member Function Documentation

◆ add_on_command_sent_callback()

template<typename F >

void esphome::modbus_controller::ModbusController::add_on_command_sent_callback ( F && callback )

inline

Set callback for commands.

Definition at line 548 of file modbus_controller.h.

◆ add_on_offline_callback()

template<typename F >

void esphome::modbus_controller::ModbusController::add_on_offline_callback ( F && callback )

inline

Set callback for offline changes.

Definition at line 556 of file modbus_controller.h.

◆ add_on_online_callback()

template<typename F >

void esphome::modbus_controller::ModbusController::add_on_online_callback ( F && callback )

inline

Set callback for online changes.

Definition at line 552 of file modbus_controller.h.

◆ add_sensor_item()

void esphome::modbus_controller::ModbusController::add_sensor_item ( SensorItem * item )

inline

Registers a sensor with the controller. Called by esphomes code generator.

Definition at line 526 of file modbus_controller.h.

◆ can_send()

bool esphome::modbus_controller::ModbusController::can_send ( )

inline

Whether more retries are allowed before the device is considered offline.

Deliberately pooled per device, not per command: online/offline is a property of the physical device.

Definition at line 542 of file modbus_controller.h.

◆ command_sent()

void esphome::modbus_controller::ModbusController::command_sent	(	int	function_code,
		int	register_address )

inline

Fire the on_command_sent trigger (called when a command's frame reaches the wire).

Definition at line 535 of file modbus_controller.h.

◆ create_polling_commands_()

void esphome::modbus_controller::ModbusController::create_polling_commands_ ( )

protected

Group the registered sensors into contiguous ranges and create one PollingDevice per range.

Definition at line 500 of file modbus_controller.cpp.

◆ device_address()

uint8_t esphome::modbus_controller::ModbusController::device_address ( ) const

inline

Definition at line 511 of file modbus_controller.h.

◆ dump_config()

void esphome::modbus_controller::ModbusController::dump_config ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 533 of file modbus_controller.cpp.

◆ ESPDEPRECATED() [1/3]

esphome::modbus_controller::ModbusController::ESPDEPRECATED	(	"Serves only ModbusCommandItem's own callbacks. Removed in 2027.3.0"	,
		"2026.9.0"	) const

Flags a finished one-shot command for removal.

Called by the command as the last action of its own callback, so the item is not destroyed here (send() and the hub still touch it) but swept later. Remove with ModbusCommandItem before 2027.3.0.

◆ ESPDEPRECATED() [2/3]

esphome::modbus_controller::ModbusController::ESPDEPRECATED	(	"Use the entity write helpers or the modbus_client actions instead. Removed in 2027.3.0"	,
		"2026.9.0"	)

Queues a one-shot modbus command (writes, custom commands); taken by value, so std::move to avoid a copy.

Remove with ModbusCommandItem before 2027.3.0.

◆ ESPDEPRECATED() [3/3]

esphome::modbus_controller::ModbusController::ESPDEPRECATED	(	"Write acknowledgements are handled by the writing entity's own device. Removed in 2027.3.0"	,
		"2026.9.0"	)

Handles a write command acknowledgement (used by write command on_data_func handlers).

Remove with ModbusCommandItem before 2027.3.0.

◆ get_max_cmd_retries()

uint8_t esphome::modbus_controller::ModbusController::get_max_cmd_retries ( )

inline

get how many times a command will be (re)sent if no response is received

Definition at line 562 of file modbus_controller.h.

◆ get_module_offline()

bool esphome::modbus_controller::ModbusController::get_module_offline ( )

inline

get if the module is offline, didn't respond the last command

Definition at line 546 of file modbus_controller.h.

◆ hub()

modbus::ModbusClientHub * esphome::modbus_controller::ModbusController::hub ( ) const

inline

The hub and modbus address this controller talks to.

Used to build commands/entities that send as their own device.

Definition at line 510 of file modbus_controller.h.

◆ increment_non_response_count()

void esphome::modbus_controller::ModbusController::increment_non_response_count ( )

inline

A command timed out; bump the consecutive-timeout counter used by can_send()/offline detection.

Definition at line 539 of file modbus_controller.h.

◆ read_options()

const modbus::CommandOptions & esphome::modbus_controller::ModbusController::read_options ( ) const

inline

the read-side command options applied to every poll

Definition at line 566 of file modbus_controller.h.

◆ set_max_cmd_retries()

void esphome::modbus_controller::ModbusController::set_max_cmd_retries ( uint8_t max_cmd_retries )

inline

called by esphome generated code to set the max_cmd_retries.

Definition at line 560 of file modbus_controller.h.

◆ set_offline_skip_updates()

void esphome::modbus_controller::ModbusController::set_offline_skip_updates ( uint16_t offline_skip_updates )

inline

called by esphome generated code to set the offline_skip_updates

Definition at line 544 of file modbus_controller.h.

◆ set_online()

void esphome::modbus_controller::ModbusController::set_online	(	bool	online,
		int	function_code,
		int	register_address )

Update the online/offline state after a response or a run of timeouts, firing the callbacks.

Definition at line 262 of file modbus_controller.cpp.

◆ set_read_options()

void esphome::modbus_controller::ModbusController::set_read_options ( modbus::CommandOptions options )

inline

called by esphome generated code with the read-side command options applied to every poll

Definition at line 564 of file modbus_controller.h.

◆ setup()

void esphome::modbus_controller::ModbusController::setup ( )

overridevirtual

Reimplemented from esphome::Component.

Definition at line 12 of file modbus_controller.cpp.

◆ sweep_completed_one_shots_()

void esphome::modbus_controller::ModbusController::sweep_completed_one_shots_ ( )

protected

Erases one-shot commands flagged by unqueue_command().

Safe even when reached from inside a hub callback (via an on_online/on_offline/on_command_sent automation that queues a command): the destructor detaches via clear_tx_queue_for_device(), which the hub allows from callbacks, and the item running its callback is not flagged until that callback returns.

Definition at line 314 of file modbus_controller.cpp.

◆ update()

void esphome::modbus_controller::ModbusController::update ( )

overridevirtual

Implements esphome::PollingComponent.

Definition at line 321 of file modbus_controller.cpp.

Field Documentation

◆ address_

uint8_t esphome::modbus_controller::ModbusController::address_ {0}

protected

Definition at line 573 of file modbus_controller.h.

◆ cmd_non_responses_

uint8_t esphome::modbus_controller::ModbusController::cmd_non_responses_ {0}

protected

consecutive non-responses; drives can_send() and offline detection

Definition at line 597 of file modbus_controller.h.

◆ command_sent_callback_

CallbackManager<void(int, int)> esphome::modbus_controller::ModbusController::command_sent_callback_ {}

protected

Command sent callback.

Definition at line 605 of file modbus_controller.h.

◆ data

uint16_t std::span<const uint8_t> esphome::modbus_controller::ModbusController::data

Definition at line 531 of file modbus_controller.h.

◆ hub_

modbus::ModbusClientHub* esphome::modbus_controller::ModbusController::hub_ {nullptr}

protected

The hub this controller's commands/entities send through, and the modbus address they target.

Definition at line 572 of file modbus_controller.h.

◆ max_cmd_retries_

uint8_t esphome::modbus_controller::ModbusController::max_cmd_retries_ {4}

protected

How many times we will retry a command if we get no response.

Definition at line 601 of file modbus_controller.h.

◆ module_offline_

bool esphome::modbus_controller::ModbusController::module_offline_ {false}

protected

if module didn't respond the last command

Definition at line 591 of file modbus_controller.h.

◆ module_offline_at_

uint16_t esphome::modbus_controller::ModbusController::module_offline_at_ {0}

protected

update_counter_ value at which the module went offline (for offline_skip_updates timing)

Definition at line 593 of file modbus_controller.h.

◆ offline_callback_

CallbackManager<void(int, int)> esphome::modbus_controller::ModbusController::offline_callback_ {}

protected

Server offline callback.

Definition at line 609 of file modbus_controller.h.

◆ offline_skip_updates_

uint16_t esphome::modbus_controller::ModbusController::offline_skip_updates_ {0}

protected

how many updates to skip if module is offline

Definition at line 599 of file modbus_controller.h.

◆ one_shot_command_items_

std::list<std::unique_ptr<ModbusCommandItem> > esphome::modbus_controller::ModbusController::one_shot_command_items_

protected

Dynamically queued one-shot commands (writes, custom commands).

std::list keeps stable addresses. Remove with ModbusCommandItem before 2027.3.0.

Definition at line 583 of file modbus_controller.h.

◆ online_callback_

CallbackManager<void(int, int)> esphome::modbus_controller::ModbusController::online_callback_ {}

protected

Server online callback.

Definition at line 607 of file modbus_controller.h.

◆ polling_devices_

FixedVector<PollingDevice> esphome::modbus_controller::ModbusController::polling_devices_

protected

One persistent PollingDevice per register range.

Built once in setup() with the exact count (FixedVector never reallocates), so the hub's device pointers stay valid once polls start sending.

Definition at line 578 of file modbus_controller.h.

◆ read_options_

modbus::CommandOptions esphome::modbus_controller::ModbusController::read_options_ {}

protected

read-side command options applied to every poll

Definition at line 603 of file modbus_controller.h.

◆ sensorset_

SensorSet esphome::modbus_controller::ModbusController::sensorset_

protected

Collection of all sensors for this component.

Definition at line 575 of file modbus_controller.h.

◆ start_address

uint16_t esphome::modbus_controller::ModbusController::start_address

Definition at line 531 of file modbus_controller.h.

◆ update_counter_

uint16_t esphome::modbus_controller::ModbusController::update_counter_ {0}

protected

counts update() cycles; drives the offline-retry cadence

Definition at line 595 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

Data Fields

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ModbusController()

Member Function Documentation

◆ add_on_command_sent_callback()

◆ add_on_offline_callback()

◆ add_on_online_callback()

◆ add_sensor_item()

◆ can_send()

◆ command_sent()

◆ create_polling_commands_()

◆ device_address()

◆ dump_config()

◆ ESPDEPRECATED() [1/3]

◆ ESPDEPRECATED() [2/3]

◆ ESPDEPRECATED() [3/3]

◆ get_max_cmd_retries()

◆ get_module_offline()

◆ hub()

◆ increment_non_response_count()

◆ read_options()

◆ set_max_cmd_retries()

◆ set_offline_skip_updates()

◆ set_online()

◆ set_read_options()

◆ setup()

◆ sweep_completed_one_shots_()

◆ update()

Field Documentation

◆ address_

◆ cmd_non_responses_

◆ command_sent_callback_

◆ data

◆ hub_

◆ max_cmd_retries_

◆ module_offline_

◆ module_offline_at_

◆ offline_callback_

◆ offline_skip_updates_

◆ one_shot_command_items_

◆ online_callback_

◆ polling_devices_

◆ read_options_

◆ sensorset_

◆ start_address

◆ update_counter_