Integration with Video Access Control Devices (Android)

Last Updated on : 2023-02-27 03:12:56download

This topic describes how to integrate Android video access control devices with the Tuya IoT Development Platform.

Terms

No. Term Description
1 cid The unique ID of a specified access control device.
2 sn The unique serial number of a specified data point (DP).
3 ATOP interface The HTTPS interface provided by Tuya.
4 Send Commands are sent from the cloud to devices through MQTT messages.
5 Report Device messages are reported to the cloud through the ATOP interface or MQTT messages.

Architecture

Integration with Video Access Control Devices (Android)

​This topic only supports integration with access control devices that have built-in Tuya IPC SDK.

Business process

Integration with Video Access Control Devices (Android)

List of data points

No. Data point Description
1 Device pairing Devices must be paired before they can receive commands from the cloud and interact with the cloud.
2 Video call Initiate, receive, and hang up calls.
3 Manage persons Add, update, remove, enable, and disable persons.
4 Manage face data Add, update, and remove face data.
5 Manage access control cards Add, update, and remove access control cards.
6 Manage QR codes Add, update, and remove QR codes.
7 Manage remote unlocking Use an app to send unlocking commands to an access control device. Then, the device unlocks a door and reports the access control record.
8 Report events The access control device recognizes people who pass by and reports their access control records.
9 Grade face images The server grades the captured face images. This feature is used only for check-in at hotels.
10 Dynamically refresh the QR code for persons’ access control In addition to the access control QR code from the cloud, a dynamically refreshable access control QR code is also supported.
11 Manage access control passwords Add, update, and remove access control passwords.

Integration process

Configure dependencies

  implementation 'com.squareup.okhttp3:okhttp:3.14.0'
  implementation 'org.apache.commons:commons-lang3:3.3.2'

Download Jizhi Community app

Download the Jizhi Community app in an app store to establish audio and video calls with the access control device through the app.

Integrate third-party device with Tuya Edge IPC SDK

For more information about integration, see the following documents:

Get the Tuya Edge Access Control SDK and demo.

Perform pairing and initialization

Request a private key

Request a private key from Tuya to decrypt pairing information.

Scan the QR code on the device

  1. Request a test account in the Tuya Community System. Note that only the Chinese version is available currently.

  2. The device scans the QR code on the construction app to pair the device. The QR code includes content in the following format:

    {
        "t":"AYRfQ***",
        "a":"a1-cn***",
        "key":"1168***"
    }
    

    The QR code will expire 10 minutes after it is generated.

  3. The device calls API operations by using a, key, and cid to get and decrypt the QR code content. The decrypted result is converted into qrcodeMap.

    // Queries pairing information.
    NetQrcodeVO netQrcodeVO = AtopFacade.getInstance().queryQrcodeInfo(a, key, cid);
    // Decrypts pairing information.
    String qrcodeInfo = AESUtils.decrypt(netQrcodeVO.getData(), secret);
    
    // Creates qrcodeMap.
    Map<String, String> qrcodeMap = JSON.parseObject(qrcodeInfo, new TypeReference<HashMap<String, String>>() {});
    qrcodeMap.put(QrcodeEnum.TOKEN.getCode(), t);
    

Initialize the SDK

    /**
     * Scans the QR code for pairing and restarts the device
     *
     * @param ctx                     The system context.
     * @param cid                     The third-party device ID. This is a unique value for each device.
     * @param qrcodeMap              The map of the QR code information.
     * @param basePath                The writable path that stores SDK configurations. The app storage directory is recommended.
     * @param recordPath              The writable path that stores video footage. The SD card is recommended.
     * @param properties              The settings of the implementation class.
     * @param paramConfigCallBack     The callback of audio and video parameters.
     */
    public void initSDK(Context ctx, String cid, Map<String,String> qrcodeMap,
          String basePath, String recordPath, Properties properties,
          MediaParamConfigCallback paramConfigCallBack)

​For more information about the key of qrcodeMap, see the code of QrcodeEnum. t, pId, uuid, and authKey must be written to the system after pairing. This way, after the device is restarted, powered off, or restored to factory default settings, it can automatically reconnect to the Tuya IoT Cloud.

Check whether the device is paired successfully:

 SharedPreferences sp = ctx.getSharedPreferences("edge_config",Context.MODE_PRIVATE);
 boolean isBind = sp.getBoolean("bind_status",false);

If the value of isBind is true, the device is paired successfully.

