MQTT Protocol Documentation（DejaOS Version）

# MQTT Protocol Documentation

## I. Overview

This document provides a set of standard interfaces applicable to face recognition devices for pushing and retrieving device information. After purchasing the device, users can directly develop a complete access control or related application system based on the interface specifications. The interface uses the MQTT communication protocol, which can interface with various generic MQTT brokers, or use the MQTT broker recommended by us.

**Document Version: V2**

#### Application Scenarios

When you need to interface with your own business system, you can communicate directly with the device via the MQTT protocol using these interfaces.

#### Interface Specification

The interface uses the MQTT protocol and is divided into Upstream and Downstream:

**Upstream (Uplink):** Refers to messages sent by the device to the backend or application.

**Downstream (Downlink):** Refers to messages sent by the backend or application to the device.

Communication is mediated through an MQTT broker. Messages contain a message topic and message content, formatted as follows:

1. **Message Topic**

> Message Title. Regardless of whether it is upstream or downstream, the rule for sending commands and returning commands is "Command" and "Command_reply". The format is as follows:

- **Downstream:** `access_device/v2/cmd/{#device_sn}/xxxx`, corresponding return command (Upstream): `access_device/v2/cmd/xxxx_reply`
- **Upstream:** `access_device/v2/event/yyyy`, corresponding return command (Downstream): `access_device/v2/event/{#device_sn}/yyyy_reply`

Note: `access_device/v2` is the specific identifier for the interface version. `cmd` indicates a command actively sent by the backend or application to the device, and `event` indicates a message or event actively sent by the device to the backend or application.

1. **Message Content**

Text format message content, the content is in JSON format.

a) Sending Message

```
{   
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time":1647580466, 
    "sign":"e0k4jrir85tje8ru4jrur499r99ii4ur",
       "data": {
        ...
    }
}
```

b) Return Message

```
{   
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time":1647580466, 
    "sign":"e0k4jrir85tje8ru4jrur499r99ii4ur",
       "data": {
        ...
    },
    "message": ""
}
```

