Handles the internal implementation of the ThingsBoard provision API. See https://thingsboard.io/docs/user-guide/device-provisioning/ for more information. More...

#include <Provision.h>

Inheritance diagram for Provision< Logger >:

[legend]

Collaboration diagram for Provision< Logger >:

[legend]

Public Member Functions
	Provision ()=default
	Constructor. More...

	~Provision () override=default

bool	Provision_Request (Provision_Callback const &callback)
	Requests othe provisioning of a new device, which will call the passed callback. If the credentials from the server for the requested provisioned device have been received. More...

API_Process_Type	Get_Process_Type () const override
	Returns the way the server response should be processed. More...

void	Process_Response (char const topic, uint8_t payload, uint32_t length) override
	Process callback that will be called upon response arrival. More...

void	Process_Json_Response (char const *topic, JsonDocument const &data) override
	Process callback that will be called upon response arrival. More...

bool	Is_Response_Topic_Matching (char const *topic) const override
	Compares received response topic and the topic this api implementation handles responses on, messages from all other topics are ignored and only messages from topics that match are handled. More...

bool	Unsubscribe () override
	Unsubcribes all callbacks, to clear up any ongoing subscriptions and stop receiving information over the previously subscribed topic. More...

bool	Resubscribe_Permanent_Subscriptions () override
	Forwards the call to let the API clear up any ongoing single-event subscriptions (Provision, Attribute Request, RPC Request) and simply resubscribes the topic for all permanent subscriptions (RPC, Shared Attribute Update) More...

void	loop () override
	Internal loop method to update inernal timers for API calls that can timeout. More...

void	Initialize () override
	Method that allows to construct internal objects, after the required callback member methods have been set already. More...

void	Set_Client_Callbacks (Callback< void, IAPI_Implementation & >::function subscribe_api_callback, Callback< bool, char const const, JsonDocument const & >::function send_json_callback, Callback< bool, char const const, char const const >::function send_json_string_callback, Callback< bool, char const const >::function subscribe_topic_callback, Callback< bool, char const const >::function unsubscribe_topic_callback, Callback< uint16_t >::function get_receive_size_callback, Callback< uint16_t >::function get_send_size_callback, Callback< bool, uint16_t, uint16_t >::function set_buffer_size_callback, Callback< size_t >::function get_request_id_callback) override
	Sets the underlying callbacks that are required for the different API Implementation to communicate with the cloud. More...

Public Member Functions inherited from IAPI_Implementation
virtual	~IAPI_Implementation ()
	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 API_Process_Type	Get_Process_Type () const =0
	Returns the way the server response should be processed. More...

virtual void	Process_Response (char const topic, uint8_t payload, uint32_t length)=0
	Process callback that will be called upon response arrival. More...

virtual void	Process_Json_Response (char const *topic, JsonDocument const &data)=0
	Process callback that will be called upon response arrival. More...

virtual bool	Is_Response_Topic_Matching (char const *topic) const =0
	Compares received response topic and the topic this api implementation handles responses on, messages from all other topics are ignored and only messages from topics that match are handled. More...

virtual bool	Unsubscribe ()=0
	Unsubcribes all callbacks, to clear up any ongoing subscriptions and stop receiving information over the previously subscribed topic. More...

virtual bool	Resubscribe_Permanent_Subscriptions ()=0
	Forwards the call to let the API clear up any ongoing single-event subscriptions (Provision, Attribute Request, RPC Request) and simply resubscribes the topic for all permanent subscriptions (RPC, Shared Attribute Update) More...

virtual void	loop ()=0
	Internal loop method to update inernal timers for API calls that can timeout. More...

virtual void	Initialize ()=0
	Method that allows to construct internal objects, after the required callback member methods have been set already. More...

virtual void	Set_Client_Callbacks (Callback< void, IAPI_Implementation & >::function subscribe_api_callback, Callback< bool, char const const, JsonDocument const & >::function send_json_callback, Callback< bool, char const const, char const const >::function send_json_string_callback, Callback< bool, char const const >::function subscribe_topic_callback, Callback< bool, char const const >::function unsubscribe_topic_callback, Callback< uint16_t >::function get_receive_size_callback, Callback< uint16_t >::function get_send_size_callback, Callback< bool, uint16_t, uint16_t >::function set_buffer_size_callback, Callback< size_t >::function get_request_id_callback)=0
	Sets the underlying callbacks that are required for the different API Implementation to communicate with the cloud. More...

