Wrapper around any arbitrary MQTT Client implementing the IMQTT_Client interface, to allow connecting and sending / retrieving data from ThingsBoard over the MQTT or MQTT with TLS/SSL protocol. More...

#include <ThingsBoard.h>

Public Member Functions
template<typename... Args>
	ThingsBoardSized (IMQTT_Client &client, uint16_t receive_buffer_size=DEFAULT_PAYLOAD_SIZE, uint16_t send_buffer_size=DEFAULT_PAYLOAD_SIZE, size_t const &max_stack_size=DEFAULT_MAX_STACK_SIZE, Args const &... args)
	Constructs a instance with the given network client that should be used to establish the connection to ThingsBoard. More...

IMQTT_Client &	Get_Client ()
	Gets the registered underlying MQTT Client implementation. More...

void	Set_Maximum_Stack_Size (size_t const &max_stack_size)
	Sets the maximum amount of bytes that we want to allocate on the stack, before the memory is allocated on the heap instead. More...

size_t const &	Get_Maximum_Stack_Size () const
	Returns the maximum amount of bytes that we want to allocate on the stack, before the memory is allocated on the heap instead. More...

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

uint16_t	Get_Receive_Buffer_Size ()
	Gets the previously set size of the internal buffer size meant for incoming MQTT data. More...

uint16_t	Get_Send_Buffer_Size ()
	Gets the previously set size of the internal buffer size meant for outgoing MQTT data. More...

void	Cleanup_Subscriptions ()
	Clears all currently subscribed callbacks and unsubscribed from all currently subscribed MQTT topics. More...

bool	connect (char const host, char const access_token=PROV_ACCESS_TOKEN, uint16_t port=DEFAULT_MQTT_PORT, char const client_id=nullptr, char const password=nullptr)
	Connects to the given server instance and port with the given credentials. More...

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

bool	connected ()
	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...

MQTT_Connection_State	Get_Connection_State ()
	Get the current connection state to the server includes possible intermediate states between connecting and disconnecting. More...

MQTT_Connection_Error	Get_Last_Connection_Error ()
	Allows to deciper the reason for a failure, while attempting to establish a connection to the MQTT broker. More...

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

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

bool	Send_Json (char const *topic, JsonDocument const &source)
	Sends key-value pairs from the given JsonDocument over the given topic. More...

bool	Send_Json_String (char const topic, char const json)
	Sends key-value pairs from the given json string over the given topic. More...

void	Subscribe_API_Implementation (IAPI_Implementation &api)
	Subscribes the given API implementation. More...

template<typename InputIterator >
void	Subscribe_API_Implementations (InputIterator const &first, InputIterator const &last)
	Subscribes the given API implementation. More...

bool	Claim_Request (size_t const &duration_ms, char const *secret_key=nullptr)
	Send a claiming request for this device. More...

template<typename T >
bool	Send_Telemetry_Data (char const *key, T const &value)
	Sends the given key-value pair as telemetry data. See https://thingsboard.io/docs/user-guide/telemetry/ for more information. More...

template<size_t MaxKeyValuePairAmount, typename InputIterator >
bool	Send_Telemetry (InputIterator const &first, InputIterator const &last)
	Send aggregated key-value pair as telemetry data. More...

bool	Send_Telemetry_String (char const *json)
	Send string containing json as telemetry data. See https://thingsboard.io/docs/user-guide/telemetry/ for more information. More...

bool	Send_Telemetry_Json (JsonDocument const &source)
	Send key-value pairs as telemetry data. See https://thingsboard.io/docs/user-guide/telemetry/ for more information. More...

template<typename T >
bool	Send_Attribute_Data (char const *key, T const &value)
	Sends the given key-value pair as attribute data. See https://thingsboard.io/docs/user-guide/attributes/ for more information. More...

template<size_t MaxKeyValuePairAmount, typename InputIterator >
bool	Send_Attributes (InputIterator const &first, InputIterator const &last)
	Send aggregated key-value pair as attribute data. More...

bool	Send_Attribute_String (char const *json)
	Send string containing json as attribute data. See https://thingsboard.io/docs/user-guide/attribute/ for more information. More...