| Parameter | Description       | Type   | Required | Remarks                                                      |
| --------- | ----------------- | ------ | -------- | ------------------------------------------------------------ |
| serialNo  | Serial Number     | string | Yes      | The backend or application must pass a unique serial number (max 32 chars) when sending a message to the device. The device will use the same serial number when reporting results. And vice versa. |
| uuid      | Device Unique ID  | string | Yes      | A string longer than 8 characters.                           |
| data      | Message Body      | object | Yes      | In JSON format. The format varies for different types of messages. The interface list mainly details this part of the data format. |
| time      | Timestamp         | long   | Yes      | 10-digit timestamp, unit: seconds.                           |
| sign      | Message Signature | string | No       | If signature is enabled, this value must be present to verify data legitimacy. Please refer to Appendix - [Signature Algorithm]. |
| code      | Result Code       | string | No       | The returned data must contain a `code`. Different codes indicate different result statuses. Please refer to: [Appendix Table 1 Code Overview](https://www.google.com/search?q=%23appendix-table-1-code-overview). |

**Note:** Every item in the message content should be named starting with a lowercase letter, followed by a combination of uppercase and lowercase letters (camelCase).

## II. Device Management and Event Interfaces

#### 2.1 Configuration Query

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/getConfig |
| ------------- | --------------------------------------------- |
|               |                                               |

Sending `data` message parameter description:

| Parameter | Type  | Required | Additional Description                                       |
| --------- | ----- | -------- | ------------------------------------------------------------ |
| data      | array | Y        | Query configuration related information, see the Object Name in [Configuration Parameter Description](https://www.google.com/search?q=%23config) |

Message sending example:

```
// Get all configurations
{
    "serialNo": "6w8keif5g6",
    "uuid": "e4720000964b5c00",
    "time": 1647580466,
    "data": "",
    "sign": ""
}

// Get a single configuration
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 1647580466,
	"data":"sysinfo",
	"sign": ""
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/getConfig_reply |
| ------------- | ------------------------------------------- |
|               |                                             |

`data` message parameter:

| Parameter | Description | Type   | Required | Additional Description |
| --------- | ----------- | ------ | -------- | ---------------------- |
| data      | Config Data | Object | Y        | See example            |

Return example:

```
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"code": "000000",
    "time": 1701061767,
    "sign": "",
	"message": "success",
	"data": {
		"nfc": {
			"nfcEn": 1,
			"nfcFt": 0,
			"nfcOrd": 0,
			"nfcAffixesFt": 1,
			"nfcPrefix": "",
			"nfcPostfix": "",
			"nfcCr": 0,
			"nfcNl": 0,
			"nfcReadIdNum": 0
		}
	}
}
```

#### 2.2 Configuration Modification

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/setConfig |
| ------------- | --------------------------------------------- |
|               |                                               |

`data` message parameter description:

| Parameter | Description | Type   | Required | Additional Description                                       |
| --------- | ----------- | ------ | -------- | ------------------------------------------------------------ |
| data      | Config Data | Object | N        | Configuration collection. Can be empty or omitted; in this case, the device will not make any configuration changes. |

<a id="config">Device Configuration Data Optional Parameters</a>

- Note: Configuration adopts a two-level grouping form. All field names use lower camelCase.

| Object Name | Field Name | Type | Meaning and Values |
| ----------- | ------------------------ | ------ | ------------------------------------------------------------ |
| | | | All configuration parameters are optional. Pass only the corresponding object and field required for configuration. |
| face | | | |
| | similarity | Int | Face recognition similarity (Default 0.5, Range 0-1) |
| | livenessOff | Int | Liveness detection: 1 On, 0 Off. Default On. |
| | livenessVal | Int | Liveness detection threshold (Default 5, Range 0-10) |
| | showNir | Int | Infrared frame: 1 On, 0 Off. Default Off. |
| | detectMask (Unused) | Int | Mask detection switch: 1 On, 0 Off. Default Off. |
| | stranger | Int | Unregistered face prompt: 0: "No voice", 1: "Please register first", 2: "Hello stranger". Default 1. |
| | voiceMode | Int | Voice after successful recognition: 0: "No voice", 1: "Play name", 2: "Play greeting". Default 1. |
| | voiceModeDate | String | Greeting content, default: "Welcome" |
| mqtt | | | |
| | addr | String | MQTT address (Format: mqtt://192.168.1.1:1883) |
| | clientId | String | MQTT Client Name |
| | username | String | MQTT Username |
| | password | String | MQTT Password |
| | qos | Int | QoS0: At most once; QoS1: At least once; QoS2: Exactly once. Default 1. |
| | prefix | String | MQTT Subscription Topic Prefix |
| | clientIdSuffix | String | Whether to add a three-digit random number to clientId, 1 Yes, 0 No. Default 0. |
| | onlinecheck | Int | Online verification switch: 1 Try offline first then failover to online verification, 0 Only offline. Default 0. |
| | timeout | Int | Online verification timeout, default 5000ms. |
| | willTopic | String | Will topic: Device automatically sends this on disconnect. Default `access_device/v2/event/offline`. |
| net | | | |
| | type | Int | 1: Ethernet, 2: WiFi, 4: 4G. Default Ethernet. |
| | ssid | String | Pass 2 for type: Device uses WiFi. ssid and pwd parameters must be passed and cannot be empty. |
| | psk | String | Pass 2 for type: Device uses WiFi. ssid and pwd parameters must be passed and cannot be empty. |
| | dhcp | int | dhcp=2: DHCP mode (Auto IP). No other params needed. dhcp=1: Custom network (Static IP). ip, gateway, subnetMask, DNS must be passed. Default 2. |
| | ip | String | E.g.: 192.168.1.123 |
| | gateway | String | E.g.: 192.168.1.1 |
| | mask | String | E.g.: 255.255.255.0 |
| | dns | String | E.g.: 114.114.114.114 |
| | mac | String | E.g.: D6:18:6C:CE:B4:60 |
| ntp | | | |
| | ntp | Int | 0 Fixed interval sync, 1 Scheduled sync. Default 1. |
| | server | String | NTP server IP. Default 182.92.12.11 |
| | hour | Int | Scheduled sync hour (24h format). Default 3. |
| | gmt | Int | Timezone (China is 8). Default 8. |
| access | | | |
| | offlineAccessNum | Int | Max storage for offline access records. Default 2000. |
| | relayTime | Int | Relay open duration (ms). Default 2000. |
| | fire | Int | Fire alarm switch. 1: On, 0: Off. Default Off. |
| | fireStatus | Int | Fire alarm status. 1: Warning, 0: Normal. Default Normal. |
| | tamper | Int | Tamper alarm switch. 1 On, 0 Off. Default Off. |
| base | | | |
| | language | String | Language: EN (English), CN (Chinese). Default CN. |
| | password | String | Backend entry password (Default: password). |
| | firstLogin | Int | First time login status: 0 Not logged in, 1 Logged in. Default 0. |
| | screenOff | Int | Screen off time (minutes), 0 Never. Default 0. |
| | screensaver | Int | Screensaver time (minutes), 0 Never. Default 0. |
| | brightness | Int | White fill light brightness: 0-100. Default 70. |
| | brightnessAuto (Pending) | Int | Auto brightness adjustment. 1 Auto. Default 1. |
| | volume | Int | Speaker volume: 0-10. Default 10. |
| | showIp | Int | Show IP: 1 Show, 0 Hide. Default 1. |
| | showSn | Int | Show SN: 1 Show, 0 Hide. Default 1. |
| | showProgramCode | Int | Show Mini-program Code: 1 Show, 0 Hide. Default 1. |
| | appMode | Int | 0: Standard Mode, 1: Simple Mode. Default 1. |
| | backlight | Int | Screen backlight: 0-100. Default 70. |
| sys | | | |
| | mac | String | MAC Address |
| | uuid | String | UUID |
| | sn | String | Device SN |
| | model | String | Device Model |
| | version | String | Version Number |
| | appVersion | String | Firmware Version |
| | releaseTime | String | Update Time |
| | heart_en | Int | Heartbeat: 1 On, 0 Off. Default 0. |
| | heart_time | Int | Heartbeat interval (seconds). Default 30. |
| | heart_topic | String | Heartbeat report topic. Default `access_device/v2/event/heartbeat`. |
| | heart_payload | String | Heartbeat content. |
| | nfc | Int | 1 On, 0 Off. Card swipe switch. Default On. |
| | pwd | Int | 1 On, 0 Off. Password opening switch. Default On. |
| | strangerImage | Int | 1 On, 0 Off. Save stranger images switch. Default On. |
| | accessImageType | Int | 1 Face, 0 Panorama. Access image type. Default Face. |
| | nfcIdentityCardEnable | Int | Cloud ID switch. 3: Cloud ID fetch, 1: Physical card ID. Default Physical card ID. |
| | devType | Int | 0: WiFi version, 1: 4G version, 2: Ethernet version, 3: Unread status. Default 3. |

Message sending example:

```
{
    "serialNo": "6w8keif5g6",
    "uuid": "e4720000964b5c00",
    "sign": "",
    "code": "000000",
    "data": {
        "net": {
            "gateway": "192.168.60.1",
            "mac": "ee:ed:00:00:5b:c1",
            "password": "",
            "ip": "192.168.63.171",
            "type": 1,
            "mask": "255.255.252.0",
            "dns": "218.4.4.4,218.2.2.2",
            "dhcp": 2,
            "ssid": ""
        },
        "base": {
            "showSn": 1,
            "screenOff": 0,
            "brightness": 100,
            "language": "CN",
            "showIp": 1,
            "screensaver": 0,
            "password": "123",
            "volume": 50,
            "brightnessAuto": 1
        },
        "sys": {
            "uuid": "e4720000964b5c00",
            "model": "vf205",
            "sn": "e45a00005bc17400",
            "status": 1,
            "appVersion": "",
            "version": "vf105_v11_access_2.0.0",
            "releaseTime": "2024-09-13 09:52:00"
        },
        "face": {
            "showNir": 1,
            "livenessVal": 0.6,
            "similarity": 0.6,
            "voiceMode": 1,
            "stranger": 1,
            "livenessOff": 1,
            "detectMask": 0
        },
        "ntp": {
            "interval": 1440,
            "server": "182.92.12.11",
            "gmt": 8,
            "ntp": 1
        },
        "mqtt": {
            "qos": 1,
            "onlinecheck": 0,
            "clientId": "e45a00005bc17400",
            "prefix": "",
            "username": "",
            "willTopic": "access_device/v2/event/offline",
            "addr": "192.168.62.110:1883",
            "password": ""
        },
        "passwordAccess": {
            "passwordAccess": 1
        },
        "access": {
            "offlineAccessNum": 2000,
            "relayTime": 2000,
            "tamperAlarm": 1
        }
    },
    "time": 1736755758
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/setConfig_reply |
| ------------- | ------------------------------------------- |
|               |                                             |

Message Parameter Description

| Parameter | Description | Type   | Required | Additional Description                       |
| --------- | ----------- | ------ | -------- | -------------------------------------------- |
| data      | Config Data | Object | Y        | Collection of returned configuration results |

Return example:

```
{

"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"code": "000000",
	"message": "success",
    "sign": "",
	"data": {
		"channel": {
			"enable": 1,
			"tcpAddr": "10.200.52.151",
			"tcpPort": 8060,
			"rs485Bps": "115200-8-N-1",
			"wg": 34
		},
		"qr": {
			"enable": 1,
			"preSufFt": 1,
			"prefix": "",
			"suffix": "",
			"qrCr": 0,
			"qrNl": 0,
			"qrFt": 0
		},
		"nfc": {
			"enable": 1,
			"nfcFt": 0,
			"nfcOrd": 0,
			"preSufFt": 1,
			"prefix": "",
			"suffix": "",
			"nfcCr": 0,
			"nfcNl": 0,
			"IdCard": 0
		},
		"customer": {
			"cusTag0": "1",
			"cusTag1": "0",
			"cusTag2": "cus_tag2",
			"cusTag3": "cus_tag3",
			"cusTag4": "cus_tag4"
		}
	}
}
```

#### 2.3 Device Upgrade

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/upgradeFirmware |
| ------------- | --------------------------------------------------- |
|               |                                                     |

`data` parameters

| Parameter | Description          | Type   | Required | Additional Description                                       |
| --------- | -------------------- | ------ | -------- | ------------------------------------------------------------ |
| type      | Upgrade Package Type | Int    | Yes      | Strict validation. 0: Local upgrade, 10: Resource upgrade (Not supported in current version) |
| url       | OTA Download URL     | String | Y        | The device accesses this URL. If accessible, download starts. If failed, returns "URL access failed, cannot download". Download does not guarantee correct file; verify on device UI for installation success. |
| md5       | Upgrade Package MD5  | string | Y        | Verify the upgrade package MD5                               |
| extra     | Extended Field       | Object | Y        |                                                              |

When `type=10`, `extra` field is mandatory. JSON supports the following fields:

| Parameter               | Description | Type   | Required | Remarks   |
| ----------------------- | ----------- | ------ | -------- | --------- |
| Background Image, Audio | Filename    | String | No       | File name |

Sending example:

```
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
	"data": {
        "type": 0,
		"url": "[http://10.102.106.165/aio.tar.xz](http://10.102.106.165/aio.tar.xz)",
		"md5": "521c2bdc835d4f13b5f9d6db164f0881"
	}
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/upgradeFirmware_reply |
| ------------- | ------------------------------------------------- |
|               |                                                   |

Return example:

```
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 2.4 Remote Control

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/control |
| ------------- | ------------------------------------------- |
|               |                                             |

`data` parameters

| Parameter | Description | Type | Required | Additional Description |
| --------- | -------------- | ------ | -------- | ------------------------------------------------------------ |
| command | Command | Int | Y | 0: Restart, 1: Remote Open Door, 2: Enable Device, 3: Disable Device, 4: Reset Device5: Play Voice, 6: Show Image, 7: Show Text 8: Remote Face Capture 9: Log 10: Issue Mini-program Code 11: WeCom (Internal Only) 12: Fingerprint Collection 13: Screensaver Wallpaper (Currently only supports 0, 1, 4, 5, 10, 11, 12, 13) |
| extra | Extended Field | String | Y | See extra extension table |

Extra extension table

| Parameter       | Description               | Type   | Required | Remarks                                                      |
| --------------- | ------------------------- | ------ | -------- | ------------------------------------------------------------ |
| wav             | Audio Filename            | String | No       | Passed when command=5. Devices with speakers will play the specified audio. Audio files can be uploaded via the firmware upgrade interface. |
| image           | Image Filename            | String | No       | Passed when command=6. Devices with screens will pop up the specified image. Image files can be uploaded via the firmware upgrade interface. |
| timeout         | Display Time              | Int    | No       | Passed when command=6. Unit: `ms`. Time UI displays the image. Default: `1500ms`. |
| msg             | Prompt Message            | String | No       | Passed when command=7. Devices with screens will pop up the specified text. |
| timeout         | Prompt Time               | Int    | No       | Passed when command=7. Unit: `ms`. Time UI displays the `msg`. Default: `1500ms`. |
| log             | Log Command               | Int    | No       | Passed when command=9. 0: Get device log (Max 10K plaintext?), 1: Clear log. |
| qrCodeBase64    | Mini-program Code         | String | No       | Passed when command=10.                                      |
| keyId           | Credential ID for Capture | String | No       | Passed when command=8.                                       |
| type            | Capture Type              | String | No       | Passed when command=8. 0: Photo + Feature, 1: Photo, 2: Feature. |
| weComStatus     | WeCom Status              | Int    | No       | Passed when command=11. 0: Unbound, 1: Bound (Internal Only). |
| WeComBindQr     | WeCom Bind Code           | Int    | No       | Passed when command=11 & weComStatus=0. For display on the bind interface (Internal Only). |
| name            | Name                      | String | No       | Passed when command=12. Used to display the name of the person collecting fingerprints. |
| wallpaperBase64 | Screensaver Wallpaper     | String | No       | Passed when command=13. Replaces screensaver wallpaper. Resolution must equal device resolution. PNG format recommended. |

Sending example:

```
{
    
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
	"data": {
		"command": 1
	}
}

// Face Capture
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
    "data": {
        "command": 8,
        "extra": {
            "keyId": "12345678"
        }
    }
}

// WeCom
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
    "data": {
        "command": 11,
        "extra": {
            "weComStatus": 0,
            "WeComBindQr": "[https://open.work.weixin.qq.com/connect/hardware?hw_code=ZxjdiTaAJ6tX702PJg1z1e_iAdM_WH7r-qYUWMBIJJY](https://open.work.weixin.qq.com/connect/hardware?hw_code=ZxjdiTaAJ6tX702PJg1z1e_iAdM_WH7r-qYUWMBIJJY)"
        }
    }
}
```

- **Device Feedback to Backend/Application**

| Message Topic     | topic: access_device/v2/cmd/control_reply |
| ----------------- | ----------------------------------------- |
| `data` parameters |                                           |

| Parameter     | Description                     | Type   | Required | Additional Description                                       |
| ------------- | ------------------------------- | ------ | -------- | ------------------------------------------------------------ |
| faceBase64    | Remote Captured Face JPG Base64 | String | No       | Returned when command=8                                      |
| featureBase64 | Remote Captured Feature Base64  | String | No       | Returned when command=8                                      |
| keyId         | Credential ID                   | String | No       | Returned when command=8, matches input                       |
| type          | Capture Type                    | String | No       | Passed when command=8. 0: Photo + Feature, 1: Photo, 2: Feature |
| fingerFeature | Fingerprint Feature             | String | No       | Returned when command=12, the collected fingerprint feature value |

Return example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}

// Face Capture
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
    "code": "000000",
    "data": {
        "faceBase64": "/9j/4AAQSkZJRgABAQAAAQABAAD/......2Q==",
        "keyId": "12345678"
    },
    "message": "success"
}
```

#### 2.5 Alarm

- **Device to Backend/Application**

| Message Topic | topic: access_device/v2/event/alarm |
| ------------- | ----------------------------------- |
|               |                                     |

`data` parameters

| Parameter | Description   | Type   | Required | Additional Description                                       |
| --------- | ------------- | ------ | -------- | ------------------------------------------------------------ |
| type      | Report Type   | Int    | Y        | Refer to [Appendix Table 2 Device Alarm Types](https://www.google.com/search?q=%23appendix-table-2-device-alarm-types) - type value |
| value     | Report Status | String | N        |                                                              |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
	"data": {
		"type": 1,
		"status": 1,
        "timeStamp":1785963258
	}
}
```

