Integration with Smart Elevator Controller

This topic describes how to integrate smart elevator controllers with the Tuya Developer Platform. If an elevator controller cannot directly communicate with the Tuya Developer Platform, you can use Tuya’s IoT Edge Gateway to help achieve the communication.

Architecture

Tuya provides the following solution to help you integrate your elevator controllers with the Tuya Developer Platform. The architecture is shown as follows:

Device features

No.	Feature	Description	devType
1	Send a command to call an elevator	The IoT Edge Gateway sends a command to call an elevator by hall call, car call, or both.	elevatorController
2	Send a command to query floor status	The IoT Edge Gateway sends a command to query the status of a specified floor.	elevatorController
3	Report floor status	After receiving the status query command from the IoT Edge Gateway, the elevator control gateway reports the current status of the specified floor.	elevatorController
4	Send a command to add a user	Add a user.	elevatorController
5	Send a command to update a user	Update the information about a specified user.	elevatorController
6	Send a command to delete a user	Delete the information about a specified user.	elevatorController
7	Send a command to add face data	Add the information about a specified face.	elevatorController
8	Send a command to update face data	Update the information about a specified face.	elevatorController
9	Send a command to delete face data	Delete the information about a specified face.	elevatorController
10	Send a command to add/update a QR code	Add or update the information about a specified QR code.	elevatorController
11	Send a command to delete a QR code	Delete the information about a specified QR code.	elevatorController
12	Send a command to add/update a card	Add or update the information about a specified card.	elevatorController
13	Send a command to delete a card	Delete a specified card.	elevatorController
14	Send a command to freeze a card	Freeze a specified card.	elevatorController
15	Send a command to unfreeze a card	Unfreeze a specified card.	elevatorController
17	Report pass records	Report the pass records.	elevatorController
1001	Report device online/offline event	Report the event that a specified device gets online or offline.	elevatorController
1	Send a command to sync device data	The IoT Edge Gateway sends a request for synchronizing the device list, and the elevator control gateway synchronizes the device list.	gateway
2	Sync device data in messages	The IoT Edge Gateway sends a request for synchronizing the device list. After receiving the request, the elevator control gateway reports the information about elevator controllers to the IoT Edge Gateway.	gateway

Integration protocol

The elevator control gateway communicates with Tuya’s IoT Edge Gateway over the MQTT protocol. The elevator control gateway works as a client, and the 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.

• port: 21883

• clientId: namely gatewayID, the ID of your elevator control gateway.

• username: the manufacturer username of the elevator control gateway. 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: abcd1234
  	username: tuya
  	password: sub(md5(clientId + username), 0, 16)-> c88ba730489ed678
  

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

Message topic reported by elevator control gateway

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

Sample message

password: "c88ba730489ed678"
payload: "{\"t\":1598010614705,\"reqId\":\"1231231231\",\"cid\":\"123122\",\"reqType\":1,\"devType\":\"elevatorController\",\"data\":{\"actionType\":\"inCall\",\"startFloor\":1,\"endFloor\":2,\"direction\":1,\"permissionFloor\":[3]}}"
secPayload: "Qsm7rT3i7lJj1ZRHvEH5X7Mxuu0lRttpd4elASdoyyV+leNnd2C6+QQWS0xag0P1mlyAzwG1yM/GEg+vQgrk9elpAIeThHRkQi5HPEcVTiLggzKBhkbG3Q6PM7PLdnX9tLF+a0cbB/KyeLuDOSn4lH7JMgCBuxuUub2Ue87/tUTKPrGfX2U5s05zC5HJmtDJ+7c09BUz7seaEH9RgdxkcZrKXKvyuIzEmBxYW1LcA6VyQX0zKvz7+0uGcam4SX/ptB4vQUY2/nwZ7tdg2U9SGg=="

Message topic subscribed by elevator control gateway

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

Sample message