bool	Send_Attribute_Json (JsonDocument const &source)
	Send key-value pairs as attribute data. See https://thingsboard.io/docs/user-guide/attribute/ for more information. More...

Detailed Description

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>
class ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >

Wrapper around any arbitrary MQTT Client implementing the IMQTT_Client interface, to allow connecting and sending / retrieving data from ThingsBoard over the MQTT or MQTT with TLS/SSL protocol.

Note: BufferSize of the underlying data buffer can be changed during the runtime and the maximum amount of data points that can ever be can be set once as template argument. Additionally, there are internal arrays that hold all subscriptions and requests and statically allocate memory on the stack, which can also be set once as a template argument. Furthermore, there are the maximum amount of values for the internal arrays of the Shared_Attribute_Callback and the Attribute_Request_Callback, which hold the amount of keys we want to request or subscribe to updates too Setting a fixed size, allows to allocate the variables in the container on the stack, which can also be set once as a template argument. Changing is only possible if a new instance of this class is created. If these values should be automatically deduced at runtime and the values dynamically allocated on the heap instead, removing the need to declare them at compile time, simply set THINGSBOARD_ENABLE_DYNAMIC to 1, before including ThingsBoard.h

Template Parameters

MaxResponse	Maximum amount of key-value pairs that will ever be received by ThingsBoard in one call, default = DEFAULT_RESPONSE_AMOUNT (8)
MaxEndpointsAmount	Maximum amount of subscribed API endpoints, DEFAULT_ENDPOINT_AMOUNT is used as the default value because it is big enough to hold one instance of every possible API Implementation, default = DEFAULT_ENDPOINT_AMOUNT (7)
Logger	Implementation that should be used to print error messages generated by internal processes and additional debugging messages if THINGSBOARD_ENABLE_DEBUG is set, default = DefaultLogger

Constructor & Destructor Documentation

◆ ThingsBoardSized()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

template<typename... Args>

ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::ThingsBoardSized	(	IMQTT_Client &	client,
		uint16_t	receive_buffer_size = `DEFAULT_PAYLOAD_SIZE`,
		uint16_t	send_buffer_size = `DEFAULT_PAYLOAD_SIZE`,
		size_t const &	max_stack_size = `DEFAULT_MAX_STACK_SIZE`,
		Args const &...	args
	)

inline

Constructs a instance with the given network client that should be used to establish the connection to ThingsBoard.

Note: Directly forwards the given arguments to the overloaded Container constructor, meaning all combinatons of arguments that would initalize an std::vector can be used to call this constructor. See possible std::vector constructors here https://en.cppreference.com/w/cpp/container/vector/vector, for the possible passable parameters. The possibilites mainly consist out of the fill constructor, where a number n and a value is given and then the value is copied into that many elements, alternatively if no value is given the default constructed value is copied n times instead, or the range constructor where we can pass an interator to the start and to the end of the data container (last element + 1) to copy every element in between thoose iterators, in the same order as in the original data container. The last option is a copy constructor where we pass another container and all the values of that container will be copied into our buffer

Template Parameters

...Args Holds the multiple arguments that will simply be forwarded to the container constructor and therefore allow to use every overloaded constructor without having to explicitly implement them

Parameters