- **Backend/Application Feedback to Device**

| Message Topic | topic: access_device/v2/event/{#uuid}/alarm_reply |
| ------------- | ------------------------------------------------- |
|               |                                                   |

Return example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 2.6 Heartbeat (Not Enabled)

- **Device to Backend/Application**

| Message Topic | topic: access_device/v2/event/heartbeat |
| ------------- | --------------------------------------- |
|               |                                         |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": ""
}
```

- **Backend/Application Feedback to Device (No Reply Needed)**

| Message Topic | topic: access_device/v2/event/{#uuid}/heartbeat_reply |
| ------------- | ----------------------------------------------------- |
|               |                                                       |

#### 2.7 Will

- **Device to Backend/Application**

| Message Topic | topic: access_device/v2/event/offline |
| ------------- | ------------------------------------- |
|               |                                       |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": ""
}
```

#### 2.8 Connection Report

- **Device to Backend/Application**

| Message Topic | topic: access_device/v2/event/connect |
| ------------- | ------------------------------------- |
|               |                                       |

Network configuration `data` parameters

| Parameter  | Description        | Type   | Required | Additional Description                   |
| ---------- | ------------------ | ------ | -------- | ---------------------------------------- |
| appVersion | App Version        | String | Y        | App version number                       |
| btMac      | Bluetooth MAC      | String | Y        | Bluetooth MAC address                    |
| mac        | Hardware Unique ID | String | N        | Device hardware unique ID                |
| clientId   | Client ID          | String | Y        | Client ID, defaults to device address    |
| name       | Device Name        | String | Y        | Device name                              |
| type       | Network Type       | Int    | Y        | Network Type (0: Ethernet 1: WIFI 2: 4G) |
| ssid       | WIFI SSID          | String | Y        | Wifi name                                |
| pwd        | WIFI Password      | String | Y        | Wifi password                            |
| dhcp       | DHCP Mode          | Int    | Y        | Is DHCP (1: Dynamic, 0: Static)          |
| ip         | IP Address         | String | Y        | IP Address                               |
| gateway    | Gateway            | String | Y        | Gateway                                  |
| dns        | DNS Server         | String | Y        | DNS Server                               |
| subnetMask | Subnet Mask        | String | Y        | Subnet Mask                              |
| netMac     | Network Card MAC   | String | Y        | Network Card MAC                         |

Sending example:

```
{
  "serialNo": "0000000001",
  "uuid": "e4720000964b5c00",
  "time": 1737364204,
  "data": {
    "appVersion": "vf203_v11_reader_1.0.0",
    "btMac": "000000000000",
    "mac": "e4ff00009df1d100",
    "clientId": "e4720000964b5c00",
    "name": "TODO",
    "type": 1,
    "ssid": "",
    "pwd": "",
    "dhcp": 1,
    "ip": "10.102.106.24",
    "gateway": "10.102.106.124",
    "dns": "10.102.106.124",
    "netMac": "ee:28:00:00:9d:f1"
  }
}
```

- **Backend/Application Feedback to Device (No Reply Needed)**

| Message Topic | topic:face_device/v2/event/connect_reply |
| ------------- | ---------------------------------------- |
|               |                                          |

#### 2.9 Online Verification

- **Device to Backend/Application**

| Message Topic | topic: access_device/v2/event/access_online |
| ------------- | ------------------------------------------- |
|               |                                             |

`data` parameters

