# Face recognition access control development document--V3.8

Modification record

Design principle

1. this product is designed for small scenarios, and the protocol is concise, with only 23 interfaces, which is convenient for docking
2. Support external network penetration. The server deployed in the public network can directly control the access control machine in the intranet, such as remote door opening and remote user adding
3. The system consists of three parts: the face access control machine (hereinafter referred to as the device end) is the client, the signaling server used to manage and control the equipment, and the data server used to receive the traffic records (including the captured pictures). The two servers can be implemented together or separately
4. Websocket + SSL (WSS) protocol is adopted between the device and the signaling server, and the server port is 443. Except for the first login command, all other commands are actively requested by the server
5. The standard HTTP post protocol is used between the device and the data server to report the traffic record through multipart message
6. The device can work offline, and can cache thousands of traffic records (the number depends on the size of the device memory) at the device end (without snapshot), and then send them out after reconnecting with the data server
7. The device supports IC card, face recognition, IC card or face recognition, and IC card + face recognition dual authentication, with voice and text prompts
8. The device supports user group configuration, and each user group can specify the access rights of different time periods
9. The device supports 4-way input: button switch, door magnet, alarm, anti prying; 2-way output: door switch relay, alarm
10. The equipment supports various functions such as remote door opening and closing, no passing, emergency door opening, alarm linkage, etc
11. The device supports normal basic functions, such as restoring factory settings, remote upgrade, restart, reading device log, etc

Signaling server function

Detailed description of interface protocol

1. Activate the device

Factory device must be activated to connect to the server

The activation is realized by independent communication protocol

2. Register users

Input face information

Set user group

Set time period permissions for each group

3. Send configuration to face recognition machine

   Synchronize all user information

Synchronization time

Parameter configuration of face recognition algorithm

Level configuration of three-way IO input (door opening button, door magnet, alarm input)

Trigger time length configuration of two IO outputs (door closing relay, alarm output)

5. Remote control door

   Door normally open

Door normally closed

6. Device management

Remote upgrade

Restore factory settings

Restart

View log

Data server function

Detailed description of interface protocol

1. Receive the record with captured photos

2. Receive offline records

3. Receive alarm record

Data server function

Detailed description of interface protocol

1. IC card

2. Face recognition

3. Double authentication: IC card and face recognition

4. Button switch, alarm and remote door opening

5. Offline record cache

6. Image + voice prompt

7. Upload of traffic records

8. Support the input and output of IO alarm signal

Intranet penetration mechanism

The device side actively connects to the external network server and maintains long connection. The external network server can rely on this long connection and send control commands to the device side to achieve the effect of penetrating the internal network

Access judgement logic

Combination judgment of IC card + face recognition + door status + user permission

Both IC card and face recognition are used to determine whether they are successful by comparing the user database on the device

There are two ways to change the state of the door

1. IO port input alarm, anti prying and other signals

2. Remote control command

User permissions are configured in user groups

Flow chart description is provided in subsequent versions

Security mechanism

Considering the application scenario, the current design of secure communication is relatively simple

1. The face recognition machine needs to configure the IP and port information of the server. These two need to be written through activation mechanism. Otherwise, the IP address is not correct, and the device will not be able to connect to the server
2. When the face recognition machine logs in, it will carry device_ ID, this ID if it is not registered on the server, the server refuses to log in
3. Burn IP address and register device_ ID is realized through the activation function on the server

Later version changed to HTTPS

Activation mechanism

Because before activation, the face machine cannot log in to the server, so the server communicates with the device by sending broadcast packets

After the device judges that the broadcast packet is legal, it resolves the IP address and port of the server carried in the packet and writes it to the device

At the same time, send a response packet with UDP and attach your own device_ID After receiving the ID, the server records the ID in the database and completes the registration

Please refer to the interface protocol for specific implementation

The later version is changed to burn the HTTPS certificate provided by the server

Protocol specification

Protocol overview

1. websocket is adopted for the protocol, version 13

2. For the convenience of development, only "text frame" in websocket is supported

3. The load data are all standard JSON strings, encoded as utf8

4. JSON string should be constructed strictly according to the rules after. If the character type field is empty, please use '' to represent it, and it cannot be deleted directly

5. user and group data will involve multiple records, and no modification command is defined. Please implement it by del + add mechanism

Request package template

The JSON format of request package includes two parts: CMD and DATE

1. CMD is the type of request, there are 21 types in total
2. DATE is the data carried by the request. It is a sub JSON. If some requests do not need data, such as get_ Time, data field can not be added, or an empty JSON: {} can be added

