Overview of Smart Access Control Service

Last Updated on : 2023-06-15 05:23:11

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

Integration procedure

Access control devices are classified into video access control devices and general access control devices.

To connect to video access control devices, you must perform the following steps:

  • Create an app and link it with a cloud development project.

    1. Log in to the Tuya IoT Development Platform.
    2. In the left-side navigation bar, choose App > App SDK > SDK Development. Click Create App and complete the creation process.
      The channel ID is the unique identifier of an app and is also known as the schema.
    3. In the left-side navigation bar, choose Cloud > Development. Create a project or click an existing project to enter the details page, choose Devices > Link My App to link the app.
  • Send Tuya’s user ID to the specified access control device. Note that you must grant the permissions on Tuya’s user ID to the device.

    1. Call the Sync Users API operation to get the Tuya’s user ID.
      The schema used to sync users refers to the above-mentioned channel ID of the app.

    2. Call the Add Device Permission API operation to grant the permissions on Tuya’s user ID to the specified access control device.

    3. Call the Add User API operation to send Tuya’s user ID to the specified access control device. This way, Tuya’s user ID is used as the user ID of the access control device.

Data points of access control devices

For more information, see Public Area Device Function Point.

Data point code Description
tyabinmc7h Face recognition
tyabirdc5c QR code
tyabiym3h3 Card
tyabi8n4fs Remote unlocking
tyabiwvwhq Video talk
tyabikrhuc Bluetooth
tyabi9pqys Password
tyabianxfw Fingerprint
tyabitkn9q Temperature measurement
tyabifgx7y Normally open
tyabiu3s3d Normally closed
tyabijhcym Schedule

APIs for access control devices

Smart access user management

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

Smart access face management

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

Smart access QR code management

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

Smart access card management

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

Smart access password management

API name API endpoint
Delete Password DELETE:/v1.0/access-control/{device_id}/persons/{person_id}/passpwd/{pass_pwd}
Update Password PUT:/v1.0/access-control/{device_id}/persons/{person_id}/passpwd/{pass_pwd}
Add Password POST:/v1.0/access-control/{device_id}/persons/{person_id}/passpwd/{pass_pwd}

Remote unlocking

API name API endpoint
Send Unlocking Command POST:/v1.0/access-control/{device_id}/persons/{person_id}/actions/open

Resident Calling

API name API endpoint
Call Users POST:/v1.0/access-control/{device_id}/persons/actions/call

Bulk operations

API name API endpoint
Bulk Add Users POST:/v1.0/access-control/{device_id}/persons
Bulk Add QR Codes POST:/v1.0/access-control/{device_id}/persons/qrcodes
Bulk Delete Users DELETE:/v1.0/access-control/{device_id}/persons
Bulk Delete Faces DELETE:/v1.0/access-control/{device_id}/persons/faces
Bulk Add Faces POST:/v1.0/access-control/{device_id}/persons/faces
Bulk Delete QR Codes DELETE:/v1.0/access-control/{device_id}/persons/qrcodes

Management of access control devices

API name API endpoint
Clear Device Data POST:/v1.0/access-control/{device_id}/actions/cleardata
Sync Device Time POST:/v1.0/access-control/{device_id}/actions/synctime

Access control event format

After you subscribe to the message service for a cloud development project, you will receive event messages from the associated access control devices.

For more information about the integration with a message queue, see Message Queue.

Report pass records

API description

When an access control event is triggered, the access control device will report this event. The event code is event_pass, and the event code of some legacy devices is pass_event.

Description of value

Parameter Type Description Required
uid String The ID of a specified user. 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
  • 6: infrared sensor
  • 8: Bluetooth
  • 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
passUrl String The temporary URL of a photo taken by the device when a person passes. This photo is taken by the device when a person passes. This photo can be downloaded through the URL. No
passPwd String The passing password, which is reported to the cloud in password mode. No
cardNo String The card number. No
temp String The body temperature. No
passType Integer The type of access control. Valid values:
  • 1: enter
  • 2: exit
No
location String The location information. No

Example

{
    "dataId": "AAXRV4BrtW9BRB9A2JY****",
    "devId": "6cac703763f7653deb****",
    "productKey": "iyktmr3hd2qp****",
    "status": [
        {
            "126": "{\"message\":\"ok\",\"success\":1,\"t\":1637548630452,\"uid\":\"hhz\",\"way\":1}",
            "code": "event_pass",
            "t": 1637548630455,
            "value": "{\"message\":\"ok\",\"success\":1,\"t\":1637548630452,\"uid\":\"hhz\",\"way\":1}"
        }
    ]
}

Report video call events

API description

This event is triggered when a person enters a room number on a video access control device to call a resident or when a person hangs up. After this event is received, call the Call Users API operation to send a notification to the resident’s app.

Parameters

Parameter Type Description Required
bizCode String The business code of a specified event. The value is doorCall here. Yes
devId String The ID of a Tuya device. Yes
productKey String The product ID. Yes
ts Long The 13-digit timestamp. Yes
bizData Object The business data. Yes

Description of bizData

