esphome::mqtt::CustomMQTTDevice Class Reference

This class is a helper class for custom components that communicate using MQTT. More...

#include <custom_mqtt_device.h>

Public Member Functions
template<typename T >
void	subscribe (const std::string &topic, void(T::*callback)(const std::string &, const std::string &), uint8_t qos=0)
	Subscribe to an MQTT topic with the given Quality of Service. More...
template<typename T >
void	subscribe (const std::string &topic, void(T::*callback)(const std::string &), uint8_t qos=0)
template<typename T >
void	subscribe (const std::string &topic, void(T::*callback)(), uint8_t qos=0)
template<typename T >
void	subscribe_json (const std::string &topic, void(T::*callback)(const std::string &, JsonObject), uint8_t qos=0)
	Subscribe to an MQTT topic and call the callback if the payload can be decoded as JSON with the given Quality of Service. More...
template<typename T >
void	subscribe_json (const std::string &topic, void(T::*callback)(JsonObject), uint8_t qos=0)
bool	publish (const std::string &topic, const std::string &payload, uint8_t qos=0, bool retain=false)
	Publish an MQTT message with the given payload and QoS and retain settings. More...
bool	publish (const std::string &topic, float value, int8_t number_decimals=3)
	Publish an MQTT message with the given floating point number and number of decimals. More...
bool	publish (const std::string &topic, int value)
	Publish an MQTT message with the given integer as payload. More...
bool	publish_json (const std::string &topic, const json::json_build_t &f, uint8_t qos, bool retain)
	Publish a JSON-encoded MQTT message with the given Quality of Service and retain settings. More...
bool	publish_json (const std::string &topic, const json::json_build_t &f)
	Publish a JSON-encoded MQTT message. More...
bool	is_connected ()
	Check whether the MQTT client is currently connected and messages can be published. More...

Detailed Description

This class is a helper class for custom components that communicate using MQTT.

It has 5 helper functions that you can use (square brackets indicate optional):

• subscribe(topic, function_pointer, [qos])
• subscribe_json(topic, function_pointer, [qos])
• publish(topic, payload, [qos], [retain])
• publish_json(topic, payload_builder, [qos], [retain])
• is_connected()

Definition at line 21 of file custom_mqtt_device.h.

Member Function Documentation

is_connected()

bool esphome::mqtt::CustomMQTTDevice::is_connected

(

)

Check whether the MQTT client is currently connected and messages can be published.

Definition at line 30 of file custom_mqtt_device.cpp.

publish() [1/3]

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

Publish an MQTT message with the given payload and QoS and retain settings.

Example:

void in_some_method() {
  publish("the/topic", "The Payload", 0, true);
}

Parameters

topic	The topic to publish to.
payload	The payload to publish.
qos	The Quality of Service to publish with. Defaults to 0
retain	Whether to retain the message. Defaults to false.

Definition at line 12 of file custom_mqtt_device.cpp.

publish() [2/3]

bool esphome::mqtt::CustomMQTTDevice::publish	(	const std::string &	topic,
		float	value,
		int8_t	number_decimals = 3
	)

Publish an MQTT message with the given floating point number and number of decimals.

Example:

void in_some_method() {
  publish("the/topic", 1.0);
  // with two digits after the decimal point
  publish("the/topic", 1.0, 2);
}

Parameters

topic	The topic to publish to.
payload	The payload to publish.
number_decimals	The number of digits after the decimal point to round to, defaults to 3 digits.

Definition at line 15 of file custom_mqtt_device.cpp.

publish() [3/3]

bool esphome::mqtt::CustomMQTTDevice::publish	(	const std::string &	topic,
		int	value
	)

Publish an MQTT message with the given integer as payload.

Example:

void in_some_method() {
  publish("the/topic", 42);
}

Parameters

topic	The topic to publish to.
payload	The payload to publish.

Definition at line 19 of file custom_mqtt_device.cpp.

publish_json() [1/2]

bool esphome::mqtt::CustomMQTTDevice::publish_json	(	const std::string &	topic,
		const json::json_build_t &	f,
		uint8_t	qos,
		bool	retain
	)

Publish a JSON-encoded MQTT message with the given Quality of Service and retain settings.

Example:

void in_some_method() {
  publish("the/topic", [=](JsonObject root) {
    root["the_key"] = "Hello World!";
  }, 0, false);
}

