Overview of Elevator Control Service

Last Updated on : 2023-06-15 05:25:34

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