Integration with Smart Elevator Controller

Last Updated on : 2023-03-03 05:49:57download

This topic describes how to integrate smart elevator controllers with the Tuya IoT Development Platform. If an elevator controller cannot directly communicate with the Tuya IoT Development 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 IoT Development Platform. The architecture is shown as follows:

Integration with Smart Elevator Controller

The elevator control gateway communicates with Tuya’s IoT Edge Gateway over the MQTT protocol.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters during subscription.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

cid, reqId, reqType, and devType are the parameters reported.

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

Note that wellDevs shows the serial number of a specified elevator shaft.

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.