Async client for a single device. More...

#include <client.hpp>

Public Types
using	ConnectHandler = std::function< void(std::error_code)>

using	MessageHandler = std::function< void(const ProtoMessage &)>

using	RawHandler = std::function< void(std::uint32_t msg_type, ByteView payload)>

using	StateHandler = std::function< void(ConnectionState)>

using	ErrorHandler = std::function< void(std::error_code, const std::string &)>

Public Member Functions
	Client (ClientOptions options)

	~Client ()

	Client (const Client &)=delete

Client &	operator= (const Client &)=delete

void	async_connect (ConnectHandler on_done) const
	Begin connecting + handshaking; `on_done` fires once when the session is ready (or with an error).

void	disconnect () const
	Begin a graceful disconnect.

ConnectionState	state () const

bool	is_connected () const

const ServerHello &	server_hello () const

void	send (const ProtoMessage &msg) const

void	send_raw (std::uint32_t msg_type, ByteView payload) const

void	on (std::uint32_t msg_type, MessageHandler handler) const

void	on_any (MessageHandler handler) const

void	on_raw (RawHandler handler) const

void	on_state (StateHandler handler) const

void	on_error (ErrorHandler handler) const

void	run () const
	Run the loop until stopped (blocking). Typically used on a worker thread.

std::size_t	run_for (std::chrono::milliseconds duration) const
	Run ready handlers for up to `duration`; returns handlers executed.

std::size_t	run_one () const
	Run a single handler, blocking until one is available; returns count.

std::size_t	poll () const
	Execute any ready handlers without blocking; returns handlers executed.

void	stop () const
	Stop the loop (causes `run` to return).

void	restart () const
	Reset a stopped loop so it can run again.

void	post (std::function< void()> fn) const
	Post `fn` to run on the client's executor.

Connection &	connection () const
	Access the underlying Connection (advanced/raw use).

EntityStore &	store ()
	The store of discovered entities and their latest states (auto-populated from every inbound message).

const EntityStore &	store () const

EntityRegistry	entities ()
	Typed, object-oriented view over the entity store: `entities().switches()`, `entities().light("ceiling")`, etc.

void	request_entity_list () const
	Ask the device to enumerate its entities (ListEntitiesRequest).

void	subscribe_to_states () const
	Ask the device to stream state updates (SubscribeStatesRequest).

BluetoothProxy &	bluetooth ()

LogStream &	logs ()

HomeAssistantServices &	home_assistant ()

VoiceAssistant &	voice ()

ZWaveProxy &	zwave ()

SerialProxy &	serial ()

SerialPort	serial_proxy (std::uint32_t instance)
	An instance-bound serial-proxy handle: `client.serial_proxy(0).write(...)`.

SerialPort	serial_proxy (const std::string &name)
	Look up a serial-proxy handle by its advertised name.

bool	has_device_info () const
	The most recently received DeviceInfo (populated when a DeviceInfoResponse is seen).

const DeviceInfo &	device_info () const

Detailed Description

Async client for a single device.

Not thread-safe: drive it from one thread (or post work onto its executor with post). SyncClient wraps this with blocking convenience methods.

Member Typedef Documentation

◆ ConnectHandler

using esphome::api::Client::ConnectHandler = std::function<void(std::error_code)>

◆ ErrorHandler

using esphome::api::Client::ErrorHandler = std::function<void(std::error_code, const std::string&)>

◆ MessageHandler

using esphome::api::Client::MessageHandler = std::function<void(const ProtoMessage&)>

◆ RawHandler

using esphome::api::Client::RawHandler = std::function<void(std::uint32_t msg_type, ByteView payload)>

◆ StateHandler

using esphome::api::Client::StateHandler = std::function<void(ConnectionState)>

Constructor & Destructor Documentation

◆ Client() [1/2]

esphome::api::Client::Client ( ClientOptions options )

explicit

◆ ~Client()

esphome::api::Client::~Client ( )

◆ Client() [2/2]

esphome::api::Client::Client ( const Client & )

delete

Member Function Documentation

◆ async_connect()

void esphome::api::Client::async_connect ( ConnectHandler on_done ) const

Begin connecting + handshaking; on_done fires once when the session is ready (or with an error).

