Integration with Multi-Door Access Controller

This topic describes how to integrate a multi-door access controller with the Tuya Developer Platform by using Tuya IoT Edge Gateway.

Architecture

Tuya provides a comprehensive solution to help integrate a multi-door access controller with the Tuya Developer Platform. The following architecture shows how to integrate a multi-door access controller by using Tuya IoT Edge Gateway.

The multi-door access controller communicates with Tuya’s IoT Edge Gateway over the MQTT protocol.

Business process

Device features

Request type	Device capability	Functional description	Data transfer type
1	Send a command to synchronize a multi-door access controller	Synchronize the information about the specified multi-door access controller.	Send
2	Report a multi-door access controller	Report the information about the specified multi-door access controller.	Report
3	Add a user	Add the information about the specified user.	Send
4	Modify a user	Modify the information about the specified user.	Send
5	Delete a user	Delete the information about the specified user.	Send
6	Add a card	Add a card.	Send
7	Modify a card	Modify a card.	Send
8	Delete a card of the specified user	Delete a card of the specified user.	Send
9	Remote unlocking	Remote unlocking.	Send
10	Keep a door always open/closed	Keep a door always open/closed.	Send
11	Generate a QR code	Generate a QR code.	Send
12	Clear the data of a multi-door access controller	Clear the data of the specified multi-door access controller.	Send
13	Report the device status	Report the event that the specified device gets online or offline.	Report
14	Report an access event	Report an access event that is implemented by the specified multi-door access controller.	Report
15	Report an alert	Report an alert event.	Report

Integration protocol

During communications over the MQTT protocol, the multi-door access controller works as a client, and Tuya IoT Edge Gateway works as a broker.

Connection authentication

• ip: the IP address of the MQTT broker. It is provided by Tuya during joint debugging on the Tuya Developer Platform. The default value is the IP address of the Tuya IoT Edge Gateway.

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

• clientId: the client ID of the multi-door access controller.

• username: the manufacturer username of the multi-door access controller. It is provided by Tuya during joint debugging on the Tuya Developer Platform.

• password: sub(md5(clientId + username), 0, 16). Here is an example to generate a password:

  clientId: abcd1***
  username: tuya
  password: sub(md5(clientId + username), 0, 16)-> c88ba730489ed678
  

  ip, port, clientId, and username must be configured in the multi-door access controller in advance. This enables the multi-door access controller to read these parameters every time it starts and thus connect to the IoT Edge Gateway.

Message topic reported by a multi-door access controller

• Push: gateway/multiaccess/out/{clientId}

• payload: base64.Encode(aes.encrypt(payload, password))

  Sample message

  password: "f4ae303385f24***"
  payload: `{"t":1655200***,"reqId":"1655200901125274***","reqType":2,"data":{}}`
  secPayload: "WMnpAqV9Diuz9hbhb5U5zMN3jgGubWaPGT3xDbY0QnUDy6B72W9pH0Li/cRN5i17dQnWqWZKnkicTZHv0G6WkKtFoEE6dkho0FhVAXOxNiY="
  

Message topic subscribed by a multi-door access controller

• Push: gateway/multiaccess/in/{clientId}

• payload: base64.Decode(aes.decrypt(payload, password))

  Sample message

  password: "f4ae303385f24***"
  secPayload: "WMnpAqV9Diuz9hbhb5U5zMN3jgGubWaPGT3xDbY0QnUDy6B72W9pH0Li/cRN5i17dQnWqWZKnkicTZHv0G6WkKtFoEE6dkho0FhVAXOxNiY="
  payload: `{"t":1655200***,"reqId":"1655200901125274***","reqType":1,"data":{}}`
  

Message encryption and decryption

Messages sent and received by devices must be encrypted and decrypted by AES.

• The message body is serialized and deserialized using JSON.
• The encryption and decryption method: AES-ECB.
• The encryption and decryption password: Use the password created for connection authentication.

Sample code

password := "f4ae303385f24***"
payload := `{"t":1655199***,"reqId":"1655199371114618***","reqType":1,"data":null}`
data, err := aes_crypto.AesECBEncrypt([]byte(payload), []byte(password))
fmt.Println(err)
base64str := base64.StdEncoding.EncodeToString(data)
fmt.Println(base64str)

dataE, err := base64.StdEncoding.DecodeString(base64str)
fmt.Println(err)
dataD, err := aes_crypto.AesECBDecrypt(dataE, []byte(password))
fmt.Println(err)
fmt.Println(string(dataD))

Device management

Send a command to synchronize a multi-door access controller