password: "c88ba730489ed678"
secPayload: "Qsm7rT3i7lJj1ZRHvEH5X7Mxuu0lRttpd4elASdoyyV+leNnd2C6+QQWS0xag0P1mlyAzwG1yM/GEg+vQgrk9elpAIeThHRkQi5HPEcVTiLggzKBhkbG3Q6PM7PLdnX9tLF+a0cbB/KyeLuDOSn4lH7JMgCBuxuUub2Ue87/tUTKPrGfX2U5s05zC5HJmtDJ+7c09BUz7seaEH9RgdxkcZrKXKvyuIzEmBxYW1LcA6VyQX0zKvz7+0uGcam4SX/ptB4vQUY2/nwZ7tdg2U9SGg==
"
payload: "{\"t\":1598010614705,\"reqId\":\"1231231231\",\"cid\":\"123122\",\"reqType\":1,\"devType\":\"elevatorController\",\"data\":{\"actionType\":\"inCall\",\"startFloor\":1,\"endFloor\":2,\"direction\":1,\"permissionFloor\":[3]}}"

Message encryption and decryption

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

• The encryption and decryption method: AES-ECB.
• The encryption and decryption password: Use the password used for connection authentication.

Sample code

password := "c88ba730489ed678"
payload := "{\"t\":1598010614705,\"reqId\":\"1231231231\",\"cid\":\"123122\",\"reqType\":1,\"devType\":\"elevatorController\",\"data\":{\"actionType\":\"inCall\",\"startFloor\":1,\"endFloor\":2,\"direction\":1,\"permissionFloor\":[3]}}"
data, err := aes_crypto.AesECBEncrypt([]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_crypto.AesECBDecrypt(dataE, []byte(password))
t.Log(err)
t.Log(string(dataD))

Device control

Send a command to call an elevator

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 1, call the elevator.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
actionType	String	unifycall: a compatible mode for car call and hall call. It applies to startFloor and endFloor at the same time. The external up and down buttons light up, and the internal floor button lights up after the elevator arrives. outCall: the hall call mode. In this mode, startFloor takes effect and endFloor can be empty. The elevator reaches the point of startFloor and lights up the external up and down buttons. inCall: the car call mode. It is triggered when a user is confirmed to be inside a car. endFloor takes effect and startFloor can be empty. The elevator lights up the internal floor button. permissionCall: grants permissions to the specified floors. The maximum length is 32 characters.	Yes
startFloor	Integer	The floor on which the elevator starts. It must be a physical floor, starting with 1.	No
endFloor	Integer	The destination floor. It must be a physical floor, starting with 1.	No
direction	Integer	The direction can be up or down.	No
permissionFloor	array	The floor on which a user is granted permissions. It must be a physical floor, starting with 1.	No

Msg message format:

{
  "t":159801061****,
	"reqId":"123123****",
	"cid":"12****",
	"reqType":1,
	"devType":"elevatorController",
	"data":{
			"actionType":"inCall"/"outCall"/"permissionCall"/"unifyCall",
			"startFloor":1,
			"endFloor":2,
			"direction":1,
			"permissionFloor":[1,3],
	}

Message format of returned result

{
  "t":159801061****,
  "reqId":"123123****",
  "cid":"12****",
  "reqType":1,
  "devType":"elevatorController",
  "data":{
  "success":true,
   "msg":"success",
   "code":200
  }
}

Send a command to query floor status

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a command is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 2, query the status of a specified floor.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
liftNum	Integer	The serial number of a specified elevator shaft. The value is not required here.	No

Msg message format:

{
	"t":159801061****,
	"reqId":123123****,
	"cid":"12****",
	"reqType":2,
	"devType":"elevatorController"
	"data":{
	"liftNum":1,
	}
}

Message format of returned result

{
  "t":159801061****,
  "reqId":"123123****",
  "cid":"12****",
  "reqType":2,
  "devType":"elevatorController",
  "data":{
   "success":true,
   "msg":"success",
   "code":200
  }
}

Report floor status

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 3, report the status of a specified floor.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
liftNum	Integer	The serial number of a specified elevator shaft.	No
status	Integer	0: The elevator is stopped. 1: The elevator is going upwards. 2: The elevator is going downwards. 3: The elevator goes wrong.	Yes
direction	Integer	0: Upwards. 1: Downwards.	Yes
curFloor	Integer	The current floor. It must be a physical floor, starting with 1.	Yes

Msg message format:

{
    "t":15980106****,
    "reqId":"112****",
    "reqType":3,
    "devType":"elevatorController",
    "cid":"12****",
    "data":{
        "devs":[
            {
                "liftNum":3,
                "status":0,
                "direction":0,
                "curFloor":2
            }
        ]
    }
}

Message format of subscription execution result

{
  "t":15980106****,
  "reqId":"123123****",
  "cid":"12****",
  "reqType":3,
  "devType":"elevatorController",
  "data":{
      "success":true,
      "msg":"success",
      "code":200
  }
}

User management

Add user

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 4, add a user.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
beginTime	int64	The start time.	Yes
endTime	int64	The expiration time.	Yes
idCard	String	The identity card. The maximum length is 64 characters.	No
secretKey	String	The user’s secret key with 32 characters. We recommend that you generate it through the UUID. The app and device generate dynamic QR codes based on the same secret key. The maximum length is 64 characters.	No
refreshTime	int64	The time interval when a QR code is refreshed. Default value: 300,000 milliseconds. Unit: milliseconds.	No
Name	String	The user’s name. The maximum length is 64 characters.	Yes
phone	String	The user’s mobile phone number. The maximum length is 64 characters.	No
uid	String	The user’s unique identifier. The maximum length is 64 characters.	Yes
permissionFloor	[ int]	The floor on which a user is granted permissions.	Yes

Msg message format:

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":4,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"beginTime":1582959882104,
        "endTime":1661666512292,
        "idCard":"123****",
        "secretKey":"wedsddfkkdsdfxdldwddiokfghed****",
        "refreshTime":300000,
        "name":"tuyaFamily",
        "phone":"1732606****",
        "uid":"3****"
        "permissionFloor":[1,3],
	}
}

