人脸识别门禁开发文档--V4.0.2

修改记录

设计原理

1. 本产品针对小型场景使用，协议力求简洁，只有23个接口，方便对接
2. 支持外网穿透，部署在公网的服务器能直接控制内网里的门禁机，比如远程开门，远程添加用户
3. 系统由3部分组成：人脸门禁机（后面简称设备端）为客户端，用于管理控制设备的信令服务器，和用于接收通行记录（包括抓拍图片）的数据服务器。两个服务器可合在一起实现，也可分开独立实现，独立部署
4. 设备和信令服务器之间，采用 WebSocket + SSL（WSS）协议，服务器端口为443。除第一条登录命令，其它所有命令都是服务器主动请求设备
5. 设备和数据服务器之间，采用标准HTTP Post协议，通过Multipart报文，把通行记录进行上报
6. 设备可脱机工作，能够缓存几千条通行记录（个数取决于设备存储器大小）在设备端（不带抓拍图），在重新连上数据服务器后，再平滑发送出去
7. 设备支持刷卡，刷脸，刷卡或刷脸，刷卡+刷脸双重认证这4种通行检测模式，检测时带语音和文字提示
8. 设备支持用户组配置，每个用户组可指定不同时间段的通行权限
9. 设备支持4路输入：按钮开关，门磁，报警，防撬；2路输出：门开关继电器，报警
10. 设备支持各种远程开关门，禁止通行，紧急开门，报警联动等功能
11. 设备支持常规的基本功能，恢复出厂设置，远程升级，重启，读取设备日志等功能

信令服务器功能

详细实现在接口协议部分描述

1. 激活设备

   出厂的设备必须通过激活，才能连接上服务器

   激活是采用了独立的通信协议实现

2. 注册用户

   录入人脸

   设置用户所属分组

   设置每个分组的时间段权限

3. 给人脸机下发配置

   同步所有用户信息

   同步时间

   声音设置

   人脸识别算法参数配置

   三路IO输入（开门按钮，门磁，报警输入）的电平配置

   两路IO输出（门闭合继电器，报警输出）的触发时间长度配置

5. 远程控制门

   门常开

   门常闭

6. 设备管理

   远程升级

   恢复出厂设置

   重启

   查看日志

数据服务器功能

详细实现在接口协议部分描述

1. 接收带抓拍照片的记录

2. 接收离线记录

3. 接收报警记录

人脸机功能

详细实现在接口协议部分描述

1. 刷卡开门

2. 人脸识别开门

3. 刷卡+人脸识别双重认证开门

4. 按钮开关，报警，远程开门

5. 离线记录缓存

6. 图像+语音提示

7. 通行记录上传

8. 支持IO报警信号的输入与输出

内网穿透机制

设备端主动连接外网服务器，并保持长连接。外网服务器可以依赖这个长连接，主动发送控制命令给设备端，达到穿透内网的效果

通行判断逻辑

刷卡 + 刷脸 + 门状态 + 用户权限 组合判断

刷卡和刷脸都是通过比对设备上的用户数据库来确定是否成功

门状态有两种方式改变

1. 通过IO口输入的报警，防撬等信号改变

2. 通过远程控制指令改变

用户权限是在"用户组"里配置的

后续版本提供流程图说明   

安全机制

考虑应用场景，目前安全通讯这一块设计的比较简单

1. 人脸机需要配置服务器的IP和端口信息，这两个需要通过激活机制才能写入。否则IP地址不对，设备将参考 1.2.3. 回应包模版法连接上服务器
2. 人脸机登录时会携带device_id，这个id如果没有在服务器上注册过，服务器拒绝登录
3. 烧写IP地址和注册device_id是通过服务器上的激活功能实现的

后续版本改为https

激活机制

因为激活前，人脸机参考 1.2.3. 回应包模版法登录服务器，所以服务器是通过发广播包的形式和设备进行通讯

