Remote Procedure Call (RPC)

Last Updated on : 2022-11-16 05:55:28download

This topic describes the protocol for RPC requests in order to call OpenAPI. Therefore, you can leverage cloud-based OpenAPI over MQTT to add more features to your business to unlock more use cases.

General RPC requests

Device sends messages

A device initiates an RPC request to the cloud.

Topic: tylink/${deviceId}/channel/rpc/request

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
    	"api":"tuya.device.xxx.config.get",
      	"apiVersion":"1.0",
        "params":{
        	"withVideoDataStorage":"true"
        }
	}
}

Description

Parameter	Type	Description	Required	Remark
${deviceId}	string	Device ID	Yes	The ID of the device that initiates an RPC request. If this is a sub-device initiating the request, the `deviceId` should be the ID of the sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	object	RPC request information	Yes	The name, version, and parameters of the RPC.
data.api	string	Name of the RPC interface	Yes	For example, `tuya.device.dynamic.config.ack`
data.apiVersion	string	Version of the RPC interface	Yes	For example, `1.0`.
data.params	object	Parameters of the RPC request	Yes	The parameter object of the interface.

Device receives messages

The device receives the result of the procedure execution.

Topic: tylink/${deviceId}/channel/rpc/response

{
	"msgId":"45lkj3551234001",
    "time":1626197189640,
	"code":0,
    "data":{
      "success":true,
      // , "errorCode":"CAMERA_STORAGE_ORDER_NOT_EXISTED"
      // ,"errorMsg":"camera storage order not existed"
      "result":{
          "bucket":"00-00-00-000",
          "endpoint":"cos.000.com"
    	}
    }
}

Description

Parameter	Type	Description	Required	Remark
${deviceId}	string	Device ID	Yes	The ID of the device that initiates an RPC request. If this is a sub-device initiating the request, the `deviceId` should be the ID of the sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
code	number	Response status code	No	The status code of the RPC request. `0` means success, the default value. Other values mean failure. This status code indicates whether the RPC channel is connected. `data.success` indicates whether the specified procedure is invoked successfully.
data	object	RPC response information	Yes	The result of the RPC request and the error code.
data.success	boolean	RPC request status	Yes	Indicates whether the specified procedure is invoked successfully.
data.result	object	RPC execution result	No	The result of procedure execution.
data.errorCode	string	RPC error code	No	Error code returned when an error occurs during RPC execution.
data.errorMsg	string	RPC error message	No	Error message returned when an error occurs during RPC execution.

The description of status codes

Status code	Description
0	The default status, indicating success.
1001	The RPC request failed.
1002	Invalid parameter.
1003	Incorrect message format.
1006	RPC request timeout.
1007	RPC channel rejects the connection request.
1008	Unknown system error.
4600	Response decoding inside the RPC channel failed.
4601	Device parameters inside the RPC channel are missing.

Reporting the integrated circuit card identifier (ICCID)

Device sends messages

A device initiates an RPC request to the cloud.

Topic: tylink/${deviceId}/channel/rpc/request

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
    	"api":"tuya.device.meta.save",
      	"apiVersion":"1.0",
        "params":{
        	"metas":{
              "catIccId":"3hj21h3j2h1jh3j27***"
            }
        }
	}
}

Description

Parameter	Type	Description	Required	Remark
${deviceId}	string	Device ID	Yes	The ID of the device that initiates an RPC request. If this is a sub-device initiating the request, the `deviceId` should be the ID of the sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	object	RPC request information	Yes	The name, version, and parameters of the RPC.
data.api	string	Name of the RPC interface	Yes	For example, `tuya.device.meta.save`.
data.apiVersion	string	Version of the RPC interface	Yes	For example, `1.0`.
data.params	object	Parameters of the RPC request	Yes	The parameter object of the interface.
data.params.metas.catIccId	string	4G device’s ICCID	Yes	ICCID is the unique identifier of an IC card, composed of 20 characters.

Device receives messages

The device receives the result of the procedure execution.

