ESPHome  2024.4.1
Public Member Functions | Protected Member Functions | Static Protected Member Functions | Protected Attributes
esphome::mqtt::MQTTClientComponent Class Reference

#include <mqtt_client.h>

Inheritance diagram for esphome::mqtt::MQTTClientComponent:
esphome::Component

Public Member Functions

 MQTTClientComponent ()
 
void set_last_will (MQTTMessage &&message)
 Set the last will testament message. More...
 
void disable_last_will ()
 Remove the last will testament message. More...
 
void set_birth_message (MQTTMessage &&message)
 Set the birth message. More...
 
void disable_birth_message ()
 Remove the birth message. More...
 
void set_shutdown_message (MQTTMessage &&message)
 
void disable_shutdown_message ()
 
void set_keep_alive (uint16_t keep_alive_s)
 Set the keep alive time in seconds, every 0.7*keep_alive a ping will be sent. More...
 
void set_discovery_info (std::string &&prefix, MQTTDiscoveryUniqueIdGenerator unique_id_generator, MQTTDiscoveryObjectIdGenerator object_id_generator, bool retain, bool clean=false)
 Set the Home Assistant discovery info. More...
 
const MQTTDiscoveryInfoget_discovery_info () const
 Get Home Assistant discovery info. More...
 
void disable_discovery ()
 Globally disable Home Assistant discovery. More...
 
bool is_discovery_enabled () const
 
void add_ssl_fingerprint (const std::array< uint8_t, SHA1_SIZE > &fingerprint)
 Add a SSL fingerprint to use for TCP SSL connections to the MQTT broker. More...
 
void set_ca_certificate (const char *cert)
 
void set_cl_certificate (const char *cert)
 
void set_cl_key (const char *key)
 
void set_skip_cert_cn_check (bool skip_check)
 
const Availabilityget_availability ()
 
void set_topic_prefix (const std::string &topic_prefix)
 Set the topic prefix that will be prepended to all topics together with "/". More...
 
const std::string & get_topic_prefix () const
 Get the topic prefix of this device, using default if necessary. More...
 
void set_log_message_template (MQTTMessage &&message)
 Manually set the topic used for logging. More...
 
void set_log_level (int level)
 
void disable_log_message ()
 Get the topic used for logging. Defaults to "<topic_prefix>/debug" and the value is cached for speed. More...
 
bool is_log_message_enabled () const
 
void subscribe (const std::string &topic, mqtt_callback_t callback, uint8_t qos=0)
 Subscribe to an MQTT topic and call callback when a message is received. More...
 
void subscribe_json (const std::string &topic, const mqtt_json_callback_t &callback, uint8_t qos=0)
 Subscribe to a MQTT topic and automatically parse JSON payload. More...
 
void unsubscribe (const std::string &topic)
 Unsubscribe from an MQTT topic. More...
 
bool publish (const MQTTMessage &message)
 Publish a MQTTMessage. More...
 
bool publish (const std::string &topic, const std::string &payload, uint8_t qos=0, bool retain=false)
 Publish a MQTT message. More...
 
bool publish (const std::string &topic, const char *payload, size_t payload_length, uint8_t qos=0, bool retain=false)
 
bool publish_json (const std::string &topic, const json::json_build_t &f, uint8_t qos=0, bool retain=false)
 Construct and send a JSON MQTT message. More...
 
void setup () override
 Setup the MQTT client, registering a bunch of callbacks and attempting to connect. More...
 
void dump_config () override
 
void loop () override
 Reconnect if required. More...
 
float get_setup_priority () const override
 MQTT client setup priority. More...
 
void on_message (const std::string &topic, const std::string &payload)
 
bool can_proceed () override
 
void check_connected ()
 
void set_reboot_timeout (uint32_t reboot_timeout)
 
void register_mqtt_component (MQTTComponent *component)
 
bool is_connected ()
 
void on_shutdown () override
 
void set_broker_address (const std::string &address)
 
void set_broker_port (uint16_t port)
 
void set_username (const std::string &username)
 
void set_password (const std::string &password)
 
void set_client_id (const std::string &client_id)
 
void set_on_connect (mqtt_on_connect_callback_t &&callback)
 
void set_on_disconnect (mqtt_on_disconnect_callback_t &&callback)
 