Message format of returned result

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":4,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	 "success":true,
         "msg":"success",
         "code":200
	}
}

Update user

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 5, update the information about a specified user.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
beginTime	int64	The start time.	No
endTime	int64	The expiration time.	No
idCard	String	The identity card. The maximum length is 64 characters.	No
secretKey	String	The user’s secret key with 32 characters. We recommend that you generate it through the UUID. The app and device generate dynamic QR codes based on the same secret key. The maximum length is 64 characters.	No
refreshTime	int64	The time interval when a QR code is refreshed. Default value: 300,000 milliseconds. Unit: milliseconds.	No
Name	String	The user’s name. The maximum length is 64 characters.	No
phone	String	The user’s mobile phone number. The maximum length is 64 characters.	No
uid	String	The user’s unique identifier. The maximum length is 64 characters.	Yes
permissionFloor	[ int]	The floor on which a user is granted permissions.	No

Msg message format:

{
	"t":159801061****,
	"reqId":123123****,
	"reqType":5,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"beginTime":1582959882104,
        "endTime":1661666512292,
        "idCard":"123****",
        "secretKey":"wedsddfkkdsdfxdldwddiokfghedf***",
        "refreshTime":300000,
        "name":"tuyaFamily",
        "phone":"1732606****",
        "uid":"3****"
        "permissionFloor":[1,3],
	}
}

Message format of returned result

{
	"t":159801061****,
	"reqId":123123****,
	"reqType":5,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"success":true,
        "msg":"success",
        "code":200
	}
}

Delete user

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 6, delete the information about a specified user.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
uid	String	The user’s unique identifier. The maximum length is 64 characters.	Yes

Msg message format:

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":6,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"uid":"123****"
	}
}

