ESPHome
2024.11.3
|
MQTTComponent is the base class for all components that interact with MQTT to expose certain functionality or data from actuators or sensors to clients. More...
#include <mqtt_component.h>
Public Member Functions | |
MQTTComponent () | |
Constructs a MQTTComponent. More... | |
void | call_setup () override |
Override setup_ so that we can call send_discovery() when needed. More... | |
void | call_loop () override |
void | call_dump_config () override |
virtual void | send_discovery (JsonObject root, SendDiscoveryConfig &config)=0 |
Send discovery info the Home Assistant, override this. More... | |
virtual bool | send_initial_state ()=0 |
virtual bool | is_internal () |
void | set_qos (uint8_t qos) |
Set QOS for state messages. More... | |
uint8_t | get_qos () const |
void | set_retain (bool retain) |
Set whether state message should be retained. More... | |
bool | get_retain () const |
void | disable_discovery () |
Disable discovery. Sets friendly name to "". More... | |
bool | is_discovery_enabled () const |
void | set_subscribe_qos (uint8_t qos) |
Set the QOS for subscribe messages (used in discovery). More... | |
virtual std::string | component_type () const =0 |
Override this method to return the component type (e.g. "light", "sensor", ...) More... | |
void | set_custom_state_topic (const char *custom_state_topic) |
Set a custom state topic. Set to "" for default behavior. More... | |
void | set_custom_command_topic (const char *custom_command_topic) |
Set a custom command topic. Set to "" for default behavior. More... | |
void | set_command_retain (bool command_retain) |
Set whether command message should be retained. More... | |
float | get_setup_priority () const override |
MQTT_COMPONENT setup priority. More... | |
void | set_availability (std::string topic, std::string payload_available, std::string payload_not_available) |
Set the Home Assistant availability data. More... | |
void | disable_availability () |
void | schedule_resend_state () |
Internal method for the MQTT client base to schedule a resend of the state on reconnect. More... | |
bool | publish (const std::string &topic, const std::string &payload) |
Send a MQTT message. More... | |
bool | publish_json (const std::string &topic, const json::json_build_t &f) |
Construct and send a JSON MQTT message. More... | |
void | subscribe (const std::string &topic, mqtt_callback_t callback, uint8_t qos=0) |
Subscribe to a MQTT topic. 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... | |
Public Member Functions inherited from esphome::Component | |
virtual void | setup () |
Where the component's initialization should happen. More... | |
virtual void | loop () |
This method will be called repeatedly. More... | |
virtual void | dump_config () |
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_shutdown () |
virtual void | on_safe_shutdown () |
uint32_t | get_component_state () const |
virtual void | mark_failed () |
Mark this component as failed. More... | |
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 (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 | |
std::string | get_discovery_topic_ (const MQTTDiscoveryInfo &discovery_info) const |
Helper method to get the discovery topic for this component. More... | |
std::string | get_default_topic_for_ (const std::string &suffix) const |
Get this components state/command/... More... | |
virtual const EntityBase * | get_entity () const =0 |
Gets the Entity served by this MQTT component. More... | |
virtual std::string | unique_id () |
A unique ID for this MQTT component, empty for no unique id. More... | |
virtual std::string | friendly_name () const |
Get the friendly name of this MQTT component. More... | |
virtual std::string | get_icon () const |
Get the icon field of this component. More... | |
virtual bool | is_disabled_by_default () const |
Get whether the underlying Entity is disabled by default. More... | |
std::string | get_state_topic_ () const |
Get the MQTT topic that new states will be shared to. More... | |
std::string | get_command_topic_ () const |
Get the MQTT topic for listening to commands. More... | |
bool | is_connected_ () const |
bool | send_discovery_ () |
Internal method to start sending discovery info, this will call send_discovery(). More... | |
std::string | get_default_object_id_ () const |
Generate the Home Assistant MQTT discovery object id by automatically transforming the friendly name. More... | |
Protected Member Functions inherited from esphome::Component | |
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... | |
Protected Attributes | |
StringRef | custom_state_topic_ {} |
StringRef | custom_command_topic_ {} |
std::unique_ptr< Availability > | availability_ |
bool | has_custom_state_topic_ {false} |
bool | has_custom_command_topic_ {false} |
bool | command_retain_ {false} |
bool | retain_ {true} |
uint8_t | qos_ {0} |
uint8_t | subscribe_qos_ {0} |
bool | discovery_enabled_ {true} |
bool | resend_state_ {false} |
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} |
MQTTComponent is the base class for all components that interact with MQTT to expose certain functionality or data from actuators or sensors to clients.
Although this class should work with all MQTT solutions, it has been specifically designed for use with Home Assistant. For example, this class supports Home Assistant MQTT discovery out of the box.
In order to implement automatic Home Assistant discovery, all sub-classes should:
In order to best separate the front- and back-end of ESPHome, all sub-classes should only parse/send MQTT messages and interact with back-end components via callbacks to ensure a clean separation.
Definition at line 61 of file mqtt_component.h.
|
explicitdefault |
Constructs a MQTTComponent.
|
overridevirtual |
Reimplemented from esphome::Component.
Definition at line 280 of file mqtt_component.cpp.
|
overridevirtual |
Reimplemented from esphome::Component.
Definition at line 260 of file mqtt_component.cpp.
|
overridevirtual |
Override setup_ so that we can call send_discovery() when needed.
Reimplemented from esphome::Component.
Definition at line 239 of file mqtt_component.cpp.
|
pure virtual |
Override this method to return the component type (e.g. "light", "sensor", ...)
Implemented in esphome::mqtt::MQTTSensorComponent, esphome::mqtt::MQTTFanComponent, esphome::mqtt::MQTTNumberComponent, esphome::mqtt::MQTTSelectComponent, esphome::mqtt::MQTTTextComponent, esphome::mqtt::MQTTDateComponent, esphome::mqtt::MQTTDateTimeComponent, esphome::mqtt::MQTTTimeComponent, esphome::mqtt::MQTTBinarySensorComponent, esphome::mqtt::MQTTCoverComponent, esphome::mqtt::MQTTLockComponent, esphome::mqtt::MQTTSwitchComponent, esphome::mqtt::MQTTUpdateComponent, esphome::mqtt::MQTTValveComponent, esphome::mqtt::MQTTButtonComponent, esphome::mqtt::MQTTAlarmControlPanelComponent, esphome::mqtt::MQTTEventComponent, esphome::mqtt::MQTTJSONLightComponent, esphome::mqtt::MQTTTextSensor, and esphome::mqtt::MQTTClimateComponent.
void esphome::mqtt::MQTTComponent::disable_availability | ( | ) |
Definition at line 238 of file mqtt_component.cpp.
void esphome::mqtt::MQTTComponent::disable_discovery | ( | ) |
Disable discovery. Sets friendly name to "".
Definition at line 220 of file mqtt_component.cpp.
|
protectedvirtual |
Get the friendly name of this MQTT component.
Definition at line 291 of file mqtt_component.cpp.
|
protected |
Get the MQTT topic for listening to commands.
Definition at line 45 of file mqtt_component.cpp.
|
protected |
Generate the Home Assistant MQTT discovery object id by automatically transforming the friendly name.
Definition at line 205 of file mqtt_component.cpp.
|
protected |
Get this components state/command/...
topic.
suffix | The suffix/key such as "state" or "command". |
Definition at line 29 of file mqtt_component.cpp.
|
protected |
Helper method to get the discovery topic for this component.
Definition at line 23 of file mqtt_component.cpp.
|
protectedpure virtual |
Gets the Entity served by this MQTT component.
Implemented in esphome::mqtt::MQTTSensorComponent, esphome::mqtt::MQTTFanComponent, esphome::mqtt::MQTTNumberComponent, esphome::mqtt::MQTTSelectComponent, esphome::mqtt::MQTTTextComponent, esphome::mqtt::MQTTDateComponent, esphome::mqtt::MQTTDateTimeComponent, esphome::mqtt::MQTTTimeComponent, esphome::mqtt::MQTTBinarySensorComponent, esphome::mqtt::MQTTCoverComponent, esphome::mqtt::MQTTLockComponent, esphome::mqtt::MQTTSwitchComponent, esphome::mqtt::MQTTUpdateComponent, esphome::mqtt::MQTTValveComponent, esphome::mqtt::MQTTButtonComponent, esphome::mqtt::MQTTAlarmControlPanelComponent, esphome::mqtt::MQTTEventComponent, esphome::mqtt::MQTTJSONLightComponent, and esphome::mqtt::MQTTTextSensor.
|
protectedvirtual |
Get the icon field of this component.
Definition at line 292 of file mqtt_component.cpp.
uint8_t esphome::mqtt::MQTTComponent::get_qos | ( | ) | const |
Definition at line 197 of file mqtt_component.cpp.
bool esphome::mqtt::MQTTComponent::get_retain | ( | ) | const |
Definition at line 199 of file mqtt_component.cpp.
|
overridevirtual |
MQTT_COMPONENT setup priority.
Reimplemented from esphome::Component.
Definition at line 219 of file mqtt_component.cpp.
|
protected |
Get the MQTT topic that new states will be shared to.
Definition at line 39 of file mqtt_component.cpp.
|
protected |
Definition at line 288 of file mqtt_component.cpp.
|
protectedvirtual |
Get whether the underlying Entity is disabled by default.
Definition at line 293 of file mqtt_component.cpp.
bool esphome::mqtt::MQTTComponent::is_discovery_enabled | ( | ) | const |
Definition at line 201 of file mqtt_component.cpp.
|
virtual |
Definition at line 294 of file mqtt_component.cpp.
bool esphome::mqtt::MQTTComponent::publish | ( | const std::string & | topic, |
const std::string & | payload | ||
) |
Send a MQTT message.
topic | The topic. |
payload | The payload. |
Definition at line 51 of file mqtt_component.cpp.
bool esphome::mqtt::MQTTComponent::publish_json | ( | const std::string & | topic, |
const json::json_build_t & | f | ||
) |
Construct and send a JSON MQTT message.
topic | The topic. |
f | The Json Message builder. |
Definition at line 57 of file mqtt_component.cpp.
void esphome::mqtt::MQTTComponent::schedule_resend_state | ( | ) |
Internal method for the MQTT client base to schedule a resend of the state on reconnect.
Definition at line 286 of file mqtt_component.cpp.
|
pure virtual |
Send discovery info the Home Assistant, override this.
Implemented in esphome::mqtt::MQTTSensorComponent, esphome::mqtt::MQTTDateComponent, esphome::mqtt::MQTTDateTimeComponent, esphome::mqtt::MQTTNumberComponent, esphome::mqtt::MQTTSelectComponent, esphome::mqtt::MQTTTextComponent, esphome::mqtt::MQTTTimeComponent, esphome::mqtt::MQTTButtonComponent, esphome::mqtt::MQTTBinarySensorComponent, esphome::mqtt::MQTTFanComponent, esphome::mqtt::MQTTJSONLightComponent, esphome::mqtt::MQTTLockComponent, esphome::mqtt::MQTTSwitchComponent, esphome::mqtt::MQTTUpdateComponent, esphome::mqtt::MQTTAlarmControlPanelComponent, esphome::mqtt::MQTTCoverComponent, esphome::mqtt::MQTTValveComponent, esphome::mqtt::MQTTEventComponent, esphome::mqtt::MQTTTextSensor, and esphome::mqtt::MQTTClimateComponent.
|
protected |
Internal method to start sending discovery info, this will call send_discovery().
Definition at line 63 of file mqtt_component.cpp.
|
pure virtual |
Implemented in esphome::mqtt::MQTTSensorComponent, esphome::mqtt::MQTTFanComponent, esphome::mqtt::MQTTDateComponent, esphome::mqtt::MQTTDateTimeComponent, esphome::mqtt::MQTTNumberComponent, esphome::mqtt::MQTTSelectComponent, esphome::mqtt::MQTTTextComponent, esphome::mqtt::MQTTTimeComponent, esphome::mqtt::MQTTBinarySensorComponent, esphome::mqtt::MQTTCoverComponent, esphome::mqtt::MQTTJSONLightComponent, esphome::mqtt::MQTTTextSensor, esphome::mqtt::MQTTEventComponent, esphome::mqtt::MQTTLockComponent, esphome::mqtt::MQTTSwitchComponent, esphome::mqtt::MQTTUpdateComponent, esphome::mqtt::MQTTButtonComponent, esphome::mqtt::MQTTValveComponent, esphome::mqtt::MQTTAlarmControlPanelComponent, and esphome::mqtt::MQTTClimateComponent.
void esphome::mqtt::MQTTComponent::set_availability | ( | std::string | topic, |
std::string | payload_available, | ||
std::string | payload_not_available | ||
) |
Set the Home Assistant availability data.
See See Home Assistant for more info.
Definition at line 231 of file mqtt_component.cpp.
void esphome::mqtt::MQTTComponent::set_command_retain | ( | bool | command_retain | ) |
Set whether command message should be retained.
Definition at line 229 of file mqtt_component.cpp.
void esphome::mqtt::MQTTComponent::set_custom_command_topic | ( | const char * | custom_command_topic | ) |
Set a custom command topic. Set to "" for default behavior.
Definition at line 225 of file mqtt_component.cpp.
void esphome::mqtt::MQTTComponent::set_custom_state_topic | ( | const char * | custom_state_topic | ) |
Set a custom state topic. Set to "" for default behavior.
Definition at line 221 of file mqtt_component.cpp.
void esphome::mqtt::MQTTComponent::set_qos | ( | uint8_t | qos | ) |
Set QOS for state messages.
Definition at line 17 of file mqtt_component.cpp.
void esphome::mqtt::MQTTComponent::set_retain | ( | bool | retain | ) |
Set whether state message should be retained.
Definition at line 21 of file mqtt_component.cpp.
void esphome::mqtt::MQTTComponent::set_subscribe_qos | ( | uint8_t | qos | ) |
Set the QOS for subscribe messages (used in discovery).
Definition at line 19 of file mqtt_component.cpp.
void esphome::mqtt::MQTTComponent::subscribe | ( | const std::string & | topic, |
mqtt_callback_t | callback, | ||
uint8_t | qos = 0 |
||
) |
Subscribe to a MQTT topic.
topic | The topic. Wildcards are currently not supported. |
callback | The callback that will be called when a message with matching topic is received. |
qos | The MQTT quality of service. Defaults to 0. |
Definition at line 209 of file mqtt_component.cpp.
void esphome::mqtt::MQTTComponent::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.
topic | The topic. Wildcards are currently not supported. |
callback | The callback with a parsed JsonObject that will be called when a message with matching topic is received. |
qos | The MQTT quality of service. Defaults to 0. |
Definition at line 213 of file mqtt_component.cpp.
|
protectedvirtual |
A unique ID for this MQTT component, empty for no unique id.
See unique ID requirements: https://developers.home-assistant.io/docs/en/entity_registry_index.html#unique-id-requirements
Reimplemented in esphome::mqtt::MQTTSensorComponent, and esphome::mqtt::MQTTTextSensor.
Definition at line 287 of file mqtt_component.cpp.
|
protected |
Definition at line 202 of file mqtt_component.h.
|
protected |
Definition at line 207 of file mqtt_component.h.
|
protected |
Definition at line 200 of file mqtt_component.h.
|
protected |
Definition at line 199 of file mqtt_component.h.
|
protected |
Definition at line 211 of file mqtt_component.h.
|
protected |
Definition at line 205 of file mqtt_component.h.
|
protected |
Definition at line 204 of file mqtt_component.h.
|
protected |
Definition at line 209 of file mqtt_component.h.
|
protected |
Definition at line 212 of file mqtt_component.h.
|
protected |
Definition at line 208 of file mqtt_component.h.
|
protected |
Definition at line 210 of file mqtt_component.h.