设备判断广播包合法后，解析出包里携带的服务器IP地址和端口，烧写到设备里

同时，用UDP发送回应包，并附带上自己的device_id，服务器收到后，把该id记录到数据库里，完成注册

具体实现请参看接口协议

后续版本改为烧写服务端提供的https证书

协议说明

协议概述

1. 协议采用websocket，版本13

2. 为方便开发，仅支持websocket里的"文本帧"

3. 负载数据全部是标准的json字符串，编码为UTF8

4. json串请严格按后面的规则构造，字符型字段如果为空，请用""来表示，不能直接删除

5. user和group数据会涉及多条记录，均没有定义修改命令，请用del + add的机制实现

请求包模版

请求包json格式统一包含cmd和data两部分

1. cmd是请求的类型，一共有21种
2. data是请求携带的数据，是一个子json，如果某些请求参考 1.2.3. 回应包模版需数据，比如get_time，data字段可以不加，或者加一个空json：｛｝

3. 下面是一个例子

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

回应包模版

回应包json格式统一包含cmd，ret，msg，data四个字段

1. cmd是对应请求包加上后缀"_resp"构成

2. ret目前只有两个值，200表示成功，500表示失败

3. msg字段用于简短描述操作，比如失败的话给出失败的原因

4. data是回应的数据，是一个子json，如果某些请求参考 1.2.3. 回应包模版需数据，可以不加，或者加一个空json：｛｝

5. ret:200 表示成功， 500表示失败， msg：为相关解释

6. 下面是一个例子

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

7. 下面是一个没有数据携带时的例子，后面描述具有协议时，没数据的回应包均按此定义，不再赘述

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

信令服务器接口协议

登录

命令

login

请求数据

回应数据

验证成功

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

验证失败

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

备注：消息由设备端发往服务端，并建立socket连接

修改密码

命令

change_password

请求数据

回应数据

参考 1.2.3. 回应包模版

备注：密码修改成功后（返回包的ret为200），就连接会断掉，然后重新连接

心跳

命令

heartbeat

请求数据

无

回应数据

参考 1.2.3. 回应包模版

备注：该心跳是服务端 --> 设备端，比较少见，特此说明下

时间设置

命令

set_time

请求数据

回应数据

参考 1.2.3. 回应包模版

时间查询

命令

get_time

请求数据

无

回应数据

备注：时间设置如果不正确，会导致与时间相关的通行权限判断异常，上报的通行记录时间也不正确

设置语言

命令

set_language

请求数据

回应数据

参考 1.2.3. 回应包模版

备注：设置成功后，会自动重启

读取语言

命令

get_language

请求数据

无

回应数据

备注：如果没有设置过，那么默认值是“SimpChinese”

设置声音

命令

set_voice

请求数据

回应数据

参考 1.2.3. 回应包模版

人脸参数设置

命令

set_face_cfg

请求数据

回应数据

参考 1.2.3. 回应包模版

人脸参数查询

命令

get_face_cfg

请求数据

无

回应数据

参看“人脸参数设置”，数据和设置数据一样

人脸验证开门方式

命令

set_face_mode

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

请求数据

回应数据

参考 1.2.3. 回应包模版

录上报地址设置

命令

set_upload_url

请求数据

回应数据

参考 1.2.3. 回应包模版

通行记录上报地址查询

命令

get_upload_url

请求数据

无

回应数据

IO口设置

命令

set_io_cfg

请求数据

door_button，door_magnetic，alarm_input，prevent_pry 嵌套的Json格式为

{
    "enable": true, //是否启用
    "level": 0      //0低电平触发，1高电平触发
}

door_relay 嵌套的Json格式为

{
    "enable": true, //是否启用
    "duration": 5   //信号持续时间，用于自动关门，单位为秒，0为参考 1.2.3. 回应包模版限长
                    //因为开门继电器比较特殊，总是高电平有效，所以这里不需要再去配置电平
}

