Reverse RPC Details

This document is intended for novice readers, introducing the concept, working principle, and configuration usage of Reverse RPC in ThingsGatewayRuntime.

What is Reverse RPC?

Basic Concept

RPC (Remote Procedure Call) is a communication method that allows one computer to call a program on another computer.

Reverse RPC is the "reverse" application of traditional RPC:

Mode	Description	Analogy
Traditional RPC	Client actively calls server methods	A customer actively goes to a restaurant to order food
Reverse RPC	Server passively accepts write requests from external systems	A restaurant prepares dishes and waits for customers to pick them up

Communication Model

Applicable Scenarios

Scenario	Description	Typical Application
Remote Control	Upper computer remotely controls field devices	Start/stop devices, adjust parameters
Data Distribution	Configuration parameters distributed to devices	Set thresholds, recipe distribution
Command Execution	Execute specific device operations	Device reset, calibration operations

---

ThingsGatewayRuntime Reverse RPC Architecture

Architecture Layers

Invocation Flow

1. External system initiates a write request
2. Protocol adaptation layer receives the request
3. Permission check (variable RPC enable, device write permission)
4. Execute variable write
5. Return execution result

---

Protocol Configuration Details

1. OPC UA Reverse RPC

Protocol Features

Feature	Description
High Security	Supports certificate authentication and encrypted communication
Cross-platform	Platform-independent communication protocol
Industrial Standard	Widely used in industrial automation

Configuration Steps

Step 1: Create an OPC UA Server device

1. Create a new channel in the gateway configuration
2. Select the OPC UA Server driver
3. Configure server parameters

Step 2: Configure server properties

Parameter	Description	Default Value
OpcUaStringUrl	OPC UA service address (semicolon-separated, multiple URLs can be set)	opc.tcp://127.0.0.1:49321
BigTextApplicationName	Application name identifier	ThingsGateway OPC UA Server
SecurityPolicy	Whether to enable security policy	false
UserName	Username (allows anonymous access when empty)	Empty
Password	Password	Empty
ServerCertificateName	Server certificate name	Empty
IsAllVariable	Whether to enable all variables	false

Step 3: Configure variable properties

Property	Description	Value
DataType	Variable data type	Select based on actual needs, default Object

Usage Method

After an external OPC UA client connects to the gateway, it can directly write to the corresponding nodes, and the gateway will automatically write the data to the corresponding variables. The OPC UA Server automatically creates the node structure based on the device name and variable name.

Common Issues

Issue	Cause	Solution
Connection refused	Certificate not trusted	Import the certificate to the trusted list or set SecurityPolicy to false
Authentication failed	Incorrect username or password	Check UserName and Password configuration
Node does not exist	Variable not correctly configured	Confirm the variable has been added to the device

---

2. Modbus Slave Reverse RPC

Protocol Features

Feature	Description
Simple and Reliable	Simple protocol, easy to implement
Widely Supported	Almost all industrial devices support it
Master-Slave Architecture	Master initiates requests, slave responds

Working Principle

The gateway acts as a Modbus slave, waiting for write requests from external masters:

External Master ────Write Command (Function Code 06/16)────▶ Gateway (Slave) ────▶ Variable Write
              ◀───────Response Result────────

Register Mapping

Register Type	Function Code	Address Range	Purpose
Coil	01 Read/05 Write	00001-09999	Digital output
Holding Register	03 Read/06 Write/16 Write	40001-49999	Analog output

Configuration Steps

Step 1: Create a Modbus Slave device

1. Add a new channel (TCP Service or serial port)
2. Select the Modbus Slave driver
3. Configure slave parameters

Step 2: Configure slave properties

Parameter	Description	Example Value
Station	Default station number	1
ModbusType	Modbus type	Tcp
DeviceRpcEnable	Allow RPC write	true

Step 3: Configure variable mapping

Variable Property	Description	Example
ServiceAddress	Slave variable address	"40001"
VariableRpcEnable	Allow RPC write	true
DataType	Data type	Int16/Float

Usage Method

The external Modbus master writes to the corresponding register address, and the gateway automatically writes the data to the mapped variable.

Test Verification

Using Modbus debug tools (such as Modbus Poll):

1. Configure connection parameters (IP, port, slave address)
2. Execute write operations
3. Observe gateway logs and variable value changes

---

3. Web API Reverse RPC

Protocol Features

Feature	Description
Easy to Use	Based on HTTP protocol, easy to integrate
Cross-platform	Any platform supporting HTTP can use it
RESTful	Standard REST API design