| Parameter | Description           | Type   | Required | Remarks                                                      |
| --------- | --------------------- | ------ | -------- | ------------------------------------------------------------ |
| code      | Permission Credential | String | Yes      | Empty if Face                                                |
| type      | Permission Type       | Int    | Yes      | Refer to [Appendix Table 3 Credential Types](https://www.google.com/search?q=%23appendix-table-3-credential-types) - num column |
| index     | Gate Controller Index | String | No       | e.g., if device controls 4 doors, index could be 1, 2, 3, 4. Can be empty. |
| time      | Access Time           | Long   | Yes      | Timestamp in seconds                                         |
| extra     | Extra Params          | Object | No       | Extensible, usually records raw data, e.g., raw text of QR scan |
| srcData   | Raw Data              | String | No       | Original data                                                |

Sending example:

```
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "data": {
        "code":"s345463434gg",
        "type": 103,
        "time": 1640917147,
        "extra":{
          "srcData" : "vg://v203AQAGAHZndWFuZwIAQAAlcOsQMXN9TJGCK5Afs14p4orxE+QnmI4gb2F85pvrvbQW1/+CyPEE1Bi3X4T3SYFZRoheykjICfdwWU+kw/Vf2965"
        }
    },
    "time": 1647580466,
    "sign": ""
}
```

- **Backend/Application Feedback to Device**

| Message Topic | topic: access_device/v2/event/{#uuid}/access_online_reply |
| ------------- | --------------------------------------------------------- |
|               |                                                           |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 1640917147,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 2.10 Enterprise WeChat (Internal Only)

- **Device to Backend/Application**

| Message Topic | topic: access_device/v2/event/wecom |
| ------------- | ----------------------------------- |
|               |                                     |

`data` parameters

| Parameter | Description   | Type   | Required | Remarks                    |
| --------- | ------------- | ------ | -------- | -------------------------- |
| type      | Business Type | Int    | Yes      | 0: Query WeCom bind status |
| extra     | Extra Params  | Object | No       | Extensible                 |

Sending example:

```
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "data": {
        "type": 0,
    },
    "time": 1647580466,
    "sign": ""
}
```

- **Backend/Application Feedback to Device**

| Message Topic | topic: access_device/v2/event/{#uuid}/wecom_reply |
| ------------- | ------------------------------------------------- |
|               |                                                   |

`data` parameters

| Parameter | Description                                           | Type   | Required | Additional Description                                       |
| --------- | ----------------------------------------------------- | ------ | -------- | ------------------------------------------------------------ |
| status    | WeCom Status (Required system field when sent type=0) | Int    | N        | 0: Unbound 1: Bound                                          |
| bindQr    | WeCom Bind Code                                       | String | N        | Mandatory when unbound, bind code for device interface display |

Return example

```
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 1647580466,
    "sign": "",
    "code": "000000",
    "data": {
        "status": 0,
        "bindQr": "[https://open.work.weixin.qq.com/connect/hardware?hw_code=ZxjdiTaAJ6tX702PJg1z1e_iAdM_WH7r-qYUWMBIJJY](https://open.work.weixin.qq.com/connect/hardware?hw_code=ZxjdiTaAJ6tX702PJg1z1e_iAdM_WH7r-qYUWMBIJJY)"
    },
    "message": "success"
}
```

## III. Access Personnel Workflow

#### 3.1 Flowchart

```
flowchart TD
 A([Start])
 B[Prepare User Data]
 C[Issue User insertUser]
 D{Wait for Reply insertUser_reply}
 E[User Stored]
 F[Record Failed Batch]
 G[Prepare Face Credential]
 H[Issue Face Credential insertKey]
 I{Wait for Reply insertKey_reply}
 J[Face Stored]
 K[Record Failed Batch]
 L[Prepare Permission Data]
 M[Issue Permission insertPermission]
 N{Wait for Reply insertPermission_reply}
 O[Permission Issued]
 P[Record Failed Batch]
 Q([End])

#### 3.2 Process Description

- The Add User and Add Credential interfaces are linked via the userId field. The Add User and Add Permission interfaces are linked via the permissionIds field.
- To register a Face | QR Code | Card, you must call Add User and Add Credential with the same `userId` value. The `permissionIds` in Add Permission must match the value in Add User. All three interfaces must be called.
- The calling order of the three interfaces (Add User, Add Credential, Add Permission) is not restricted. The device will not check if `userId` and `permissionIds` have issues or association status immediately. However, the recommended order is Add User -> Credential -> Permission.
- `userId` is the primary key in Add User. Ensure it is unique during batch issuance; otherwise, user data with the same `userId` will be updated. The `permissionIds` in issuance must correspond one-to-one with the `permissionId` in Add Permission.
- `keyId` is the primary key in Add Credential. Ensure it is unique during batch issuance; otherwise, data with the same `keyId` will be updated. The `userId` in issuance must correspond one-to-one with the previously added User's `userId`.
- `permissionId` is the primary key in Add Permission. Ensure it is unique during batch issuance; otherwise, data with the same `permissionId` will be updated.
- It is not recommended to use the same value for `userId`, `keyId`, and `permissionId` for the same person. If a person has multiple QR codes, cards, or permissions, the IDs would need special handling. It is recommended that the three IDs be different values and then mapped/associated.

## IV. User Management Interfaces

#### 4.1 Add User

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/insertUser |
| ------------- | ---------------------------------------------- |
|               |                                                |

`data` parameters (Limit 100 per request)

| Parameter     | Description    | Type   | Required | Additional Description                                       |
| ------------- | -------------- | ------ | -------- | ------------------------------------------------------------ |
| userId        | User ID        | String | Y        | Unique, no duplicates allowed. Only alphanumeric, length 128 bytes. E.g., SW200 |
| name          | User Name      | String | Y        | name parameter is mandatory and cannot be empty. Length 128 bytes. |
| permissionIds | Permission IDs | Array  | Y        | User and permission mapping, corresponds to `permissionId` when issuing permissions. |
| extra         | Extra Params   | Object | No       | Other extra user attributes                                  |

- When issuing a user with an existing `userId` to the device, the device will automatically update all information for that user based on the `userId`.

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"data": [{
			"userId": "20190101120101",
        	"permissionIds":["6584132"],
			"name": "Zhang San",
			"extra": {
				"xxxx": "xxxx"
			}
		},
		{
			"userId": "20190101120102",
			"name": "Li Si",
            "permissionIds":["6584132"],
			"extra": {
				"xxxx": "xxxx"
			}
		}
	],
	"time": 1647580466,
	"sign": ""
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/insertUser_reply |
| ------------- | -------------------------------------------- |
|               |                                              |

- General `data` field description (Present only on failure):

| Parameter | Description       | Type   | Additional Description                          |
| --------- | ----------------- | ------ | ----------------------------------------------- |
| userId    | User ID           | String | Failed User ID                                  |
| errmsg    | Error Description | String | Specific reason for error, e.g., parsing failed |

Return Success Example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Return Failure Example

```
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "code": "C00001",
    "time": 1761275206,
    "sign": "",
    "message": "insertUser: Failed to insert user",
    "data": [
        {
            "userId": "20190101120101",
            "errmsg": "user array parse (0) failed"
        },
        {
            "userId": "20190101120102",
            "errmsg": "user array parse (1) failed"
        }
    ]
}
```

#### 4.2 Delete User

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/delUser |
| ------------- | ------------------------------------------- |
|               |                                             |

`data` parameters

| Parameter | Description | Type  | Required | Additional Description   |
| --------- | ----------- | ----- | -------- | ------------------------ |
| data      | User ID     | array | Y        | Each member is a User ID |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": ["001","002","003"]
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/delUser_reply |
| ------------- | ----------------------------------------- |
|               |                                           |

- General `data` field description (Present only on failure):

| Parameter | Description       | Type   | Additional Description                          |
| --------- | ----------------- | ------ | ----------------------------------------------- |
| userId    | User ID           | String | Failed User ID                                  |
| errmsg    | Error Description | String | Specific reason for error, e.g., parsing failed |

Return Success Example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Return Failure Example

```
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275616,
    "sign": "",
    "message": "delUser: Failed to delete user",
    "data": [
        {
            "userId": "001",
            "errmsg": "delete userId:001 failure"
        },
        {
            "userId": "002",
            "errmsg": "delete userId:002 failure"
        }
    ]
}
```

#### 4.3 Clear Users

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/clearUser |
| ------------- | --------------------------------------------- |
|               |                                               |

Sending example:

```
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 1754032384,
    "sign": ""
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/clearUser_reply |
| ------------- | ------------------------------------------- |
|               |                                             |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "000000",
	"time": 1754032640,
	"sign": "",
	"message": "success"
}
```

#### 4.4 Query User

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/getUser |
| ------------- | ------------------------------------------- |
|               |                                             |

`data` parameters

| Parameter | Description       | Type   | Required | Additional Description                               |
| --------- | ----------------- | ------ | -------- | ---------------------------------------------------- |
| userId    | User ID           | String | N        | • Query user info by specified ID • id               |
| name      | User Name         | String | N        | If name does not exist, query is not limited by name |
| size      | Max size per page | int    | Y        | Return range (0,100]                                 |
| page      | Page Number       | int    | Y        | Page number, starts from 0.                          |

Sending example:

```
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 1751538000,
    "sign": "",
    "data": {
        "userId": "",
        "name": "",
        "page": 0,
        "size": 10
    }
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/getUser_reply |
| ------------- | ----------------------------------------- |
|               |                                           |

User Query `data` parameters

| Parameter | Description | Type | Required | Additional Description |
| --------- | ------------------- | ----- | -------- | ------------------------------------------------------ |
| page | Current Page | Int | Y | Current Page |
| size | Page Size | Int | Y | Current Page Size |
| total | Total Count | Int | Y | Total Count |
| totalPage | Total Pages | Int | Y | Total Pages |
| count | Result Array Length | Int | Y | Length of query result array, <= size, e.g., last page |
| content | Permission Array | Array | Y | See <content data> table |

`content` data

| Parameter     | Description    | Type   | Required | Additional Description |
| ------------- | -------------- | ------ | -------- | ---------------------- |
| userId        | User ID        | String | Y        |                        |
| name          | User Name      | String | Y        |                        |
| permissionIds | Permission IDs | Array  | Y        |                        |
| extra         | Extended Field | Object | Y        | extra table            |

`extra` table

| Parameter | Description     | Type | Required | Additional Description |
| --------- | --------------- | ---- | -------- | ---------------------- |
| userType  | User Type       | Int  | Y        |                        |
| addSrc    | Register Source | Int  | Y        |                        |
| addTime   | Register Time   | Int  | Y        |                        |

Return example

```
On Success:
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "000000",
	"time": 1754032390,
	"sign": "",
	"message": "Success",
	"data": {
		"page": 0,
		"size": 10,
		"total": 5,
		"totalPage": 0,
		"count": 5,
		"content": [{
			"userId": "1",
			"name": "James",
            "permissionIds":["6584132"],
			"extra": {
				"userType": 1,
				"addSrc": 0,
				"addTime": 1754027509921
			}
		}, {
			"userId": "2",
			"name": "Lily",
			"permissionIds":["6584132"],
			"extra": {
				"userType": 1,
				"addSrc": 1,
				"addTime": 1754027489423
			}
		}, {
			"userId": "3",
			"name": "Grace",
			"permissionIds":["6584132"],
			"extra": {
				"userType": 0,
				"addSrc": 1,
				"addTime": 1754027489433
			}
		}, {
			"userId": "4",
			"name": "Wendy",
            "permissionIds":["6584132"],
			"extra": {
				"userType": 0,
				"addSrc": 1,
				"addTime": 1754027489443
			}
		}, {
			"userId": "5",
			"name": "Emma",
            "permissionIds":["6584132"],
			"extra": {
				"userType": 0,
				"addSrc": 1,
				"addTime": 1754027489458
			}
		}]
	}
}
When no users registered:
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "C00001",
	"time": 1754032816,
	"sign": "",
	"message": "selectUser: no data as this select condition"
}
```

#### 4.5 Modify User

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/modifyUser |
| ------------- | ---------------------------------------------- |
|               |                                                |

`data` parameters (Limit 100 per request)

| Parameter     | Description    | Type   | Required | Additional Description                                       |
| ------------- | -------------- | ------ | -------- | ------------------------------------------------------------ |
| userId        | User ID        | String | Y        | Unique, no duplicates allowed. Only alphanumeric, length 128 bytes. E.g., SW200 |
| name          | User Name      | String | N        | name parameter must be passed and cannot be empty. Length 128 bytes. |
| permissionIds | Permission IDs | Array  | N        | User and permission mapping, corresponds to `permissionId` when issuing permissions. |
| extra         | Extra Params   | Object | N        | Other extra user attributes                                  |

- Can only modify information for users with existing `userId`.

Sending example:

