Send RPC Request to the Related Device

ThingsBoard allows you to send remote procedure calls RPC from server-side applications to devices and vice versa.
This Tutorial is to show you how to send a remote request call to a Related Device using Rule Engine.

• Use case
  • Prerequisites
• Model definition
• Message flow
• Configuring the Rule Chain
  • Creating a new Rule Chain (Tutorial of RPC Call Request)
    • Adding the required nodes
      • Node A: Message Type Switch
      • Node B: Save TimeSeries
      • Node C: Related attributes
      • Node D: Change Orignator
      • Node E: Save TimeSeries
      • Node F: Transform Script
      • Node G: Filter Script
      • Node H: RPC call request
• How to verify the Rule Chain
• Configuring Dashboards
• See Also
  • Next steps

Use case

Let’s assume the following use case:

• you have the following devices connected to ThingsBoard:
  • Wind Direction Sensor.
  • Rotating System.
• also, you have one asset:
  • Wind Turbine.
• You want to initiate an RPC request to the Rotating System and change the direction of the Wind Turbine according to the direction of the wind.
• The RPC call will have two properties:
  • method: spinLeft or spinRight.
  • params: value.

Prerequisites

We assume you have completed the following guides and reviewed the articles listed below:

• Getting Started guide.
• Rule Engine Overview.

Model definition

The Wind Turbine has two devices installed: Wind Direction Sensor and Rotating System.

• The Wind turbine is represented as an Asset. Its name is Wind Turbine and its type is Wind turbine.
• The Wind Direction Sensor is represented as a Device. Its name is Wind Direction Sensor and its type is Direction Sensor.
• The Rotating System is represented as a Device. Its name is Rotating System and its type is Rotating System.
• Create a relation of the type Contains:
  • from Wind Turbine to Wind Direction Sensor, and
  • from Wind Turbine to Rotating System.
• Create a relation of the type Uses:
  • from Rotating System to Wind Direction Sensor.

Message flow

In this section, we explain the purpose of each node in this tutorial:

• Node A: Message Type Switch node.
  • Routes incoming messages based on the message type.
• Node B: Save Timeseries node.
  • Stores messages telemetry from Wind Direction Sensor and Rotating System into the database.
• Node C: Related attributes.
  • Loads the source telemetry windDirection of the related Wind Direction Sensor and save it into the Message metadata with the name windDirection.
• Node D: Change originator node.
  • Change the originator from Devices Wind Direction Sensor and Rotating System to the related Asset Wind Turbine and the submitted message will be processed as a message from Asset.
• Node E: Save Timeseries node.
  • Stores messages telemetry from Asset Wind Turbine into the database.
• Node F: Transformation Script.
  • Transform an original message into RPC request message.
• Node G: Filter Script node.
  • Checks if msgType of incoming message is RPC message.
• Node H: RPC call request node.
  • Takes the message payload and sends it as a response to the Rotating System.

Configuring the Rule Chain

The following screenshot shows how the Tutorial of RPC Call Request Rule Chain should look like:

• Download the attached json file for the rule chain indicated above and import it.
• Don’t forget to mark the new rule chain as “root”.

Also, you can create the new Rule Chain from scratch. The following section shows you how to create it.

Creating a new Rule Chain (Tutorial of RPC Call Request)

• Go to Rule Chains -> Add new Rule Chain
• Enter the Name field as Tutorial of RPC Call Request, then click the ADD button.

• The new Rule Chain is now created. Don’t forget to mark it as “root”.

Adding the required nodes

In this tutorial, you will create 8 nodes as it will be explained in the following sections:

Node A: Message Type Switch

• Add the Message Type Switch node and connect it to the Input node.
  This node will route the incoming messages according to the message type, namely POST_TELEMETRY_REQUEST.

• Enter the Name field as Message Type Switch.

Node B: Save TimeSeries

• Add the Save TimeSeries node and connect it to the Message Type Switch node with a relation type Post telemetry.
  This node will store TimeSeries data from incoming Message payload to the database and associate them to the Device, that is identified by the Message Originator, namely Wind Direction Sensor and Rotating System.

• Enter the Name field as Save Time Series.

Node C: Related attributes

• Add the Related attributes node and connect it to the Save TimeSeries node with a relation type Success.
  This node will load the source telemetry windDirection from the related Wind Direction Sensor to Rotating System and save it into the Message metadata with the name windDirection.
• Fill in the fields with the input data shown in the following table:

Node D: Change Orignator

