Reverse RPC

Reverse RPC is not a standalone menu but a set of capabilities for external systems to initiate write or control requests to GatewayRuntime through interfaces such as Web API, MQTT, OPC UA Server, and Modbus Slave. Before use, you need to confirm variable write permissions, role authorization, and the corresponding protocol entry configuration.

First, look at terminology

terminology	On-site understanding
reverse RPC	external system active call gateway. On-site can be understood as "the upper-level system sending write, control, or query requests in reverse."
RPC writes	external system backwrite points. It is only recommended to enable control at control points and when on-site confirmation allows remote control.
RPC writes the topic prefix for the topic request sent by the external system in the MQTT scenario	MQTT scenario. Requests and responses to the topic must be agreed upon by both parties.
Target-level write switch	Main switch on forwarding targets or server plugins; when closed, variables under this target cannot be written to external systems.
Variable-level write switch	Write switch on a single variable; only external systems can write to that variable if both the target and variable levels are allowed.
Broker	MQTT message server, responsible for receiving and distributing Topic messages.

Meaning of Reverse RPC

In GatewayRuntime, reverse RPC can be understood as "the external system reverse-calling the gateway's write capability." The external system does not passively receive data uploaded by the gateway but can initiate write, control, or query requests to the gateway; After the gateway completes permission verification, variable verification, and plugin writing, it returns the execution result.

Link	Description
Web API Writing	External system calls variable writing interface after login.
MQTT RPC	The external system issues an RPC request to the agreed topic, and after processing it, the gateway issues a response.
OPC UA Server	Nodes exposed by external OPC UA clients write to gateways.
Modbus Slave	External Modbus master writes the coil or register mapped to the gateway.
Debug page writing	Operations personnel verify the write link in GatewayRuntime Web through variable write pop-ups or device debug pages.

Write Prerequisites

Whether a reverse RPC succeeds depends not only on the external request format but also on variables, permissions, and plugin capabilities.

Checklist	Description
Variable Read and Write Permissions	Variables should be allowed to be written. Read-only variables should not be written.
RPC Write Switch (Allows External System Reverse Write Points)	When RPC writing is required in variable or plugin properties, make sure the corresponding switch is enabled.
Write Check	If write check is enabled, after a successful write, the variable will be read again and the callback value will be compared. Points that only write variables, delay after write, or have proportional conversion or writeback rounding should not be enabled arbitrarily.
Plugin Write Capability	Collection plugins or server plugins must support the corresponding write method.
Device Online Status	When writing to the real device, the channel and device should be in a communicative state.
Role API Permissions	Web users or integration accounts need to have corresponding API permissions, such as variable writes, debug writes, or MQTT debugging and publishing.

Variable write pop-up can be used to quickly verify on-site whether the variable itself supports writing.

Web API Writing

Web API writing is suitable for upper-level systems, MES, SCADA, operations platforms, or custom programs to directly call GatewayRuntime.

Steps	Operations
Login	Call the authentication interface to obtain the Bearer Token, or at The web is logged in and debugged.
Authorization	In "System Administration → Role Management → Authorization," assign variable write API permissions to the integration account role.
Write	Call the variable write interface from the current API documentation: /api/gatewaywritevariablecontroller/setvariablevalue.
Validation	Confirm write results in variable lists, variable details, device logs, or RPC logs.

API permissions can search for variable write-related permissions in the role authorization drawer.

The request body is usually organized as "device name → variable name → value to write." For the endpoint path, authentication method, and response structure, follow the interface description in the Gateway API documentation.

Call a collection-plugin special method

When a variable has a Special method (Other Method), the same variable-write endpoint invokes the plugin method instead of writing a regular point. The method variable must still be writable, allow RPC writing, belong to a device that is not paused, and pass role authorization.

For example, an OPC UA Client method variable selects CallMethodByNodeIdAsync and stores the object and method NodeIds in its address. The external request supplies the method inputs as the variable value:

{
  "OPC device": {
    "Start method": [123, "start"]
  }
}

The outer array is the method argument list. When a method has one array argument, submit a nested array such as [[1, 2, 3]]. See OPC UA Client for variable configuration and OPC UA type-conversion rules. An MQTT RPC script enters the same method-call path after it resolves the same device name, variable name, and JSON value.

MQTT RPC

MQTT RPC is suitable for scenarios where external systems already use MQTT Broker. When the gateway is used as an MQTT Client Producer or MQTT Server-related target, RPC Topics and scripts can be configured via target properties.