Topic: tylink/${deviceId}/channel/rpc/response

{
    "msgId": "45lkj3551234001",
    "time": 1626197189640,
    "code": 0,
    "data": {
        "t": 1662452307,
        "success": true,
        "result": true
    }
}

Description

Parameter	Type	Description	Required	Remark
${deviceId}	string	Device ID	Yes	The ID of the device that initiates an RPC request. If this is a sub-device initiating the request, the `deviceId` should be the ID of the sub-device.
version	string	Protocol version	No	The protocol version defaults to 1.0, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
code	number	Response status code	No	The status code of the RPC request. `0` means success, the default value. Other values mean failure. This status code indicates whether the RPC channel is connected. `data.success` indicates whether the specified procedure is invoked successfully.
data	object	RPC response information	Yes	The result of the RPC request and the error code.
data.success	boolean	RPC request status	Yes	Indicates whether the specified procedure is invoked successfully.
data.result	object	RPC execution result	No	The result of procedure execution.
data.errorCode	string	RPC error code	No	Error code returned when an error occurs during RPC execution.
data.errorMsg	string	RPC error message	No	Error message returned when an error occurs during RPC execution.

Get the short URL for QR code binding

Device sends messages

A device initiates an RPC request to the cloud.

Topic: tylink/${deviceId}/channel/rpc/request

{
	"msgId":"45lkj3551234001",
  	"time":1626197189638,
	"data":{
    	"api":"tuya.device.qrcode.bind.info.get",
      	"apiVersion":"1.0",
        "params":{
        }
	}
}

Description

Parameter	Type	Description	Required	Remark
${deviceId}	string	Device ID	Yes	The ID of the device that initiates an RPC request. If this is a sub-device, the `deviceId` should be the ID of the sub-device.
version	string	Protocol version	No	The protocol version defaults to `1.0`, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
data	object	RPC request information	Yes	The name, version, and parameters of the RPC.
data.api	string	Name of the RPC interface	Yes	For example, `tuya.open.iot.product.device.bind.code`
data.apiVersion	string	Version of the RPC interface	Yes	For example, `1.0`.
data.params	object	Parameters of the RPC request	Yes	The parameter object of the interface.

Device receives messages

The device receives the result of the procedure execution.

Topic: tylink/${deviceId}/channel/rpc/response

{
    "msgId": "45lkj3551234001",
    "time": 1626197189640,
    "code": 0,
    "data": {
        "t": 1662452307,
        "success": true,
        "result":{
          "shortUrl":"https://t.tuya.com/AYNuQRli"
        }
    }
}

Description

Parameter	Type	Description	Required	Remark
${deviceId}	string	Device ID	Yes	The ID of the device that initiates an RPC request. If this is a sub-device, the `deviceId` should be the ID of the sub-device.
version	string	Protocol version	No	The protocol version defaults to `1.0`, which is the only valid value currently.
msgId	string	Message ID	Yes	A string up to 32 characters in length. A message ID is used to correlate responses and requests.
time	number	Message timestamp	Yes	The Unix timestamp when a message is sent, in seconds (10-digit value) or milliseconds (13-digit value).
code	number	Response status code	No	The status code of the RPC request. `0` means success, the default value. Other values mean failure. This status code indicates whether the RPC channel is connected. `data.success` indicates whether the specified procedure is invoked successfully.
data	object	RPC response information	Yes	The result of the RPC request and the error code.
data.success	boolean	RPC request status	Yes	Indicates whether the specified procedure is invoked successfully.
data.result	object	RPC execution result	No	The result of procedure execution.
data.result.shortUrl	string	Short URL	Yes	For example, `https://t.tuya.com/AYNuQRLi`
data.errorCode	string	RPC error code	No	Error code returned when an error occurs during RPC execution.
data.errorMsg	string	RPC error message	No	Error message returned when an error occurs during RPC execution.

Reference

For more information, see MQTT Topics.

Prev DocTime Service

Next DocTuya IoT Core SDK for C