```
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"data": [{
			"userId": "20190101120101",
            "name":"Li Si",
        	"permissionIds":["6584133"]
		},
		{
			"userId": "20190101120102",
			"name": "Wang Er Ma",
			"extra": {
				"xxxx": "xxxx"
			}
		}
	],
	"time": 1647580466,
	"sign": ""
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/modifyUser_reply |
| ------------- | -------------------------------------------- |
|               |                                              |

- General `data` field description (Present only on failure):

| Parameter | Description       | Type   | Additional Description                          |
| --------- | ----------------- | ------ | ----------------------------------------------- |
| userId    | User ID           | String | Failed User ID                                  |
| errmsg    | Error Description | String | Specific reason for error, e.g., parsing failed |

Return Success Example

```
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Return Failure Example

```
{
    "serialNo": "6w8keif5g6",
    "uuid": "e4720000964b5c00",
    "code": "C00001",
    "time": 1761275206,
    "sign": "",
    "message": "modifyUser: Failed to modifyUser",
    "data": [
        {
            "userId": "20190101120101",
            "errmsg": "user array parse (0) failed"
        },
        {
            "userId": "20190101120102",
            "errmsg": "user array parse (1) failed"
        }
    ]
}
```

## V. Credential Management Interfaces

#### 5.1 Add Credential

- **Backend/Application to Device**

| Message Topic | topic:access_device/v2/cmd/{#uuid}/insertKey |
| ------------- | -------------------------------------------- |
|               |                                              |

`data` parameters (Limit 100 per request)

| Parameter | Required        | Type   | Description | Remarks                                                      |
| --------- | --------------- | ------ | ----------- | ------------------------------------------------------------ |
| keyId     | Credential ID   | String | Yes         | Credential unique ID                                         |
| userId    | User ID         | String | Yes         | User unique ID                                               |
| type      | Credential Type | int    | Yes         | Refer to [Appendix Table 4 Credential Types](https://www.google.com/search?q=%23appendix-table-4-credential-types) - num column |
| code      | Credential Data | String | Yes         | Pass base64 of JPG image for Face type                       |
| extra     | Extra Params    | Object | No          | Other extra credential attributes                            |

`extra` table

| Parameter | Description        | Type   | Required | Additional Description                                       |
| --------- | ------------------ | ------ | -------- | ------------------------------------------------------------ |
| faceType  | Register Face Type | String | Y        | 0: base64, 1: Feature value, 2: URL download, 3: zip package (Face type only supports same type issuance, and cannot be sent with other credential types in same package) |

- `userId` must match `userId` in Add User.
- When issuing a credential with an existing `keyId` to the device, the device will automatically update credential information based on `keyId`.
- The device will register batch-issued credentials one by one; if any credential fails, failure info is recorded in real-time, and after all credentials are processed, a complete failure record is summarized and returned.

Sending example:

```
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "data": [{
            "keyId": "20190101120101",
            "userId": "20190101120101",
            "type": 300,
            "code": "ZnNmZHNmYXNkZmFzZGY=........",
        	"extra":{
                "faceType":"0"
            }
        },
        {
            "keyId": "20190101120101",
            "userId": "20190101120102",
            "type": 103,
            "code": "1233456"
        }
    ],
    "time": 1647580466,
    "sign": ""
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/insertKey_reply |
| ------------- | ------------------------------------------- |
|               |                                             |

- General `data` field description (Present only on failure):

| Parameter | Description       | Type   | Additional Description                          |
| --------- | ----------------- | ------ | ----------------------------------------------- |
| keyId     | Credential ID     | String | Failed Credential ID                            |
| errmsg    | Error Description | String | Specific reason for error, e.g., parsing failed |

Return Success Example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Return Failure Example

```
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275488,
    "sign": "",
    "message": "insertKey: Failed to insert credential",
    "data": [
        {
            "keyId": "20190101120101",
            "errmsg": "key array parse (0) failed"
        },
        {
            "keyId": "20190101120102",
            "errmsg": "key array parse (1) failed"
        }
    ]
}
```

#### 5.2 Query Credential

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/getKey |
| ------------- | ------------------------------------------ |
|               |                                            |

`data` parameters

| Parameter | Description         | Type   | Required | Additional Description                                       |
| --------- | ------------------- | ------ | -------- | ------------------------------------------------------------ |
| keyId     | Credential ID       | String | N        | Credential unique ID                                         |
| userId    | User ID             | String | N        | User unique ID                                               |
| type      | Query specific type | int    | N        | Refer to [Appendix Table 4 Credential Types](https://www.google.com/search?q=%23appendix-table-4-credential-types) - num column |
| size      | Max size per page   | int    | Y        | Return range (0,100]                                         |
| page      | Page Number         | int    | Y        | Page number, starts from 0. index must be less than total pages. E.g., if total pages is 1, index can only be 0. |

Sending example:

```
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "data":{
      "keyId": "20190101120101",
      "userId": "20190101120101",
      "type":300,
      "page": 0,
      "size": 10
    },
    "time": 1647580466,
    "sign": ""
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/getKey_reply |
| ------------- | ---------------------------------------- |
|               |                                          |

User Query `data` parameters

| Parameter | Description | Type | Required | Additional Description |
| --------- | ------------------- | ----- | -------- | ------------------------------------------------------ |
| page | Current Page | Int | Y | Current Page |
| size | Page Size | Int | Y | Current Page Size |
| total | Total Count | Int | Y | Total Count |
| totalPage | Total Pages | Int | Y | Total Pages |
| count | Result Array Length | Int | Y | Length of query result array, <= size, e.g., last page |
| content | Credential Array | Array | Y | See <content data> table |

`content` data

| Parameter | Required        | Type   | Description | Remarks                                                      |
| --------- | --------------- | ------ | ----------- | ------------------------------------------------------------ |
| keyId     | Credential ID   | String | Y           | Credential unique ID                                         |
| userId    | User ID         | String | Y           | User unique ID                                               |
| type      | Credential Type | int    | Y           | Refer to [Appendix Table 4 Credential Types](https://www.google.com/search?q=%23appendix-table-4-credential-types) - num column |
| code      | Credential Data | String | Y           | Base64 for face type                                         |
| extra     | Extra Params    | Object | N           | Other extra credential attributes                            |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"result": 0,
	"code": "000000",
	"message": "success",
	"data": {
		"page": 0,
		"size": 20,
		"total": 2,
		"totalPage": 1,
		"count": 2,
		"content": [{
				"keyId": "100001",
            	"userId": "13",
				"type": "",
				"code": "Card Value",
            	"extra": {
					"xxxx":"xxx"
                }
			},
			{
				"keyId": "100002",
                "userId": "12",
				"type": "",
				"code": "Code Value"
			}
		]
	}
}
```

#### 5.3 Delete Credential

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/delKey |
| ------------- | ------------------------------------------ |
|               |                                            |

`data` parameters

| Parameter | Required      | Type  | Must | Remarks              |
| --------- | ------------- | ----- | ---- | -------------------- |
| keyIds    | Credential ID | array | No   | Credential unique ID |
| userIds   | User ID       | array | No   | User unique ID       |

- Simultaneous passing of `keyIds` and `userIds` is allowed. If deleting repeatedly, or attempting to delete non-existent credentials, no error will be reported.

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": {
        "keyIds":["20190101120101","20190101120102"],
        "userIds":["20190101120101","20190101120102"]
    }
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/delKey_reply |
| ------------- | ---------------------------------------- |
|               |                                          |

- General `data` field description (Present only on failure):

| Parameter | Description       | Type   | Additional Description                          |
| --------- | ----------------- | ------ | ----------------------------------------------- |
| keyId     | Credential ID     | String | Failed Credential ID                            |
| errmsg    | Error Description | String | Specific reason for error, e.g., parsing failed |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Return Failure Example

```
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275488,
    "sign": "",
    "message": "delKey: Failed to delete credential",
    "data": [
        {
            "keyId": "20190101120101",
            "errmsg": "delKey by userId: 20190101120101 error"
        },
        {
            "keyId": "invalid",
            "errmsg": "array item:1's userId is invalid"
        }
    ]
}
```

#### 5.4 Clear Credentials

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/clearKey |
| ------------- | -------------------------------------------- |
|               |                                              |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": ""
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/clearKey_reply |
| ------------- | ------------------------------------------ |
|               |                                            |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 5.5 Modify Credential

- **Backend/Application to Device**

| Message Topic | topic:access_device/v2/cmd/{#uuid}/modifyKey |
| ------------- | -------------------------------------------- |
|               |                                              |

`data` parameters (Limit 100 per request)

| Parameter | Required        | Type   | Description | Remarks                                                      |
| --------- | --------------- | ------ | ----------- | ------------------------------------------------------------ |
| keyId     | Credential ID   | String | Y           | Credential unique ID                                         |
| userId    | User ID         | String | N           | User unique ID                                               |
| type      | Credential Type | int    | N           | Refer to [Appendix Table 4 Credential Types](https://www.google.com/search?q=%23appendix-table-4-credential-types) - num column |
| code      | Credential Data | String | N           | Pass base64 for Face type (Does it support other registration types?). Face type only supports single issuance, and cannot be sent with other credential types in same package. |
| extra     | Extra Params    | Object | N           | Other extra credential attributes                            |

`extra` table

| Parameter | Description        | Type   | Required | Additional Description                                       |
| --------- | ------------------ | ------ | -------- | ------------------------------------------------------------ |
| faceType  | Register Face Type | String | Y        | 0: base64, 1: Feature value, 2: URL download, 3: zip package |

- When modifying `userId`, ensure the `userId` definitely exists in Users, otherwise access will fail.
- Can only modify information for credentials with existing `keyId`.

Sending example:

```
{
    "serialNo": "6w8keif5g6",
    "uuid": "e4720000964b5c00",
    "data": [{
            "keyId": "20190101120101",
            "userId": "20190101120101",
            "type": 300,
            "code": "ZnNmZHNmYXNkZmFzZGY=........",
        	"extra":{
                "faceType":"301"
            }
        },
        {
            "keyId": "20190101120101",
            "userId": "20190101120102",
            "type": 103,
            "code": "1233456"
        }
    ],
    "time": 1647580466,
    "sign": ""
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/modifyKey_reply |
| ------------- | ------------------------------------------- |
|               |                                             |

- General `data` field description (Present only on failure):

| Parameter | Description       | Type   | Additional Description                          |
| --------- | ----------------- | ------ | ----------------------------------------------- |
| keyId     | Credential ID     | String | Failed Credential ID                            |
| errmsg    | Error Description | String | Specific reason for error, e.g., parsing failed |

Return Success Example

```
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Return Failure Example

```
{
    "serialNo": "6w8keif5g6",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275488,
    "sign": "",
    "message": "modifyKey: Failed to modifyKey",
    "data": [
        {
            "keyId": "20190101120101",
            "errmsg": "key array parse (0) failed"
        },
        {
            "keyId": "20190101120102",
            "errmsg": "key array parse (1) failed"
        }
    ]
}
```

## VI. Permission Management Interfaces

#### 6.1 Add Permission

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/insertPermission |
| ------------- | ---------------------------------------------------- |
|               |                                                      |

`data` parameters (Limit 100 per request)

| Parameter    | Description   | Type   | Required | Remarks                                                      |
| ------------ | ------------- | ------ | -------- | ------------------------------------------------------------ |
| permissionId | Permission ID | String | Y        | Permission unique ID. Used for adding and deleting. Recommend 32-bit random value. |
| time         | Time Range    | Object | N        | [View Time Range](https://www.google.com/search?q=%23appendix-table-5-time-range-description) |
| extra        | Extra Params  | Object | N        | Other extra permission attributes, reserved, optional.       |

Sending example:

```
{
	"scerialNo": "0000000001",
	"sign": "",
	"time": 1704866881,
	"uuid": "e4720000964b5c00",
	"data": [{
		"permissionId": "6584132",
		"time": {
			"type": 3,
			"weekPeriodTime": {
				"1": "9:00-14:05",
				"2": "12:00-13:30|15:00-16:30"
			},
			"range": {
				"beginTime": 1640917147,
				"endTime": 1790917147
			}
		}
	}]

}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/insertPermission_reply |
| ------------- | -------------------------------------------------- |
|               |                                                    |

- General `data` field description (Present only on failure):

| Parameter    | Description       | Type   | Additional Description                          |
| ------------ | ----------------- | ------ | ----------------------------------------------- |
| permissionId | Permission ID     | String | Failed Permission ID                            |
| errmsg       | Error Description | String | Specific reason for error, e.g., parsing failed |

Return Success Example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Return Failure Example

```
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275616,
    "sign": "",
    "message": "insertPermission: Failed to insert permission",
    "data": [
        {
            "permissionId": "6584132",
            "errmsg": "permission array parse (0) failed"
        },
        {
            "permissionId": "6584133",
            "errmsg": "permission array parse (1) failed"
        }
    ]
}
```

#### 6.2 Query Permission

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/getPermission |
| ------------- | ------------------------------------------------- |
|               |                                                   |

`data` parameters

| Parameter    | Description       | Type   | Required | Additional Description                                       |
| ------------ | ----------------- | ------ | -------- | ------------------------------------------------------------ |
| permissionId | Permission ID     | String | N        |                                                              |
| page         | Max size per page | Int    | Y        | Return range (0,100]                                         |
| size         | Page Number       | Int    | Y        | Page number, starts from 0. index must be less than total pages. |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": {
        "page": 0,
		"size": 100
	}
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/getPermission_reply |
| ------------- | ----------------------------------------------- |
|               |                                                 |

