Integration with Video Access Control Devices (Android)

This topic describes how to integrate Android video access control devices with the Tuya Developer 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

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

Business process

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