- Public Member Functions inherited from esphome::Component
float get_actual_setup_priority () const
 
void set_setup_priority (float priority)
 
virtual float get_loop_priority () const
 priority of loop(). More...
 
void call ()
 
virtual void on_safe_shutdown ()
 
uint32_t get_component_state () const
 
virtual void mark_failed ()
 Mark this component as failed. More...
 
bool is_failed ()
 
bool is_ready ()
 
bool status_has_warning () const
 
bool status_has_error () const
 
void status_set_warning (const char *message="unspecified")
 
void status_set_error (const char *message="unspecified")
 
void status_clear_warning ()
 
void status_clear_error ()
 
void status_momentary_warning (const std::string &name, uint32_t length=5000)
 
void status_momentary_error (const std::string &name, uint32_t length=5000)
 
bool has_overridden_loop () const
 
void set_component_source (const char *source)
 Set where this component was loaded from for some debug messages. More...
 
const char * get_component_source () const
 Get the integration where this component was declared as a string. More...
 

Protected Member Functions

void send_device_info_ ()
 
void start_connect_ ()
 Reconnect to the MQTT broker if not already connected. More...
 
void start_dnslookup_ ()
 
void check_dnslookup_ ()
 
void recalculate_availability_ ()
 Re-calculate the availability property. More...
 
bool subscribe_ (const char *topic, uint8_t qos)
 
void resubscribe_subscription_ (MQTTSubscription *sub)
 
void resubscribe_subscriptions_ ()
 
- Protected Member Functions inherited from esphome::Component
virtual void call_loop ()
 
virtual void call_setup ()
 
virtual void call_dump_config ()
 
void set_interval (const std::string &name, uint32_t interval, std::function< void()> &&f)
 Set an interval function with a unique name. More...
 
void set_interval (uint32_t interval, std::function< void()> &&f)
 
bool cancel_interval (const std::string &name)
 Cancel an interval function. More...
 
void set_retry (const std::string &name, uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)
 Set an retry function with a unique name. More...
 
void set_retry (uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> &&f, float backoff_increase_factor=1.0f)
 
bool cancel_retry (const std::string &name)
 Cancel a retry function. More...
 
void set_timeout (const std::string &name, uint32_t timeout, std::function< void()> &&f)
 Set a timeout function with a unique name. More...
 
void set_timeout (uint32_t timeout, std::function< void()> &&f)
 
bool cancel_timeout (const std::string &name)
 Cancel a timeout function. More...
 
void defer (const std::string &name, std::function< void()> &&f)
 Defer a callback to the next loop() call. More...
 
void defer (std::function< void()> &&f)
 Defer a callback to the next loop() call. More...
 
bool cancel_defer (const std::string &name)
 Cancel a defer callback using the specified name, name must not be empty. More...
 

Static Protected Member Functions

static void dns_found_callback (const char *name, ip_addr_t *ipaddr, void *callback_arg)
 
static void dns_found_callback (const char *name, const ip_addr_t *ipaddr, void *callback_arg)
 

Protected Attributes

MQTTCredentials credentials_
 
MQTTMessage last_will_
 The last will message. More...
 