Query `data` parameters

| Parameter | Description | Type | Required | Additional Description |
| --------- | ------------------- | ----- | -------- | ------------------------------------------------------ |
| page | Current Page | Int | Y | Current Page |
| size | Page Size | Int | Y | Current Page Size |
| total | Total Count | Int | Y | Total Count |
| totalPage | Total Pages | Int | Y | Total Pages |
| count | Result Array Length | Int | Y | Length of query result array, <= size, e.g., last page |
| content | Permission Array | Array | Y | See <content data> table |

`content` data

| Parameter    | Description    | Type   | Required | Additional Description                                       |
| ------------ | -------------- | ------ | -------- | ------------------------------------------------------------ |
| permissionId | Permission ID  | String | Y        |                                                              |
| time         | Time Range     | String | Y        | [View Time Range](https://www.google.com/search?q=%23appendix-table-5-time-range-description) |
| extra        | Extended Field | Object | N        |                                                              |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"sign": "",
	"code": "000000",
	"data": {
		"content": [{
			"permissionId": "6584132",
			"time": {
				"type": 3,
				"range": {
					"beginTime": 1640917147,
					"endTime": 1790917147
				},
				"weekPeriodTime": {
					"1": "9:00-14:05",
					"2": "12:00-13:30|15:00-16:30"
				}
			}
		}],
		"page": 0,
		"size": 200,
		"total": 1,
		"totalPage": 1,
		"count": 1
	},
	"message": "success",
	"time": 1711595116
}
```

#### 6.3 Delete Permission

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/delPermission |
| ------------- | ------------------------------------------------- |
|               |                                                   |

`data` parameters

| Parameter     | Description    | Type  | Required | Remarks              |
| ------------- | -------------- | ----- | -------- | -------------------- |
| permissionIds | Permission IDs | array | No       | Permission unique ID |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"data": {
		"permissionIds": ["20190101120101", "20190101120102"]
	},
	"time": 1647580466,
	"sign": ""
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/delPermission_reply |
| ------------- | ----------------------------------------------- |
|               |                                                 |

- General `data` field description (Present only on failure):

| Parameter    | Description       | Type   | Additional Description                          |
| ------------ | ----------------- | ------ | ----------------------------------------------- |
| permissionId | Permission ID     | String | Failed Permission ID                            |
| errmsg       | Error Description | String | Specific reason for error, e.g., parsing failed |

Return Success Example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Return Failure Example

```
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275488,
    "sign": "",
    "message": "delPermission: Failed to delete permission",
    "data": [
        {
            "permissionId": "20190101120101",
            "errmsg": "delete permission by userId:20190101120101 failed"
        },
        {
            "permissionId": "invalid",
            "errmsg": "get array item:1 failure"
        }
    ]
}
```

#### 6.4 Clear Permissions

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/clearPermission |
| ------------- | --------------------------------------------------- |
|               |                                                     |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": ""
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/clearPermission_reply |
| ------------- | ------------------------------------------------- |
|               |                                                   |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 6.5 Modify Permission

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/modifyPermission |
| ------------- | ---------------------------------------------------- |
|               |                                                      |

`data` parameters (Limit 100 per request)

| Parameter    | Description   | Type   | Required | Remarks                                                      |
| ------------ | ------------- | ------ | -------- | ------------------------------------------------------------ |
| permissionId | Permission ID | String | Y        | Permission unique ID. Used for adding and deleting. Recommend 32-bit random value. |
| time         | Time Range    | Object | N        | [View Time Range](https://www.google.com/search?q=%23appendix-table-5-time-range-description) |
| extra        | Extra Params  | Object | N        | Other extra credential attributes (Reserved, optional).      |

Sending example:

```
{
	"scerialNo": "123456",
	"sign": "",
	"time": 1704866881,
	"uuid": "e4720000964b5c00",
	"data": [{
		"permissionId": "6584132",
		"time": {
			"type": 0,
		}
	}]
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/modifyPermission_reply |
| ------------- | -------------------------------------------------- |
|               |                                                    |

- General `data` field description (Present only on failure):

| Parameter    | Description       | Type   | Additional Description                          |
| ------------ | ----------------- | ------ | ----------------------------------------------- |
| permissionId | Permission ID     | String | Failed Permission ID                            |
| errmsg       | Error Description | String | Specific reason for error, e.g., parsing failed |

Return Success Example

```
{
	"serialNo": "123456",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Return Failure Example

```
{
    "serialNo": "123456",
    "uuid": "e4720000964b5c00",
    "code": "C00001",
    "time": 1761275616,
    "sign": "",
    "message": "insertPermission: Failed to modifyPermission",
    "data": [
        {
            "permissionId": "6584132",
            "errmsg": "permission array parse (0) failed"
        },
        {
            "permissionId": "6584133",
            "errmsg": "permission array parse (1) failed"
        }
    ]
}
```

## VII. Security Key Management Interfaces

#### 7.1 Add Security Key

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/insertSecurity |
| ------------- | -------------------------------------------------- |
|               |                                                    |

`data` parameters (Limit 100 per request)

| Parameter  | Description     | Type   | Required | Additional Description                   |
| ---------- | --------------- | ------ | -------- | ---------------------------------------- |
| securityId | Security ID     | String | Y        | Key unique ID                            |
| type       | Key Type        | String | Y        | Key type, e.g., RSA, AES                 |
| key        | Key Code        | String | Y        | Key encoding, e.g., vguang               |
| value      | Key Value       | String | Y        |                                          |
| startTime  | Start Time      | Int    | Y        | Key start time, timestamp (seconds)      |
| endTime    | Expiration Time | Int    | Y        | Key expiration time, timestamp (seconds) |

Sending example:

```
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "data": [{
            "type": "RSA",
            "securityId": "213v",
            "key": "vguang",
            "value": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
            "startTime": 1560303425,
            "endTime": 1683918932
        },
        {
            "type": "RSA",
            "securityId": "213t",
            "key": "test",
            "value": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
            "startTime": 1560303425,
            "endTime": 1683918932
        }
    ],
    "time": 1647580466,
    "sign": ""
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/insertSecurity_reply |
| ------------- | ------------------------------------------------ |
|               |                                                  |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "Success"
}
```

#### 7.2 Query Security Key

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/getSecurity |
| ------------- | ----------------------------------------------- |
|               |                                                 |

`data` parameters

| Parameter  | Description       | Type   | Required | Additional Description                                       |
| ---------- | ----------------- | ------ | -------- | ------------------------------------------------------------ |
| securityId | Security ID       | String | Y        | Key unique ID                                                |
| type       | Key Type          | String | Y        | Key type, e.g., RSA, AES                                     |
| code       | Key Code          | String | Y        | Key encoding, e.g., vguang                                   |
| page       | Max size per page | Int    | Y        | Return range (0,100]                                         |
| size       | Page Number       | Int    | Y        | Page number, starts from 0. index must be less than total pages. |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": {
        "securityId": "001",
		"type": "RSA",
		"code": "vguang",
		"startTime": 1640917147,
		"endTime": 1672453147
	}
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/getSecurity_reply |
| ------------- | --------------------------------------------- |
|               |                                               |

`data` parameters

| Parameter | Description | Type | Required | Additional Description |
| --------- | ------------------- | ----- | -------- | ------------------------------------------------------ |
| page | Current Page | Int | Y | Current Page |
| size | Page Size | Int | Y | Current Page Size |
| total | Total Count | Int | Y | Total Count |
| totalPage | Total Pages | Int | Y | Total Pages |
| count | Result Array Length | Int | Y | Length of query result array, <= size, e.g., last page |
| content | Key Array | Array | Y | See <content data> table |

`content` data

| Parameter | Description     | Type   | Required | Additional Description                   |
| --------- | --------------- | ------ | -------- | ---------------------------------------- |
| type      | Key Type        | String | Y        | Key type, e.g., RSA, AES                 |
| code      | Key Code        | String | Y        | Key encoding, e.g., vguang               |
| key       | Key Value       | String | Y        |                                          |
| startTime | Start Time      | Int    | Y        | Key start time, timestamp (seconds)      |
| endTime   | Expiration Time | Int    | Y        | Key expiration time, timestamp (seconds) |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"code": "000000",
	"message": "success",
	"data": {
		"page": 0,
		"size": 20,
		"total": 1,
		"totalPage": 1,
		"count": 1,
		"content": [{
            "securityId": "001",
			"type": "RSA",
			"code": "vguang",
			"key": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
			"startTime": 1563456783,
			"endTime": 1963456783
		}， {
            "securityId": "002",
			"type": "RSA",
			"code": "vguang",
			"key": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
			"startTime": 1563456783,
			"endTime": 1963456783
		}]
	}
}
```