client	MQTT Client implementation that should be used to establish the connection to ThingsBoard
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, default = DEFAULT_PAYLOAD_SIZE (64)
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, default = DEFAULT_PAYLOAD_SIZE (64)
max_stack_size	Maximum amount of bytes we want to allocate on the stack. Is used when sending a lot of data at once over MQTT, because to actually send the JsonDocument data it first has to be serialized into a json string payload. To achieve this the data contained in the JsonDocument is copied for the scope of the Send_Json method and is then copied into the outgoing MQTT buffer. This variable therefore decides the threshold where the JsonDocument is copied into the heap instead of a object on the stack. This is created to ensure no StackOverflow occurs because most supported boards run the actual sending code in a seperate FreeRTOS Task with limited stack space where even a stack allocation of 4 KiB might already cause a crash To circumvent this copy the alternative mentioned in the send_buffer_size argument can also be used because it skips the internal copy alltogether, because the JsonDocument is instead directly copied into the outgoing MQTT buffer, default = DEFAULT_MAX_STACK_SIZE (1024)
max_response_size	Maximum amount of bytes allocated for the interal JsonDocument structure that holds the received payload. Size is calculated automatically from certain characters in the received payload (',', '{', '[') but if we receive a malicious payload that contains these symbols in a string {"example":",,,,,,..."}. It is possible to cause huge allocations, but because the memory only lives for as long as the subscribed callback methods it should not be a problem, especially because attempting to allocate too much memory, will cause the allocation to fail, which is checked. But if the failure of that heap allocation is subscribed for example with the heap_caps_register_failed_alloc_callback method on the ESP32, then that subscribed callback will be called and could theoretically restart the device. To circumvent that we can simply set the size of this variable to a value that should never be exceeded by a non malicious json payload. If this safety feature is not required, because the heap allocation failure callback is not subscribed, then the value of the variable can simply be kept as 0, which means we will not check the received payload for its size before the allocation happens, default = DEFAULT_MAX_RESPONSE_SIZE (0)
buffering_size	Amount of bytes allocated to speed up serialization. Used when THINGSBOARD_ENABLE_STREAM_UTILS is enabled 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. The variable therefore decides the exact buffering size for these packets, where bigger packets cause faster serialization but in exchange require more memory, default = DEFAULT_BUFFERING_SIZE (64)
...args	APIs that should be connected to ThingsBoard and therefore be able to send and receive data over MQTT, that will be forwarded into the overloaded Container constructor see https://en.cppreference.com/w/cpp/container/vector/vector for more information. Ensure the actual API implementations are kept alive as long as the instance of this class. Because the values are not copied, but a non owning pointers to the values are inserted into the local container member variable instead

Member Function Documentation

◆ Claim_Request()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Claim_Request	(	size_t const &	duration_ms,
		char const *	secret_key = `nullptr`
	)

inline

Send a claiming request for this device.

Note: Allows any user registered on the cloud to assign the device as their own (claim), as long as they enter the given corresponding device name and secret key in the given amount of time. Optionally the secret key can be left empty, results in the cloud allowing any user to claim the device without the need to enter a secret key. See https://thingsboard.io/docs/user-guide/claiming-devices/ for more information

Parameters

duration_ms Total time in milliseconds that the device can be claimed for. If the device is not claimed in the given timeframe then another claiming request would need to be sent to allow for the device to be claimed again

secret_key Non owning pointer to the password that needs to be entered to claim the device. Functions as an additional security mechanism to only allow the actual inteded user to claim the device. If this feature is not needed and claiming without the password is wanted simply pass a nullptr or empty string as the argument instead. Does not need to kept alive as the function copies the data into the outgoing MQTT buffer to publish the claiming request, default = nullptr

Returns: Whether copying the created claiming request into the outgoing MQTT buffer, was successful or not

◆ Cleanup_Subscriptions()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

void ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Cleanup_Subscriptions ( )

inline

Clears all currently subscribed callbacks and unsubscribed from all currently subscribed MQTT topics.

Note: Any response that will stil be received is discarded and any ongoing firmware update is aborted and will not be finished. Was done automatically in the connect() method in previous versions of the library, but is not done anymore, because connect() method now reconencts to all previously subscribed MQTT topics instead, therefore there is no need anymore to discard all previously subscribed callbacks and letting the user resubscribe by hand themselves, because that resubscription is now handled automatically. But to allow for the use case of complete unsubscriptions this method still exists

◆ connect()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::connect	(	char const *	host,
		char const *	access_token = `PROV_ACCESS_TOKEN`,
		uint16_t	port = `DEFAULT_MQTT_PORT`,
		char const *	client_id = `nullptr`,
		char const *	password = `nullptr`
	)

inline

Connects to the given server instance and port with the given credentials.