Detailed Description

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

Handles the internal implementation of the ThingsBoard provision API. See https://thingsboard.io/docs/user-guide/device-provisioning/ for more information.

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

◆ Provision()

template<typename Logger = DefaultLogger>

Provision< Logger >::Provision ( )

default

Constructor.

◆ ~Provision()

template<typename Logger = DefaultLogger>

Provision< Logger >::~Provision ( )

overridedefault

Member Function Documentation

◆ Get_Process_Type()

template<typename Logger = DefaultLogger>

API_Process_Type Provision< Logger >::Get_Process_Type ( ) const

inlineoverridevirtual

Returns the way the server response should be processed.

Note: Response can only ever be process using one option, because the response is either unserialized data, which we need to process as such (OTA Firmware Update) or actually JSON which needs to be serialized (everything else)

Returns: How the API implementation processes the server response

Implements IAPI_Implementation.

◆ Initialize()

template<typename Logger = DefaultLogger>

void Provision< Logger >::Initialize ( )

inlineoverridevirtual

Method that allows to construct internal objects, after the required callback member methods have been set already.

Note: Required for API Implementations that subscribe further API calls, because immediately calling in the constructor can lead, to attempted subscriptions before the client callbacks are actually subscribed. Therefore we have to call methods like that, in this method instead, because it ensures all member methods are instantiated already

Implements IAPI_Implementation.

◆ Is_Response_Topic_Matching()

template<typename Logger = DefaultLogger>

bool Provision< Logger >::Is_Response_Topic_Matching ( char const * topic ) const

inlineoverridevirtual

Compares received response topic and the topic this api implementation handles responses on, messages from all other topics are ignored and only messages from topics that match are handled.

Note: For the comparsion we either compare the full expected string with null termination, if the response topic does not include additional parameters, example being shared attribute update (v1/devices/me/attributes). Or we compare only before the null termination for topics that include additional parameters in the response. Like for example the original request id in the response of the attribute request (v1/devices/me/attributes/response/1)

Parameters

topic Non owning pointer to the previously subscribed topic, we got the response over. Does not need to be kept alive, because the topic is only used for the scope of the method itself

Returns: Whether the received response topic matches the topic this api implementation handles responses on

Implements IAPI_Implementation.

◆ loop()

template<typename Logger = DefaultLogger>

void Provision< Logger >::loop ( )

inlineoverridevirtual

Internal loop method to update inernal timers for API calls that can timeout.

Note: Only exists on boards that can not use the ESP Timer, because that one uses the FreeRTOS timer in the background instead and therefore does not require calling a loop method

Implements IAPI_Implementation.

◆ Process_Json_Response()

template<typename Logger = DefaultLogger>

void Provision< Logger >::Process_Json_Response	(	char const *	topic,
		JsonDocument const &	data
	)

inlineoverridevirtual

Process callback that will be called upon response arrival.

Note: Responsible for handling the alredy serialized payload. If the response only wants to be handled before serialization Process_Response should contain the implementation instead and Get_Process_Type should return API_Process_Type::RAW

Parameters

topic	Non owning pointer to the previously subscribed topic, we got the response over. Does not need to be kept alive, because the topic is only used for the scope of the method itself
data	Payload sent by the server over our given topic, that contains our key value pairs

Implements IAPI_Implementation.

◆ Process_Response()

template<typename Logger = DefaultLogger>

void Provision< Logger >::Process_Response	(	char const *	topic,
		uint8_t *	payload,
		uint32_t	length
	)

inlineoverridevirtual

Process callback that will be called upon response arrival.

Note: Responsible for handling the payload before serialization. If the response only wants to be handled after serialization Process_Json_Response should contain the implementation instead and Get_Process_Type should return API_Process_Type::JSON

Parameters

topic	Non owning pointer to the previously subscribed topic, we got the response over. Does not need to be kept alive, because the topic is only used for the scope of the method itself
payload	Non owning pointer to the payload that was sent over the cloud and received over the given topic. Does not need to be kept alive, because the byte payload is only used for the scope of the method itself
length	Total length of the received payload

Implements IAPI_Implementation.

◆ Provision_Request()

template<typename Logger = DefaultLogger>

bool Provision< Logger >::Provision_Request ( Provision_Callback const & callback )