Initialize the implementation class of access control APIs

The following example shows the key of properties. value is implemented by the third party in the APIs. The implementation class can be called only after initialization.

    Properties properties = new Properties();
    // Implement a video talk event
    properties.put("dc_talk", "com.tuya.ai.ipcsdkdemo.edge.TalkReceiveEventImpl");
    // Implement a remote unlocking event
    properties.put("dc_door", "com.tuya.ai.ipcsdkdemo.edge.DoorReceiveEventImpl");
    // Implement a person's event
    properties.put("dc_userInfo", "com.tuya.ai.ipcsdkdemo.edge.TenementReceiveEventImpl");
    // Implement a face recognition event
    properties.put("dc_faceInfo", "com.tuya.ai.ipcsdkdemo.edge.TenementReceiveEventImpl");
    // Implement a card event
    properties.put("dn_cardInfo","com.tuya.ai.ipcsdkdemo.edge.CardReceiveEventImpl");
    // Implement a QR code event
    properties.put("dc_qrCodeInfo","com.tuya.ai.ipcsdkdemo.edge.QrCodeReceiveEventImpl");
    // Implement an access control event with passwords
    properties.put("dc_passPwd","com.tuya.ai.ipcsdkdemo.edge.PassPwdReceiveEventImpl");
    // Implement a data clearing event
    properties.put("dc_dataClear", "com.tuya.ai.ipcsdkdemo.edge.DataClearEventImpl");
    // Implement a time sync event
    properties.put("dc_timeSync", "com.tuya.ai.ipcsdkdemo.edge.TimeSyncEventImpl");

Implement features with APIs

The IPC SDK has encapsulated the commands sent by the cloud into APIs. A third party only needs to implement specific APIs. For more information about the APIs, see the list of APIs.

API description

Video call

// Starts, answers, or hangs up a video call.
AtopFacade.getInstance().sendControlProtocol(controlProtocolRequest);

Call method

Interface Method
AtopFacade sendControlProtocol

Request parameter

Parameter Type Description Required
controlProtocolRequest ControlProtocolRequest The request object. Yes

Description of ControlProtocolRequest

Parameter Type Description Required
SN String The serial number. This parameter is required in all modes except calling. The value must be the serial number returned in a calling session. No
mode String The device mode, such as ac_doorbell for a doorbell. Yes
type String The operation type. See the subsequent descriptions. Yes
deviceId String The device ID. Yes
targetAddress String The destination address. 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. Yes
extend String After a call is answered and then hanged up, a JSON string is returned, such as {"beginTime":1592373736,"endTime":1593373736}.
  • beginTime: the time when a call is answered.
  • endTime: the time when a call is ended. The time type is Long.
No

Response parameter

Type Description
String The serial number.

Description of operation types

Operation type Scene Operation
1 The device calls the app and indoor monitor. The device sends an event of type 1.
3 The device calls the app and indoor monitor and then hangs up. The app and indoor monitor do not operate. The device sends an event of type 3. If the call is answered on the app, the extend parameter is required.
4 The device calls the app and indoor monitor. The call is not answered within the timeout period, and the device hangs up. The default timeout period of calling is 30s. The device sends an event of type 4.
5 The device calls the app and indoor monitor. The app or indoor monitor answers and then hangs up. The SDK will send a callback event to the device. The device sends an event of type 5. The extend parameter is required.
6 The device calls the app and indoor monitor. The app or indoor monitor answers. The SDK will send a callback event to the device. The device sends an event of type 6.
7 The device calls the app and indoor monitor. The call is answered, the conversation time exceeds the timeout period, and then the device hangs up. The default conversation timeout period is 90s. The device sends an event of type 7. The extend parameter is required.

Report pass records

// Reports access control events
MqttEventSupport.getInstance().publishThirdEvent(thirdEventRequest);

Call method

Interface Method
AtopFacade publishThirdEvent

Request parameter

Parameter Type Description Required
thirdEventRequest ThirdEventRequest The request object. Yes

Description of ThirdEventRequest

Parameter Type Description Required
UID String The user ID. Yes
operTime String Event occurrence time Yes
way int The unlocking method. Valid values:
  • 1: card
  • 2: password
  • 3: QR code
  • 4: face
  • 5: fingerprint
  • 6: infrared sensor
  • 8: Bluetooth
  • 9: remote control
  • 10: others
Yes
imageId String The ID of a specified image file. See how to get the image ID. No
passPwd String The access control password. It is required 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
isSuccess boolean Specifies whether the operation is successful.
  • true: succeeded.
  • false: failed.