Parameters

topic	The topic to publish to.
payload	The payload to publish.
qos	The Quality of Service to publish with.
retain	Whether to retain the message.

Definition at line 24 of file custom_mqtt_device.cpp.

publish_json() [2/2]

bool esphome::mqtt::CustomMQTTDevice::publish_json	(	const std::string &	topic,
		const json::json_build_t &	f
	)

Publish a JSON-encoded MQTT message.

Example:

void in_some_method() {
  publish("the/topic", [=](JsonObject root) {
    root["the_key"] = "Hello World!";
  });
}

Parameters

topic	The topic to publish to.
payload	The payload to publish.

Definition at line 27 of file custom_mqtt_device.cpp.

subscribe() [1/3]

template<typename T >

void esphome::mqtt::CustomMQTTDevice::subscribe	(	const std::string &	topic,
		void(T::*)(const std::string &, const std::string &)	callback,
		uint8_t	qos = 0
	)

Subscribe to an MQTT topic with the given Quality of Service.

Example:

class MyCustomMQTTDevice : public Component, public mqtt:CustomMQTTDevice {
 public:
  void setup() override {
    subscribe("the/topic", &MyCustomMQTTDevice::on_message);
    pinMode(5, OUTPUT);
  }

  // topic and payload parameters can be removed if not needed
  // e.g: void on_message() {

  void on_message(const std::string &topic, const std::string &payload) {
    // do something with topic and payload
    if (payload == "ON") {
      digitalWrite(5, HIGH);
    } else {
      digitalWrite(5, LOW);
    }
  }
};

Template Parameters

T	A C++ template argument for determining the type of the callback.

Parameters

topic	The topic to subscribe to. Re-subscription on re-connects is automatically handled.
callback	The callback (must be a class member) to subscribe with.
qos	The Quality of Service to subscribe with. Defaults to 0.

Definition at line 191 of file custom_mqtt_device.h.

subscribe() [2/3]

template<typename T >

void esphome::mqtt::CustomMQTTDevice::subscribe	(	const std::string &	topic,
		void(T::*)(const std::string &)	callback,
		uint8_t	qos = 0
	)

Definition at line 197 of file custom_mqtt_device.h.

subscribe() [3/3]

template<typename T >

void esphome::mqtt::CustomMQTTDevice::subscribe	(	const std::string &	topic,
		void(T::*)()	callback,
		uint8_t	qos = 0
	)

Definition at line 201 of file custom_mqtt_device.h.

subscribe_json() [1/2]

template<typename T >

void esphome::mqtt::CustomMQTTDevice::subscribe_json	(	const std::string &	topic,
		void(T::*)(const std::string &, JsonObject)	callback,
		uint8_t	qos = 0
	)

Subscribe to an MQTT topic and call the callback if the payload can be decoded as JSON with the given Quality of Service.

Example:

class MyCustomMQTTDevice : public Component, public mqtt:CustomMQTTDevice {
 public:
  void setup() override {
    subscribe_json("the/topic", &MyCustomMQTTDevice::on_json_message);
    pinMode(5, OUTPUT);
  }

  // topic parameter can be remove if not needed:
  // e.g.: void on_json_message(JsonObject payload) {

  void on_json_message(const std::string &topic, JsonObject payload) {
    // do something with topic and payload
    if (payload["number"] == 1) {
      digitalWrite(5, HIGH);
    } else {
      digitalWrite(5, LOW);
    }
  }
};

Template Parameters

T	A C++ template argument for determining the type of the callback.

Parameters

topic	The topic to subscribe to. Re-subscription on re-connects is automatically handled.
callback	The callback (must be a class member) to subscribe with.
qos	The Quality of Service to subscribe with. Defaults to 0.

Definition at line 206 of file custom_mqtt_device.h.

subscribe_json() [2/2]

template<typename T >

void esphome::mqtt::CustomMQTTDevice::subscribe_json	(	const std::string &	topic,
		void(T::*)(JsonObject)	callback,
		uint8_t	qos = 0
	)

Definition at line 212 of file custom_mqtt_device.h.

---

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

• /opt/build/esphome/esphome/components/mqtt/custom_mqtt_device.h
• /opt/build/esphome/esphome/components/mqtt/custom_mqtt_device.cpp