Parameter Type Description Required
deviceId String The ID of a Tuya device. Yes
type Integer The operation type. See the subsequent descriptions. Yes
sn String The serial number. It is unique in the same video call process. Yes
targetAddress String The room number that is called. For example, 01-01-01-01-01-01 means Room 01, Floor 01, Unit 01, Building 01, Block 01, Community 01. If one level is empty, enter 00. For example, if there is no block, the value of the block field is 00.
The digits of the room number are related to the device location. If a device is installed on the unit door, only the floor number and room number are required.
Yes
happenTime Long The 13-digit timestamp. No

Description of operation types

Operation type Scene Operation
1 The device calls the resident. The device sends an event of type 1.
2 The device calls the resident and then hangs up the call. The device sends an event of type 3. If the call is answered on the app, the call start time and end time have values.
3 The device calls the resident. The call is not answered within the timeout period, and the device hangs up. The default calling timeout period is 30s. The device sends an event of type 4.
4 The device calls the resident. The resident answers the call and hangs up. The device sends an event of type 5. The call start time and end time have values.
5 The device calls the resident. The call is answered, the talk time exceeds the timeout period, and then the device hangs up. The default talk timeout period is 90s. The device sends an event of type 7. The talk start time and end time have values.

Example

{
    "bizCode": "doorCall",
    "bizData": {
        "happenTime": 1612514362591,
        "targetAddress": "00-00-00-00-01-01",
        "sn": "121258194744908****",
        "type": 4
    },
    "devId": "6ce23ee0de009667c0****",
    "productKey": "hipg3mmwafxc****",
    "ts": 1637292665405
}

Report access control alerts

API description

An access control device proactively reports an alert event to the user. The event code is alarm_info_report.

Description of value

Parameter Type Description Required
alarmId String The serial number of a specified alert. Yes
alarmType Integer The type of a specified alert. Valid values:
  • 1: tamper alarm.
  • 2: stranger alarm.
  • 3: trailing.
  • 4: loitering.
  • 5: anti-passback.
  • 10: others.
Yes
alarmCont String The content of a specified alert. Yes
picUrl String The URL of a specified picture. No
happenTime Long The time when an alert is sent. Yes
confirmEnable Boolean Indicates whether the alert has been processed. Valid values:
  • true: already processed.
  • false: not processed yet.
No
extendData String The extension data in JSON format. No

Description of extendData

Parameter Type Description Required
taggerType Integer The type of a specified trailer, a second person following the first one who has passed through the gate. This field is required when alarmType is 3, indicating the alert type is trailing. Valid values:
  • 1: family member.
  • 2: stranger.
No

Example

{
    "dataId": "AAXRV4BrtW9BRB9A2JYW****",
    "devId": "6cac703763f7653deb****",
    "productKey": "iyktmr3hd2qp****",
    "status": [
        {
            "126": "{\"alarmName\": \"Device exception\",\"happenTime\": 1609435288373,\"alarmType\": 1,\"alarmCont\": \"Exception\",\"confirmEnable\": false,\"alarmId\": \"123123123123\",\"extendData\": \"\"}",
            "code": "alarm_info_report",
            "t": 1637548630455,
            "value": "{\"alarmName\": \"Device exception\",\"happenTime\": 1609435288373,\"alarmType\": 1,\"alarmCont\": \"Exception\",\"confirmEnable\": false,\"alarmId\": \"123123123123\",\"extendData\": \"\"}"
        }
    ]
}

Miscellaneous

Access 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 resident. You need to implement the process to send the QR code to the access control 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 user information.

Access 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 resident information to the device. Then, the device generates a dynamic QR code based on the dynamic key of the resident information.
  2. The device saves a static QR code, or generates a dynamic QR code based on the dynamic key of the resident.
  3. Generate a QR code on the app.
  4. The access control device scans the QR code. After the data matches, the user is identified and the passing event is reported.

Access QR code format

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 JSON format.

Sample:

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

Generate a dynamic QR code in the following steps.

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

Sample code of the generateTOTP method:

/**
   Generate a dynamic QR code
   *
   * @param uid     Tuya user ID
   * @param secretKey   The secret key, 32-digit string. It is recommended to be generated by the UUID.
   * @param refreshTime    The refresh time of the 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 time is less than 16 characters, pad it with zeros, such as 30B649C -> 00000000030B649C
      StringBuilder timeBuilder = new StringBuilder(time);
      while (timeBuilder.length() < 16) {
          timeBuilder.insert(0, "0");
      }
      time = timeBuilder.toString();

      // 2. Convert a hexadecimal value to a binary value
      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 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****
    Key: 46bff10b9bf843fab194cf246bfe****
    QR code refresh time: 5 × 60 × 1000
    QR code information generated by the `generateTOTP` method: e4af****
    Perform Base64 encoding of `ay16110581781387****|e4af****`.
    The resulting string is as follows:
    7kCzIejJVhfwYOGGJLr1iUUPRXP69AiNMGcMhowRSVA=
    QR code content is shown as follows:
    {
    "qrcode": "7kCzIejJVhfwYOGGJLr1iUUPRXP69AiNMGcMhowRSVA="
    }

Access 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 Integration with event format v1.0 of devices in public area.

Report access control records

API description

When an access control event is triggered, the access control device will report this event to you.

Parameters

Parameter name Data type Description Required
bizCode String The business code of a specified event. The value is edge_device here. 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: door_pass. Yes
deviceId String The ID of a specified Tuya device. Yes
way Integer The access control methods. Valid values:
  • 1: card
  • 2: password
  • 3: QR code
  • 4: face
  • 5: fingerprint
  • 9: remote control
  • 10: others
Yes
personId String The ID of a specified person that passes the access control device. Specify -1 for a stranger. Yes
passUrl 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
cardNo String The card number. No
temp String The body temperature. No
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
happenTime Long The 13-digit timestamp when a device goes online or offline. Yes

Example

{
	"data": "{\"mode\":\"door_pass\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\",\\\"happenTime\\\":1612514362591,\\\"message\\\":\\\"门禁通行\\\",\\\"passURL\\\":\\\"http://www.xxx.com/image.jpg\\\",\\\"personId\\\":\\\"ay16110581781387n472\\\",\\\"way\\\":4}\",\\\"success\\\":1}\"}",
	"bizCode": "edge_device",
	"eventType": "edge_report_data"
}

Report video call events

API description

This event is triggered when a person enters a room number on a video access control device to call a resident or when a person hangs up. After this event is received, request the Call Users API operation to send a notification to the resident’s app.

Parameters

Parameter name Data type Description Required
bizCode String The business code of a specified event. The value is edge_device here. 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: door_call. Yes
deviceId String The ID of a specified Tuya device. Yes
type Integer The operation type. See the subsequent descriptions. Yes
sn String The serial number. It is unique in the same video call process. Yes
targetAddress String The room number that is called. For example, 01-01-01-01-01-01 means Room 01, Floor 01, Unit 01, Building 01, Block 01, Community 01. If one level is empty, enter 00. For example, if there is no block, the value of the block field is 00.
The digits of the room number are related to the device location. If a device is installed on the unit door, only the floor number and room number are required.
Yes
beginTime Long The 13-digit timestamp when a video call starts. No
endTime Long The 13-digit timestamp when a video call ends. No
happenTime Long The 13-digit timestamp when an event occurs. Yes

Description of operation types

Operation type Scene Operation
1 The device calls the resident. The device sends an event of type 1.
2 The device calls the resident and then hangs up the call. The device sends an event of type 3. If the call is answered on the app, the call start time and end time have values.
3 The device calls the resident. The call is not answered within the timeout period, and the device hangs up. The default calling timeout period is 30s. The device sends an event of type 4.
4 The device calls the resident. The resident answers the call and hangs up. The device sends an event of type 5. The call start time and end time have values.
5 The device calls the resident. The call is answered, but the talk time exceeds the timeout period, so the device hangs up. The default talk timeout period is 90s. The device sends an event of type 7. The talk start time and end time have values.

Example

{
	"data": "{\"mode\":\"door_call\",\"data\":\"{\\\"deviceId\\\":\\\"002dj00118fe34d9****\\\",\\\"beginTime\\\":1612514362591,\\\"endTime\\\":1612514362591,\\\"targetAddress\\\":\\\"00-00-00-00-01-01\\\",\\\"sn\\\":\\\"1212581947449081856\\\",\\\"callType\\\":4}\"}",
	"bizCode": "edge_device",
	"eventType": "edge_report_data"
}

Report access control alerts

API description

An access control device proactively reports an alert event.

Parameters

Parameter name Data type Description Required
bizCode String The business code of a specified event. The value is edge_device here. 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: door_alarm. Yes
deviceId String The ID of a specified Tuya device. Yes
alarmId String The ID of a specified alert. Yes
alarmType Integer The alert type. Valid values:
  • 1: tamper alarm
  • 2: stranger alarm
  • 3: trailing
  • 4: loitering
  • 5: anti-passback
  • 10: others
Yes
alarmCont String The content of a specified alert. Yes
picUrl String The URL of a specified image. No
happenTime Long The time when an alert is sent. Yes
confirmEnable Boolean Specifies whether an alert is processed.
  • true: already processed.
  • false: to be processed.
No
extendData String The extension field in the JSON format. No

Description of extendData

Parameter name Data type Description Required
taggerType Integer The type of a specified trailer who follows another person to pass through the gate together. This field is required when the value of alarmType is 3, indicating the alert type is trailing. Valid values:
  • 1: family member
  • 2: stranger
No

Example

{
  "data": "{\"mode\":\"door_pass\",\"data\":\"{\\\"deviceId\\\":\\\"123123123\\\",\\\"alarmName\\\": \\\"Device exception\\\",\\\"happenTime\\\": 1609435288373,\\\"alarmType\\\": 1,\\\"alarmCont\\\": \\\"Exception\\\",\\\"confirmEnable\\\": false,\\\"alarmId\\\": \\\"123123123123\\\",\\\"extendData\\\": \\\"\\\"}\"}",
  "bizCode": "edge_device",
  "eventType": "edge_report_data"
}