alarm_output 嵌套的Json格式为

{
    "enable": true, //是否启用
    "level": 0,     //0低电平触发，1高电平触发
    "duration": 5   //信号持续时间，用于自动停止报警，单位为秒，0为参考 1.2.3. 回应包模版限长
}

回应数据

参考 1.2.3. 回应包模版

IO口查询

命令

get_io_cfg

请求数据

无

回应数据

嵌套的Json参看“IO口设置”

用户添加

命令

add_user

请求数据

回应数据

参考 1.2.3. 回应包模版

备注：user_id是必须存在的，如果用户只是刷脸，card_id可以为空字符串，目前不支持纯刷卡用户（必须录入人脸）

用户修改

命令

modify_user

请求数据

回应数据

参考 1.2.3. 回应包模版

备注：user_id是必须存在的，如果用户只是刷脸，card_id可以为空字符串，目前不支持纯刷卡用户（必须录入人脸）

用户删除

命令

del_user

请求数据

回应数据

参考 1.2.3. 回应包模版

用户批量添加

add_users

请求数据

[
    {
        "user_id":"",
        "name":"",
        "card_id":"",
        "sfz_id":"",
        "group_id":"",
        "start_time":"",
        "end_time":"",
        "url":"",
        "face_jpg":""
    },
    {
        "user_id":"",
        "name":"",
        "card_id":"",
        "sfz_id":"",
        "group_id":"",
        "start_time":"",
        "end_time":"",
        "url":"",
        "face_jpg":""
    },
    {}............剩余数据
]

回应数据

参考 1.2.3. 回应包模版

备注：user_id是必须存在的，如果用户只是刷脸，card_id可以为空字符串，目前不支持纯刷卡用户（必须录入人脸）

设备处理方式：

1：设备接收后校验数据格式是否正确，正确将要添加的数据列表存入消息队列。存入成功后立即返回成功给服务器。服务器再发送下一批数据，设备再次接收存储。 设备端消费消息队列执行添加操作，再将操作结果返回给服务器。 整个流程是异步操作 优点：操作流程响应快，可操作大量数据 缺点：需要实现消息队列功能，增加业务逻辑

2：限制服务端请求的数量，例如每次10条。设备收到请求后执行添加操作。将操作结果返回给服务端。服务端再次发送下一批数据，设备再执行添加操作。 整个流程是同步操作 优点：实现简单，设备只需要执行批量操作逻辑。 缺点：操作时间变长，只适合小部分数据的批量操作。

用户批量修改

modify_users

请求数据

参考 add_users

回应数据

参考 1.2.3. 回应包模版

用户批量删除

命令

del_users

请求数据

回应数据

参考 1.2.3. 回应包模版

用户查询

命令

query_user

请求数据

单个用户回应数据

所有用户回应数据

例子如下

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

备注：因为数据量比较大，查询不会返回特征信息

用户剩余个数

命令

get_user_capacity

请求数据

无

回应数据

用户组添加

命令

add_group

请求数据

嵌套的Json格式为

{
    "start_time": "00:00", //开始时间
    "end_time":"23:59", //结束时间，和开始时间一起，决定了能在什么时间段里工作
    "op_type":1 //操作类型，0:特权，1:刷卡，2:人脸，3:人脸加刷卡，4:人脸或刷卡，5:禁止通行
}

回应数据

参考 1.2.3. 回应包模版

备注：用户组目地是为了批量给用户赋予在不同时间段开门的权限，比如可以建立一个特权组，把所有时间段的操作都设为“特权”，那么用户可以不受限的通行；建立一个行政组，每天5：30以后就不能开门；建立一个程序员组，凌晨2点以后不能开门。这里预设了5组时间，可以灵活配置，设备不负责检测时间段重叠，只按照第一个匹配成功的时间段进行操作。如果一个时间段都没匹配上，那么当参考 1.2.3. 回应包模版权开门处理。注意“0特权”，当门状态为“禁止通行”时，依然可以开门