Message format of returned result

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":6,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
       "success":true,
       "msg":"success",
       "code":200
	}
}

Add face

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 7, add the information about a specified face.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
uid	String	The user’s unique identifier. The maximum length is 64 characters.	Yes
faceid	String	The unique identifier of a specified face image. The maximum length is 64 characters.	Yes
url	String	The URL of a specified face image. The maximum length is 256 characters.	Yes

Msg message format:

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":7,
	"devType":"elevatorController",
	"cid":"123****"
	"data":{
	"uid":"375****",
        "faceid":"663****",
        "url":"https://s1.ax1x.com/2020/07/22/****.png"
	}
}

Message format of returned result

{
	"t":15980106****,
	"reqId":123****,
	"reqType":7,
	"devType":"elevatorController",
	"cid":"123****"
	"data":{
	"success":true,
        "msg":"success",
        "code":200
	}
}

Update Face

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 8, update the information about a specified face image.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
uid	String	The user’s unique identifier. The maximum length is 64 characters.	Yes
faceid	String	The unique identifier of a specified face image. The maximum length is 64 characters.	Yes
url	String	The URL of a specified face image. The maximum length is 256 characters.	Yes

Msg message format:

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":8,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"uid":"375****",
        "faceid":"6666",
        "url":"https://s1.ax1x.com/2020/07/22/****.png"
	}
}

Message format of returned result

{
	"reqId":123123****,
	"reqType":8,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"success":true,
        "msg":"success",
        "code":200
	}
}

Delete Face

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 9, delete the information about a specified face image.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
faceid	String	The unique identifier of a specified face image. The maximum length is 64 characters.	Yes

Msg message format:

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":9,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
        "faceid":"66****"
	}
}

Message format of returned result

{
	"reqId":123123****,
	"reqType":9,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
       "success":true,
       "msg":"success",
       "code":200
	}
}

Add/update QR code

The mapping relationship between qrcode and person is set up in the device. After qrcode is recognized, the corresponding person and floor information will be recognized.

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 10, add or update the information about a specified QR code.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
uid	String	The user’s unique identifier. The maximum length is 64 characters.	Yes
qrcode	String	The 16-digit hexadecimal string. The maximum length is 64 characters.	Yes

Msg message format:

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":7,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"uid":"375****",
        "qrcode":"fff****",
	}
}

Message format of returned result

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":10,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"success":true,
        "msg":"success",
       "code":200
	}
}

Delete QR Code

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 11, delete the information about a specified QR code.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
uid	String	The user’s unique identifier. The maximum length is 64 characters.	Yes

Msg message format:

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":11,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"uid":"375****",
	}
}

Message format of returned result

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":11,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"success":true,
        "msg":"success",
       "code":200
	}
}

Add/update card

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 12, add or update the information about a specified card.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
uid	String	The user’s unique identifier. The maximum length is 64 characters.	Yes
cardId	String	The card ID. The maximum length is 64 characters.	Yes

Msg message format:

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":12,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"uid":"375****",
	"cardId":"123****"
	}
}

Message format of returned result

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":12,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"success":true,
        "msg":"success",
        "code":200
	}
}

Delete card

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 13, delete the information about a specified card.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
cardId	String	The card ID. The maximum length is 64 characters.	Yes

Msg message format:

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":13,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"cardId":"123****"
	}
}

Message format of returned result

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":13,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"success":true,
        "msg":"success",
       "code":200
	}
}

Freeze a specified card

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 14, freeze the information about a specified card.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
cardId	String	The card ID. The maximum length is 64 characters.	Yes

Msg message format:

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":14,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	 "cardId":"12****"
	}
}

Message format of returned result

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":14,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
        "success":true,
       "msg":"success",
      "code":200
	}
}

Unfreeze a card

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 15, unfreeze the information about a specified card.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
cardId	String	The card ID. The maximum length is 64 characters.	Yes

Msg message format:

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":15,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
	"cardId":"123****"
	}
}