Interface Description

Interface	Method	Description
/api/GatewayWriteVariableController/SetVariableValue	POST	Write variable value
/api/GatewayAuthController/Login	POST	Login to get Token
/api/GatewayDataController/GetVariableStatusPageList	POST	Read variable value

Configuration Steps

Step 1: Enable Web API service

The Web API service runs automatically when the gateway starts, on port 6100.

Step 2: Configure variable RPC properties

Enable RPC write permission in the variable properties.

Step 3: Get authentication Token

After login, get the Token. Subsequent requests need to carry the Token.

Usage Method

Request Example:

POST /api/GatewayWriteVariableController/SetVariableValue
Header: Authorization: Bearer {"{token}"}
Body: {
  "Device1": {
    "temperature_setpoint": 28.5
  }
}

Response Example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "Device1": {
      "temperature_setpoint": {
        "IsSuccess": true,
        "OperCode": 0,
        "ErrorMessage": ""
      }
    }
  }
}

Authentication Description

Item	Description
Authentication Method	JWT Token
Token Validity Period	Default 15 days (configurable via JWTOptions.ExpiredTime, in minutes)
Default Account	admin / 111111

---

4. MQTT Reverse RPC

Protocol Features

Feature	Description
Lightweight	Small protocol overhead, suitable for low-bandwidth environments
Publish/Subscribe	Decoupled message delivery pattern
IoT Friendly	Widely used in IoT scenarios

Topic Design

Topic	Description	Example
Write Request	Receive write requests	gateway/rpc/write
Write Response	Return execution result	gateway/rpc/write/Response
Data Request	Trigger data push	gateway/rpc/quest

Message Format

Write Request Message:

{
  "Device1": {
    "temperature_setpoint": 28.5
  }
}

Response Message:

{
  "Device1": {
    "temperature_setpoint": {
      "IsSuccess": true,
      "OperCode": 0,
      "ErrorMessage": ""
    }
  }
}

Error Response Example:

{
  "Device1": {
    "temperature_setpoint": {
      "IsSuccess": false,
      "OperCode": 500,
      "ErrorMessage": "The variable does not exist"
    }
  }
}

Configuration Steps

Step 1: Configure MQTT connection

Parameter	Description	Example Value
IP	IP address	localhost
Port	Port	1883
ClientId	Client ID	gateway_client

Step 2: Configure RPC topics

Parameter	Description	Example Value
RPC Write Topic	RPC write topic prefix	gateway/rpc/write
Data Request Topic	Topic that triggers a full data upload	gateway/rpc/quest
QoS Level	QoS level	AtMostOnce

Step 3: Configure variable RPC properties

Variable Property	Description	Value
Allow RPC Write	Allow this variable to be written through RPC	true

QoS Level Description

Level	Description	Applicable Scenario
0	At most once, may be lost	Non-critical data
1	At least once, may be duplicated	General scenarios
2	Exactly once	Critical data

---

Common Issues

Q1: RPC write failed, prompt "Insufficient permissions"

Solution:

1. Check if VariableRpcEnable is true in the variable properties (Modbus Slave / MQTT)
2. Check if DeviceRpcEnable is true in the device properties (Modbus Slave / MQTT)
3. Check if the user role has the corresponding permission

Q2: OPC UA connection refused

Solution:

1. Import the client certificate into the server's trusted list
2. Ensure the client and server security policies are consistent (SecurityPolicy configuration)
3. Check firewall rules
4. If security policy is not needed, set SecurityPolicy to false

Q3: MQTT message lost

Solution:

1. Increase the QoS level to at least 1
2. Check if the topic configuration is correct
3. Enable client auto-reconnect

Q4: Web API Token expired

Solution:

1. The Token validity period is 15 days by default (configurable via JWTOptions.ExpiredTime), re-login is required after expiration
2. Call the refresh interface when the Token is about to expire

---

Appendix

Glossary

Term	Explanation
RPC	Remote Procedure Call, a computer communication protocol
Reverse RPC	An RPC mode where the server passively accepts external calls
OPC UA	Open Platform Communications Unified Architecture, an industrial communication standard
Modbus	A communication protocol widely used in the industrial field
MQTT	Message Queue Telemetry Transport, a lightweight IoT protocol
QoS	Quality of Service level

Related Links

• Gateway API Documentation - RESTful API detailed interface description
• Data Management - Channel, device, variable configuration
• Quick Start - Deployment and usage guide

---

Tip

This document is continuously updated. If you have any questions, please provide feedback in the community or check the latest online documentation.