用户组删除

命令

del_group

请求数据

回应数据

参考 1.2.3. 回应包模版

备注：如果已经有用户关联的组被删掉后，用户在开门时将提示“权限配置丢失”的错误，参考 1.2.3. 回应包模版法开门

用户组查询

命令

query_group

请求数据

单组回应数据

嵌套的Json格式参看“用户组添加”

所有组回应数据

例子如下

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

门远程控制

命令

remote_ctrl

请求数据

回应数据

参考 1.2.3. 回应包模版

备注：切回正常状态时，如果门是开着的，会自动关门；如果有报警输出，会自动关闭报警输出。控制类型会影响用户通行，比如“禁止通行”下，除了特权用户，其它都参考 1.2.3. 回应包模版法开门

门状态查询

命令

get_door_status

请求数据

无

回应数据

备注：方便服务器远程检查门的状态，以做出相应操作。比如监控门是否被非法打开。第一项是门的逻辑状态，其余项是传感器的状态值（经过IO口的配置项转换过）

报警温度设置

命令

set_temperature

请求数据

回应数据

参考 1.2.3. 回应包模版

备注：超过(不包含)此温度后有警报提示

二维码下发

命令

set_qrcode

请求数据

回应数据

参考 1.2.3. 回应包模版

备注：收到二维码后，设备屏幕会立刻更新二维码显示，手机扫描后，可以实现访客远程开门

恢复出厂设置

命令

factory_reset

请求数据

无

回应数据

参考 1.2.3. 回应包模版

备注：设备会重启

远程升级

命令

upgrade

请求数据

回应数据

参考 1.2.3. 回应包模版

备注：升级文件下载好后，会关闭所有功能，开始烧写flash，烧写完成后会重启

远程重启

命令

restart

请求数据

无

回应数据

参考 1.2.3. 回应包模版

调试日志读取

命令

get_log

请求数据

无

回应数据

备注：设备上一个循环写的日志文件，该文件通过该协议可以被读出，方便测试

调试开关

命令

debug_enable

请求数据

回应数据

参考 1.2.3. 回应包模版

备注：调试开启后，设备将会把很多调试信息写入日志，方便远程调取查看。调试默认关闭，debug字段为1后立即生效，但是不会保存，重启后又恢复为0

韦根查询

命令

get_weigand_cfg

请求数据

无

回应数据

备注：mode为1时在刷卡时屏幕显示为韦根34卡号，输出时对应的user_id或card_id将处理为34类型

韦根设置

命令

set_weigand_cfg

请求数据

回应数据

参考 1.2.3. 回应包模版

健康码配置查询

命令

get_zhicheng_cfg

请求数据

无

回应数据

健康码设置

命令

set_zhicheng_cfg

请求数据

回应数据

参考 1.2.3. 回应包模版

数据服务器接口协议

通行记录上传

命令

为/set_upload_url接口里设置的url

请求数据

格式为multipart报文，分为两部分，第一部分是json字符串，内容如下

第二部分是jpg文件，整个报文示例如下

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="data"
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--

回应数据

参考 1.2.3. 回应包模版

pass_result 详细说明：

备注：

• 刷卡通行，离线记录，异常记录都不携带抓拍照片，报文里不会携带jpg部分
• 异常记录只有device_id，time，message这3个字段有效，其余字段置空
• record_type=0表示实时通行记录，record_type=1表示离线通行记录，record_type=2表示报警信息
• card_id, group_id, name看上去比较冗余，实际上都可以通过查询user_id获取，这里提供出来是为了方便

激活协议

激活协议用于设备部署时，根据使用环境，配置信令服务器地址，以及设备本身的IP地址

协议采用广播包通讯，设备端口7030

设备查询命令

后台服务器地址设置命令

设备IP配置命令

备注：协议全部采用自然语言交互，字符大小写敏感