Message format of returned result

{
	"t":15980106****,
	"reqId":123123****,
	"reqType":15,
	"devType":"elevatorController",
	"cid":"12****"
	"data":{
        "success":true,
        "msg":"success",
       "code":200
	}
}

Report access control records by card

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 17, report the access control records.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
liftNum	Integer	The serial number of a specified elevator shaft.	No
uid	String	The user ID. The maximum length is 64 characters.	Yes
startFloor	Integer	The start floor where a specified card is swiped.	No
endFloor	Integer	The destination floor.	No
operTime	Integer	The occurrence time in seconds.	Yes
way	Integer	The elevator control methods. Valid values: 1: card 2: password 3: QR code 4: face 5: fingerprint 9: remote control 10: others	Yes
imageUrl	String	The URL of a photo taken when a person passes. The maximum length is 256 characters.	No
temp	float64	The body temperature.	No
isSuccess	bool	Indicates whether the operation is successful.	Yes
message	String	The failure information. The maximum length is 256 characters.	No

Msg message format:

{
    "t":15980106****,
    "reqId":"112****",
    "reqType":17,
    "devType":"elevatorController",
    "cid":"12****",
    "data":{
        "devs":[
            {
                "liftNum":3,
                "uid":"234****",
                "startFloor":1,
                "endFloor":2,
                "operTime": 3223454989032,
           	"way": 1,
           	"isSuccess": true
            }
        ]
    }
}

Message format of subscription execution result

{
  "t":15980106****,
  "reqId":"123123****",
  "cid":"12****",
  "reqType":17,
  "devType":"elevatorController",
  "data":{
      "success":true,
      "msg":"success",
      "code":200
  }
}

Device management

Report device online and offline events

The elevator controller is connected to the IoT Edge Gateway through the elevator control gateway. The events of devices getting online or offline through the elevator control gateway must be reported to the IoT Edge Gateway.

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. We recommend that the value of reqId be generated by the UUID. The visitor management system can monitor the returned result based on reqId. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 1001, report the events of sub-devices getting online or offline.	Yes
devType	String	The device type. Default value: elevatorController. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified third-party 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
status	Integer	The device status. Valid values: 0: A device goes offline. 1: A device goes online.	Yes

Msg message format:

{
 "t":15980106****,
 "reqId":"123123****",
 "cid":"01D728C3****",
 "reqType":1001,
 "devType":"elevatorController",
 "data":{
  	"status":1
	}
}

Message format of subscription execution result

{
  "t":15980106****,
  "reqId":"123123****",
  "cid":"01D728C3****",
  "reqType":1001,
  "devType":"elevatorController",
  "data":{
      "success":true,
      "msg":"success",
      "code":200
  }
}

Send a command to sync device data

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 1, request to sync the device data.	Yes
devType	String	The device type. Default value: gateway. The maximum length is 32 characters.	Yes
syncDevType	String	The type of the device to be synchronized. Default value: elevatorController. The maximum length is 32 characters.	Yes

Msg message format:

{
	"t":123123****,
        "reqId":"12****",
	"reqType":1,
	"devType":"gateway"
	"data":{
			"syncDevType":"elevatorController"
	}
}

Message format of returned result

{
  "t":15980106****,
  "reqId":"123123****",
  "reqType":1,
  "devType":"gateway",
  "data":{
      "success":true,
      "msg":"success",
      "code":200
  }
}

Sync device data in messages

The edge gateway sends a request for synchronizing the device data. On receiving the request, the elevator control gateway reports the data of elevator controllers under the elevator control gateway.

Request parameter