Yes
message String The error message, indicating the error cause. No

Response parameter

Type Description
boolean
  • true: The call is successful.
  • false: The call failed.

Report access control alerts

// Reports access control alert events
MqttEventSupport.getInstance().publishDoorAlarmEvent(thirdDoorAlarmRequest);

Call method

Port Method
MqttEventSupport publishDoorAlarmEvent

Request parameter

Parameter Type Description Required
thirdDoorAlarmRequest ThirdDoorAlarmRequest The request object. Yes

Description of ThirdDoorAlarmRequest

Parameter Type Description Required
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 alert value. Yes
imageId String The ID of a specified image file. See how to get the image ID. No
happenTime Long The time when an alert was sent. Yes
confirmEnable Boolean The processing status of a specified alert. Valid values:
  • true: already processed.
  • false: to be processed.
No
extendData String The extension field in the 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

Response parameter

Type Description
boolean Specifies whether the operation is successful. Valid values:
  • true: success.
  • false: failure.

Upload image

Upload images in .jpg format by default
String fileId = AtopFacade.getInstance().uploadImageFile(fileBytes);

Call method

Interface Method
AtopFacade uploadImageFile

Request parameter

Parameter Type Description Required
fileBytes byte[] The byte array of a specified image file. Yes

Response parameter

Type Description
String The ID of a specified image file.

Grade face images

Evaluate the face images captured by the access control device, and return the grades. If a face image is confirmed to be qualified, it will be sent to other access control devices.

// Grades the face images
FaceScoreVO faceScoreVO = AtopFacade.getInstance().evaluateFaceQuality(fileId);

Call method

Interface Method
AtopFacade evaluateFaceQuality

Request parameter

Parameter Type Description Required
fileID String The ID of a specified image file. Yes

Response parameter

Type Description
FaceScoreVO The result object of grading a face image.

Description of FaceScoreVO

Parameter Type Description Required
value Double Valid values: 0 to 10. The recognition is successful if the grade is above 8. Yes
url String The URL of the face image. Yes

Verify a person’s access permission

Perform the following steps to verify a person’s access permission.

  1. The person needs to pass validation by access control card, face, or QR code.
  2. In case of failure, the access will be denied.
  3. If the validation is successful, request the interface to verify the person’s access permission. That is, verify the health code to get the health code status.
  4. If the health code is yellow or red, the access will be denied. If the health code is green or does not exist, the access is allowed.
// Verifies the health code
HealthCodeVO healthCodeVO = AtopFacade.getInstance().checkHealthCode(UID, deviceId, verifyTypeList);

Call method

Interface Method
AtopFacade checkHealthCode

Request parameter

Parameter Type Description Required
UID String The user ID. Yes
deviceID String The device ID. Yes
verifyTypeList List<Integer> The list of validation types.
  • 1: health code
Yes

Response parameter

Type Description
HealthCodeVO The result object of verifying the health code.

Description of HealthCodeVO

