mqtt_component.h

Go to the documentation of this file.

#pragma once
 
#include "esphome/core/defines.h"
 
#ifdef USE_MQTT
 
#include <memory>
 
#include "esphome/core/automation.h"
#include "esphome/core/component.h"
#include "esphome/core/entity_base.h"
#include "esphome/core/progmem.h"
#include "esphome/core/string_ref.h"
#include "mqtt_client.h"
 
namespace esphome::mqtt {
 
struct SendDiscoveryConfig {
  bool state_topic{true};    
  bool command_topic{true};  
};
 
class MQTTComponent;  // Forward declaration
 
// Validated in Python: cv.Length(max=64), DISCOVERY_PREFIX_MAX_LEN in mqtt/__init__.py
static constexpr size_t MQTT_DISCOVERY_PREFIX_MAX_LEN = 64;
// Format: prefix + "/" + type + "/" + name + "/" + object_id + "/config" + null
static constexpr size_t MQTT_DISCOVERY_TOPIC_MAX_LEN = MQTT_DISCOVERY_PREFIX_MAX_LEN + 1 + MQTT_COMPONENT_TYPE_MAX_LEN +
                                                       1 + ESPHOME_DEVICE_NAME_MAX_LEN + 1 + OBJECT_ID_MAX_LEN + 7 + 1;
 
void log_mqtt_component(const char *tag, MQTTComponent *obj, bool state_topic, bool command_topic);
 
#define LOG_MQTT_COMPONENT(state_topic, command_topic) log_mqtt_component(TAG, this, state_topic, command_topic)
 
// Macro to define component_type() with compile-time length verification
// Usage: MQTT_COMPONENT_TYPE(MQTTSensorComponent, "sensor")
#define MQTT_COMPONENT_TYPE(class_name, type_str) \
  const char *class_name::component_type() const { return type_str; } \
  static_assert(sizeof(type_str) - 1 <= MQTT_COMPONENT_TYPE_MAX_LEN, \
                #class_name "::component_type() exceeds MQTT_COMPONENT_TYPE_MAX_LEN");
 
// Macro to define custom topic getter/setter with compile-time suffix length verification.
// Set the topic before setup(): subscriptions rebuild it when needed, so a later change only reaches the broker
// after a reconnect.
#define MQTT_COMPONENT_CUSTOM_TOPIC_(name, type) \
  static_assert(sizeof(#name "/" #type) - 1 <= MQTT_SUFFIX_MAX_LEN, \
                "topic suffix " #name "/" #type " exceeds MQTT_SUFFIX_MAX_LEN"); \
\
 protected: \
  std::string custom_##name##_##type##_topic_{}; \
\
 public: \
  void set_custom_##name##_##type##_topic(const std::string &topic) { this->custom_##name##_##type##_topic_ = topic; } \
  StringRef get_##name##_##type##_topic_to(std::span<char, MQTT_DEFAULT_TOPIC_MAX_LEN> buf) const { \
    if (!this->custom_##name##_##type##_topic_.empty()) \
      return StringRef(this->custom_##name##_##type##_topic_.data(), this->custom_##name##_##type##_topic_.size()); \
    return this->get_default_topic_for_to_(buf, #name "/" #type, sizeof(#name "/" #type) - 1); \
  } \
  MQTTTopicSource get_##name##_##type##_topic_source() const { \
    using Self = std::remove_cvref_t<decltype(*this)>; \
    return this->topic_source_<Self, &Self::get_##name##_##type##_topic_to>(); \
  } \
  std::string get_##name##_##type##_topic() const { \
    if (this->custom_##name##_##type##_topic_.empty()) \
      return this->get_default_topic_for_(#name "/" #type); \
    return this->custom_##name##_##type##_topic_; \
  }
 
#define MQTT_COMPONENT_CUSTOM_TOPIC(name, type) MQTT_COMPONENT_CUSTOM_TOPIC_(name, type)
 
class MQTTComponent : public Component {
  friend void log_mqtt_component(const char *tag, MQTTComponent *obj, bool state_topic, bool command_topic);
 
 public:
  explicit MQTTComponent();
 
  void call_setup() override;
 
  virtual void send_discovery(JsonObject root, SendDiscoveryConfig &config) = 0;
 
  virtual bool send_initial_state() = 0;
 
  bool is_internal() const { return this->is_internal_; }
 
  void set_qos(uint8_t qos);
  uint8_t get_qos() const { return this->qos_; }
 
  void set_retain(bool retain);
  bool get_retain() const { return this->retain_; }
 
  void disable_discovery();
  bool is_discovery_enabled() const;
 
  void set_subscribe_qos(uint8_t qos);
 
  virtual const char *component_type() const = 0;
 
  template<typename T> void set_custom_state_topic(T &&custom_state_topic) {
    this->custom_state_topic_ = std::forward<T>(custom_state_topic);
  }
  template<typename T> void set_custom_command_topic(T &&custom_command_topic) {
    this->custom_command_topic_ = std::forward<T>(custom_command_topic);
  }
  void set_command_retain(bool command_retain);
 
  float get_setup_priority() const override;
 
  void set_availability(std::string topic, std::string payload_available, std::string payload_not_available);
  void disable_availability();
 
  void schedule_resend_state();
 
  bool is_resend_pending() const { return this->resend_state_; }
 
  void process_resend();
 
  bool publish(const std::string &topic, const std::string &payload);
 
  bool publish(const std::string &topic, const char *payload, size_t payload_length);
 
  bool publish(const std::string &topic, const char *payload) {
    return this->publish(topic.c_str(), payload, strlen(payload));
  }
 
  bool publish(const char *topic, const char *payload, size_t payload_length);
 
  bool publish(StringRef topic, const char *payload, size_t payload_length) {
    return this->publish(topic.c_str(), payload, payload_length);
  }
 
  bool publish(const char *topic, const char *payload);
 
  bool publish(StringRef topic, const char *payload) { return this->publish(topic.c_str(), payload); }
 
#ifdef USE_ESP8266
  bool publish(const std::string &topic, ProgmemStr payload);
 
  bool publish(const char *topic, ProgmemStr payload);
 
  bool publish(StringRef topic, ProgmemStr payload) { return this->publish(topic.c_str(), payload); }
#endif
 
  bool publish_json(const std::string &topic, const json::json_build_t &f);
 
  bool publish_json(const char *topic, const json::json_build_t &f);
 
  bool publish_json(StringRef topic, const json::json_build_t &f) { return this->publish_json(topic.c_str(), f); }
 
  template<typename T, typename F> void subscribe(T &&topic, F &&callback, uint8_t qos = 0) {
    global_mqtt_client->subscribe(std::forward<T>(topic), std::forward<F>(callback), qos);
  }
 
  template<typename T, typename F> void subscribe_json(T &&topic, F &&callback, uint8_t qos = 0) {
    global_mqtt_client->subscribe_json(std::forward<T>(topic), std::forward<F>(callback), qos);
  }
 
 protected:
  static constexpr uint32_t SEND_DEFER_ID = 0;
 
  bool publish_float_(StringRef topic, float value, int8_t accuracy);
 
  StringRef get_discovery_topic_to_(std::span<char, MQTT_DISCOVERY_TOPIC_MAX_LEN> buf,
                                    const MQTTDiscoveryInfo &discovery_info) const;
 
  StringRef get_default_topic_for_to_(std::span<char, MQTT_DEFAULT_TOPIC_MAX_LEN> buf, const char *suffix,
                                      size_t suffix_len) const;
 
  std::string get_default_topic_for_(const std::string &suffix) const;
 
  virtual const EntityBase *get_entity() const = 0;
 
  const LogString *log_name_() const;
  ESPDEPRECATED("Use log_name_() for logging. Removed in 2027.5.0", "2026.11.0")
  const StringRef &friendly_name_() const;
 
  bool is_disabled_by_default_() const;
 
  StringRef get_state_topic_to_(std::span<char, MQTT_DEFAULT_TOPIC_MAX_LEN> buf) const;
 
  StringRef get_command_topic_to_(std::span<char, MQTT_DEFAULT_TOPIC_MAX_LEN> buf) const;
 
  MQTTTopicSource command_topic_source_() const;
 
  template<typename C, StringRef (C::*Getter)(std::span<char, MQTT_DEFAULT_TOPIC_MAX_LEN>) const>
  MQTTTopicSource topic_source_() const {
    return {[](const void *context, std::span<char, MQTT_DEFAULT_TOPIC_MAX_LEN> buf) {
              return (static_cast<const C *>(context)->*Getter)(buf);
            },
            static_cast<const C *>(this)};
  }
 
  std::string get_state_topic_() const;
 
  std::string get_command_topic_() const;
 
  bool is_connected_() const;
 
  bool send_discovery_();
 
  // ========== INTERNAL METHODS ==========
  // (In most use cases you won't need these)
  StringRef get_default_object_id_to_(std::span<char, OBJECT_ID_MAX_LEN> buf) const;
 
  TemplatableValue<std::string> custom_state_topic_{};
  TemplatableValue<std::string> custom_command_topic_{};
 
  std::unique_ptr<Availability> availability_;
 
  // Packed bitfields - QoS values are 0-2, bools are flags
  uint8_t qos_ : 2 {0};
  uint8_t subscribe_qos_ : 2 {0};
  bool command_retain_ : 1 {false};
  bool retain_ : 1 {true};
  bool discovery_enabled_ : 1 {true};
  bool resend_state_ : 1 {false};
  bool is_internal_ : 1 {false};  
 
  bool compute_is_internal_();
};
 
}  // namespace esphome::mqtt
 
#endif  // USE_MQTt