Remote Procedure Calls

This section documents the RPC interface exposed by the TEG Gateway for operational control, diagnostics, and maintenance tasks.

RPC Handler

Handle ThingsBoard RPC requests for the Edge Gateway.

This module implements the Edge Gateway’s server-side handling of ThingsBoard Remote Procedure Calls (RPC). Incoming RPC requests are dispatched to a curated set of supported methods and a response is sent back on the corresponding ThingsBoard RPC response topic.

The RPC interface is intended for operational control, diagnostics, and maintenance tasks, such as rebooting the device, restarting the controller, initializing remote file management attributes, or republishing archived telemetry.

Security notes

Some RPC methods (notably run_command) can execute arbitrary commands on the host system. Access to such methods must be restricted using ThingsBoard permissions and dashboard access control.

on_mqtt_msg.on_rpc_request.on_rpc_request(rpc_msg_id, method, params)[source]

Dispatch an incoming RPC request.

Parameters:

  • rpc_msg_id (str) – ThingsBoard RPC request identifier.

  • method (str) – RPC method name.

  • params (Any) – RPC params payload (type depends on method).

Return type:

None

on_mqtt_msg.on_rpc_request.rpc_archive_discard_messages(rpc_msg_id, _method, params)[source]

Discard (delete) archived telemetry messages within a time range.

Return type:

None

on_mqtt_msg.on_rpc_request.rpc_archive_republish_messages(rpc_msg_id, _method, params)[source]

Republish archived telemetry messages within a time range.

Return type:

None

on_mqtt_msg.on_rpc_request.rpc_exit(rpc_msg_id, _method, _params)[source]

Terminate the gateway process to trigger a supervised restart.

Return type:

None

on_mqtt_msg.on_rpc_request.rpc_init_files(rpc_msg_id, _method, _params)[source]

Initialize client attributes required for remote file management.

This creates an empty FILE_HASHES client attribute and requests the FILES shared attribute to re-run definition validation and synchronization.

Return type:

None

on_mqtt_msg.on_rpc_request.rpc_ping(rpc_msg_id, _method, _params)[source]

Health check RPC that returns a static ‘Pong’ response.

Return type:

None

on_mqtt_msg.on_rpc_request.rpc_reboot(rpc_msg_id, _method, _params)[source]

Reboot the Edge Gateway host system.

Sends an RPC response immediately and triggers a system reboot shortly after.

Return type:

None

on_mqtt_msg.on_rpc_request.rpc_restart_controller(rpc_msg_id, _method, _params)[source]

Restart the controller container without rebooting the host.

Return type:

None

on_mqtt_msg.on_rpc_request.rpc_run_command(rpc_msg_id, _method, params)[source]

Execute a command on the Edge Gateway host.

This method executes an arbitrary command and returns its combined stdout/stderr output. The command is killed if it exceeds the provided timeout.

Parameters are validated strictly. This method is powerful and must be protected via ThingsBoard access control.

Return type:

None

on_mqtt_msg.on_rpc_request.rpc_shutdown(rpc_msg_id, _method, _params)[source]

Shut down (power off) the Edge Gateway host system.

Return type:

None

on_mqtt_msg.on_rpc_request.send_rpc_method_error(rpc_msg_id, msg)[source]

Send a standardized error response for an RPC method.

Return type:

None

on_mqtt_msg.on_rpc_request.send_rpc_response(rpc_msg_id, response)[source]

Send an RPC response

Return type:

bool

on_mqtt_msg.on_rpc_request.verify_start_end_timestamp_params(params)[source]

Validate timestamp range parameters for archive operations.

Parameters:

params (Any) – RPC params dictionary expected to contain start_timestamp_ms and end_timestamp_ms as integers.

Return type:

Optional[str]

Returns:

An error string if invalid, otherwise None.