Integration with Perimeter Devices

This topic describes how to integrate perimeter devices with Tuya’s smart industry.

Architecture

Tuya provides a comprehensive solution to help integrate smart perimeter devices with the Tuya Developer Platform. The architecture is shown as follows:

The perimeter system is abstracted into three elements on the Tuya Developer Platform: perimeter host, perimeter area, and defense zone.

• Perimeter host: The perimeter alarm host directly connected to the Tuya IoT Edge Gateway can process the signals from detectors.

• Defense zone: Alarm triggers, detectors, and other detection points directly connected to the perimeter host.

• Perimeter area: The logical areas of a defense zone. A defense zone can be divided into groups. Operations such as arming and disarming are performed based on areas. If no area is specified and the entire host is uniformly armed and disarmed, you can regard the entire host as a defense zone. However, if the host supports individual arming and disarming of a single zone, each zone can be abstracted as an area for operation.

  

  The perimeter host communicates with Tuya’s IoT Edge Gateway over the MQTT protocol.

Business process

Device features

reqType	Feature	Description	Message type
1	Send a command to report the host device data	Tuya IoT Edge Gateway actively initiates a device information sync request to the perimeter host.	Send
2	Report the host device data	The host device reports data on receiving a data sync request based on protocol 1, and can also report data regularly.	Report
3	Send a command to report the area data	Tuya IoT Edge Gateway sends an area information sync request to the perimeter host.	Send
4	Report area data	The host device reports the area data on receiving a data sync request based on protocol 3, and can also report data regularly.	Report
5	Send an arming or disarming command	Tuya IoT Edge Gateway sends an arming or disarming message to the perimeter host. Upon receiving the message, the perimeter host arms or disarms the specified areas.	Send
6	Send a command to mute areas	Tuya IoT Edge Gateway sends a message to the perimeter host, requesting to mute the areas. Upon receiving the message, the perimeter host mutes the specified areas.	Send
7	Send a command to report the defense zone device data	Tuya IoT Edge Gateway sends a command to the perimeter host, requesting to report the defense zone device data.	Send
8	Report the defense zone device data	The host device reports the defense zone device data after receiving a data report request based on protocol 7, and can also report data regularly.	Report
9	Send a command to bypass or restore a defense zone	Tuya IoT Edge Gateway actively initiates a request to the perimeter host, requesting to bypass or restore a specified defense zone. Upon receiving the request, the host controls the defense zone devices to be bypassed or restored.	Send
10	Send a command to mute a defense zone	Tuya IoT Edge Gateway actively initiates a request to the perimeter host, requesting to mute a specified defense zone. Upon receiving the request, the host controls the defense zone devices to mute a specified defense zone where an alarm is triggered.	Send
1001	Report an online/offline event of a host/defense zone device	Report a message when a host device or defense zone device goes online or online. The message can be reported regularly.	Report

Connection authentication

• ip: the IP address of the MQTT broker. It is provided by Tuya during joint debugging on the Tuya Developer Platform.

• port: the port number of the MQTT broker. It is provided by Tuya during joint debugging on the Tuya Developer Platform.

• clientId: the ID of a specified perimeter host. The maximum length is 32 characters.

• username: the username of a specified perimeter system manufacturer. It is provided by Tuya during joint debugging on the Tuya Developer Platform.

• password: sub(md5(cid + username), 0, 16).

• Here is an example to generate a password:

  clientId: abcd1234***
  username: tu***
  password: sub(md5(cid + username), 0, 16)-> c88ba730489ed678
  

  ip, port, clientId, and username must be set in the local perimeter gateway in advance, so the local perimeter gateway can read these parameters every time it starts, allowing connection to the Tuya IoT Edge Gateway.

Message topic reported by perimeter host

Push: gateway/perimeter/out/{gatewayID}
Payload: base64.Encode(aes.encrypt(Msg, password))

Encryption example