#### 7.3 Delete Security Key

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/delSecurity |
| ------------- | ----------------------------------------------- |
|               |                                                 |

`data` parameters

| Parameter | Description | Type  | Required | Additional Description |
| --------- | ----------- | ----- | -------- | ---------------------- |
| data      | Security ID | array | Y        | Each member is an id   |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": ["001","002","003"]
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/delSecurity_reply |
| ------------- | --------------------------------------------- |
|               |                                               |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 7.4 Clear Security Keys

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/clearSecurity |
| ------------- | ------------------------------------------------- |
|               |                                                   |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": ""
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/clearSecurity_reply |
| ------------- | ----------------------------------------------- |
|               |                                                 |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

## VIII. Recognition Records

#### 8.1 Recognition Record Query

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/getRecords |
| ------------- | ---------------------------------------------- |
|               |                                                |

`data` parameters

| Parameter | Description      | Type   | Required | Additional Description                                       |
| --------- | ---------------- | ------ | -------- | ------------------------------------------------------------ |
| recordId  | Access Record ID | String | N        | Access record unique identifier                              |
| userId    | User ID          | array  | N        | Query records for specified User IDs. Pass -1 to query records for all users. |
| name      | User Name        | String | N        | If name does not exist, query is not limited by name         |
| startTime | Start Time       | Int    | N        | Don't pass if not querying by time. If querying by time, pass timestamp. |
| endTime   | End Time         | Int    | N        | Don't pass if not querying by time. If querying by time, pass timestamp. |
| page      | Page Size        | Int    | Y        | Return images (0, 50], No images (0,1000]                    |
| size      | Page Number      | Int    | Y        | Starts from 0                                                |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": {
		"userId": ["001","002"],
		"name": "",
		"startTime": -1,
		"endTime": -1,
		"page": 0,
		"size": 100
	}
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/getRecords_reply |
| ------------- | -------------------------------------------- |
|               |                                              |

`data` parameters

| Parameter | Description | Type | Required | Additional Description |
| --------- | ------------------- | ----- | -------- | ------------------------------------------------------ |
| page | Current Page | Int | Y | Current Page |
| size | Page Size | Int | Y | Current Page Size |
| total | Total Count | Int | Y | Total Count |
| totalPage | Total Pages | Int | Y | Total Pages |
| count | Result Array Length | Int | Y | Length of query result array, <= size, e.g., last page |
| content | Record Array | Array | Y | See <content data> table |

`content` data

| Parameter | Description            | Type   | Required | Additional Description                                       |
| --------- | ---------------------- | ------ | -------- | ------------------------------------------------------------ |
| recordId  | Access Record ID       | String | Y        | Access record unique identifier                              |
| userId    | User ID                | String | Y        |                                                              |
| type      | Permission Type        | Int    | Y        | Refer to [Appendix Table 3 Credential Types](https://www.google.com/search?q=%23appendix-table-3-credential-types)-num when Face/Card/Code is independent. If Face+Card / Face+Code combined, use 301 for Face+Card, 302 for Face+Code. |
| timeStamp | Timestamp              | Int    | Y        |                                                              |
| result    | Result                 | Int    | Y        | 0: Success, non-0: Failure                                   |
| name      | User Name              | String | N        |                                                              |
| code      | Photo/Card/Code/Pwd/BT | String | Y/N      | type=300/301/302, otherwise fill Base64 photo data. For other types fill corresponding credential value. |
| extra     | Other Data             | Object | N        | Fill card or code value for Face+Card/Face+Code; can fill temperature info |
| error     | Error Info             | String | N        |                                                              |

`extra` table

| Parameter   | Description            | Type   | Required | Additional Description                                  |
| ----------- | ---------------------- | ------ | -------- | ------------------------------------------------------- |
| temperature | Temperature            | Float  | N        |                                                         |
| code        | Photo/Card/Code/Pwd/BT | String | N        | Fill card or code value for Face/Card/Code verification |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"result": 0,
	"code": "000000",
	"message": "success",
	"data": {
		"index": 0,
		"length": 100,
		"total": 3,
		"totalPage": 1,
		"size": 3,
		"content": [{
			"recordId": "6w8keif5g6",
			"userId": "100002",
			"name": "Chang Yongbin",
			"timeStamp": 1639475284,
			"code": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
		},
		{
			"recordId": "6w8keif5g7",
			"userId": "100002",
			"name": "Chang Yongbin",
			"timeStamp": 1639475288,
			"code": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
		},
		{
			"recordId": "6w8keif5g8",
			"userId": "100002",
			"name": "Chang Yongbin",
			"timeStamp": 1639475291,
			"code": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
		}]
	}
}
```

#### 8.2 Recognition Record Delete

- **Backend/Application to Device**

| Message Topic | topic: access_device/v2/cmd/{#uuid}/delRecords |
| ------------- | ---------------------------------------------- |
|               |                                                |

`data` parameters

| Parameter | Description | Type | Required | Additional Description |
| --------- | ---------------- | ----- | -------- | ------------------------------------------------------------ |
| recordId | Access Record ID | array | N | Access record unique identifier |
| userId | User ID | array | N | |
| startTime | Start Time | Int | N | Pass >0 to delete records after startTime. Pass <=0 or omit to delete all. |
| endTime | End Time | Int | N | Pass >0 to delete records before endTime. Pass <=0 or omit to delete all. |

Sending example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": {
		"recordId": ["6w8keif5g8"]
	}
}
```

- **Device Feedback to Backend/Application**

| Message Topic | topic: access_device/v2/cmd/delRecords_reply |
| ------------- | -------------------------------------------- |
|               |                                              |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 8.3 Access Record Report

- **Device to Backend/Application**