Note: Additionally internal Containers are not deleted or changed when reconnecting so any permanent subscriptions already previously subscribed, does not need to be resubscribed. Furthermore if there are still any active permanent subscriptions (server-side RPC or shared attribute update subscriptions), the aforementioned topics will be resubscribed automatically as soon as the device has successfully connected. This means that any permanent subscriptions will immediately be notified of any changes again once the device connects. This removes the need to register these callbacks every time the device disconnects and instead can be done once at startup. They can even be subscribed before the device has even connected to the cloud

Parameters

host	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
access_token	Non owning pointer to access token, that allows to differentiate which MQTT device is sending the traffic to the MQTT broker. Can be "provision", if the device creates itself instead. See https://thingsboard.io/docs/user-guide/device-provisioning/?mqttprovisioning=without#provision-device-apis for more information. Additionally it has to be kept alive by the user for the runtime of the MQTT client connection, default = PROV_ACCESS_TOKEN ("provision")
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, default = DEFAULT_MQTT_PORT (1883)
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, default = nullptr
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, default = nullptr

Returns: Whether connecting to ThingsBoard was successful or not

◆ connected()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::connected ( )

inline

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()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

void ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::disconnect ( )

inline

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_Client()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

IMQTT_Client & ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Get_Client ( )

inline

Gets the registered underlying MQTT Client implementation.

Note: Allows for calling method directly on the client itself, not advised in normal use cases, as it might cause problems if the library expects the client to be sending / receiving data but it can not do that anymore, because it has been disconnected or certain settings were changed

Returns: Reference to the registered underlying MQTT Client implementation

◆ Get_Connection_State()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

MQTT_Connection_State ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Get_Connection_State ( )

inline

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()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

MQTT_Connection_Error ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Get_Last_Connection_Error ( )

inline

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_Maximum_Stack_Size()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

size_t const & ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Get_Maximum_Stack_Size ( ) const

inline

Returns the maximum amount of bytes that we want to allocate on the stack, before the memory is allocated on the heap instead.

Returns: Maximum amount of bytes we want to allocate on the stack

◆ Get_Receive_Buffer_Size()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

uint16_t ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Get_Receive_Buffer_Size ( )

inline

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()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

uint16_t ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Get_Send_Buffer_Size ( )

inline

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

Returns: Internal size of the buffer

◆ loop()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::loop ( )

inline

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

◆ Send_Attribute_Data()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

template<typename T >

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Send_Attribute_Data	(	char const *	key,
		T const &	value
	)

inline

Sends the given key-value pair as attribute data. See https://thingsboard.io/docs/user-guide/attributes/ for more information.

Template Parameters

T	Type of the passed value

Parameters

key	Non owning pointer to the key of the key-value pair. Does not need to kept alive as the function copies the data into the outgoing MQTT buffer to publish the key-value pair
value	Value of the key-value pair

Returns: Whether copying the key-value pair into the outgoing MQTT buffer, was successful or not

◆ Send_Attribute_Json()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Send_Attribute_Json ( JsonDocument const & source )

inline

Send key-value pairs as attribute data. See https://thingsboard.io/docs/user-guide/attribute/ for more information.

Parameters

source JsonDocument containing our json key-value pairs, is checked before usage for any possible occuring internal errors. See https://arduinojson.org/v6/api/jsondocument/ for more information

Returns: Whether copying the key-value pairs into the outgoing MQTT buffer, was successful or not

◆ Send_Attribute_String()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Send_Attribute_String ( char const * json )

inline

Send string containing json as attribute data. See https://thingsboard.io/docs/user-guide/attribute/ for more information.

Parameters

json	Non owning pointer to the string containing our json key-value pairs Does not need to kept alive as the function copies the data into the outgoing MQTT buffer to publish the key-value pairs

Returns: Whether copying the key-value pairs into the outgoing MQTT buffer, was successful or not

◆ Send_Attributes()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

template<size_t MaxKeyValuePairAmount, typename InputIterator >

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Send_Attributes	(	InputIterator const &	first,
		InputIterator const &	last
	)

inline

Send aggregated key-value pair as attribute data.

Note: Expects iterators to a container containing Attribute class instances. See https://thingsboard.io/docs/user-guide/attribute/ for more information

Template Parameters

