Overview of Elevator Control Service

This topic describes how to integrate with open capabilities of elevator control devices.

Data points of elevator control devices

For more information about data points, see Modify Data Point.

Data point code	Description
face_lift	Take an elevator by face recognition.
qrcode_lift	Take an elevator by scanning a QR code.
out_lift	Support hall call.
unify_lift	Call an elevator by car call and hall call. The elevator status is reported, including the elevator shaft, the current floor where the elevator car stops, and the traveling direction.
out_auth	Call an elevator by car call and hall call. The elevator status is not reported.
public_lift	The elevator car can stop at public floors that do not require authorization.

APIs for elevator control devices

Elevator control user management

API name	API endpoint
Delete Person	DELETE:/v1.0/elevator-control/{device_id}/persons/{person_id}
Update Person	PUT:/v1.0/elevator-control/{device_id}/persons/{person_id}
Add Person	POST:/v1.0/elevator-control/{device_id}/persons/{person_id}

Elevator control face management

API name	API endpoint
Delete Face	DELETE:/v1.0/elevator-control/{device_id}/persons/{person_id}/faces/{face_id}
Add Face	POST:/v1.0/elevator-control/{device_id}/persons/{person_id}/faces/{face_id}
Update Face	PUT:/v1.0/elevator-control/{device_id}/persons/{person_id}/faces/{face_id}

Elevator control card management

API name	API endpoint
Unfreeze Elevator Control Card	PUT:/v1.0/elevator-control/{device_id}/persons/{person_id}/card/{card_no}/unfreeze
Freeze Elevator Control Card	PUT:/v1.0/elevator-control/{device_id}/persons/{person_id}/card/{card_no}/freeze
Add Elevator Control Card	POST:/v1.0/elevator-control/{device_id}/persons/{person_id}/card/{card_no}
Delete Elevator Control Card	DELETE:/v1.0/elevator-control/{device_id}/persons/{person_id}/card/{card_no}

Send a command to call an elevator

API name	API endpoint
Send Elevator Call Command	POST:/v1.0/elevator-control/{device_id}/persons/{person_id}/actions/call

Elevator control QR code management

API name	API endpoint
Delete QR Code	DELETE:/v1.0/elevator-control/{device_id}/persons/{person_id}/qrcodes/{qr_code}
Update QR Code	PUT:/v1.0/elevator-control/{device_id}/persons/{person_id}/qrcodes/{qr_code}
Add QR Code	POST:/v1.0/elevator-control/{device_id}/persons/{person_id}/qrcodes/{qr_code}

Elevator control event format

After you subscribe to the message service for a cloud development project, you will receive event messages from the linked elevator control devices. For more information about the integration with a message queue, see Message Queue.

Report pass records

API description

When an elevator control device is triggered, the party who performs the integration process will be notified of the pass event. The event code is pass_event.

Description of value

Parameter	Type	Description	Required
uid	String	The ID of a specified person. Specify -1 for a stranger.	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
t	Long	The 13-digit timestamp of the time when a person passes.	Yes
success	Integer	Indicates whether the operation is successful. Valid values: 1: success 0: failure	Yes
message	String	The description of a specified passing event. In case of a failure, an error message will be returned.	No
picUrl	String	The temporary URL of a photo taken when a person passes. This photo is taken by the device when a person passes. This photo can be downloaded through the URL.	No
temp	String	The body temperature.	No
startFloor	Integer	The floor on which the elevator starts.	No
endFloor	Integer	The floor at which the elevator arrives.	No
lifeNum	Integer	The serial number of a specified elevator shaft.	No
extend	String	The extension field.	No

Example

{
    "dataId": "AAXRV4BrtW9BRB9A2JYW****",
    "devId": "6ca****",
    "productKey": "e6rz6vba81wm****",
    "status": [
        {
            "12": "{\"message\":\"ok\",\"success\":1,\"t\":1637548630452,\"uid\":\"zs123\",\"way\":4}",
            "code": "pass_event",
            "t": 1637548630455,
            "value": "{\"message\":\"ok\",\"success\":1,\"t\":1637548630452,\"uid\":\"zs123\",\"way\":1}"
        }
    ]
}

Report the status monitoring event

API description

Report the elevator status, including the elevator shaft, the current floor where the elevator car stops, and the traveling direction. The event code is function_data.

Description of value

Parameter	Type	Description	Required
shaftList	List	A list of elevator cars.	Yes

Description of ElevatorShaftDTO

Parameter	Type	Description	Required
lifeNum	Integer	The serial number of a specified elevator shaft.	No
status	Integer	The status of a specified elevator. Valid values: 0: The elevator is stopped. 1: The elevator is going upwards. 2: The elevator is going downwards. 3: The elevator goes wrong.	No
direction	Integer	The traveling direction of a specified elevator. Valid values: 0: Upwards. 1: Downwards.	No
curFloor	Integer	The current floor. It must be a physical floor.	No