Configuration Items	Description
RPC Write Topic	Topic prefix for write requests published by external systems. With tg/rpc/write, requests are sent to tg/rpc/write/<request-id>, and responses are read from tg/rpc/write/<request-id>/Response.
Data Request Topic	Topic for the latest data snapshot requested by an external system. After receiving the message, the gateway uploads variables, devices, or alarm data according to the target configuration.
RPC Script	RPC message script for customizing request parsing, write target selection, result processing, or response structure.
QoS level	RPC message publishing/subscription quality level. Key write recommendations include choosing the appropriate QoS based on Broker capabilities.
Username/password	Broker authentication information.
Enable SSL/TLS certificate configuration	Certificate, CA, target host, and protocol configuration in TLS scenarios.

The MQTT Client debug page can be used to validate the publish and subscription links.

Debug Item	Description
Publish Message	Fill in Topic, Payload, QoS, and Retain before publishing the test message.
Status and Subscriptions	View client connection status and add or unsubscribe to Topics.
Message Log	Observes Debugging WebSocket, publishing, subscribing, and responding to messages.

OPC UA Server and Modbus Slave

server class plugins allow external clients to actively connect to gateways and then write to nodes or registers via protocols.

Plugin Type	Write Method	Key Configuration
OPC UA Server	nodes exposed by external OPC UA client write gateways.	Service address, security policy, username and password, server certificate, target-level write switch, and variable-level write switch.
Modbus Slave	External Modbus master writes coils or holds registers.	Listen address, station number, slave variable address, variable data type, target-level write switch, variable-level write switch, client permission list.

After enabling the "security policy" of OPC UA Server, the client needs to connect according to the signature or encryption policy and trust the server certificate; Allow anonymous connections when closed. OPC UA writing must satisfy both the "allow RPC write" in the target configuration and the "allow RPC write" in the variable properties; either turn off will make the corresponding variable unwritable.

Modbus Slave's "Client Permission List" only applies to client IPs accessed in TCP server mode. When the list is empty, it is not restricted by IP; If the list is not empty, the missed TCP client cannot access the slave; The hit client then clicks "Write Allowed" to decide whether to write to the client. * means matching all clients. When only reading is allowed, you can configure * and disable "Write allowed"; Only allows specifying the host computer to write and configure by IP segmentation by the host computer.

Modbus Slave writes must simultaneously meet the target level of "allowing RPC writes" and the variable level of "allowing RPC writes." When "Write to Memory Now" is enabled, the external master writes to the slave memory value in the gateway first, making it easier for the master to read the new value immediately; Whether the actual device has completed control depends on the write result of the collection device to which the variable belongs.

Debugging and Verification

Before going live with reverse RPC, it is recommended to verify in the following order:

1. In "Collection Configuration," confirm the variable read/write type, data type, address, and write check.
2. Use the "Write" popup in the variable list to verify whether a single variable can be successfully written.
3. Select the device in Collection Configuration and use More Functions → Debug to verify protocol address read/write capabilities.
4. If using MQTT, use the MQTT Client or MQTT Server debug page to verify Topic, QoS, and message logs.
5. If using Web API, use the role authorization drawer to confirm API permissions, then check the RPC logs and operation logs.

Foundation debug page is suitable for verifying general address read/write.

Permission Configuration Recommendations

Account Type	Recommended Permissions
Read-only integrated account	Only grants data query interfaces, not variable write, debug write, or restart interfaces.
Control the integrated account	Only grant permission to write variables or MQTT/debug interfaces required for the specified write link.
Operations Account	Grants permissions for variable writing, device debugging, log queries, and log exports.
Administrator account	grants role authorization, menu maintenance, system settings, and restart permissions.

Menu button authorization only controls visible web page entrances; API authorization controls interface call capabilities. The production environment should check both types of permissions simultaneously.

Common Issues

Phenomena	Handling Suggestions
Web API returns permissionless	Checks whether the current user role has variable write API permission, and logs in again or refreshes permissions.
Write button is invisible	Check menu button authorization, variable read/write permissions, and page button permissions.
Write failed but interface call	Check variable data type, write value format, device online status, and device logs; When write check is enabled, confirm whether the callback value can immediately equal the write value.
MQTT unresponsive	checks RPC writing topics, subscribe topics, broker authentication, QoS, TLS, and message logs.
Special method was not executed	Check the selected special method, write permission, RPC-write permission, paused state, and parameter or method errors in the RPC log.
OPC UA write failure	Check certificate trust, security policies, username and password, target-level write switch, variable-level write switch, and node writable status.
Modbus write invalid	Checkstation number, register address, function code, data type, byte order, target-level write switch, variable-level write switch, and client permission list.
After writing, variable values recover again	On-site devices may refuse to write, or the collection cycle may reread the true value; Check device log confirmation.

Related Links

• Collection Configuration
• Plugin Manual Index
• OPC UA Client
• Data Forwarding
• Role Management
• Gateway API documentation