3. Here is an example

    {
        "cmd": "login",
        "data": {
            "firmware_ver": "1",
            "device_id": "1234567890",
            "device_type": "zhongding_mj"
        }
    }
   

Response package template

The JSON format of the response package contains four fields: CMD, RET, MSG and DATE

1. CMD is the corresponding request packet with the suffix "_resp" structure

2. RET has only two values, 200 for success and 500 for failure

3. The MSG field is used to briefly describe the operation. For example, if the operation fails, the reason for the failure is given

4. DATA is the response data, which is a sub JSON. If some requests do not need data, you can not add it, or add an empty JSON: {}

5. Here is an example

   {
        "cmd": "get_time_resp",
        "ret": 200,
        "msg": "get time OK",
        "data": {
            "time": "2020-01-09 12:47:47"
        }
   }

6. The following is an example when there is no data to carry. When there is a protocol, all response packets without data are defined in this way

   {
        "cmd": "login_resp",
        "ret": 500,
        "msg": "xxx"
   }
   

Signaling server interface protocol

Log in

Command

login

Request data

Response data

Verified successfully

{
    "cmd": "login_resp",
    "ret": 200
}

verification failed

{
    "cmd": "login_resp",
    "ret": 500
}

Note: the message is sent from the device to the server, and the Socket connection is established

Modify password

Command

change_password

Request data

Response data

Refer to 1.2.3. Response package template

Note: after the password is successfully modified (RET of the returned packet is 200), the connection will be broken and then reconnected

Heartbeat

Command

heartbeat

Request data

Non

Response data

Refer to 1.2.3. Response package template

Note: the heartbeat is server side > device side, which rarely occurs

Time setting

Command

set_time

Request data

Response data

Refer to 1.2.3. Response package template

Time query

Command

get_time

Request data

Non

Response data

Note: if the time setting is not correct, it will lead to abnormal judgment of time related access rights, and the reported access record time is also incorrect

Set language

Command

set_language

Request data

Response data

Non

Note: after setting, it will restart automatically

Read language

Command

get_language

Request data

Non

Response data

Note: the default is "SimpChinese"

Set sound

Command

set_voice

Request data

Refer to 1.2.3. Response package template

Command

set_face_cfg

Request data

Response data

Non

Face parameter query

Command

get_face_cfg

Request data

Non

Response data

Refer to "face parameter setting", the data is the same as the setting data

Address setting of identification data reporting

Command

set_face_mode

"duration":3,"way":0/1/2

Request data

Response data

Refer to 1.2.3. Response package template

Reporting address settings

Command

set_upload_url

Request data

Response data

Refer to 1.2.3. Response package template

Access record report address query

Command

get_upload_url

Request data

Non

Response data

IO port setting

Command

set_io_cfg

Request data

door_button，door_magnetic，alarm_input，prevent_pry The nested JSON format is

   {
    "enable": true, //Enable or not
    "level": 0      //0 low level trigger, 1 high level trigger
   }

door_relay The nested JSON format is

{
    "enable": true, //Enable or not
    "duration": 5   //Signal duration, used for automatic door closing, in seconds, 0 for infinite length
                    //Because the door opening relay is special, it is always high level, so there is no need to configure the level here
}

alarm_output The nested JSON format is

{
    "enable": true, //Enable or not
    "level": 0,     //0 low level trigger, 1 high level trigger
    "duration": 5   //Signal duration, used for automatic stop alarm, unit is seconds, 0 is infinite
}

Response data

Refer to 1.2.3. Response package template

IO port query

Command

get_io_cfg

Request data

Non

Response data

See "IO port setting" for nested JSON

User add

Command

add_user

Request data

Response data

Refer to 1.2.3. Response package template

Note: user_id must exist. If the user only uses face recognition, user_id can be an empty string. At present, pure IC card users are not supported (face recognition is required)

User delete

Command

del_user

Request data

Response data

Refer to 1.2.3. Response package template

User query

Command

query_user

Request data

Single user response data

All user response data

Example

{
    "list_len": 5,
    "user_id_list": [
        "001",
        "002",
        "003",
        "004"
    ]
}

Note: because of the large amount of data, the query will not return the feature information

Number of users remaining

Command

get_user_capacity

Request data

Non

Response data

User group add

Command

add_group

Request data

The nested JSON format is

{
    "start_time": "00:00", //Start time
    "end_time":"23:59", //The end time, together with the start time, determines what period of time you can work
    "op_type":1 //Operation type: 0: privilege, 1: IC card, 2: face recognition, 3: face recognition or IC card, 4: face recognition + IC card, 5: no access
}

Response data

Non