password := "c88ba730489ed***"
payload := "{\"t\":1598010614***,\"reqId\":\"1231231***\",\"cid\":\"123122***\",\"reqType\":2,\"data\":{\"devName\":\"East Gate Fire Control Area***\",\"devInstallAddr\":\"East Date***\",\"ipAddr\":\"127.0.0.1\"}}"
secPayload: "mEtVf8YFr1SvlzgWDdLaef4jSL0olvsfdk9W7mpDSof961PQOdL0J784WFuGeHj9L25sdhcXSg4lZRdUnyfmhNSMXiie5WdbeK7R5fkc/OzL3NNvOnxi8mI2R2Bq24K3AnmGEkAjFtxNa2+6XmMSgSFNAHJlZBg8H4TACvpQxXYlj2R550KKRXLEXuE8X4khLQp1VhtvIhXEimGujz8T8uBdNLCb8o2CzRquRvjosZM1DKwSxNzc5oRFyrFz****"

Message topic subscribed by perimeter host

Push: gateway/perimeter/in/{gatewayID}
Payload: base64.Decode(aes.decrypt(Msg, password))

Decryption example

password := "c88ba730489ed***"
secPayload: "mEtVf8YFr1SvlzgWDdLaef4jSL0olvsfdk9W7mpDSof961PQOdL0J784WFuGeHj9L25sdhcXSg4lZRdUnyfmhNSMXiie5WdbeK7R5fkc/OzL3NNvOnxi8mI2R2Bq24K3AnmGEkAjFtxNa2+6XmMSgSFNAHJlZBg8H4TACvpQxXYlj2R550KKRXLEXuE8X4khLQp1VhtvIhXEimGujz8T8uBdNLCb8o2CzRquRvjosZM1DKwSxNzc5oRFyrFz****"
payload := "{\"t\":1598010614***,\"reqId\":\"1231231***\",\"cid\":\"123122***\",\"reqType\":2,\"data\":{\"devName\":\"East Gate Fire Control Area***\",\"devInstallAddr\":\"East Date***\",\"ipAddr\":\"127.0.0.1\"}}"

Message encryption

• Messages sent and received by devices must be encrypted and decrypted by Advanced Encryption Standard (AES).
• The message body is serialized and deserialized in the JSON format.
• The encryption and decryption method: AES-ECB.
• The encryption and decryption password: Use the {password} created for connection authentication.

Sample code

   	password := "c88ba730489ed***"
	payload := "{\\\"t\\\":1598010614***,\\\"reqId\\\":\\\"1231231231***\\\",\\\"cid\\\":\\\"123122***\\\",\\\"reqType\\\":2,\\\"data\\\":{\\\"devName\\\":\\\"East Gate Fire Control Area***\\\",\\\"devInstallAddr\\\":\\\"East Gate***\\\",\\\"ipAddr\\\":\\\"127.0.0.1\\\"}}"
	data, err := aes_ecb_psk5.Encrypt([]byte(payload), []byte(password))
	t.Log(err)
	base64str := base64.StdEncoding.EncodeToString(data)
	t.Log(base64str)

	dataE, err := base64.StdEncoding.DecodeString(base64str)
	t.Log(err)
	dataD, err := aes_ecb_psk5.Decrypt(dataE, []byte(password))
	t.Log(err)
	t.Log(string(dataD))

Data point and message content

Control message

Send a command to report the host device data

Tuya IoT Edge Gateway actively initiates a device information sync request to the perimeter host. On receiving the message, the perimeter host reports the host information.

Request parameter

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The identifier of a specified request. We recommend that the request identifier be generated by the UUID. The visitor management system can listen for the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 1, send a command to report the host device data.	Yes
cid	String	The ID of a specified host device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters.	Yes
data	Object	The business data.	Yes

Format of Msg:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 1,
	"data": {}
}

Report the execution result in the following format:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 1,
	"data": {
		"success": true,
		"msg": "sucess",
		"code": 200
	}
}

Report the host device data

The host device reports data on receiving a data sync request based on protocol 1, and can also report data regularly.

The list of parameters to be reported:

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The identifier of a specified request. We recommend that the request identifier be generated by the UUID. The visitor management system can listen for the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 2, report the host device data.	Yes
cid	String	The ID of a specified host device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters.	Yes
data	Object	The business data.	Yes
+ devName	String	The name of a specified device. The maximum length is 64 characters.	Yes
+ devInstallAddr	String	The location where the device is installed. The maximum length is 64 characters.	No
+ ipAddr	String	The location where the device is installed. The maximum length is 64 characters.	No