It is used for synchronizing a multi-door access controller. After the multi-door access controller is connected to the MQTT server of Tuya IoT Edge Gateway, the gateway sends a command to synchronize the device information. After receiving the command, the multi-door access controller reports the device information.

Request parameter

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 1 to synchronize the information about the specified multi-door access controller.	Yes
data	Object	The business data.	Yes

Message format

{
	"t": 159801061***,
	"reqId": 123123***,
	"reqType": 1,
	"data": {}
}

Report the multi-door access controller

The multi-door access controller reports the device information. Then, Tuya IoT Edge Gateway will add or update the reported information.

Request parameter

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 2 to report the device information.	Yes
data	Array	The business data.	Yes
+ cid	String	The unique device ID of the specified multi-door access controller.	Yes
+ deviceName	String	The device name of the specified multi-door access controller.	Yes
+ installLocation	String	The location where the device is installed.	No
+ subDevices	Array	The unique ID of an access control sub-device that is linked with the specified multi-door access controller.	Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 2,

    "data": [{
        "cid": "doorId***",
        "deviceName": "F1 Hall",
        "installLocation": "East of F1 Hall",
        "subDevices": ["1", "2", "3", "4"]
    }]
}

Device Control

Add a user

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 3 to add the information about the specified user.	Yes
cid	String	The unique ID of the specified access controller.	Yes
data	Object	The business data.	Yes
+subDevices	Array	The ID of the specified door.	Yes
+uid	String	The user ID, with no more than 32 characters.	Yes
+idCard	String	The identity card number of the specified user, with no more than 32 characters.	No
+phone	String	The 11-digit mobile phone number.	No
+beginTime	Long	The 13-digit timestamp when a validity period starts.	Yes
+endTime	Long	The 13-digit timestamp when a validity period ends.	Yes
+name	String	The name of the specified user, with no more than 64 characters.	Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 3,
    "cid": "doorId***",
    "data": {
        "uid": "21313***",
        "subDevices": ["1", "2", "3", "4"],
        "idCard": "350725***",
        "phone": "188***",
        "beginTime": 1676007834382,
        "endTime": 1676007844382,
        "name": "Tom**"
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "reqType": 3,
   "cid": "doorId***",
   "data": {
        "success": true,
        "msg": "success",
    }
}

Modify a user

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 4 to modify the information about the specified user.	Yes
cid	String	The unique ID of the specified access controller.	Yes
data	Object	The business data.	Yes
+subDevices	Array	The ID of the specified door.	Yes
+uid	String	The user ID, with no more than 32 characters.	Yes
+idCard	String	The identity card number of the specified user, with no more than 32 characters.	No
+phone	String	The 11-digit mobile phone number.	No
+beginTime	Long	The 13-digit timestamp when a validity period starts.	Yes
+endTime	Long	The 13-digit timestamp when a validity period ends.	Yes
+name	String	The name of the specified user, with no more than 64 characters.	Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 4,
    "cid": "doorId***",
    "data": {
        "subDevices": ["1", "2", "3", "4"],
        "idCard": "350725***",
        "phone": "188***",
        "beginTime": 1676007834382,
        "endTime": 1676007844382,
        "name": "Tom**",
        "uid": "350715***"
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "cid": "doorId***",
   "reqType": 4,
   "data": {
        "success": true,
        "msg": "success",
    }
}

Delete a user

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 5 to delete the information about the specified user.	Yes
cid	String	The unique ID of the specified access controller.	Yes
data	Object	The business data.	Yes
+uid	String	The user ID, with no more than 32 characters.	Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 5,
    "cid": "doorId***",
    "data": {
        "uid": "350715***"
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "reqType": 5,
   "cid": "doorId***",
   "data": {
        "success": true,
        "msg": "success"
    }
}

Add a card

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 6, add a card.	Yes
cid	String	The ID of the specified access controller.	Yes
data	Object	The business data.	Yes
+uid	String	The user ID, with no more than 32 characters.	Yes
+cardNo	String	The card number.	Yes

Message format