Note: the purpose of user group is to batch give users permission to open doors in different time periods. For example, a privilege group can be established, and the operation in all time periods can be set as "privilege", so that users can pass freely; Set up an administrative group, which can't open after 5:30 every day; Set up a programmer group, which can't open after 2 a.m. There are five preset groups

Time can be flexibly configured. The device is not responsible for detecting the overlap of time periods, and only operates according to the first time period successfully matched. If a time period is not matched, it will be handled when there is no right to open the door. Pay attention to "0 privilege". When the door status is "no passing", it can still be opened

User group delete

Command

del_group

Request data

Response data

Refer to 1.2.3. Response package template

Note: if a group associated with a user has been deleted, the user will be prompted with the error of "permission configuration lost" when opening the door, and cannot open the door

User group query

Command

query_group

Request data

Single response data

For nested JSON formats, see "user group add"

All group response data

Example

{
    "list_len": 5,
    "group_id_list": [
        "001",
        "002",
        "003",
        "004"
    ]
}

Remote control of door

Command

remote_ctrl

Request data

Response data

Refer to 1.2.3. Response package template

Note: when the door is switched back to normal state, it will close automatically if the door is open; If there is an alarm output, the alarm output will be automatically turned off. The control type will affect the user access, for example, under "no access", no door can be opened except for privileged users

Door status query

Command

get_door_status

Request data

Non

Response data

Note: it is convenient for the server to remotely check the status of the door to make corresponding operation. For example, monitoring whether the door is opened illegally. The first item is the logic state of the gate, and the other items are the state value of the sensor (converted through the configuration item of the IO port)

Alarm temperature setting

Command

set_temperature

Request data

Response data

Refer to 1.2.3. Response package template

Note: there is an alarm when the temperature exceeds (does not include)

QR code distribution

Command

set_qrcode

Request data

Response data

Refer to 1.2.3. Response package template

Note: after receiving the QR code, the device screen will immediately update the QR code display. After mobile phone scanning, visitors can remotely open the door

Restore factory settings

Command

factory_reset

Request data

Non

Response data

Refer to 1.2.3. Response package template

Note: the device will restart

Remote upgrade

Command

upgrade

Request data

Response data

Non

Note: after the upgrade file is downloaded, all functions will be turned off and flash will be started. After the flash is finished, it will be restarted

Remote Reboot

Command

restart

Request data

Non

Response data

Refer to 1.2.3. Response package template

Debug log read

Command

get_log

Request data

Non

Response data

Note: a circular log file written on the device, which can be read through the protocol, and is easy to test

Debug switch

Command

debug_enable

Request data

Response data

Refer to 1.2.3. Response package template

Note: after debugging is started, the device will write a lot of debugging information into the log to facilitate remote access. Debugging is turned off by default. When the debug field is 1, it will take effect immediately, but it will not be saved. After restart, it will return to 0

Wiegand query

Command

get_weigand_cfg

Request data

Response data

Non

Remarks: When the mode is 1, the Wiegand 34 card number will be displayed on the screen when swiping the card, and the corresponding user_id or card_id will be processed as type 34 when outputting.

Wiegand settings

Command

set_weigand_cfg

Request data

Response data

Refer to 1.2.3. Response package template

Data server interface protocol

Access record upload

Command

For /set_ upload_ URL set in URL interface

Request data

The format is multipart message, which is divided into two parts. The first part is JSON string, and the content is as follows

The second part is JPG file. The whole message example is as follows

POST /zdmj/upload HTTP/1.1
Host: 10.2.5.56:8080
Connection: keep-alive
Content-Type: multipart/form-data; boundary=zhongding-boundary
Content-Length: 100

--zhongding-boundary
Content-Disposition: form-data; name="record"
Content-Type: application/json

...json data...
--zhongding-boundary
Content-Disposition: form-data; name="jpg"; filename="000000001.jpg"
Content-Type: image/jpeg

...jpg data...
--zhongding-boundary--

Response data

Refer to 1.2.3. Response package template

pass_result Detailed description:

Remarks:

-IC card access, offline records, abnormal records do not carry snapshot photos, the message will not carry the JPG part -The exception record is only Device_ID, Time and Message fields are valid, and the rest are empty -Record_ Type = 0 means real-time traffic record, Record_ Type = 1 means offline traffic record, Record_ Type = 2 indicates alarm information -Card_ id, Group_ ID and Name seem to be redundant. In fact, they can be queried by User_ ID acquisition is provided here for convenience

Activation protocol

When the activation protocol is used for device deployment, the signaling server address and the IP address of the device itself are configured according to the usage environment

The protocol adopts broadcast packet communication, and the device port 7030

Device query command

Background server address setting command

Device IP configuration command

Note: the protocol adopts natural language interaction, and the characters are case sensitive