Example

{
    "dataId": "AAXRV4BrtW9BRB9A2JYW****",
    "devId": "6ca****",
    "productKey": "e6rz6vba81wm****",
    "status": [
        {
            "6": "{\"shaftList\":[{\"lifeNum\":1,\"curFloor\":1,\"direction\":0,\"status\":1},{\"lifeNum\":2,\"curFloor\":1,\"direction\":0,\"status\":1}]}",
            "code": "function_data",
            "t": 1637548630455,
            "value": "{\"shaftList\":[{\"lifeNum\":1,\"curFloor\":1,\"direction\":0,\"status\":1},{\"lifeNum\":2,\"curFloor\":1,\"direction\":0,\"status\":1}]}"
        }
    ]
}

Others

Elevator control QR code

Currently, QR codes are classified into static QR codes and dynamic QR codes.

• Static QR code: The QR code remains unchanged. The QR code is bound with a person. You need to implement the process to send the QR code to the device.
• Dynamic QR code: The QR code is refreshed regularly. The QR code is dynamically generated according to the secret key and time factor in the person information.

Elevator control QR code process

1. Send a QR code.
   • Static QR code: You call the API operation to send a static QR code to the device.
   • Dynamic QR code: You call the API operation to send the person information to the device. Then, the device generates a dynamic QR code based on the dynamic key of the person information.
2. The device saves a static QR code or generates a dynamic QR code based on the dynamic key of the person.
3. Generate a QR code on the app.
4. The elevator control device scans the QR code. After the data matches, the person is identified and the passing event is reported.

Elevator control QR code format

The QR code content format is shown as follows:

{
  "qrcode": "7kCzIejJVhfwYOGGJLr1iUUPRXP69AiNMGcMhowRSVA="  // value: Base64 encoded string
}

Generate a QR code on the app

Static QR code

Generate a static QR code in the following steps.

1. Concatenate a QR code string in the format of “UID|QR code content”.
2. Encode “UID|QR code content” based on Base64.
3. Generate the QR code content in the JSON format.

Sample:

    User ID: ay16110581781387****
    QR code content: 46bff10b9bf843fab194cf246bfedda8
    Perform Base64 encoding of "ay16110581781387****|46bff10b9bf843fab194cf246bfedda8".
    The resulting string is as follows:
      YXkxNjExMDU4MTc4MTM4N240Mjd8NDZiZmYxMGI5YmY4NDNmYWIxOTRjZjI0NmJmZWRkYTg=
    The QR code content is shown as follows:
    {
      "qrcode": "YXkxNjExMDU4MTc4MTM4N240Mjd8NDZiZmYxMGI5YmY4NDNmYWIxOTRjZjI0NmJmZWRkYTg="
    }

Dynamic QR code

Generate a dynamic QR code in the following steps.

1. Generate the QR code information through the generateTOTP method.
2. Encode “UID|QR code content” based on Base64.
3. Generate the QR code content in the JSON format.

Sample code of the generateTOTP method:

