Integration with Multi-Door Access Controller

Last Updated on : 2023-06-21 06:38:44download

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

Architecture

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

Integration with Multi-Door Access Controller

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

Business process

Tuya IoT Development PlatformIoT Edge GatewayDevice GatewaySynchronize the device informationActivate the deviceReturn the resultReturn the resultSend control commands from the cloudSend commandsReturn the execution resultReturn the resultReport device propertiesReport device propertiesReturn the processing resultReturn the resultRegularly report device online and offline eventsReport device online and offline eventsTuya IoT Development PlatformIoT Edge GatewayDevice Gateway

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