Parameter	Type	Description	Required
t	Long	The time when a push notification is sent.	Yes
reqId	String	The ID of a specified request. The maximum length is 64 characters.	Yes
reqType	Integer	When the value of reqType is 2, report the device data sync message.	Yes
devType	String	The device type. Default value: gateway. The maximum length is 32 characters.	Yes
cid	String	The ID of a specified elevator controller. 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
Name	String	The name of a specified elevator controller. The maximum length is 64 characters.	No
installLocation	String	The location where the elevator controller is installed. The maximum length is 256 characters.	No
initFloor	Integer	The floor from which the elevator starts, such as -1.	Yes
syncDevType	String	The type of the device to be synchronized. Default value: elevatorController. The maximum length is 32 characters.	Yes
wellDevs	list	The serial number of a specified elevator car. Enter all elevator shafts that are connected to the elevator controller.	Yes
wellNum	int	The serial number of a specified elevator shaft.	Yes

Msg message format:

{
  "t": 15980106****,
  "reqID": "123123****",
  "reqType": 2,
  "devType": "gateway",
  "data": {
    "devs": [
      {
        "cid": "123****",
        "name": "No. 1 Elevator, Building 3",
        "installLocation": "No. 1 Elevator, Building 3",
        "initFloor": 1,
        "wellDevs": [
          {"wellNum":1},
          {"wellNum":2}
        ]
      },
      {
        "cid": "123****",
        "name": "No. 2 Elevator, Building 3",
        "installLocation": "No. 2 Elevator, Building 3",
        "initFloor": 1
      }
    ],
    "syncDevType": "elevatorController"
  }
}

Message format of subscription execution result

{
  "t":15980106****,
  "reqId":"123123****",
  "reqType":2,
  "devType":"gateway",
  "data":{
      "success":true,
      "msg":"success",
      "code":200
  }
}

Dynamic QR code

The device must support the QR codes in two formats:

v1.0 QR code:

Format:

7421371370865597349888943036

v2.0 QR code:

Format:

{
	"qrcode":"YXkxNjExMDU4MTc4MTM4N240Mjd8ZTRhZjIzZTY="  // The value is the Base64 encoded string
}

Verify QR code

After scanning, the device verifies the QR code in the following steps.

1. Check the content of the QR code to determine whether it is v1.0 or v2.0.

   • If it is a v1.0 QR code, compare it with the user’s QR code. If the comparison is successful, access will be allowed.
   • If it is a v2.0 QR code, first decode the content through the Base64 method, and parse the QR code information.

2. Compare and verify the static QR code, and compare the QR code information with the user’s QR code. If the comparison is successful and the QR code is still valid, access will be allowed.

3. If the comparison fails, perform dynamic QR code verification.

   • In case of success, the access will be allowed.
   • In case of failure, the access will be denied.

Verifies a dynamic QR code

Interface description

TOTPUtils.java
 /**
 * Verifies a dynamic QR code
 *
 * @param uid     Tuya user ID.
 * @param secretKey   The secret key, 32-digit string.
 * @param willVerifyTotp    The QR code information to be verified.
 * @param refreshTime    The refresh time of a QR code.
 * @return boolean  The QR code verification result.
 */
 public static boolean verifyTOTPFlexibility(string uid, string secretKey, string
willVerifyTotp, Long refreshTime)

Sample v2.0 QR code:

• The content of the QR code:

  	{
  		"qrcode":"YXkxNjExMDU4MTc4MTM4N240Mjd8ZTRhZjIzZTY=" //The value is the Base64 encoded string
  	}
  

• Verification process:

  1. Perform Base64 decoding of YXkxNjExMDU4MTc4MTM4N240Mjd8ZTRhZjIzZTY and get a string "ay16110581781387n427 | e4af23e6", indicating that:

     • User ID: ay16110581781387****
     • QR code information: e4af23e6****

  2. Get a static QR code based on the user ID for comparison. If the comparison fails, perform dynamic QR code verification.

  3. QR code refresh time: 5 × 60 × 1000 = 300,000 milliseconds. It equals 5 minutes.

  4. Query the user’s secretKey based on the user ID.

  5. Then, call the dynamic QR code verification interface TOTPUtils.verifyTOTPFlexibility. If true is returned, the verification is passed.