Handles the internal implementation of the ThingsBoard client-side RPC API. See https://thingsboard.io/docs/user-guide/rpc/#client-side-rpc for more information. More...

#include <Client_Side_RPC.h>

Inheritance diagram for Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >:

[legend]

Collaboration diagram for Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >:

[legend]

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

	~Client_Side_RPC () override=default

bool	RPC_Request (RPC_Request_Callback const &callback)
	Requests the response from one client-side rpc method, which will call the passed callback. If a response from the server for the executed client-side rpc method was 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<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>
class Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >

Handles the internal implementation of the ThingsBoard client-side RPC API. See https://thingsboard.io/docs/user-guide/rpc/#client-side-rpc 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
MaxSubscriptions	Maximum amount of simultaneous client-side rpc requests. Once the maximum amount has been reached it is not possible to increase the size, this is done because it allows to allocate the internal memory on the stack instead of the heap, default = DEFAULT_SUBSCRIPTION_AMOUNT (1)
MaxRequestRPC	Maximum amount of key-value pairs that will ever be sent as parameters to the requested client-side rpc method, allows to allocate the internal memory on the stack instead of the heap. Default value is big enough only call client-side rpc methods with no parameters. Being a value of 2 to hold the default method name and params key needed for a well-formed request. If additional parameters are ever sent with a request the size has to be increased by one for each value in the JsonArray sent as a parameter, default = DEFAULT_REQUEST_RPC_AMOUNT (2)

Constructor & Destructor Documentation

◆ Client_Side_RPC()

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>

Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >::Client_Side_RPC ( )

default

Constructor.

◆ ~Client_Side_RPC()

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>

Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >::~Client_Side_RPC ( )

overridedefault

Member Function Documentation

◆ Get_Process_Type()

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>

API_Process_Type Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, 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<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>

void Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, 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<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>

bool Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, 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<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>

void Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, 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<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>

void Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, 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<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>

void Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, 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.

◆ Resubscribe_Permanent_Subscriptions()

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>

bool Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, 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.

◆ RPC_Request()

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>

bool Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, Logger >::RPC_Request ( RPC_Request_Callback const & callback )

inline

Requests the response from one client-side rpc method, which will call the passed callback. If a response from the server for the executed client-side rpc method was received.

Note: Because the client-side rpc 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/rpc/#client-side-rpc for more information

Parameters

callback Callback method that will be called when the response from the server for the executed client-side rpc method 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

◆ Set_Client_Callbacks()

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>

void Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, 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<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRequestRPC = DEFAULT_REQUEST_RPC_AMOUNT, typename Logger = DefaultLogger>

bool Client_Side_RPC< MaxSubscriptions, MaxRequestRPC, 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/Client_Side_RPC.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Client_Side_RPC()

◆ ~Client_Side_RPC()

Member Function Documentation

◆ Get_Process_Type()

◆ Initialize()

◆ Is_Response_Topic_Matching()

◆ loop()

◆ Process_Json_Response()

◆ Process_Response()

◆ Resubscribe_Permanent_Subscriptions()

◆ RPC_Request()

◆ Set_Client_Callbacks()

◆ Unsubscribe()