/**
     * Generate a dynamic QR code
     *
     * @param uid     Tuya user ID
     * @param secretKey   The secret key, a 32-digit string. It is recommended to be generated by the UUID.
     * @param refreshTime    The refresh time of a QR code
     * @return
     */
    public static TOTPTokenCodeDTO generateTOTP(String uid, String secretKey, Long refreshTime) {
        if (StringUtils.isBlank(uid) || StringUtils.isBlank(secretKey) || refreshTime == null) {
            log.error("Request parameter error, uid:{}, secretKey:{}, refreshTime:{}", uid, secretKey, refreshTime);
            throw new RuntimeException("Request parameter error");
        }

        // Get the timestamp of the current time
        long now = new Date().getTime();
        // Convert the dynamic factor to hexadecimal
        String time = Long.toHexString(timeFactor(now, refreshTime)).toUpperCase();
        String totp = doGenerateTOTP(uid + secretKey, time);
        // The duration after the dynamic code is generated in this cycle
        long usedTime = validTime(now, refreshTime);
        return new TOTPTokenCodeDTO(totp, usedTime);
    }

    /**
     * @param key   The user ID + seed key
     * @param time  The time factor
     * @return
     */
    private static String doGenerateTOTP(String key, String time) {
        // 1. If the time is less than 16 characters, pad it with zeros. Example: 30B649C -> 00000000030B649C
        StringBuilder timeBuilder = new StringBuilder(time);
        while (timeBuilder.length() < 16) {
            timeBuilder.insert(0, "0");
        }
        time = timeBuilder.toString();

        // 2. Convert hexadecimal format to binary format
        byte[] msg = hexStr2Bytes(time);
        // 3. Convert the key to bytes
        byte[] k = key.getBytes();
        // 4. Hash encryption
        byte[] hash = hmac_sha("HmacSHA256", k, msg);
        // 5. Return a dynamic password of the specified number of digits
        String encodeHexStr = Hex.encodeHexString(hash);
        StringBuilder result = new StringBuilder(encodeHexStr);
        // 6. If the returned value is less than the specified number of digits, pad it with 0
        while (result.length() < 8) {
            result.insert(0, "0");
        }
        return result.substring(0, 8);
    }

    /**
     * Get the dynamic factor
     *
     * @param targetTime   The specified time
     * @param refreshTime   The time step in milliseconds, as the refresh interval of the dynamic password
     * @return long
     */
    private static long timeFactor(Long targetTime, long refreshTime) {
        return targetTime / refreshTime;
    }

    /**
     // Get the duration after the dynamic code is generated in this cycle
     *
     * @param targetTime
     * @param refreshTime
     * @return
     */
    private static long validTime(long targetTime, long refreshTime) {
        return targetTime % refreshTime;
    }

    /**
     * Hash encryption
     *
     * @param crypto  The encryption algorithm
     * @param keyBytes    The key array
     * @param text     The encrypted content
     * @return byte[]
     */
    private static byte[] hmac_sha(String crypto, byte[] keyBytes, byte[] text) {
        try {
            Mac hmac;
            hmac = Mac.getInstance(crypto);
            SecretKeySpec macKey = new SecretKeySpec(keyBytes, "AES");
            hmac.init(macKey);
            return hmac.doFinal(text);
        } catch (GeneralSecurityException gse) {
            throw new RuntimeException(gse);
        }
    }

    private static byte[] hexStr2Bytes(String hex) {
        byte[] sourceArray = new BigInteger("10" + hex, 16).toByteArray();
        byte[] targetArray = new byte[sourceArray.length - 1];
        // Copy and paste the original array to the target array
        // src: the source array. srcPos: the starting position of the source array to be copied. dest: the target array. destPos: the starting position of the target array to be copied. length: the length to be copied.
        System.arraycopy(sourceArray, 1, targetArray, 0, targetArray.length);
        return targetArray;
    }

Sample:

    User ID: ay16110581781387****
    Secret key: 46bff10b9bf843fab194cf246bfedda8
    QR code refresh time: 5 × 60 × 1000
    The QR code information generated by the `generateTOTP` method: e4af****
    Perform Base64 encoding of `ay16110581781387****|e4af23e6`.
    The resulting string is as follows:
    7kCzIejJVhfwYOGGJLr1iUUPRXP69AiNMGcMhowRSVA=
    The QR code content is shown as follows:
    {
    "qrcode": "7kCzIejJVhfwYOGGJLr1iUUPRXP69AiNMGcMhowRSVA="
    }

Elevator control event format v1.0

Device event messages are compatible with v1.0 format. If you want to subscribe to the v1.0 format, please contact Tuya’s staff. For more information about the integration process, see Device event format v1.0.

Report access control records

API description

When an elevator control device is triggered, you will be notified of the pass event.

Parameters

Parameter name	Data type	Description	Required
bizCode	String	The business code of a specified event. Default value: edge_device.	Yes
eventType	String	The type of a specified event. Default value: edge_report_data.	Yes
mode	String	The mode of a specified event. Default value: elevator-pass.	Yes
deviceId	String	The ID of a specified Tuya device.	Yes
uid	String	The ID of a specified person that passes the access control device. Specify -1 for a stranger.	Yes
way	Integer	The access control method. Valid values: 1: card 2: password 3: QR code 4: face 5: fingerprint 9: remote control 10: others	Yes
t	Long	The 13-digit timestamp of the time when a person passes.	Yes
success	Integer	Indicates whether the operation is successful. Valid values: 1: success 0: failure	Yes
message	String	The description of a specified access control event. In case of a failure, an error message will be returned.	No
passUrl	String	The temporary URL of a photo taken when a person passes. This photo can be downloaded through the URL.	No
temp	String	The body temperature.	No
startFloor	Integer	The floor on which the elevator starts.	No
endFloor	Integer	The floor at which the elevator arrives.	No
lifeNum	Integer	The serial number of a specified elevator shaft.	No
extend	String	The extension field.	No

Example

{
	"data": "{\"mode\":\"elevator-pass\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\",\\\"t\\\":1612514362591,\\\"message\\\":\\\"success\\\",\\\"passUrl\\\":\\\"http://www.xxx.com/image.jpg\\\",\\\"uid\\\":\\\"ay16110581781387n***\\\",\\\"way\\\":4}\",\\\"success\\\":1}\"}",
	"bizCode": "edge_device",
	"eventType": "edge_report_data"
}