Integration with Perimeter Devices

Last Updated on : 2024-06-18 09:49:51download

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:

Integration with Perimeter Devices

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.

    Integration with Perimeter Devices

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

Business process

Integration with Perimeter Devices

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
	}
}