• Add the Change Orignator node and connect it to the Save TimeSeries node with a relation type Success.
  This node will change the originator from Devices Wind Direction Sensor and Rotating System to the Related Asset Wind Turbine that has a relation of the type Contains from each of them.
  As a result, the submitted message will be processed as a message from this Entity
• Fill in the fields with the input data shown in the following table:

Node E: Save TimeSeries

• Add the Save TimeSeries node and connect it to the Change Orignator node with a relation type Success.
  This node will store the TimeSeries data from the incoming Message payload into the database from the Asset Wind Turbine that is Message Originator.
• Enter the Name field as Save Time Series.

Node F: Transform Script

• Add the Transform Script node and connect it to the Related attributes node with a relation type Success.
  This node will transform an original message into RPC request message.
• The RPC call will have 2 properties:
  • method: spinLeft or spinRight.
  • params: value.

• Enter the Name field as New RPC Message.
• Add the following Script:

 var newMsg = {};
 var value = Math.abs(msg.turbineDirection - metadata.windDirection);
 if ((value < 180 && msg.turbineDirection < metadata.windDirection)||
     (value > 180 && msg.turbineDirection > metadata.windDirection)) {
     newMsg.method = 'spinLeft';
 }
 if ((value <= 180 && msg.turbineDirection > metadata.windDirection)||
     (value >= 180 && msg.turbineDirection < metadata.windDirection)) {
     newMsg.method = 'spinRight';
 }
 if(newMsg.method == 'spinLeft' || 'spinRight'){
     msgType = 'RPC message';
 }
 newMsg.params = Math.round(value * 100) / 100;
 return {msg: newMsg, metadata: metadata, msgType: msgType}; 

Node G: Filter Script

• Add the the Filter Script node and connect it to the Transform Script node with a relation type Success.
  This node will check if msgType of incoming message is RPC message.

• Enter the Name field as Check RPC Message.
• Add the following Script:

: return msgType == 'RPC message'; 

Node H: RPC call request

• Add the RPC call request node and connect it to the Filter Script node with a relation type True.
  This node takes the message payload and sends it as a response to the Message Originator.
• Enter the Name field as Rotating System.
• Enter the Timeout value as 60 seconds.

This Rule chain is now ready and you need to save it.

How to verify the Rule Chain

• Use the following javascript code to emulate the Wind Direction Sensor device.
  • WindDirectionEmulator.js.
• Also, use the following javascript code to emulate the Rotating System device.
  This code contains a method to emulate changing the turbine direction based on the incoming RPC message.
  • RotatingSystemEmulator.js.

To run the scripts, you need to do the following steps:

• Copy the Wind Direction Sensor device access token and the Rotating System device access token, then paste them in the script.
  You can copy the access token from the Device page.
  
  In this tutorial,
  • the Wind Direction Sensor device access token is Z61K03FAGSziW9b0nKsm
  • the Rotating System device access token is jSuvzrURCbw7q4LGtygc

  However, these access tokens are unique and you will need to copy the access tokens of your devices.

• Open the terminal and go to the folder that contains these emulator scripts, then run the following commands:
  • node WindDirectionEmulator.js
  • node RotatingSystemEmulator.js

Configuring Dashboards

The following screenshot shows how the Wind Turbine Dashboard should look like:

Download the attached json file for the dashboard indicated above and import it.

• Go to Dashboards -> Add new Dashboard -> Import Dashboard and drop the downloaded json file.

The next Step is to configure the aliases used by the imported dashboard.

Click the Edit alias button and enter the input data shown in the following table:

The configuration of the dashboard is now completed and you can verify that it works as expected.

Also, you can see:

• how to work with RPC call reply Rule Node

Please refer to the second link under the See Also section to see how to do this.

See Also

• For more details about how RPC works in Thignsboard, please refer to the RPC capabilities guide.

• RPC Reply With data from Related Device guide.

Next steps

• Getting started guides - These guides provide quick overview of main ThingsBoard features. Designed to be completed in 15-30 minutes.

• Installation guides - Learn how to setup ThingsBoard on various available operating systems.

• Connect your device - Learn how to connect devices based on your connectivity technology or solution.

• Data visualization - These guides contain instructions how to configure complex ThingsBoard dashboards.

• IoT Data analytics - Learn how to use rule engine to perform basic analytics tasks.

• Hardware samples - Learn how to connect various hardware platforms to ThingsBoard.

• Advanced features - Learn about advanced ThingsBoard features.

• Contribution and Development - Learn about contribution and development in ThingsBoard.