Overview of Smart Access Control Service

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