Parameter Type Description Required
UID String The user ID. Yes
extend String A JSON string like {\"healthCode\":\"unknown\"}. Yes

Description of extend

Validation type extend Description
1 Returns the healthCode field
  • unknown: The health code is unknown, with an internal exception or with no health code.
  • red: The health code is red.
  • green: The health code is green.
  • yellow: The health code is yellow.

APIs to be implemented by the third party

Add person

This interface supports idempotence. After a person with a specified UID is added, this person with the same UID can be added again successfully.

Call method

Interface Method
TenementReceiveEvent addTenement

Request parameter

Parameter Type Description Required
tenementRequest TenementRequest The request object. Yes
eventContext EventContext The context session. Yes

Description of EventContext

Parameter Type Description Required
gatewayId String The ID of a specified Tuya IoT edge gateway. Yes
deviceId String The device ID. Yes
deviceName String The name of a specified Tuya device. No
cid String The ID of a specified third-party device. Yes
commType String The type of device connection. Valid values: MQTT and HTTP. No
deviceIp String The IP address of a specified device. No
macAddress String The MAC address of a specified device. No
productType String The product category. No
productId String The product ID. Yes
installLocation String The location where a device is intalled. No
deviceDesc String The description of a specified device. No
activeStatus String The status of a specified device. Valid values:
  • 0: The device is not paired.
  • 1: The device is paired.
Yes
extendData String The extension field in the JSON format. No

Description of TenementRequest

Parameter Type Description Required
uid String Tuya user ID. Yes
name String The username. No
idCard String The identity card ID of the user. No
phone String The mobile phone number. No
beginTime Long The 13-digit timestamp when a validity period starts. No
endTime Long The 13-digit timestamp when a validity period ends. No
timeRuleList List<TimeRuleInfo> The list of time rules. No
userFloor Integer The floor where a person is located. It is used when the elevator is called from the edge gateway. This feature must be supported by the device. 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. No
refreshTime Long The time when a QR code is refreshed. Default value: 5 minutes. Unit: milliseconds. No
extend String The extension field in the JSON format. No

Description of TimeRuleInfo

Parameter Type Description Required
ruleId String The ID of a specified rule. Yes
ruleName String The name of a specified rule. No
period String The allowed period in the format of a JSON string. For example, [{“weekDay”:1,“weekTime”:[{“start”:“32400000”,“end”:“64800000”}]},{“weekDay”:2,“weekTime”:[{“start”:“68400000”,“end”:“75600000”}]}]. No
allowedDate String The allowed date in the format of a JSON string. For example, [{“start”:“1571587200000”,“end”:“1864569600000”},{“start”:“1573022801885”,“end”:“1864569600000”}]. No
deniedDate String The denied date in the format of a JSON string. For example, [{“start”:“1571587200000”,“end”:“1864569600000”},{“start”:“1573022801885”,“end”:“1864569600000”}]. No

If beginTime and endTime are not empty, the person’s validity period is the same as beginTime and endTime. Otherwise, timeRuleList will prevail. The value of timeRuleList supports up to 3 entries.

Description of time rules:

  • period: allowed period. You can specify which periods of the week are allowed.

  • weekDay: use 1 to 7 to represent Monday to Sunday respectively. The start time and end time are represented by the number of milliseconds from 0 o’clock. For example, 32400000 means 9 o’clock. For example, [{"weekDay":1,"weekTime":[{"start":"32400000","end":"64800000"}]},{"weekDay":2,"weekTime":[{"start":"684000000","end":"75600000"}]}] means that the access is allowed from 9:00 to 18:00 on Monday and from 19:00 to 21:00 on Tuesday.

  • allowedDate: The 13-digit timestamp of the time when the access is allowed.

  • deniedDate: The 13-digit timestamp of the time when the access is denied.

  • Time priority: denied date > allowed date > allowed period.
    First, check whether the visit time is in the denied date. If yes, access will be denied. If not, check whether the visit time is in the allowed date. If yes, access is allowed. If not, continue to check whether it is in the allowed period. If yes, access is allowed. Otherwise, the access is denied. To determine time rules, you can refer to or use the utility class com.tuya.edge.utils.RuleCheckUtils.

Response parameter

Type Description
BaseResult The returned result.

Description of BaseResult

Parameter Type Description Required
success boolean The returned result. Valid values:
  • true: success.
  • false: failure.
Yes
code String The returned code. No
msg String The returned message. Yes
data Object The returned data. No

Update person

Call method

Interface Method
TenementReceiveEvent modifyTenement

Request parameter

Parameter Type Description Required
tenementRequest TenementRequest The request object. See details. Yes
eventContext EventContext The context session. See details. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Delete person

Call method

Interface Method
TenementReceiveEvent removeTenement

Request parameter

Parameter Type Description Required
removeTenementRequest RemoveTenementRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of RemoveTenementRequest

Parameter Type Description Required
uid String Tuya user ID. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Verify access permission

Call method

Interface Method
TenementReceiveEvent enableTenement

Request parameter

Parameter Type Description Required
enableTenementRequest EnableTenementRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of EnableTenementRequest

Parameter Type Description Required
uid String Tuya user ID. Yes
enable Integer Specifies whether to enable the access permission. Valid values:
  • 0: disable.
  • 1: enable.
The added person’s access permission is enabled by default. If the permission is disabled, the person cannot pass based on the face, QR code, or access card.
Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Add Face

This interface supports idempotence. After a face image with a specified faceId is added, the face image with the same faceId can be added again and a success response is returned.

Call method

Interface Method
FaceImageReceiveEvent addFaceImage

Request parameter

Parameter Type Description Required
faceImageRequest FaceImageRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of FaceImageRequest

Parameter Type Description Required
uid String Tuya user ID. Yes
faceId String The face ID. Yes
url String The URL of the face image. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Update Face Information

Call method

Interface Method
FaceImageReceiveEvent modifyFaceImage

Request parameter

Parameter Type Description Required
faceImageRequest FaceImageRequest The request object. See details. Yes
eventContext EventContext The context session. See details. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Delete face

Call method

Interface Method
FaceImageReceiveEvent removeFaceImage

Request parameter

Parameter Type Description Required
removeFaceImageRequest RemoveFaceImageRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of RemoveFaceImageRequest

Parameter Type Description Required
uid String Tuya user ID. Yes
faceId String The face ID. No

Response parameter

Type Description
BaseResult The returned result. See details.

Add Card

Call method

Interface Method
CardReceiveEvent addCard

Request parameter

Parameter Type Description Required
cardRequest CardRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of CardRequest

Parameter Type Description Required
uid String Tuya user ID. Yes
cardNo String The access card number. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

This interface supports idempotence. After a card with a specified cardNo is added, the card with the same cardNo can be added again and a success response is returned. Each user can have only one access control card. If another card is added to the same user, a failure result will be returned.

Update Card

Each user can have only one access control card. A user’s previous card must be cleared before the card is updated.

Call method

Interface Method
CardReceiveEvent modifyCard

Request parameter

Parameter Type Description Required
cardRequest CardRequest The request object. See details. Yes
eventContext EventContext The context session. See details. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Delete card

Call method

Interface Method
CardReceiveEvent removeCard

Request parameter

Parameter Type Description Required
removeCardRequest RemoveCardRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of RemoveCardRequest

Parameter Type Description Required
uid String Tuya user ID. Yes
cardNo String The number of the card to be deleted. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Enable/disable card

Call method

Interface Method
CardReceiveEvent enableCard

Request parameter

Parameter Type Description Required
enableCardRequest EnableCardRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of EnableCardRequest

Parameter Type Description Required
uid String Tuya user ID. Yes
enable Integer Specifies whether to enable the access permission. Valid values:
  • 0: disable.
  • 1: enable.
Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Add QR Code

This interface supports idempotence. After a specified qrCode is added, the same qrCode can be added again. Each user can have only one QR code. If a second QR code is added to the same user, a failure result will be returned.

Call method

Interface Method
QcCodeReceiveEvent addQcCode

Request parameter

Parameter Type Description Required
qrCodeRequest QrCodeRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of QrCodeRequest

Parameter Type Description Required
uid String Tuya user ID. Yes
qrCode String The QR code. It is valid within the person’s validity period. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Update QR Code

Each user can have only one QR code. The user’s previous QR code must be cleared before the QR code is updated.

Call method

Interface Method
QcCodeReceiveEvent modifyQcCode

Request parameter

Parameter Type Description Required
qrCodeRequest QrCodeRequest The request object. See details. Yes
eventContext EventContext The context session. See details. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Delete QR code

Call method

Interface Method
QcCodeReceiveEvent removeQcCode

Request parameter

Parameter Type Description Required
removeQrCodeRequest RemoveQrCodeRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of RemoveQrCodeRequest

Parameter Type Description Required
uid String Tuya user ID. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Manage remote unlocking

Remote unlocking does not verify the person’s permission. A door is opened as long as the device receives the specified remote unlocking request.

Call method

Interface Method
DoorReceiveEvent openDoor

Request parameter

Parameter Type Description Required
doorRequest DoorRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of DoorRequest

Parameter Type Description Required
uid String Tuya user ID. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Clear device data

Clear device data with one click, such as person, face, card, and password. It is used when a device is initialized or returned to the factory for repair.

Call method

Port Method
DataClearEvent clearData

Request parameter

Parameter Type Description Required
doorDataClearRequest DoorDataClearRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of DoorDataClearRequest

Parameter Type Description Required
all Boolean Specifies whether to clear all the data. No
person Boolean Specifies whether to clear the data of all persons. No
face Boolean Specifies whether to clear the data of all faces. No
card Boolean Specifies whether to clear the data of all card numbers. No
qrcode Boolean Specifies whether to clear the data of all QR codes. No
passPwd Boolean Specifies whether to clear the data of all access control passwords. No
other Boolean Specifies whether to clear other data. No

Response parameter

Type Description
BaseResult The returned result. See details.

Synchronize device time

The cloud service sends the time to a specified device, so the device time is synchronized with the time in the cloud.

Call method

Port Method
TimeSyncEvent syncTime

Request parameter

Parameter Type Description Required
doorTimeSyncRequest DoorTimeSyncRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of DoorTimeSyncRequest

Parameter Type Description Required
timestamp Long The timestamp. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Enable/disable access control device

  1. If the device feature is disabled, features such as card, password, QR code, face, fingerprint, and remote unlocking will not be available.

  2. If the device feature is enabled, features such as card, password, QR code, face, fingerprint, and remote unlocking will be available.

Call method

Interface Method
CustomReceiveEvent receiveCustomInfo

Request parameter

Parameter Type Description Required
customRequest CustomRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of CustomRequest

Parameter Type Description Required
sn String The serial number and unique identifier of a specified request. Yes
bizType String The business type. Default value: maintain. Yes
operateType String The operation type. Default value: enable_disable_device. Yes
extendData String A JSON string, such as {"value" :1}. Valid values:
  • 1: enable.
  • 0: disable.
Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Add Password

Each user supports multiple passwords, and different users can be assigned the same password.
This interface supports idempotence. A successful result will be returned if a user is assigned the same password again.

Call method

Interface Method
PassPwdReceiveEvent addPassPwd

Request parameter

Parameter Type Description Required
passPwdRequest PassPwdRequest The request object. Yes
eventContext EventContext The context session. See details. Yes

Description of PassPwdRequest

Parameter Type Description Required
uid String Tuya user ID. Yes
passPwd String The access control password. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Update password

Modify the user’s password. If the specified old password (oldPassPwd) does not exist under the user, a failure result will be returned.

Call method

Interface Method
PassPwdReceiveEvent modifyPassPwd

Request parameter

Parameter Type Description Required
passPwdRequest PassPwdRequest The request object. See details. Yes
eventContext EventContext The context session. See details. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Delete password

Delete the user’s password. If the specified password to be deleted (passPwd) does not exist under the user, a failure result will be returned.

Call method

Interface Method
PassPwdReceiveEvent removePassPwd

Request parameter

Parameter Type Description Required
passPwdRequest PassPwdRequest The request object. See details. Yes
eventContext EventContext The context session. See details. Yes

Response parameter

Type Description
BaseResult The returned result. See details.

Hang up Video Call

Send a command of hanging up to a specified video access control device. After receiving the command, the device stops video streaming.

Call method

Port Method
CallRefuseEvent callRefuse

Request parameter

Parameter Type Description Required
callRefuseRequest CallRefuseRequest The request object. Yes
eventContext EventContext The context session. See Parameters. Yes

Description of QrCodeRequest

Parameter Type Description Required
type Integer The type of hanging up the video call.
1: The app rejects and hangs up all calls.
Yes
mes String The reason for hanging up a video call. No

Response parameter

Type Description
BaseResult The returned result. See Parameters.

Others

QR code recognition

The device must support the QR codes in two formats:

  • v1.0 QR code:
7421371370865597349888943036
  • v2.0 QR code:
{
  "qrcode": "YXkxNjExMDU4MTc4MTM4N240Mjd8ZTRhZjIzZTY=" //value: Base64 encoded string
}

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.

  2. If it is a v1.0 QR code, compare it with the person’s QR code. If the comparison is successful, the person is allowed to pass.

  3. If it is a v2.0 QR code, first decode the content through the Base64 method, and parse the QR code information.

  4. Compare and verify the static QR code, and compare the QR code information with the person’s QR code. If the comparison is successful, the person is allowed to pass.

  5. If the comparison fails, verify it through the dynamic QR code verification interface. If the verification is successful, the access will be allowed. Otherwise, the access will be denied.

The interface to verify dynamic QR code:

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 the 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=" //value: Base64 encoded string
}

YXkxNjExMDU4MTc4MTM4N240Mjd8ZTRhZjIzZTY= Get a string after Base64 decoding
"ay16110581781387***|e4af***"

User ID: ay16110581781387***
QR code information: e4af***

1. Get a static QR code based on the user ID for comparison.
2. If the comparison fails, perform dynamic QR code verification.
   QR code refresh time: 5 × 60 × 1000
3. Query the user's secretKey based on the user ID.
4. Then, call the dynamic QR code verification interface `TOTPUtils.verifyTOTPFlexibility`.
  If `true` is returned, the verification is passed.

Access control card recognition

The access control device must support reading access control cards. The person’s card number is stored in the seventh sector of the card. After the device reads the card number from the seventh sector, it is compared with the person’s access control card in the device. If the comparison is successful, the card is recognized.