inline

Requests othe provisioning of a new device, which will call the passed callback. If the credentials from the server for the requested provisioned device have been received.

Note: The configured provision device key / secret decide which device profile is used to create the device from. Optionally a device name can be passed or be left empty (cloud will use a random string as the name instead). The data contained in that callback, being the device credentials, can then be used to disconnect and reconnect to the ThingsBoard server as our newly created device. Because the provisiong request is a single event subscription, meaning we only ever receive one response for one request, the request is automatically unsubscribde and the internally allocated data for the request deleted as soon as the response has been received and handled by the subscribed callback. See https://thingsboard.io/docs/user-guide/device-provisioning/ for more information

Parameters

callback Callback method that will be called when the requested provision response has been received

Returns: Whether sending the request to the cloud was successfull. Is non-blocking and therefore a true value returned by this method does not guarantee a response will ever be received. If wanted by the user the optional timeout callback and timeout time in the callback instance can be configured, which will inform the user by calling the timeout callback, if no response has been received by the server in the expected time

◆ Resubscribe_Permanent_Subscriptions()

template<typename Logger = DefaultLogger>

bool Provision< Logger >::Resubscribe_Permanent_Subscriptions ( )

inlineoverridevirtual

Forwards the call to let the API clear up any ongoing single-event subscriptions (Provision, Attribute Request, RPC Request) and simply resubscribes the topic for all permanent subscriptions (RPC, Shared Attribute Update)

Returns: Whether resubscribing was successfull or not

Implements IAPI_Implementation.

◆ Set_Client_Callbacks()

template<typename Logger = DefaultLogger>

void Provision< Logger >::Set_Client_Callbacks	(	Callback< void, IAPI_Implementation & >::function	subscribe_api_callback,
		Callback< bool, char const *const, JsonDocument const & >::function	send_json_callback,
		Callback< bool, char const const, char const const >::function	send_json_string_callback,
		Callback< bool, char const *const >::function	subscribe_topic_callback,
		Callback< bool, char const *const >::function	unsubscribe_topic_callback,
		Callback< uint16_t >::function	get_receive_size_callback,
		Callback< uint16_t >::function	get_send_size_callback,
		Callback< bool, uint16_t, uint16_t >::function	set_buffer_size_callback,
		Callback< size_t * >::function	get_request_id_callback
	)

inlineoverridevirtual

Sets the underlying callbacks that are required for the different API Implementation to communicate with the cloud.

Note: 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

subscribe_api_callback	Method which allows to subscribe additional API endpoints, points to Subscribe_API_Implementation per default
send_json_callback	Method which allows to send arbitrary JSON payload, points to Send_Json per default
send_json_string_callback	Method which allows to send arbitrary JSON string payload, points to Send_Json_String per default
subscribe_topic_callback	Method which allows to subscribe to arbitrary topics, points to m_client.subscribe per default
unsubscribe_topic_callback	Method which allows to unsubscribe from arbitrary topics, points to m_client.unsubscribe per default
get_receive_size_callback	Method which allows to get the current underlying receive size of the buffer, points to m_client.get_receive_buffer_size per default
get_send_size_callback	Method which allows to get the current underlying send size of the buffer, points to m_client.get_send_buffer_size per default
set_buffer_size_callback	Method which allows to set the current underlying size of the buffer, points to m_client.set_buffer_size per default
get_request_id_callback	Method which allows to get the current request id as a mutable reference, points to getRequestID per default

Implements IAPI_Implementation.

◆ Unsubscribe()

template<typename Logger = DefaultLogger>

bool Provision< Logger >::Unsubscribe ( )

inlineoverridevirtual

Unsubcribes all callbacks, to clear up any ongoing subscriptions and stop receiving information over the previously subscribed topic.

Returns: Whether unsubscribing all the previously subscribed callbacks and from the previously subscribed topic, was successful or not

Implements IAPI_Implementation.

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

src/Provision.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Provision()

◆ ~Provision()

Member Function Documentation

◆ Get_Process_Type()

◆ Initialize()

◆ Is_Response_Topic_Matching()

◆ loop()

◆ Process_Json_Response()

◆ Process_Response()

◆ Provision_Request()

◆ Resubscribe_Permanent_Subscriptions()

◆ Set_Client_Callbacks()

◆ Unsubscribe()