MQTT Client interface that contains the method that a class that can be used to send and receive data over an MQTT connection should implement. More...

#include <IMQTT_Client.h>

Public Member Functions
virtual	~IMQTT_Client ()
	Virtual default destructor, created to ensure that if a pointer to this class is used and deleted, we will also call the derived base class destructor. More...

virtual void	set_data_callback (Callback< void, char , uint8_t , unsigned int >::function callback)=0
	Sets the callback that is called, if any message is received by the MQTT broker. More...

virtual void	set_connect_callback (Callback< void >::function callback)=0
	Sets the callback that is called, if we have successfully established a connection with the MQTT broker. More...

virtual bool	set_buffer_size (uint16_t receive_buffer_size, uint16_t send_buffer_size)=0
	Changes the size of the buffer for sent and received MQTT messages. More...

virtual uint16_t	get_receive_buffer_size ()=0
	Gets the previously set size of the internal buffer size meant for incoming MQTT data. More...

virtual uint16_t	get_send_buffer_size ()=0
	Gets the previously set size of the internal buffer size meant for outgoing MQTT data. More...

virtual void	set_server (char const *domain, uint16_t port)=0
	Configures the server and port that the client should connect with over MQTT. More...

virtual bool	connect (char const client_id, char const user_name, char const *password)=0
	Connects to the previously with set_server configured server instance and port with the given credentials. More...

virtual void	disconnect ()=0
	Force disconnects from the previously connected server and should release all used resources. More...

virtual bool	loop ()=0
	Receives / sends any outstanding messages from and to the MQTT broker. More...

virtual bool	publish (char const topic, uint8_t const payload, size_t const &length)=0
	Sends the given payload over the previously established connection. More...

virtual bool	subscribe (char const *topic)=0
	Subscribes to MQTT message on the given topic, which will cause an internal callback to be called for each message received on that topic from the server, it should then, call the previously configured callback with set_data_callback() with the received data. More...

virtual bool	unsubscribe (char const *topic)=0
	Unsubscribes to previously subscribed MQTT messages of the given topic. More...

virtual bool	connected ()=0
	Returns our current connection status to MQTT, true meaning we are connected, false meaning we have been disconnected or have not established a connection yet. More...

virtual MQTT_Connection_State	get_connection_state () const =0
	Get the current connection state to the server includes possible intermediate states between connecting and disconnecting. More...

virtual MQTT_Connection_Error	get_last_connection_error () const =0
	Allows to deciper the reason for a failure, while attempting to establish a connection to the MQTT broker. More...

virtual void	subscribe_connection_state_changed_callback (Callback< void, MQTT_Connection_State, MQTT_Connection_Error >::function callback)=0
	Sets the callback that is called, whenever the underlying state of our connection with the MQTT broker changes. More...

Detailed Description

MQTT Client interface that contains the method that a class that can be used to send and receive data over an MQTT connection should implement.