Format of Msg:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 2,
	"data": {
		"devName": "East Gate Fire Control Area***",
		"devInstallAddr": "East Gate***",
		"ipAddr": "127.0.0.1"
	}
}

Return the execution result in the following format:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 2,
	"data": {
		"success": true,
		"msg": "sucess",
		"code": 200
	}
}

Send a command to report the area data

Tuya IoT Edge Gateway sends an area information sync request to the perimeter host. Upon receiving the request, the perimeter host reports the area information.

The request parameters are as follows:

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The identifier of a specified request. We recommend that the request identifier be generated by the UUID. The visitor management system can listen for the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 3, send a command to report the area data.	Yes
cid	String	The ID of a specified host device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters.	Yes
data	Object	The business data.	Yes

Format of Msg:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 3,
	"data": {}
}

Report the execution result in the following format:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 3,
	"data": {
		"success": true,
		"msg": "sucess",
		"code": 200
	}
}

Report area data

The host device reports the area data upon receiving a data sync request based on protocol 3, and can also report data regularly.

The list of parameters to be reported:

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The identifier of a specified request. We recommend that the request identifier be generated by the UUID. The visitor management system can listen for the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 4, report the area data.	Yes
cid	String	The ID of a specified host device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters.	Yes
data	Object	The business data.	Yes
+ areas	Array	The area data.	Yes
++ areaId	String	The ID of a specified area. The maximum length is 64 characters.	Yes
++ areaName	String	The area name. The maximum length is 64 characters.	Yes
++ pointCids	String[]	The list of device cid in a specified area.
The maximum length of each cid is 64 characters.	Yes

Format of Msg:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 4,
	"data": {
		"areas": [{
				"areaId": "a_1",
				"areaName": "East Area***",
				"pointCids": [
					"11112***",
					"11113***",
					"11114***"
				]
			},
			{
				"areaId": "a_2***",
				"areaName": "West Area***",
				"pointCids": [
					"11114***",
					"11115***",
					"11116***"
				]
			}
		]
	}
}

Return the execution result in the following format:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 4,
	"data": {
		"success": true,
		"msg": "sucess",
		"code": 200
	}
}

Send an area arming or disarming command

Tuya IoT Edge Gateway sends an arming or disarming message to the perimeter host. Upon receiving the message, the perimeter host arms or disarms the specified areas.

The request parameters are as follows:

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The identifier of a specified request. We recommend that the request identifier be generated by the UUID. The visitor management system can listen for the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 5, send a command to arm or disarm a specified area.	Yes
cid	String	The ID of a specified host device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters.	Yes
data	Object	The business data.	Yes
+ areaId	String	The ID of a specified area to be armed or disarmed.	Yes
+ armed	Boolean	True: Arm the area. False: Disarm the area.	Yes

Format of Msg:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 5,
	"data": {
		"areaId":"a-1",
		"armed": true
	}
}

Report the execution result in the following format:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 5,
	"data": {
		"success": true,
		"msg": "sucess",
		"code": 200
	}
}

Send a command to mute areas

Tuya IoT Edge Gateway sends a message to the perimeter host, requesting to mute the areas. Upon receiving the message, the perimeter host mutes the specified areas.

The request parameters are as follows:

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The identifier of a specified request. We recommend that the request identifier be generated by the UUID. The visitor management system can listen for the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 6, send a command to mute a specified area.	Yes
cid	String	The ID of a specified host device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters.	Yes
data	Object	The business data.	Yes
+ areaId	String	The ID of a specified area to be armed or disarmed.	Yes

Format of Msg:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 6,
	"data": {
		"areaId":"a-1",
	}
}

Return the execution result in the following format:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 6,
	"data": {
		"success": true,
		"msg": "sucess",
		"code": 200
	}
}

Send a command to report the defense zone device data

Tuya IoT Edge Gateway sends a command to the perimeter host, requesting to report the defense zone device data. On receiving the request, the perimeter host reports the information about the defense zone.

The request parameters are as follows:

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The identifier of a specified request. We recommend that the request identifier be generated by the UUID. The visitor management system can listen for the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 7, send a command to report the host device data.	Yes
cid	String	The ID of a specified defense zone device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters.	Yes
data	Object	The business data.	Yes

