Wrapper around the ArduinoHttpClient to allow connecting and sending / retrieving data from ThingsBoard over the HTTP or HTTPS protocol. More...

#include <ThingsBoardHttp.h>

Public Member Functions
	ThingsBoardHttpSized (IHTTP_Client &client, char const access_token, char const host, uint16_t port=80U, bool keep_alive=true, size_t const &max_stack_size=DEFAULT_MAX_STACK_SIZE)
	Constructs a instance with the given network client that should be used to establish the connection to ThingsBoard. 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	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...

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...

bool	Send_Get_Request (char const *path, std::string &response)
	Attempts to send a GET request over HTTP or HTTPS. More...

bool	Send_Post_Request (char const path, char const json)
	Attempts to send a POST request over HTTP or HTTPS. More...

Detailed Description

template<typename Logger = DefaultLogger>
class ThingsBoardHttpSized< Logger >

Wrapper around the ArduinoHttpClient to allow connecting and sending / retrieving data from ThingsBoard over the HTTP or HTTPS protocol.

Note: BufferSize of the underlying data buffer as well as the maximum amount of data points that can ever be sent have to defined as template arguments. Changing is only possible if a new instance of this class is created. If these values should be changeable and dynamic instead. Simply set THINGSBOARD_ENABLE_DYNAMIC to 1, before including ThingsBoardHttp.h

Template Parameters

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

◆ ThingsBoardHttpSized()

template<typename Logger = DefaultLogger>

ThingsBoardHttpSized< Logger >::ThingsBoardHttpSized	(	IHTTP_Client &	client,
		char const *	access_token,
		char const *	host,
		uint16_t	port = `80U`,
		bool	keep_alive = `true`,
		size_t const &	max_stack_size = `DEFAULT_MAX_STACK_SIZE`
	)

inline

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

Note: Directly connects to the given host over the given port

Parameters

client	HTTP Client implementation that should be used to establish the connection to ThingsBoard
access_token	Non owning pointer to the access token used to verify the devices identity with the ThingsBoard server. Additionally it has to be kept alive by the user for the runtime of the HTTP or HTTPS connection
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 HTTP client connection
port	Port that will be used to establish a connection and send / receive data. Should be either 80 for HTTP (unencrypted) or 443 for HTTPS (encrypted). 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 = 80
keep_alive	Attempts to keep the establishes TCP connection alive to make sending data faster, default = true
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 HTTP, 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 HTTP 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 HTTP buffer, default = DEFAULT_MAX_STACK_SIZE (1024)

Member Function Documentation

◆ Get_Maximum_Stack_Size()

template<typename Logger = DefaultLogger>

size_t const & ThingsBoardHttpSized< 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

◆ Send_Attribute_Data()

template<typename Logger = DefaultLogger>

template<typename T >

bool ThingsBoardHttpSized< 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 HTTP buffer to publish the key-value pair
value	Value of the key-value pair

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

◆ Send_Attribute_Json()

template<typename Logger = DefaultLogger>

bool ThingsBoardHttpSized< 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 HTTP buffer, was successful or not

◆ Send_Attribute_String()

template<typename Logger = DefaultLogger>

bool ThingsBoardHttpSized< 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 HTTP buffer to publish the key-value pairs

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

◆ Send_Attributes()

template<typename Logger = DefaultLogger>

template<size_t MaxKeyValuePairAmount, typename InputIterator >

bool ThingsBoardHttpSized< 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 HTTP buffer, was successful or not

Template Parameters

MaxKeyValuePairAmount Maximum amount of json key value pairs, which will ever be sent with this method to the cloud. Should simply be the biggest distance between first and last iterator this method is ever called with

◆ Send_Get_Request()

template<typename Logger = DefaultLogger>

bool ThingsBoardHttpSized< Logger >::Send_Get_Request	(	char const *	path,
		std::string &	response
	)

inline

Attempts to send a GET request over HTTP or HTTPS.

Parameters

path	API path we want to get data from (example: /api/v1/$TOKEN/rpc)
response	String the GET response will be copied into, will not be changed if the GET request wasn't successful

Returns: Whetherr sending the GET request was successful or not

◆ Send_Json()

template<typename Logger = DefaultLogger>

bool ThingsBoardHttpSized< 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 HTTP buffer

Parameters

topic	Non owning pointer to topic that the message is sent over, where different HTTP topics expect a different kind of payload. Does not need to kept alive as the function copies the data into the outgoing HTTP 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 HTTP buffer, was successful or not

◆ Send_Json_String()

template<typename Logger = DefaultLogger>

bool ThingsBoardHttpSized< 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 HTTP topics expect a different kind of payload. Does not need to kept alive as the function copies the data into the outgoing HTTP 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 HTTP buffer. Does not need to kept alive as the function copies the data into the outgoing HTTP buffer to publish the given payload

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

◆ Send_Post_Request()

template<typename Logger = DefaultLogger>

bool ThingsBoardHttpSized< Logger >::Send_Post_Request	(	char const *	path,
		char const *	json
	)

inline

Attempts to send a POST request over HTTP or HTTPS.

Parameters

path	API path we want to send data to (example: /api/v1/$TOKEN/attributes)
json	String containing our json key value pairs we want to attempt to send

Returns: Whetherr sending the POST request was successful or not

◆ Send_Telemetry()

template<typename Logger = DefaultLogger>

template<size_t MaxKeyValuePairAmount, typename InputIterator >

bool ThingsBoardHttpSized< 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 HTTP buffer, was successful or not

◆ Send_Telemetry_Data()

template<typename Logger = DefaultLogger>

template<typename T >

bool ThingsBoardHttpSized< 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 HTTP buffer to publish the key-value pair
value	Value of the key-value pair

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

◆ Send_Telemetry_Json()

template<typename Logger = DefaultLogger>

bool ThingsBoardHttpSized< 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 HTTP buffer, was successful or not

◆ Send_Telemetry_String()

template<typename Logger = DefaultLogger>

bool ThingsBoardHttpSized< 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 HTTP buffer to publish the key-value pairs

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

◆ Set_Maximum_Stack_Size()

template<typename Logger = DefaultLogger>

void ThingsBoardHttpSized< 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 HTTP, 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 HTTP 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 HTTP buffer

Parameters

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

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

src/ThingsBoardHttp.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ThingsBoardHttpSized()

Member Function Documentation

◆ Get_Maximum_Stack_Size()

◆ Send_Attribute_Data()

◆ Send_Attribute_Json()

◆ Send_Attribute_String()

◆ Send_Attributes()

◆ Send_Get_Request()

◆ Send_Json()

◆ Send_Json_String()

◆ Send_Post_Request()

◆ Send_Telemetry()

◆ Send_Telemetry_Data()

◆ Send_Telemetry_Json()

◆ Send_Telemetry_String()

◆ Set_Maximum_Stack_Size()