Must be driven by the event loop afterwards.

◆ bluetooth()

BluetoothProxy & esphome::api::Client::bluetooth ( )

◆ connection()

Connection & esphome::api::Client::connection ( ) const

Access the underlying Connection (advanced/raw use).

◆ device_info()

const DeviceInfo & esphome::api::Client::device_info ( ) const

◆ disconnect()

void esphome::api::Client::disconnect ( ) const

Begin a graceful disconnect.

◆ entities()

EntityRegistry esphome::api::Client::entities ( )

Typed, object-oriented view over the entity store: entities().switches(), entities().light("ceiling"), etc.

◆ has_device_info()

bool esphome::api::Client::has_device_info ( ) const

The most recently received DeviceInfo (populated when a DeviceInfoResponse is seen).

has_device_info() reports whether it is valid yet.

◆ home_assistant()

HomeAssistantServices & esphome::api::Client::home_assistant ( )

◆ is_connected()

bool esphome::api::Client::is_connected ( ) const

◆ logs()

LogStream & esphome::api::Client::logs ( )

◆ on()

void esphome::api::Client::on	(	std::uint32_t	msg_type,
		MessageHandler	handler
	)		const

◆ on_any()

void esphome::api::Client::on_any ( MessageHandler handler ) const

◆ on_error()

void esphome::api::Client::on_error ( ErrorHandler handler ) const

◆ on_raw()

void esphome::api::Client::on_raw ( RawHandler handler ) const

◆ on_state()

void esphome::api::Client::on_state ( StateHandler handler ) const

◆ operator=()

Client & esphome::api::Client::operator= ( const Client & )

delete

◆ poll()

std::size_t esphome::api::Client::poll ( ) const

Execute any ready handlers without blocking; returns handlers executed.

◆ post()

void esphome::api::Client::post ( std::function< void()> fn ) const

Post fn to run on the client's executor.

◆ request_entity_list()

void esphome::api::Client::request_entity_list ( ) const

Ask the device to enumerate its entities (ListEntitiesRequest).

◆ restart()

void esphome::api::Client::restart ( ) const

Reset a stopped loop so it can run again.

◆ run()

void esphome::api::Client::run ( ) const

Run the loop until stopped (blocking). Typically used on a worker thread.

◆ run_for()

std::size_t esphome::api::Client::run_for ( std::chrono::milliseconds duration ) const

Run ready handlers for up to duration; returns handlers executed.

◆ run_one()

std::size_t esphome::api::Client::run_one ( ) const

Run a single handler, blocking until one is available; returns count.

◆ send()

void esphome::api::Client::send ( const ProtoMessage & msg ) const

◆ send_raw()

void esphome::api::Client::send_raw	(	std::uint32_t	msg_type,
		ByteView	payload
	)		const

◆ serial()

SerialProxy & esphome::api::Client::serial ( )

◆ serial_proxy() [1/2]

SerialPort esphome::api::Client::serial_proxy ( const std::string & name )

Look up a serial-proxy handle by its advertised name.

Requires the device's DeviceInfo to have been received (the client caches it); throws ApiError if absent or the name is unknown.

◆ serial_proxy() [2/2]

SerialPort esphome::api::Client::serial_proxy ( std::uint32_t instance )

An instance-bound serial-proxy handle: client.serial_proxy(0).write(...).

◆ server_hello()

const ServerHello & esphome::api::Client::server_hello ( ) const

◆ state()

ConnectionState esphome::api::Client::state ( ) const

◆ stop()

void esphome::api::Client::stop ( ) const

Stop the loop (causes run to return).

◆ store() [1/2]

EntityStore & esphome::api::Client::store ( )

The store of discovered entities and their latest states (auto-populated from every inbound message).

◆ store() [2/2]

const EntityStore & esphome::api::Client::store ( ) const

◆ subscribe_to_states()

void esphome::api::Client::subscribe_to_states ( ) const

Ask the device to stream state updates (SubscribeStatesRequest).

◆ voice()

VoiceAssistant & esphome::api::Client::voice ( )

◆ zwave()

ZWaveProxy & esphome::api::Client::zwave ( )

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

include/esphome/api/client.hpp

Public Types

Public Member Functions