InputIterator	Class that allows for forward incrementable access to data of the given data container, allows for using / passing either std::vector or std::array. See https://en.cppreference.com/w/cpp/iterator/input_iterator for more information on the requirements of the iterator
MaxKeyValuePairAmount	Maximum amount of key-value pairs, which will ever be sent with this method. Should simply be the biggest distance between first and last iterator this method is ever called with

Parameters

first	Iterator pointing to the first element in the data container
last	Iterator pointing to the end of the data container (last element + 1)

Returns: Whether copying the key-value pairs into the outgoing MQTT buffer, was successful or not

◆ Send_Json()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Send_Json	(	char const *	topic,
		JsonDocument const &	source
	)

inline

Sends key-value pairs from the given JsonDocument over the given topic.

Note: The passed JsonDocument data first has to be serialized into a json string payload to be then copied into the outgoing MQTT buffer. To circumvent this copy the alternative mentioned in the send_buffer_size argument of the constructor can also be used because it skips the internal copy alltogether, because the JsonDocument is instead directly copied into the outgoing MQTT buffer

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
source	JsonDocument containing our json key-value pairs, is checked before usage for any possible occuring internal errors. See https://arduinojson.org/v6/api/jsondocument/ for more information

Returns: Whether copying the payload contained in the source into the outgoing MQTT buffer, was successful or not

◆ Send_Json_String()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Send_Json_String	(	char const *	topic,
		char const *	json
	)

inline

Sends key-value pairs from the given json string over the given topic.

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
json	Non owning pointer to the string containing serialized json key-value pairs that should be copied into the outgoing MQTT buffer. Does not need to kept alive as the function copies the data into the outgoing MQTT buffer to publish the given payload

Returns: Whether copying the payload contained in the json string into the outgoing MQTT buffer, was successful or not

◆ Send_Telemetry()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

template<size_t MaxKeyValuePairAmount, typename InputIterator >

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Send_Telemetry	(	InputIterator const &	first,
		InputIterator const &	last
	)

inline

Send aggregated key-value pair as telemetry data.

Note: Expects iterators to a container containing Telemetry class instances. See https://thingsboard.io/docs/user-guide/telemetry/ for more information

Template Parameters

InputIterator	Class that allows for forward incrementable access to data of the given data container, allows for using / passing either std::vector or std::array. See https://en.cppreference.com/w/cpp/iterator/input_iterator for more information on the requirements of the iterator
MaxKeyValuePairAmount	Maximum amount of key-value pairs, which will ever be sent with this method. Should simply be the biggest distance between first and last iterator this method is ever called with

Parameters

first	Iterator pointing to the first element in the data container
last	Iterator pointing to the end of the data container (last element + 1)

Returns: Whether copying the key-value pairs into the outgoing MQTT buffer, was successful or not

◆ Send_Telemetry_Data()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

template<typename T >

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Send_Telemetry_Data	(	char const *	key,
		T const &	value
	)

inline

Sends the given key-value pair as telemetry data. See https://thingsboard.io/docs/user-guide/telemetry/ for more information.

Template Parameters

T	Type of the passed value

Parameters

key	Non owning pointer to the key of the key-value pair. Does not need to kept alive as the function copies the data into the outgoing MQTT buffer to publish the key-value pair
value	Value of the key-value pair

Returns: Whether copying the key-value pair into the outgoing MQTT buffer, was successful or not

◆ Send_Telemetry_Json()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Send_Telemetry_Json ( JsonDocument const & source )

inline

Send key-value pairs as telemetry data. See https://thingsboard.io/docs/user-guide/telemetry/ for more information.

Parameters

source JsonDocument containing our json key-value pairs, is checked before usage for any possible occuring internal errors. See https://arduinojson.org/v6/api/jsondocument/ for more information

Returns: Whether copying the key-value pairs into the outgoing MQTT buffer, was successful or not

◆ Send_Telemetry_String()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Send_Telemetry_String ( char const * json )

inline

Send string containing json as telemetry data. See https://thingsboard.io/docs/user-guide/telemetry/ for more information.

Parameters

json	Non owning pointer to the string containing our json key-value pairs Does not need to kept alive as the function copies the data into the outgoing MQTT buffer to publish the key-value pairs