| Message Topic | topic: access_device/v2/event/access |
| ------------- | ------------------------------------ |
|               |                                      |

Message parameter description

`data` parameters

| Parameter | Description            | Type   | Required | Additional Description                                       |
| --------- | ---------------------- | ------ | -------- | ------------------------------------------------------------ |
| userId    | User ID                | String | Y        |                                                              |
| type      | User Type              | Int    | Y        | Refer to [Appendix Table 4 Credential Types](https://www.google.com/search?q=%23appendix-table-4-credential-types)-num column. If Face+Card / Face+Code combined, use 301 for Face+Card, 302 for Face+Code. |
| timeStamp | Timestamp              | Int    | Y        |                                                              |
| result    | Result                 | Int    | Y        | 0: Success, non-0: Failure                                   |
| name      | User Name              | String | N        |                                                              |
| code      | Photo/Card/Code/Pwd/BT | String | Y/N      | type=300/301/302, otherwise fill Base64 photo data. For other types fill corresponding credential value. |
| extra     | Other Data             | Object | N        | Fill card or code value for Face+Card/Face+Code              |
| error     | Error Info             | String | N        |                                                              |

`extra` table

| Parameter | Description            | Type   | Required | Additional Description                                  |
| --------- | ---------------------- | ------ | -------- | ------------------------------------------------------- |
| code      | Photo/Card/Code/Pwd/BT | String | N        | Fill card or code value for Face/Card/Code verification |

Sending example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": [{
		"userId": "412725202101011234",
		"type": 302,
		"timeStamp": 1639475284,
		"result": 0,
		"error": "success",
		"name": "Zhang San",
		"code": "/9j/4AAQSkZJRgABAQEAYABgAAD…",
		"extra": {
			"code": "&llgyAQASADQxMjcyNTIwMjEwMTAxMTIzNA==\@3Fa"
		}
	}]
}
```

- **Backend/Application Feedback to Device**

| Message Topic | topic: access_device/v2/event/{#uuid}/access_reply |
| ------------- | -------------------------------------------------- |
|               |                                                    |

Return example

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "000000",
	"message": "success"
}
```

## Appendix Table 1 Code Overview

| Type            | code          | Info                          | Description                                                  |
| --------------- | ------------- | ----------------------------- | ------------------------------------------------------------ |
| Success         | 000000        | Successfully executed command | None                                                         |
| General Error   | 100000        | Unknown Error                 | None                                                         |
| General Error   | 100001        | Device disabled               | Many commands are not allowed after device is disabled       |
| General Error   | 100002        | Device busy, try again later  | Device is upgrading, setting network, or in other tasks      |
| General Error   | 100003        | Signature verification failed | None                                                         |
| General Error   | 100004        | Timeout Error                 | None                                                         |
| General Error   | 100005        | Device Offline                | None                                                         |
| Param Exception | 200000-299999 | Parameter Exception           | Different commands have different param specs, refer to param exception description after each interface |
| Other Exception | 300000-399999 | Other known exceptions        | Different commands correspond to different exceptions, refer to description after each interface |

## Appendix Table 2 Device Alarm Types

| Type         | type | value                 | door                        |
| ------------ | ---- | --------------------- | --------------------------- |
| Door Magnet  | 0    | 0: Open, 1: Closed    | Index of corresponding door |
| Fire Alarm   | 1    | 0: Normal, 1: Warning | None                        |
| Tamper Alarm | 2    | 0: Normal, 1: Warning | None                        |

## Appendix Table 3 & 4 Credential Types

| type        | num           | Description                                                  |
| ----------- | ------------- | ------------------------------------------------------------ |
| face        | 300           | 300: Face Data                                               |
| qrcode      | 100, 101, 103 | 100: Pass-through Code, 101: Static Code, 103: Dynamic Code  |
| password    | 400           | 400: Password Data, length: 6 digits                         |
| card        | 200           | 200: Normal Card, 201: CPU Encrypted Card, 202: Sector Encrypted Card (Must issue uppercase normal sequence card number; lowercase will default to uppercase storage) |
| fingerprint | 500           | 500: Fingerprint Data                                        |
| bluetooth   | 600           | 600: Bluetooth Access Credential                             |
| openButton  | 800           | 800: Open Door Button                                        |

## Appendix Table 5 Time Range Description

Supports the following four time range settings:

- 1. Default Mode: Unlimited time, always valid.

```
{
    "type": 0
}
```

- 1. Normal Mode: Valid from start time to end time.

```
{
    "type": 1,
    "range": {
      "beginTime": 1640917147,
      "endTime": 1690917147
    }
}
```

- 1. Daily Mode: Valid during specific times each day, invalid at other times (Multiple time segments per day must not overlap, supports up to 5 groups). `dayPeriodTime` parameter format: "HH:MM-HH:MM", 24-hour format. E.g.: "08:00-09:30|10:00-11:30", max 5 segments. "00:00-24:00": Represents valid all day. Multiple segments separated by `|`, no spaces. E.g.: "08:00-09:30|10:00-11:30|12:00-13:30|15:00-16:30|17:00-18:30"

```
{
	"type": 2,
	"dayPeriodTime": "12:00-13:30|15:00-16:30",
	"range": {
		"beginTime": 1640917147,
		"endTime": 1690917147
	}
}
```

- 1. Week Repeat Mode: Valid during specific times on specific days (Mon-Sun), invalid at other times (Multiple time segments per day must not overlap, supports up to 5 groups). `weekPeriodTime` parameter format: "HH:MM-HH:MM", 24-hour format. E.g.: "08:00-09:30|10:00-11:30", max 5 segments. At least one day (1~7) must be passed, missing item means no permission. "00:00-24:00": Represents valid all day. Multiple segments separated by `|`, no spaces. E.g.: "08:00-09:30|10:00-11:30|12:00-13:30|15:00-16:30|17:00-18:30"

```
{
    "type": 3,
    "weekPeriodTime":{
      "1":"9:00-10:00",
      "2":"12:00-13:30|15:00-16:30"
    },
    "range": {
      "beginTime": 1640917147,
      "endTime": 1690917147
    }
}
```

## IX. Applicable Device List

| Device Model | Device Name | Adapted Version | Date Adapted | Remarks |
| ------------ | ----------- | --------------- | ------------ | ------- |
| -            | -           | -               | -            | -       |
| -            | -           | -               | -            | -       |

## X. Revision History

| Version | Date       | Author         | Interfaces Involved                     | Modification Content                                         |
| ------- | ---------- | -------------- | --------------------------------------- | ------------------------------------------------------------ |
| V1.0.0  | 2025.05.29 | Shi Lei        | *                                       | Document submission                                          |
| V1.0.1  | 2025.06.26 | Dong Xianglong | Config Interfaces, All Query Interfaces | Explained unified config field format, updated description of `count` field in query returns |
| V1.0.2  | 2025.06.27 | He Panlong     | Credential Interfaces                   | Corrected `type` field in credentials from string to int     |
| V1.0.3  | 2025.06.30 | He Panlong     | Delete Interfaces                       | Clarified meanings of parameters in all database deletion protocols |
| V1.0.4  | 2025.07.14 | Shi Lei        | User Interfaces                         | 1. Corrected user query page/size description errors, added user query examples |
| V1.0.5  | 2025.07.28 | Dong Xianglong | Config Table                            | Proofread all current face configuration fields              |
| V1.0.6  | 2025.08.21 | Shi Lei        | Process Description                     | Added user issuance flowchart and description, added notes to some interfaces, modified field descriptions |
| V1.0.7  | 2025.08.26 | Shi Lei        | Access Record Report                    | Removed `result` field from reply, added `message` field to interface spec |
| V1.0.8  | 2025.09.29 | Shi Lei        | User, Credential, Permission            | Removed `userId` from permission, added `permissionIds` to user; standardized all examples, changed all messages to English replies |
| V1.0.9  | 2025.10.28 | Shi Lei        | WeCom, Remote Control                   | Added WeCom function, added remote face capture, fixed some error examples |
| V1.0.10 | 2025.11.3  | Ma Zhixiang    | Alarm, Remote Control                   | Added tamper and fire alarm configs, modified log and mini-program code issuance |
| V1.0.11 | 2025.11.5  | Ma Zhixiang    | Permission Daily Mode, Access Records   | Modified daily mode rules, added `recordId` to access record query and deletion |
| V1.0.12 | 2025.11.6  | Ma Zhixiang    | Access Record Report                    | Adjusted access record report JSON format, removed `content` level |
| V1.0.13 | 2025.11.7  | Ma Zhixiang    | Configs, Card Issuance Format           | Corrected `base.password`, `base.volume`, `net.type`, added `mqtt.clientIdSuffix`, added card number issuance restriction (uppercase sequence) to credential types |
| V1.0.14 | 2025.11.8  | Ma Zhixiang    | Door Magnet Status                      | Corrected door magnet status enum                            |
| V1.0.15 | 2025.11.20 | Ma Zhixiang    | Correct Config Defaults, Add Configs    | Corrected default values (similarity, volume), added config (backlight) |
| V1.0.16 | 2025.12.10 | Ma Zhixiang    | Remote Control                          | Added Fingerprint Collection, Screensaver Wallpaper to Remote Control |
| V1.0.17 | 2025.12.18 | Ma Zhixiang    | Remote Control                          | Remote face capture: added capture type and feature value fields |