Note: Seperates the specific implementation used from the ThingsBoard client, allows to use different clients depending on different needs. In this case the main use case of the seperation is to both support Espressif IDF and Arduino with the following libraries as recommendations. The default MQTT Client for Arduino is the PubSubClient forked from ThingsBoard (https://github.com/thingsboard/pubsubclient), it includes fixes to solve issues with using std::function callbacks for non ESP boards. For Espressif IDF however the default MQTT Client is the esp-mqtt (https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/mqtt.html) component. The aforementioned recommendations are already implemented in the library and can can simply be used and included when using the library, for Arduino the Arduino_MQTT_Client can simply be included and for Espressif IDF the Espressif_MQTT_Client can simply be included, the implementations have been tested and should be compatible when used in conjunction with the ThingsBoard client. Alternatively when using Arduino it is possible to enable support for THINGSBOARD_ENABLE_STREAM_UTILS by importing the ArduinoStreamUtils (https://github.com/bblanchon/ArduinoStreamUtils) in the project. This feature allows to improve the underlying data streams by directly writing the data into the MQTT Client instead of into an output buffer, but writing each byte one by one, would be too slow, therefore the ArduinoStreamUtils (https://github.com/bblanchon/ArduinoStreamUtils) library is used to buffer those calls into bigger packets. This allows sending data that is very big without requiring to allocate that much memory, because it is sent in smaller packets. To support this feature, however this interface needs to additionally implement the Print interface, because that is required by the wrapper class BufferingPrint, which only exists on Arduino This then allows to send arbitrary size payloads if that is done the internal buffer of the MQTT Client implementation can theoretically set the value as big as the buffering_size passed to the constructor + enough memory to hold the topic and MQTT Header ~= 20 bytes. This will mean though that all messages are sent over the StreamUtils library as long as they are bigger than the internal send buffer size, which needs more time than sending a message directly but has the advantage of requiring less memory

Constructor & Destructor Documentation

◆ ~IMQTT_Client()

virtual IMQTT_Client::~IMQTT_Client ( )

inlinevirtual

Virtual default destructor, created to ensure that if a pointer to this class is used and deleted, we will also call the derived base class destructor.

Note: Deleting a base class destructor that does not have a virtual destructor is undefined behaviour, because the derived class destructor originally instantiated with new is never called. This can cause potential memory leaks, because derived classes can not clean up their internal members as expected and instead simply leak them

Member Function Documentation

◆ connect()

virtual bool IMQTT_Client::connect	(	char const *	client_id,
		char const *	user_name,
		char const *	password
	)

pure virtual

Connects to the previously with set_server configured server instance and port with the given credentials.

Parameters

client_id	Non owning pointer to client identification code, that allows to differentiate which MQTT device is sending the traffic to the MQTT broker. Additionally it has to be kept alive by the user for the runtime of the MQTT client connection
user_name	Non owning pointer to client username that is used to authenticate, who is connecting over MQTT. Additionally it has to be kept alive by the user for the runtime of the MQTT client connection
password	Non owning pointer to client password that is used to authenticate, who is connecting over MQTT. Additionally it has to be kept alive by the user for the runtime of the MQTT client connection

Returns: Whether the client could establish the connection successfully or not

◆ connected()

virtual bool IMQTT_Client::connected ( )

pure virtual

Returns our current connection status to MQTT, true meaning we are connected, false meaning we have been disconnected or have not established a connection yet.

Returns: Whether the client is currently connected or not

◆ disconnect()

virtual void IMQTT_Client::disconnect ( )

pure virtual

Force disconnects from the previously connected server and should release all used resources.

Note: Be aware that Espressif_MQTT_Client automatically reconnects, as long as Espressif_MQTT_Client::set_disable_auto_reconnect was not set to true

◆ get_connection_state()

virtual MQTT_Connection_State IMQTT_Client::get_connection_state ( ) const

pure virtual

Get the current connection state to the server includes possible intermediate states between connecting and disconnecting.

Note: Only the Espressif_MQTT_Client ever returns the intermediate states, because the implementation is non blocking. Meaning calling disconnect will not immediately disconnect from the cloud but instead require a while. In comparsion Arduino_MQTT_Client is blocking, meaning we block until we disconnected or connected. If the ERROR state is returned, the reason for the failed connection can be deciphered more clearly using get_last_connection_error

Returns: The current state of the connection to the MQTT broker

◆ get_last_connection_error()

virtual MQTT_Connection_Error IMQTT_Client::get_last_connection_error ( ) const

pure virtual

Allows to deciper the reason for a failure, while attempting to establish a connection to the MQTT broker.

Note: Shows the reason for the last failure to connect or the current one, if get_connection_state returns the ERROR state

Returns: The last error that occured while attempting to establish a connection to MQTT

◆ get_receive_buffer_size()

virtual uint16_t IMQTT_Client::get_receive_buffer_size ( )

pure virtual

Gets the previously set size of the internal buffer size meant for incoming MQTT data.

Returns: Internal size of the buffer

◆ get_send_buffer_size()

virtual uint16_t IMQTT_Client::get_send_buffer_size ( )

pure virtual

Gets the previously set size of the internal buffer size meant for outgoing MQTT data.

Returns: Internal size of the buffer

◆ loop()

virtual bool IMQTT_Client::loop ( )

pure virtual

Receives / sends any outstanding messages from and to the MQTT broker.

Note: Only required if the MQTT client is blocking and does not use a seperate task to process messages. This is the case for Arduino_MQTT_Client, which requires calls to this method to actually process the received and sent data. For the Espressif_MQTT_Client however, this method simply does nothing and never needs to be called, because received and set data is processed using a seperate FreeRTOS task

Returns: Whether sending or receiving the oustanding the messages was successful or not. Returns false if an internal error occured or the connection has been lost. Exact state can be read from get_connection_state and get_last_connection_error

◆ publish()

virtual bool IMQTT_Client::publish	(	char const *	topic,
		uint8_t const *	payload,
		size_t const &	length
	)

pure virtual

Sends the given payload over the previously established connection.

Parameters

topic	Non owning pointer to topic that the message is sent over, where different MQTT topics expect a different kind of payload. Does not need to kept alive as the function copies the data into the outgoing MQTT buffer to publish the given payload
payload	Payload containg the data that should be sent
length	Length of the payload in bytes

Returns: Whether publishing the payload on the given topic was successful or not

◆ set_buffer_size()

virtual bool IMQTT_Client::set_buffer_size	(	uint16_t	receive_buffer_size,
		uint16_t	send_buffer_size
	)

pure virtual

Changes the size of the buffer for sent and received MQTT messages.

Note: The value can not be bigger than uint16_t because the maximum message size received or sent by MQTT can never be bigger than 64K, because it relies on TCP and the TCP size limit also uses a uint16_t internally for the size parameter

Parameters

receive_buffer_size Maximum amount of data that can be received via MQTT at once, expected behaviour is that, if bigger packets are received they are discarded and a warning is printed to the console. Should be big enough to hold the biggest response that is expected to be ever received by the device at once

send_buffer_size Maximum amount of data that can be sent via MQTT at once, expected behaviour is that, if we attempt to send data that is bigger, it will simply not be sent and a message is printed to the console instead. Should be big enough to hold the biggest request that is expected to be ever sent by the device at once. Alternatively when using Arduino it is possible to enable support for THINGSBOARD_ENABLE_STREAM_UTILS by importing the ArduinoStreamUtils (https://github.com/bblanchon/ArduinoStreamUtils) in the project. This feature allows to improve the underlying data streams by directly writing the data into the MQTT Client instead of into an output buffer, but writing each byte one by one, would be too slow, therefore the ArduinoStreamUtils (https://github.com/bblanchon/ArduinoStreamUtils) library is used to buffer those calls into bigger packets. This allows sending data that is very big without requiring to allocate that much memory, because it is sent in smaller packets. To support this feature, however this interface needs to additionally implement the Print interface, because that is required by the wrapper class BufferingPrint, which only exists on Arduino This then allows to send arbitrary size payloads if that is done the internal buffer of the MQTT Client implementation can theoretically set the value as big as the buffering_size passed to the constructor + enough memory to hold the topic and MQTT Header ~= 20 bytes. This will mean though that all messages are sent over the StreamUtils library as long as they are bigger than the internal send buffer size, which needs more time than sending a message directly but has the advantage of requiring less memory

Returns: Whether allocating the needed memory for the given buffer sizes was successful or not

◆ set_connect_callback()

virtual void IMQTT_Client::set_connect_callback ( Callback< void >::function callback )

pure virtual

Sets the callback that is called, if we have successfully established a connection with the MQTT broker.

Note: Directly set by the used ThingsBoard client to its internal method, therefore calling again and overriding as a user ist not recommended, unless you know what you are doing. If receiving information once the device has connected is wanted by the user it is recommended to use subscribe_connection_state_changed_callback method instead

Parameters

callback Method that should be called on established MQTT connection

◆ set_data_callback()

virtual void IMQTT_Client::set_data_callback ( Callback< void, char *, uint8_t *, unsigned int >::function callback )

pure virtual

Sets the callback that is called, if any message is received by the MQTT broker.

Note: The callback is called with the topic string that the message was received over, as well as the payload data and the size of that payload data. Directly set by the used ThingsBoard client to its internal methods, therefore calling again and overriding as a user ist not recommended, unless you know what you are doing

Parameters

callback Method that should be called on received MQTT response

◆ set_server()

virtual void IMQTT_Client::set_server	(	char const *	domain,
		uint16_t	port
	)

pure virtual

Configures the server and port that the client should connect with over MQTT.

Note: Should be called atleast once before calling connect() so the target server and port to connect too have been configured

Parameters

domain Non owning pointer to server instance name the client should connect too. Additionally it has to be kept alive by the user for the runtime of the MQTT client connection

port Port that will be used to establish a connection and send / receive data. Should be either 1883 for unencrypted MQTT or 8883 for MQTT with TLS/SSL encryption. The latter is recommended if relevant data is sent or if the client receives and handles Remote Procedure Calls or Shared Attribute Update Callbacks from the server, because using an unencrpyted connection, will allow 3rd parties to listen to the communication and impersonate the server sending payloads which might influence the device in unexpected ways. However if Over the Air udpates are enabled secure communication should definetly be enabled, because if that is not done a 3rd party might impersonate the server sending a malicious payload, which is then flashed onto the device instead of the real firmware. Which depeding on the payload might even be able to destroy the device or make it otherwise unusable. See https://stackoverflow.blog/2020/12/14/security-considerations-for-ota-software-updates-for-iot-gateway-devices/ for more information on the aforementioned security risk

◆ subscribe()

virtual bool IMQTT_Client::subscribe ( char const * topic )

pure virtual

Subscribes to MQTT message on the given topic, which will cause an internal callback to be called for each message received on that topic from the server, it should then, call the previously configured callback with set_data_callback() with the received data.

Parameters

topic Non owning pointer to topic we want to receive a notification about if messages are sent by the server. Does not need to kept alive as the function copies the data into the outgoing MQTT buffer to subscribe to the given topic

Returns: Wheter subscribing the given topic was possible or not, should return false and a warning should be printed, if the connection has been lost or the topic does not exist

◆ subscribe_connection_state_changed_callback()

virtual void IMQTT_Client::subscribe_connection_state_changed_callback ( Callback< void, MQTT_Connection_State, MQTT_Connection_Error >::function callback )

pure virtual

Sets the callback that is called, whenever the underlying state of our connection with the MQTT broker changes.

Note: Is called when we for example attempt to connect to the MQTT broker, or once the underlying client has connected or failed to connect. Passes the current connection state, also accessible with get_connection_state and the last error that occured while trying to connect, also accessible with get_last_connection_error as additional information

Parameters

callback Method that should be called on state changes to our MQTT connection

◆ unsubscribe()

virtual bool IMQTT_Client::unsubscribe ( char const * topic )

pure virtual

Unsubscribes to previously subscribed MQTT messages of the given topic.

Parameters

topic Non owning pointer to topic we want to stop receiving a notification about if messages are sent by the server Does not need to kept alive as the function copies the data into the outgoing MQTT buffer to unsubscribe from the given topic

Returns: Wheter unsubscribing the given topic was possible or not, should return false and a warning should be printed, if the connection has been lost or the topic was not previously subscribed

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

src/IMQTT_Client.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~IMQTT_Client()

Member Function Documentation

◆ connect()

◆ connected()

◆ disconnect()

◆ get_connection_state()

◆ get_last_connection_error()

◆ get_receive_buffer_size()

◆ get_send_buffer_size()

◆ loop()

◆ publish()

◆ set_buffer_size()

◆ set_connect_callback()

◆ set_data_callback()

◆ set_server()

◆ subscribe()

◆ subscribe_connection_state_changed_callback()

◆ unsubscribe()