{
  "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 6,
    "cid": "doorId***",
    "data": {
        "uid": "350715***"
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "reqType": 6,
   "cid": "doorId***",
   "data": {
        "success": true,
        "msg": "success"
    }
}

Modify a card

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 7 to modify a card.	Yes
cid	String	The ID of the specified multi-door access controller.	Yes
data	Object	The business data.	Yes
+uid	String	The user ID, with no more than 32 characters.	Yes
+cardNo	String	The new card number.	Yes
+oldCardNo	String	The old card number.	Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 7,
    "cid": "doorId***",
    "data": {
        "uid": "350715***",
  		  "oldCardNo": ,
        "cardNo": ""
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "reqType": 7,
   "cid": "doorId***",
   "data": {
        "success": true,
        "msg": "success"
    }
}

Delete a card

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 8 to delete a card.	Yes
cid	String	The ID of the specified multi-door access controller.	Yes
data	Object	The business data.	Yes
+uid	String	The user ID, with no more than 32 characters.	Yes
+cardNo	String	The card number.	Yes

Message format

{
  "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 8,
    "cid": "doorId***",
    "data": {
        "uid": "350715***",
        "cardNo": ""
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "reqType": 8,
   "cid": "doorId***",
   "data": {
        "success": true,
        "msg": "success"
    }
}

Remote unlocking

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 9 to perform remote unlocking.	Yes
cid	String	The ID of the specified multi-door access controller.	Yes
data	Object	The business data.	Yes
+uid	String	The user ID, with no more than 32 characters.	Yes
+doorNo	String	The ID of the specified door.	Yes

Message format

{
  "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 9,
    "cid": "doorId***",
    "data": {
        "uid": "350715***",
        "doorNo": "1"
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "reqType": 9,
   "cid": "doorId***",
   "data": {
        "success": true,
        "msg": "success"
    }
}

Keep a door always open/closed

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 10 to keep a door always open or always closed.	Yes
cid	String	The ID of the specified multi-door access controller.	Yes
data	Object	The business data.	Yes
+uid	String	The user ID, with no more than 32 characters.	Yes
+doorNo	String	The ID of the specified door.	Yes
+type	Integer	The enumeration values. 0: Put the device into the normal working state. 1: Keep a door always open. 2: Keep a door always closed.	Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 10,
    "cid": "doorId***",
    "data": {
        "uid": "350715***",
        "doorNo": "1",
        "type": 1
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "reqType": 10,
   "cid": "doorId***",
   "data": {
        "success": true,
        "msg": "success"
    }
}

Generate a QR code

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 11, and the device generates a QR code.	Yes
cid	String	The ID of the specified multi-door access controller.	Yes
data	Object	The business data.	Yes
+uid	String	The user ID, with no more than 32 characters.	Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 11,
    "cid": "doorId***",
    "data": {
        "uid": "350715***"
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "reqType": 11,
   "cid": "doorId***",
   "data": {
        "success": true,
        "msg": "success"
				"qrcode": "backkdsaodkoke"

    }
}

Clear the data of a multi-door access controller

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 12 to clear the data of the specified multi-door access controller.	Yes
cid	String	The ID of the specified multi-door access controller.	Yes
data	Object	The business data.	Yes
+all	Boolean	Specifies whether to clear all the data.	No
+person	Boolean	Specifies whether to clear the data of all users.	No
+face	Boolean	Specifies whether to clear the data of all faces.	No
+card	Boolean	Specifies whether to clear the data of all card numbers.	No
+qrcode	Boolean	Specifies whether to clear the data of all QR codes.	No
+passpwd	Boolean	Specifies whether to clear the data of all access control passwords.	No
+other	Boolean	Specifies whether to clear other data.	No

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 12,
    "cid": "doorId***",
    "data": {
        "all": true,
        "person": false,
        "face": false,
        "card": false,
        "qrcode": false,
        "passpwd": false,
        "other": false
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "reqType": 12,
   "cid": "doorId***",
   "data": {
        "success": true,
        "msg": "success"
    }
}

Report the device status

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 13 to report the device status.	Yes
cid	String	The ID of the specified multi-door access controller.	Yes
data	Object	The business data.	Yes
+online	Integer	The enumeration values. 1: The device is offline. 2: The device is online.	Yes

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 13,
    "cid": "doorId***",
    "data": {
        "online": 2
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "reqType": 13,
   "cid": "doorId***",
   "data": {
        "success": true,
        "msg": "success"
    }
}

Report an access event

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 14 to report an access event.	Yes
cid	String	The ID of the specified multi-door access controller.	Yes
data	Object	The business data.	Yes
+doorNo	String	The ID of the specified door.	Yes
+uid	String	The user ID.	Yes
+success	Integer	The returned result. 0: failure. 1: success.	Yes
+way	String	The access control methods. Valid values: 1: card. 2: password. 3: QR code. 4: face recognition. 5: fingerprint. 9: remote unlocking. 10: others.	Yes
+t	Long	The time when a user passes.	Yes
+location	String	The location of the specified reader. Valid values: 0: unknown. 1: entry. 2: exit.	Yes
+imageUrl	String	The URL of a photo taken when a user passes. Only .png files are supported.	No
+cardNo	String	The card number. This field is required when a card is used.	No
+temp	String	The temperature in format of a floating-point number string.	No

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 14,
    "cid": "doorId***",
    "data": {
        "doorNo": "1",
        "uid": "350715***",
        "success": 1,
        "way": "1",
        "t": 1655275***,
        "location": "1",
        "cardNo": "4132493",
        "temp": "36.8",
        "imageUrl": "https://oss.tuya.com/80/1.jpg"
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "reqType": 14,
   "cid": "doorId***",
   "data": {
        "success": true,
        "msg": "success"
    }
}

Report an alert event

Parameter	Data type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of the specified request. We recommend that the value of reqId be generated by the UUID. The gateway can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	Set the value of reqType to 15 to report an alert event.	Yes
cid	String	The ID of the specified multi-door access controller.	Yes
data	Object	The business data.	Yes
+alarmId	String	The ID of the specified alert event.	Yes
+doorNo	String	The ID of the specified door.	Yes
+alarmType	Integer	The alert type. Valid values: 1: tamper alarm. 2: stranger alarm. 10: others.	Yes
+alarmCont	String	The content of the specified alert event.	No
+imageUrl	String	The URL of the specified alert image.	No
+t	Integer	The timestamp when the specified alert event occurs.	Yes
+confirmEnable	Boolean	Specifies whether an alert event is processed. true: already processed.	No
+extendData	String	The extension information.	No

Message format

{
    "t": 1655275***,
    "reqId": "16552757***",
    "reqType": 15,
    "cid": "doorId***",
    "data": {
        "doorNo": "1",
        "alarmId": "fsajifasif",
        "alarmType": 2,
        "alarmCont": "Stranger alarm",
        "t": 1655275***,
        "imageUrl": "https://oss.tuya.com/80/1.jpg",
        "confirmEnable": false,
        "extendData": ""
    }
}

Response message format

{
   "t": 1655275***,
   "reqId": "16552757***",
   "reqType": 15,
   "cid": "doorId***",
   "data": {
        "success": true,
        "msg": "success"
    }
}

Sample application

MQTT connection example:

import (
	"crypto/md5"
	"encoding/hex"
	"fmt"
	"log"
	"time"

	mqtt "github.com/eclipse/paho.mqtt.golang"
)

var (
	client mqtt.Client
	pubTopic string
	subTopic string
	password string
)

func main() {
	log.SetFlags(log.LstdFlags | log.Lshortfile)

	var (
		username = "multiaccess***"
		clientId = "multiaccess"
		broker   = "tcp://ip:port"
	)
	password = string(genSecKey(clientId, username))
	pubTopic = fmt.Sprintf("gateway/multiaccess/out/%s", clientId)
	subTopic = fmt.Sprintf("gateway/multiaccess/in/%s", clientId)

	opts := mqtt.NewClientOptions().SetClientID(clientId).SetUsername(username).SetPassword(password)
	opts = opts.SetAutoReconnect(true).SetCleanSession(true).SetKeepAlive(5 * time.Second).
		SetMaxReconnectInterval(10 * time.Second).
		SetConnectRetry(true).SetConnectRetryInterval(time.Second)

	opts.AddBroker(broker)
	opts.SetOnConnectHandler(func(client mqtt.Client) {
		log.Println("connected")

		client.Subscribe(subTopic, 1, onMessage)
	}).SetConnectionLostHandler(func(client mqtt.Client, err error) {
		log.Println("connect lost")
	})
	client = mqtt.NewClient(opts)
	token := client.Connect()
	if ok := token.WaitTimeout(time.Second * 10); !ok {
		panic("connect timeout")
	}

	for {
	}
}

func onMessage(client mqtt.Client, msg mqtt.Message) {
	log.Printf("onmessage, topic:%v, messageId:%v, msg: %+v\n", msg.Topic(), msg.MessageID(), string(msg.Payload()))
	// Message processing logic
}

// publish Send messages
func publish(payload []byte) error {
	token := client.Publish(pubTopic, 1, true, payload)
	log.Println(token)
	return nil
}

func genSecKey(clientID, userName string) []byte {
	secKey := genMd5(clientID + userName)[:16]
	return []byte(secKey)
}

func genMd5(source string) (md5str string) {
	md5Ctx := md5.New()
	md5Ctx.Write([]byte(source))
	cipherStr := md5Ctx.Sum(nil)
	md5str = hex.EncodeToString(cipherStr)
	return
}