MQTTMessage birth_message_
 The birth message (e.g. More...
 
bool sent_birth_message_ {false}
 
MQTTMessage shutdown_message_
 
Availability availability_ {}
 Caches availability. More...
 
MQTTDiscoveryInfo discovery_info_
 The discovery info options for Home Assistant. More...
 
std::string topic_prefix_ {}
 
MQTTMessage log_message_
 
std::string payload_buffer_
 
int log_level_ {ESPHOME_LOG_LEVEL}
 
std::vector< MQTTSubscriptionsubscriptions_
 
MQTTBackendESP32 mqtt_backend_
 
MQTTBackendESP8266 mqtt_backend_
 
MQTTBackendLibreTiny mqtt_backend_
 
MQTTClientState state_ {MQTT_CLIENT_DISCONNECTED}
 
network::IPAddress ip_
 
bool dns_resolved_ {false}
 
bool dns_resolve_error_ {false}
 
std::vector< MQTTComponent * > children_
 
uint32_t reboot_timeout_ {300000}
 
uint32_t connect_begin_
 
uint32_t last_connected_ {0}
 
optional< MQTTClientDisconnectReasondisconnect_reason_ {}
 
- Protected Attributes inherited from esphome::Component
uint32_t component_state_ {0x0000}
 State of this component. More...
 
float setup_priority_override_ {NAN}
 
const char * component_source_ {nullptr}
 

Detailed Description

Definition at line 96 of file mqtt_client.h.

Constructor & Destructor Documentation

◆ MQTTClientComponent()

esphome::mqtt::MQTTClientComponent::MQTTClientComponent ( )

Member Function Documentation

◆ add_ssl_fingerprint()

void esphome::mqtt::MQTTClientComponent::add_ssl_fingerprint ( const std::array< uint8_t, SHA1_SIZE > &  fingerprint)

Add a SSL fingerprint to use for TCP SSL connections to the MQTT broker.

To use this feature you first have to globally enable the ASYNC_TCP_SSL_ENABLED define flag. This function can be called multiple times and any certificate that matches any of the provided fingerprints will match. Calling this method will also automatically disable all non-ssl connections.

Warning
This is not secure and not how SSL is usually done. You'll have to add a separate fingerprint for every certificate you use. Additionally, the hashing algorithm used here due to the constraints of the MCU, SHA1, is known to be insecure.
Parameters
fingerprintThe SSL fingerprint as a 20 value long std::array.

◆ can_proceed()

bool esphome::mqtt::MQTTClientComponent::can_proceed ( )
overridevirtual

Reimplemented from esphome::Component.

◆ check_connected()

void esphome::mqtt::MQTTClientComponent::check_connected ( )

◆ check_dnslookup_()

void esphome::mqtt::MQTTClientComponent::check_dnslookup_ ( )
protected

◆ disable_birth_message()

void esphome::mqtt::MQTTClientComponent::disable_birth_message ( )

Remove the birth message.

◆ disable_discovery()

void esphome::mqtt::MQTTClientComponent::disable_discovery ( )

Globally disable Home Assistant discovery.

◆ disable_last_will()

void esphome::mqtt::MQTTClientComponent::disable_last_will ( )

Remove the last will testament message.

◆ disable_log_message()

void esphome::mqtt::MQTTClientComponent::disable_log_message ( )

Get the topic used for logging. Defaults to "<topic_prefix>/debug" and the value is cached for speed.

◆ disable_shutdown_message()

void esphome::mqtt::MQTTClientComponent::disable_shutdown_message ( )

◆ dns_found_callback() [1/2]

static void esphome::mqtt::MQTTClientComponent::dns_found_callback ( const char *  name,
ip_addr_t ipaddr,
void *  callback_arg 
)
staticprotected

◆ dns_found_callback() [2/2]

static void esphome::mqtt::MQTTClientComponent::dns_found_callback ( const char *  name,
const ip_addr_t ipaddr,
void *  callback_arg 
)
staticprotected

◆ dump_config()

void esphome::mqtt::MQTTClientComponent::dump_config ( )
overridevirtual

Reimplemented from esphome::Component.

◆ get_availability()

const Availability& esphome::mqtt::MQTTClientComponent::get_availability ( )

◆ get_discovery_info()

const MQTTDiscoveryInfo& esphome::mqtt::MQTTClientComponent::get_discovery_info ( ) const

Get Home Assistant discovery info.

◆ get_setup_priority()

float esphome::mqtt::MQTTClientComponent::get_setup_priority ( ) const
overridevirtual

MQTT client setup priority.

Reimplemented from esphome::Component.

◆ get_topic_prefix()

const std::string& esphome::mqtt::MQTTClientComponent::get_topic_prefix ( ) const

Get the topic prefix of this device, using default if necessary.

◆ is_connected()

bool esphome::mqtt::MQTTClientComponent::is_connected ( )

◆ is_discovery_enabled()

bool esphome::mqtt::MQTTClientComponent::is_discovery_enabled ( ) const

◆ is_log_message_enabled()

bool esphome::mqtt::MQTTClientComponent::is_log_message_enabled ( ) const

◆ loop()

void esphome::mqtt::MQTTClientComponent::loop ( )
overridevirtual

Reconnect if required.

Reimplemented from esphome::Component.

◆ on_message()

void esphome::mqtt::MQTTClientComponent::on_message ( const std::string &  topic,
const std::string &  payload 
)

◆ on_shutdown()

void esphome::mqtt::MQTTClientComponent::on_shutdown ( )
overridevirtual

Reimplemented from esphome::Component.

◆ publish() [1/3]

bool esphome::mqtt::MQTTClientComponent::publish ( const MQTTMessage message)

Publish a MQTTMessage.

Parameters
messageThe message.

◆ publish() [2/3]

bool esphome::mqtt::MQTTClientComponent::publish ( const std::string &  topic,
const std::string &  payload,
uint8_t  qos = 0,
bool  retain = false 
)

Publish a MQTT message.

Parameters
topicThe topic.
payloadThe payload.
retainWhether to retain the message.

◆ publish() [3/3]

bool esphome::mqtt::MQTTClientComponent::publish ( const std::string &  topic,
const char *  payload,
size_t  payload_length,
uint8_t  qos = 0,
bool  retain = false 
)

◆ publish_json()

bool esphome::mqtt::MQTTClientComponent::publish_json ( const std::string &  topic,
const json::json_build_t f,
uint8_t  qos = 0,
bool  retain = false 
)

Construct and send a JSON MQTT message.

Parameters
topicThe topic.
fThe Json Message builder.
retainWhether to retain the message.

◆ recalculate_availability_()

void esphome::mqtt::MQTTClientComponent::recalculate_availability_ ( )
protected

Re-calculate the availability property.

◆ register_mqtt_component()

void esphome::mqtt::MQTTClientComponent::register_mqtt_component ( MQTTComponent component)

◆ resubscribe_subscription_()

void esphome::mqtt::MQTTClientComponent::resubscribe_subscription_ ( MQTTSubscription sub)
protected

◆ resubscribe_subscriptions_()

void esphome::mqtt::MQTTClientComponent::resubscribe_subscriptions_ ( )
protected

◆ send_device_info_()

void esphome::mqtt::MQTTClientComponent::send_device_info_ ( )
protected

◆ set_birth_message()

void esphome::mqtt::MQTTClientComponent::set_birth_message ( MQTTMessage &&  message)

Set the birth message.

◆ set_broker_address()

void esphome::mqtt::MQTTClientComponent::set_broker_address ( const std::string &  address)
inline

Definition at line 249 of file mqtt_client.h.

◆ set_broker_port()

void esphome::mqtt::MQTTClientComponent::set_broker_port ( uint16_t  port)
inline

Definition at line 250 of file mqtt_client.h.

◆ set_ca_certificate()

void esphome::mqtt::MQTTClientComponent::set_ca_certificate ( const char *  cert)
inline

Definition at line 148 of file mqtt_client.h.

◆ set_cl_certificate()

void esphome::mqtt::MQTTClientComponent::set_cl_certificate ( const char *  cert)
inline

Definition at line 149 of file mqtt_client.h.

◆ set_cl_key()

void esphome::mqtt::MQTTClientComponent::set_cl_key ( const char *  key)
inline

Definition at line 150 of file mqtt_client.h.

◆ set_client_id()

void esphome::mqtt::MQTTClientComponent::set_client_id ( const std::string &  client_id)
inline

Definition at line 253 of file mqtt_client.h.

◆ set_discovery_info()

void esphome::mqtt::MQTTClientComponent::set_discovery_info ( std::string &&  prefix,
MQTTDiscoveryUniqueIdGenerator  unique_id_generator,
MQTTDiscoveryObjectIdGenerator  object_id_generator,
bool  retain,
bool  clean = false 
)

Set the Home Assistant discovery info.

See MQTT Discovery.

Parameters
prefixThe Home Assistant discovery prefix.
unique_id_generatorControls how UniqueId is generated.
object_id_generatorControls how ObjectId is generated.
retainWhether to retain discovery messages.

◆ set_keep_alive()

void esphome::mqtt::MQTTClientComponent::set_keep_alive ( uint16_t  keep_alive_s)

Set the keep alive time in seconds, every 0.7*keep_alive a ping will be sent.

◆ set_last_will()

void esphome::mqtt::MQTTClientComponent::set_last_will ( MQTTMessage &&  message)

Set the last will testament message.

◆ set_log_level()

void esphome::mqtt::MQTTClientComponent::set_log_level ( int  level)

◆ set_log_message_template()

void esphome::mqtt::MQTTClientComponent::set_log_message_template ( MQTTMessage &&  message)

Manually set the topic used for logging.

◆ set_on_connect()

void esphome::mqtt::MQTTClientComponent::set_on_connect ( mqtt_on_connect_callback_t &&  callback)

◆ set_on_disconnect()

void esphome::mqtt::MQTTClientComponent::set_on_disconnect ( mqtt_on_disconnect_callback_t &&  callback)

◆ set_password()

void esphome::mqtt::MQTTClientComponent::set_password ( const std::string &  password)
inline

Definition at line 252 of file mqtt_client.h.

◆ set_reboot_timeout()

void esphome::mqtt::MQTTClientComponent::set_reboot_timeout ( uint32_t  reboot_timeout)

◆ set_shutdown_message()

void esphome::mqtt::MQTTClientComponent::set_shutdown_message ( MQTTMessage &&  message)

◆ set_skip_cert_cn_check()

void esphome::mqtt::MQTTClientComponent::set_skip_cert_cn_check ( bool  skip_check)
inline

Definition at line 151 of file mqtt_client.h.

◆ set_topic_prefix()

void esphome::mqtt::MQTTClientComponent::set_topic_prefix ( const std::string &  topic_prefix)

Set the topic prefix that will be prepended to all topics together with "/".

This will, in most cases, be the name of your Application.

For example, if "livingroom" is passed to this method, all state topics will, by default, look like "livingroom/.../state"

Parameters
topic_prefixThe topic prefix. The last "/" is appended automatically.

◆ set_username()

void esphome::mqtt::MQTTClientComponent::set_username ( const std::string &  username)
inline

Definition at line 251 of file mqtt_client.h.

◆ setup()

void esphome::mqtt::MQTTClientComponent::setup ( )
overridevirtual

Setup the MQTT client, registering a bunch of callbacks and attempting to connect.

Reimplemented from esphome::Component.

◆ start_connect_()

void esphome::mqtt::MQTTClientComponent::start_connect_ ( )
protected

Reconnect to the MQTT broker if not already connected.

◆ start_dnslookup_()

void esphome::mqtt::MQTTClientComponent::start_dnslookup_ ( )
protected

◆ subscribe()

void esphome::mqtt::MQTTClientComponent::subscribe ( const std::string &  topic,
mqtt_callback_t  callback,
uint8_t  qos = 0 
)

Subscribe to an MQTT topic and call callback when a message is received.

Parameters
topicThe topic. Wildcards are currently not supported.
callbackThe callback function.
qosThe QoS of this subscription.

◆ subscribe_()

bool esphome::mqtt::MQTTClientComponent::subscribe_ ( const char *  topic,
uint8_t  qos 
)
protected

◆ subscribe_json()

void esphome::mqtt::MQTTClientComponent::subscribe_json ( const std::string &  topic,
const mqtt_json_callback_t callback,
uint8_t  qos = 0 
)

Subscribe to a MQTT topic and automatically parse JSON payload.

If an invalid JSON payload is received, the callback will not be called.

Parameters
topicThe topic. Wildcards are currently not supported.
callbackThe callback with a parsed JsonObject that will be called when a message with matching topic is received.
qosThe QoS of this subscription.

◆ unsubscribe()

void esphome::mqtt::MQTTClientComponent::unsubscribe ( const std::string &  topic)

Unsubscribe from an MQTT topic.

If multiple existing subscriptions to the same topic exist, all of them will be removed.

Parameters
topicThe topic to unsubscribe from. Must match the topic in the original subscribe or subscribe_json call exactly.

Field Documentation

◆ availability_

Availability esphome::mqtt::MQTTClientComponent::availability_ {}
protected

Caches availability.

Definition at line 287 of file mqtt_client.h.

◆ birth_message_

MQTTMessage esphome::mqtt::MQTTClientComponent::birth_message_
protected

The birth message (e.g.

the message that's send on an established connection. See last_will_ for what different values denote.

Definition at line 283 of file mqtt_client.h.

◆ children_

std::vector<MQTTComponent *> esphome::mqtt::MQTTClientComponent::children_
protected

Definition at line 315 of file mqtt_client.h.

◆ connect_begin_

uint32_t esphome::mqtt::MQTTClientComponent::connect_begin_
protected

Definition at line 317 of file mqtt_client.h.

◆ credentials_

MQTTCredentials esphome::mqtt::MQTTClientComponent::credentials_
protected

Definition at line 277 of file mqtt_client.h.

◆ disconnect_reason_

optional<MQTTClientDisconnectReason> esphome::mqtt::MQTTClientComponent::disconnect_reason_ {}
protected

Definition at line 319 of file mqtt_client.h.

◆ discovery_info_

MQTTDiscoveryInfo esphome::mqtt::MQTTClientComponent::discovery_info_
protected
Initial value:
{
.prefix = "homeassistant",
.retain = true,
.clean = false,
.unique_id_generator = MQTT_LEGACY_UNIQUE_ID_GENERATOR,
.object_id_generator = MQTT_NONE_OBJECT_ID_GENERATOR,
}

The discovery info options for Home Assistant.

Undefined optional means default and empty prefix means disabled.

Definition at line 290 of file mqtt_client.h.

◆ dns_resolve_error_

bool esphome::mqtt::MQTTClientComponent::dns_resolve_error_ {false}
protected

Definition at line 314 of file mqtt_client.h.

◆ dns_resolved_

bool esphome::mqtt::MQTTClientComponent::dns_resolved_ {false}
protected

Definition at line 313 of file mqtt_client.h.

◆ ip_

network::IPAddress esphome::mqtt::MQTTClientComponent::ip_
protected

Definition at line 312 of file mqtt_client.h.

◆ last_connected_

uint32_t esphome::mqtt::MQTTClientComponent::last_connected_ {0}
protected

Definition at line 318 of file mqtt_client.h.

◆ last_will_

MQTTMessage esphome::mqtt::MQTTClientComponent::last_will_
protected

The last will message.

Disabled optional denotes it being default and an empty topic denotes the the feature being disabled.

Definition at line 280 of file mqtt_client.h.

◆ log_level_

int esphome::mqtt::MQTTClientComponent::log_level_ {ESPHOME_LOG_LEVEL}
protected

Definition at line 300 of file mqtt_client.h.

◆ log_message_

MQTTMessage esphome::mqtt::MQTTClientComponent::log_message_
protected

Definition at line 298 of file mqtt_client.h.

◆ mqtt_backend_ [1/3]

MQTTBackendESP32 esphome::mqtt::MQTTClientComponent::mqtt_backend_
protected

Definition at line 304 of file mqtt_client.h.

◆ mqtt_backend_ [2/3]

MQTTBackendESP8266 esphome::mqtt::MQTTClientComponent::mqtt_backend_
protected

Definition at line 306 of file mqtt_client.h.

◆ mqtt_backend_ [3/3]

MQTTBackendLibreTiny esphome::mqtt::MQTTClientComponent::mqtt_backend_
protected

Definition at line 308 of file mqtt_client.h.

◆ payload_buffer_

std::string esphome::mqtt::MQTTClientComponent::payload_buffer_
protected

Definition at line 299 of file mqtt_client.h.

◆ reboot_timeout_

uint32_t esphome::mqtt::MQTTClientComponent::reboot_timeout_ {300000}
protected

Definition at line 316 of file mqtt_client.h.

◆ sent_birth_message_

bool esphome::mqtt::MQTTClientComponent::sent_birth_message_ {false}
protected

Definition at line 284 of file mqtt_client.h.

◆ shutdown_message_

MQTTMessage esphome::mqtt::MQTTClientComponent::shutdown_message_
protected

Definition at line 285 of file mqtt_client.h.

◆ state_

MQTTClientState esphome::mqtt::MQTTClientComponent::state_ {MQTT_CLIENT_DISCONNECTED}
protected

Definition at line 311 of file mqtt_client.h.

◆ subscriptions_

std::vector<MQTTSubscription> esphome::mqtt::MQTTClientComponent::subscriptions_
protected

Definition at line 302 of file mqtt_client.h.

◆ topic_prefix_

std::string esphome::mqtt::MQTTClientComponent::topic_prefix_ {}
protected

Definition at line 297 of file mqtt_client.h.


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