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

#include <Server_Side_RPC.h>

Inheritance diagram for Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >:

[legend]

Collaboration diagram for Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >:

[legend]

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

	~Server_Side_RPC () override=default

template<typename InputIterator >
bool	RPC_Subscribe (InputIterator const &first, InputIterator const &last)
	Subscribes multiple server-side RPC callbacks, that will be called if a request from the server for the method with the given name is received. More...

bool	RPC_Subscribe (RPC_Callback const &callback)
	Subscribe one server-side RPC callback, that will be called if a request from the server for the method with the given name is received. More...

bool	RPC_Unsubscribe ()
	Unsubcribes all server-side RPC callbacks. See https://thingsboard.io/docs/user-guide/rpc/#server-side-rpc for more information. 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 MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>
class Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >

Handles the internal implementation of the ThingsBoard server-side RPC API. See https://thingsboard.io/docs/user-guide/rpc/#server-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 server-side RPC subscriptions. Once the maximum amount has been reached it is not possible to increase the size, this is done because it allows to allcoate the memory on the stack instead of the heap, default = DEFAULT_SUBSCRIPTION_AMOUNT (1)
MaxRPC	Maximum amount of key-value pairs that will ever be sent in the subscribed callback method of an RPC_Callback, allows to use a StaticJsonDocument on the stack in the background. If we simply use .to<JsonVariant>(); on the received document and use .set() to change the internal value then the size requirements are 0. However if we attempt to send multiple key-value pairs, we have to adjust the size accordingly. See https://arduinojson.org/v6/assistant/ for more information on how to estimate the required size and divide the result by 16 to receive the required MaxRPC value, default = DEFAULT_RPC_AMOUNT (0)

Constructor & Destructor Documentation

◆ Server_Side_RPC()

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >::Server_Side_RPC ( )

default

Constructor.

◆ ~Server_Side_RPC()

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >::~Server_Side_RPC ( )

overridedefault

Member Function Documentation

◆ Get_Process_Type()

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

API_Process_Type Server_Side_RPC< MaxSubscriptions, MaxRPC, 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 MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

void Server_Side_RPC< MaxSubscriptions, MaxRPC, 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 MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

bool Server_Side_RPC< MaxSubscriptions, MaxRPC, 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 MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

void Server_Side_RPC< MaxSubscriptions, MaxRPC, 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 MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

void Server_Side_RPC< MaxSubscriptions, MaxRPC, 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 MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

void Server_Side_RPC< MaxSubscriptions, MaxRPC, 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 MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

bool Server_Side_RPC< MaxSubscriptions, MaxRPC, 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_Subscribe() [1/2]

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

template<typename InputIterator >

bool Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >::RPC_Subscribe	(	InputIterator const &	first,
		InputIterator const &	last
	)

inline

Subscribes multiple server-side RPC callbacks, that will be called if a request from the server for the method with the given name is received.

Note: Can be called even if we are currently not connected to the cloud, this is the case because the only interaction that requires an active connection is the subscription of the topic that we receive the response on and that subscription is also done automatically by the library once the device has established a connection to the cloud. Therefore this method can simply be called once at startup before a connection has been established and will then automatically handle the subscription of the topic once the connection has been established. See https://thingsboard.io/docs/user-guide/rpc/#server-side-rpc 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

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 subscribing the given callbacks was successful or not

◆ RPC_Subscribe() [2/2]

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

bool Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >::RPC_Subscribe ( RPC_Callback const & callback )

inline

Subscribe one server-side RPC callback, that will be called if a request from the server for the method with the given name is received.

Note: Can be called even if we are currently not connected to the cloud, this is the case because the only interaction that requires an active connection is the subscription of the topic that we receive the response on and that subscription is also done automatically by the library once the device has established a connection to the cloud. Therefore this method can simply be called once at startup before a connection has been established and will then automatically handle the subscription of the topic once the connection has been established. See https://thingsboard.io/docs/user-guide/rpc/#server-side-rpc for more information

Parameters

callback Callback method that will be called

Returns: Whether subscribing the given callback was successful or not

◆ RPC_Unsubscribe()

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

bool Server_Side_RPC< MaxSubscriptions, MaxRPC, Logger >::RPC_Unsubscribe ( )

inline

Unsubcribes all server-side RPC callbacks. See https://thingsboard.io/docs/user-guide/rpc/#server-side-rpc for more information.

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

◆ Set_Client_Callbacks()

template<size_t MaxSubscriptions = DEFAULT_SUBSCRIPTION_AMOUNT, size_t MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

void Server_Side_RPC< MaxSubscriptions, MaxRPC, 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 MaxRPC = DEFAULT_RPC_AMOUNT, typename Logger = DefaultLogger>

bool Server_Side_RPC< MaxSubscriptions, MaxRPC, 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/Server_Side_RPC.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Server_Side_RPC()

◆ ~Server_Side_RPC()

Member Function Documentation

◆ Get_Process_Type()

◆ Initialize()

◆ Is_Response_Topic_Matching()

◆ loop()

◆ Process_Json_Response()

◆ Process_Response()

◆ Resubscribe_Permanent_Subscriptions()

◆ RPC_Subscribe() [1/2]

◆ RPC_Subscribe() [2/2]

◆ RPC_Unsubscribe()

◆ Set_Client_Callbacks()

◆ Unsubscribe()