Returns: Whether copying the key-value pairs into the outgoing MQTT buffer, was successful or not

◆ Set_Buffer_Size()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

bool ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Set_Buffer_Size	(	uint16_t	receive_buffer_size,
		uint16_t	send_buffer_size
	)

inline

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_Maximum_Stack_Size()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

void ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Set_Maximum_Stack_Size ( size_t const & max_stack_size )

inline

Sets the maximum amount of bytes that we want to allocate on the stack, before the memory is allocated on the heap instead.

Note: Is used when sending a lot of data at once over MQTT, because to actually send the JsonDocument data it first has to be serialized into a json string payload. To achieve this the data contained in the JsonDocument is copied for the scope of the Send_Json method and is then copied into the outgoing MQTT buffer. This variable therefore decides the threshold where the JsonDocument is copied into the heap instead of a object on the stack. This is created to ensure no StackOverflow occurs because most supported boards run the actual sending code in a seperate FreeRTOS Task with limited stack space where even a stack allocation of 4 KiB might already cause a crash To circumvent this copy the alternative mentioned in the send_buffer_size argument of the constructor can also be used because it skips the internal copy alltogether, because the JsonDocument is instead directly copied into the outgoing MQTT buffer

Parameters

max_stack_size Maximum amount of bytes we want to allocate on the stack

◆ Subscribe_API_Implementation()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

void ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Subscribe_API_Implementation ( IAPI_Implementation & api )

inline

Subscribes the given API implementation.

Note: Ensure the actual API implementation is kept alive as long as the instance of this class. Because the value is not copied, but a non owning pointer to the value is inserted into the local container member variable instead

Parameters

api	Additional API that should be connected to ThingsBoard and therefore be able to send and receive data over MQTT

◆ Subscribe_API_Implementations()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

template<typename InputIterator >

void ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Subscribe_API_Implementations	(	InputIterator const &	first,
		InputIterator const &	last
	)

inline

Subscribes the given API implementation.

Note: Ensure the actual API implementations that should be connected to ThingsBoard and therefore be able to send and receive data over MQTT. Ensure the actual API implementations are kept alive as long as the instance of this class. Because the values are not copied, but a non owning pointers to the values are inserted into the local container member variable instead

Template Parameters

InputIterator Class that allows for forward incrementable access to data of the given data container, allows for using / passing either std::vector or std::array. See https://en.cppreference.com/w/cpp/iterator/input_iterator for more information on the requirements of the iterator

Parameters

first	Iterator pointing to the first element in the data container
last	Iterator pointing to the end of the data container (last element + 1)

◆ Subscribe_Connection_State_Changed_Callback()

template<size_t MaxResponse = DEFAULT_RESPONSE_AMOUNT, size_t MaxEndpointsAmount = DEFAULT_ENDPOINT_AMOUNT, typename Logger = DefaultLogger>

void ThingsBoardSized< MaxResponse, MaxEndpointsAmount, Logger >::Subscribe_Connection_State_Changed_Callback ( Callback< void, MQTT_Connection_State, MQTT_Connection_Error >::function callback )

inline

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

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

src/ThingsBoard.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ThingsBoardSized()

Member Function Documentation

◆ Claim_Request()

◆ Cleanup_Subscriptions()

◆ connect()

◆ connected()

◆ disconnect()

◆ Get_Client()

◆ Get_Connection_State()

◆ Get_Last_Connection_Error()

◆ Get_Maximum_Stack_Size()

◆ Get_Receive_Buffer_Size()

◆ Get_Send_Buffer_Size()

◆ loop()

◆ Send_Attribute_Data()

◆ Send_Attribute_Json()

◆ Send_Attribute_String()

◆ Send_Attributes()

◆ Send_Json()

◆ Send_Json_String()

◆ Send_Telemetry()

◆ Send_Telemetry_Data()

◆ Send_Telemetry_Json()

◆ Send_Telemetry_String()

◆ Set_Buffer_Size()

◆ Set_Maximum_Stack_Size()

◆ Subscribe_API_Implementation()

◆ Subscribe_API_Implementations()

◆ Subscribe_Connection_State_Changed_Callback()