Format of Msg:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 7,
	"data": {}
}

Report the execution result in the following format:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 7,
	"data": {
		"success": true,
		"msg": "sucess",
		"code": 200
	}
}

Report the defense zone device data

The host device reports the defense zone device data upon receiving a data report request based on protocol 7, and can also report data regularly.

The list of parameters to be reported:

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The identifier of a specified request. We recommend that the request identifier be generated by the UUID. The visitor management system can listen for the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 8, report the host device data.	Yes
cid	String	The ID of a specified host device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters.	Yes
data	Object	The business data.	Yes
+ points	Array	The business data.	Yes
++ pointCid	String	The cid of a specified defense zone device. The maximum length is 64 characters.	Yes
++ devName	String	The name of a specified device. The maximum length is 64 characters.	Yes
++ devInstallAddr	String	The location where the device is installed. The maximum length is 64 characters.	No
++ ipAddr	String	The location where the device is installed. The maximum length is 64 characters.	No

Format of Msg:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 8,
	"data": {
		"points": [{
				"pointCid": "p-1",
				"devName": "East Gate Fire Control Area***",
				"devInstallAddr": "East Gate***",
				"ipAddr": "127.0.0.1"
			},
			{
				"pointCid": "p-2",
				"devName": "East Gate Fire Control Area***",
				"devInstallAddr": "East Gate***",
				"ipAddr": "127.0.0.1"
			}
		]
	}
}

Return the execution result in the following format:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 8,
	"data": {
		"success": true,
		"msg": "sucess",
		"code": 200
	}
}

Send a command to bypass a defense zone

Tuya IoT Edge Gateway actively initiates a request to the perimeter host, requesting to bypass or restore a specified defense zone. Upon receiving the request, the host controls the defense zone devices to be bypassed or restored.

The request parameters are as follows:

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String (Max. 64 characters)	The identifier of a specified request. We recommend that the request identifier be generated by the UUID. The visitor management system can listen for the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 9, send a command to bypass a specified defense zone.	Yes
cid	String (Max. 64 characters)	The ID of a specified defense zone device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters.	Yes
data	Object	The business data.	Yes
+ byPass	Boolean	true: Bypass a defense zone. false: Restore a defense zone.	Yes

Format of Msg:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 9,
	"data": {
		"byPass":true,
	}
}

Return the execution result in the following format:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 9,
	"data": {
		"success": true,
		"msg": "sucess",
		"code": 200
	}
}

Send a command to mute a defense zone

Tuya IoT Edge Gateway actively initiates a request to the perimeter host, requesting to mute a specified defense zone. Upon receiving the request, the perimeter host controls the defense zone devices to mute a specified defense zone where an alarm is triggered.

The request parameters are as follows:

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The identifier of a specified request. We recommend that the request identifier be generated by the UUID. The visitor management system can listen for the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 10, send a command to mute a specified defense zone.	Yes
cid	String	The ID of a specified defense zone device. It can be a unique readable identifier of the device, such as device SN, MAC address, or IMEI. The maximum length is 64 characters.	Yes
data	Object	The business data.	Yes

Format of Msg:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 10,
	"data": {}
}

Return the execution result in the following format:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"cid": "123***",
	"reqType": 10,
	"data": {
		"success": true,
		"msg": "sucess",
		"code": 200
	}
}

Device management

Report device online and offline events

Report a message when a host device or defense zone device goes online or online. The message can be reported regularly. Enter the device cid into the online or offline parameter.

The list of parameters to be reported:

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The identifier of a specified request. We recommend that the request identifier be generated by the UUID. The visitor management system can listen for the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 1001, report the device online or offline data.	Yes
data	Object	The business data.	Yes
+ online	String[]	The list of cid of the host device or defense zone device. The maximum length of each cid is 64 characters.	Yes
+ offline	String[]	The list of cid of the host device or defense zone device. The maximum length of each cid is 64 characters.	Yes

Format of Msg:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"reqType": 1001,
	"data": {
			"online": ["h-1","p-1"],
			"offline": []
		}
}

Return the execution result in the following format:

{
	"t": 1598010614***,
	"reqId": "1231231***",
	"reqType": 1001,
	"data": {
		"success": true,
		"msg": "sucess",
		"code": 200
	}
}