IIoTNext Platform

⌘K
  2. Home
  4. Docs
  6. IIoTNext Platform
  8. Key Concepts
  10. Control Commands

Control Commands

Control Remote Device from IIoTNext Platform

Server-side RPC

The Server-side RPC feature allows you to send the request from IIoTNext Platform to the device and optionally get the response back to the platform.

The typical use cases of the server-side RPC calls are all sorts of remote control: reboot, turn the engine on/off, change state of the gpio/actuators, change configuration parameters, etc.

Server-side RPC is divided into one-way and two-way:

  • One-way RPC request does not expect the device to provide any reply.
  • A two-way RPC request expects to receive a response from the device within a configurable timeout.

Server-side RPC structure

The body of server-side RPC request consists of multiple fields:

  • method – mandatory, name of the method to distinguish the RPC calls. For example, “getCurrentTime” or “getWeatherForecast”. The value of the parameter is a string.
  • params – mandatory, parameters used for processing of the request. The value is a JSON. Leave empty JSON “{}” if no parameters are needed.
  • timeout – optional, value of the processing timeout in milliseconds. The default value is 10000 (10 seconds). The minimum value is 5000 (5 seconds).
  • expirationTime – an optional, value of the epoch time (in milliseconds, UTC timezone). Overrides timeout if present.
  • persistent – optional, see [persistent] vs [lightweight] RPC. The default value is “false”.
  • retries – optional, defines how many times persistent RPC will be re-sent in case of failures on the network and/or device side.
  • additionalInfo – optional, defines metadata for the persistent RPC that will be added to the [persistent RPC events].

Example of the RPC request:

{
   "method": "setGPIO",
   "params": {
     "pin": 4,
     "value": 1
   },
  "timeout": 30000
}

 

The RPC response may be any JSON. For example:

{
   "pin": 4,
   "value": 1,
   "changed": true
}

 

Sending server-side RPC

Using the Dashboard

The Control Widgets are used to send RPC commands to the device. The most popular widgets are “RPC Button”, “Round Switch”, “Switch Control” and “Knob Control”. The advanced settings of those widgets allow you to define RPC method name and params. You may also develop custom widgets and use control api to send RPC commands.

Using the Rule Engine

All server-side RPC commands that are sent from the widgets or REST API are eventually transformed to the rule engine message with the “RPC_CALL_FROM_SERVER_TO_DEVICE” message type.

The message contains unique UUID based identifier that is stored in the “requestUUID” metadata field. You may design your Rule flow to process the incoming message using transformation, enrichment or any other rule node type. Finally, one should use RPC Call Request node to send the message to the device.

You may also create the RPC using generator node:

var msg = { method: "rpcCommand", params: {} };
var metadata = { 
    expirationTime: new Date().getTime() + 60000,
    oneway: true,
    persistent: false
};
var msgType = "RPC_CALL_FROM_SERVER_TO_DEVICE";

return { msg: msg, metadata: metadata, msgType: msgType };

Processing server-side RPC on the device

IIoTNext Platform provides a convenient API to receive and process server-side RPC commands on the device. This API is specific for each supported network protocol. You can review API and examples on the corresponding reference page:

Rule flow events

Changes to the RPC states are pushed to the Rule Engine as separate messages. Each RPC state has a corresponding message type. See the image below:

The message contains exhaustive information about the RPC request, including entity ids and “additionalInfo” from the RPC request body. The “RPC Successful” message also contains a reply from the device. These messages are useful if you would like to process the reply from the device in the external system.

See an example of a successful RPC message below:

{
    "id": {
        "entityType": "RPC",
        "id": "bea26301-1aec-11ec-9441-73a37bbb7cd2"
    },
    "createdTime": 1632236465459,
    "tenantId": {
        "entityType": "TENANT",
        "id": "ab937a40-3f98-11eb-a8d6-f5a87f07d4be"
    },
    "deviceId": {
        "entityType": "DEVICE",
        "id": "3e46db70-e480-11eb-9d0e-1f8899a6f9b3"
    },
    "expirationTime": 1632236525354,
    "request": {
        "id": "bea26301-1aec-11ec-9441-73a37bbb7cd2",
        "tenantId": {
            "entityType": "TENANT",
            "id": "ab937a40-3f98-11eb-a8d6-f5a87f07d4be"
        },
        "deviceId": {
            "entityType": "DEVICE",
            "id": "3e46db70-e480-11eb-9d0e-1f8899a6f9b3"
        },
        "oneway": false,
        "expirationTime": 1632236525354,
        "body": {
            "method": "rpcCommand",
            "params": "{}"
        },
        "persisted": true,
        "retries": null
    },
    "response": {
        "test": "passed"
    },
    "status": "SUCCESSFUL",
    "additionalInfo": "{\"param1\":\"value1\",\"param2\":\"value2\"}"
}

 

 






                    


	                  
                    

                                            




    

        
How can we help?