Modbus controller class. More...

#include <modbus_controller.h>

Inheritance diagram for esphome::modbus_controller::ModbusController:

Public Member Functions
void	dump_config () override

void	setup () override

void	update () override

void	set_parent (modbus::ModbusClientHub *hub)

void	set_address (uint8_t address)

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

uint8_t	device_address () const

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

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.

void	on_write_register_response (EntityType register_type, uint16_t start_address, std::span< const uint8_t > data)
	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

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)

void	status_set_error ()

void	status_set_error (const LogString *message)

void	status_clear_warning ()

void	status_clear_error ()

void	status_momentary_warning (const char *name, uint32_t length=5000)
	Set warning status flag and automatically clear it after a timeout.

void	status_momentary_error (const char *name, uint32_t length=5000)
	Set error status flag and automatically clear it after a timeout.

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)

Protected Member Functions
void	create_polling_commands_ ()
	parse sensormap_ and create range of sequential addresses Group the registered sensors into contiguous ranges and create one polling command per range.

void	create_polling_command_ (RegisterRange &&range)
	build one persistent polling command from a range and add it to polling_command_items_

void	update_range_ (ModbusCommandItem &cmd)
	send a range's polling command if it is due this update

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.

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.

std::vector< ModbusCommandItem >	polling_command_items_ {}
	One persistent command per register range, each its own ModbusClientDevice.

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

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 skip_updates and offline timing

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.

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 400 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 443 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 451 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 447 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 424 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 437 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 430 of file modbus_controller.h.

◆ create_polling_command_()

void esphome::modbus_controller::ModbusController::create_polling_command_ ( RegisterRange && range )

inlineprotected

build one persistent polling command from a range and add it to polling_command_items_

Definition at line 464 of file modbus_controller.h.

◆ create_polling_commands_()

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

protected

parse sensormap_ and create range of sequential addresses Group the registered sensors into contiguous ranges and create one polling command per range.

Definition at line 237 of file modbus_controller.cpp.

◆ device_address()

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

inline

Definition at line 416 of file modbus_controller.h.

◆ dump_config()

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

overridevirtual

Reimplemented from esphome::Component.

Definition at line 364 of file modbus_controller.cpp.

◆ 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 457 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 441 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 415 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 434 of file modbus_controller.h.

◆ on_write_register_response()

void esphome::modbus_controller::ModbusController::on_write_register_response	(	EntityType	register_type,
		uint16_t	start_address,
		std::span< const uint8_t >	data )

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

Definition at line 387 of file modbus_controller.cpp.

◆ queue_command()

void esphome::modbus_controller::ModbusController::queue_command ( ModbusCommandItem command )

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

Definition at line 164 of file modbus_controller.cpp.

◆ set_address()

void esphome::modbus_controller::ModbusController::set_address ( uint8_t address )

inline

Definition at line 411 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 455 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 439 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 143 of file modbus_controller.cpp.

◆ set_parent()

void esphome::modbus_controller::ModbusController::set_parent ( modbus::ModbusClientHub * hub )

inline

Definition at line 410 of file modbus_controller.h.

◆ setup()

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

overridevirtual

Reimplemented from esphome::Component.

Definition at line 11 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 192 of file modbus_controller.cpp.

◆ unqueue_command()

void esphome::modbus_controller::ModbusController::unqueue_command ( const ModbusCommandItem * command )

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.

Definition at line 178 of file modbus_controller.cpp.

◆ update()

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

overridevirtual

Implements esphome::PollingComponent.

Definition at line 207 of file modbus_controller.cpp.

◆ update_range_()

void esphome::modbus_controller::ModbusController::update_range_ ( ModbusCommandItem & cmd )

protected

send a range's polling command if it is due this update

Definition at line 197 of file modbus_controller.cpp.

Field Documentation

◆ address_

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

protected

Definition at line 480 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 502 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 508 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 479 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 506 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 496 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 498 of file modbus_controller.h.

◆ offline_callback_

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

protected

Server offline callback.

Definition at line 512 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 504 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.

Definition at line 489 of file modbus_controller.h.

◆ online_callback_

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

protected

Server online callback.

Definition at line 510 of file modbus_controller.h.

◆ polling_command_items_

std::vector<ModbusCommandItem> esphome::modbus_controller::ModbusController::polling_command_items_ {}

protected

One persistent command per register range, each its own ModbusClientDevice.

Built once in setup() (create_polling_commands_ feeds each range straight in; the vector may reallocate as it grows, which is safe because no command has registered with the hub yet) and never appended to afterward, so the hub's device pointers stay valid once commands start sending.

Definition at line 487 of file modbus_controller.h.

◆ sensorset_

SensorSet esphome::modbus_controller::ModbusController::sensorset_

protected

Collection of all sensors for this component.

Definition at line 482 of file modbus_controller.h.

◆ update_counter_

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

protected

counts update() cycles; drives skip_updates and offline timing

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

Protected Member Functions

Protected Attributes

Detailed Description

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_command_()

◆ create_polling_commands_()

◆ device_address()

◆ dump_config()

◆ get_max_cmd_retries()

◆ get_module_offline()

◆ hub()

◆ increment_non_response_count()

◆ on_write_register_response()

◆ queue_command()

◆ set_address()

◆ set_max_cmd_retries()

◆ set_offline_skip_updates()

◆ set_online()

◆ set_parent()

◆ setup()

◆ sweep_completed_one_shots_()

◆ unqueue_command()

◆ update()

◆ update_range_()

Field Documentation

◆ address_

◆ cmd_non_responses_

◆ command_sent_callback_

◆ hub_

◆ max_cmd_retries_

◆ module_offline_

◆ module_offline_at_

◆ offline_callback_

◆ offline_skip_updates_

◆ one_shot_command_items_

◆ online_callback_

◆ polling_command_items_

◆ sensorset_

◆ update_counter_