人脸门禁终端物模型协议 V1.0

一、简介

本协议主要用于人脸门禁业务场景。
编码类型：utf-8
版本变更说明：

父版本号：在协议发生不兼容性修改的情况下递增，同时清空子版本号；

子版本号：在增删协议接口或字段时递增；

二、物模型约定

2.1 心跳

上报

主题：sys/{product_id}/{device_id}/thing/heart
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
time	long	是	时间：13 位时间戳
interval	int	否	心跳间隔：30 - 1200 之间的整数(单位：秒)，默认值：30

示例：

{
  "id": "111",
  "time": 1618540337564,
  "interval": 30
}

主题：sys/{product_id}/{device_id}/thing/heart/response
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
time	long	是	时间：13 位时间戳
interval	int	否	心跳间隔：30 - 1200 之间的整数(单位：秒)，默认值：30

示例：

{
  "id": "111",
  "time": 1618540337564,
  "interval": 30
}

2.2 时间校准

上报

主题：sys/{product_id}/{device_id}/thing/ntp
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
deviceSendTime	long	是	代表设备发出时间校准请求的时间，13 位时间戳

示例：

{
  "id": "222",
  "deviceSendTime": 1571724098000
}

主题：sys/{product_id}/{device_id}/thing/ntp/response
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
deviceSendTime	long	是	代表设备发出时间校准请求的时间，13 位时间戳
serverRecvTime	long	是	代表 IoT 服务端接收到时间校准请求的时间，13 位时间戳
serverSendTime	long	是	代表 IoT 服务端响应时间校准请求的时间，13 位时间戳

示例：

{
  "id": "222",
  "deviceSendTime": 1571724098000,
  "serverRecvTime": 1571724098110,
  "serverSendTime": 1571724098115
}

2.3 属性上报

上报

主题：sys/{product_id}/{device_id}/thing/properties/up
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
version	string	是	协议版本号：目前协议版本号唯一取值为 1.0
method	string	是	请求方法：例如 thing.properties.up
sys	object	是	-
├─ ack	int	是	是否返回响应数据：1- 云端返回响应数据，0- 云端不返回响应数据
params	object	否	请求参数
├─ xxx	object	否	xxx 为任意属性
│ ├─ value	object	是	上报的属性值
│ └─ time	long	是	属性上报时间戳，类型为 UTC 毫秒级时间

示例：

{
  "id": "333",
  "version": "1.0",
  "sys": {
    "ack": 0
  },
  "params": {
    "power": {
      "value": "on",
      "time": 1524448722000
    }
  },
  "method": "thing.properties.up"
}

上报回复

主题：sys/{product_id}/{device_id}/thing/properties/up/response
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
version	string	是	与请求参数中 version 相同
method	string	是	与请求参数中 method 相同
code	int	是	结果状态码：200- 成功，460- 物模型校验失败，400- 设备未上线
message	string	是	返回结果信息：请求成功时，返回 success
data	object	否	请求成功时，返回的数据固定为空

示例：

{
  "code": 200,
  "data": null,
  "id": "333",
  "message": "success",
  "method": "thing.properties.up",
  "version": "1.0"
}

2.4 属性获取

获取

主题：sys/{product_id}/{device_id}/thing/properties/get
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
version	string	是	协议版本号：目前协议版本号唯一取值为 1.0
method	string	是	请求方法：例如 thing.properties.get
params	string[]	是	要进行属性查询的设备参数名列表，若查询的设备参数为非默认模块的参数，需要使用冒号进行区分

示例：

{
  "id": "444",
  "version": "1.0",
  "params": [
    "temperature",
    "test:power"
  ],
  "method": "thing.properties.get"
}

获取回复

主题：sys/{product_id}/{device_id}/thing/properties/get/response
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
version	string	是	与请求参数中 version 相同
method	string	是	与请求参数中 method 相同
code	int	是	结果状态码：200- 成功，460- 物模型校验失败，400- 设备未上线
message	string	是	返回结果信息：请求成功时，返回 success
data	object	否	请求成功时，返回的数据固定为查询到的设备参数值

示例：

{
  "code": 200,
  "data": {
    "params": {
      "temperature": 23.6,
      "test:power": 1
    }
  },
  "id": "444",
  "message": "success",
  "method": "thing.properties.get",
  "version": "1.0"
}

2.5 属性设置

设置

主题：sys/{product_id}/{device_id}/thing/properties/set
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
version	string	是	协议版本号：目前协议版本号唯一取值为 1.0
method	string	是	请求方法：例如 thing.properties.set
params	object	是	属性设置参数

示例：

{
  "id": "555",
  "version": "1.0",
  "params": {
    "temperature": "30.5",
    "test:power": "30.5"
  },
  "method": "thing.properties.set"
}

设置回复

主题：sys/{product_id}/{device_id}/thing/properties/set/response
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
version	string	是	与请求参数中 version 相同
method	string	是	与请求参数中 method 相同
code	int	是	结果状态码：200- 成功，460- 物模型校验失败，400- 设备未上线
message	string	是	返回结果信息：请求成功时，返回 success
data	object	否	请求成功时，返回的数据固定为空

示例：

{
  "code": 200,
  "data": null,
  "id": "555",
  "message": "success",
  "method": "thing.properties.set",
  "version": "1.0"
}

2.6 事件上报

事件上报

主题：sys/{product_id}/{device_id}/thing/event/up
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
version	string	是	协议版本号：目前协议版本号唯一取值为 1.0
method	string	是	请求方法：例如 thing.event.up
identifier	string	是	为物模型中定义的事件标识符，若为自定义模块，则 $t s l . f u n c t i o n Bl oc k I d :$ {tsl.event.identifier}
ack	int	是	-
params	object	是	-
├─ time	long	否	属性上报时间戳，类型为 UTC 毫秒级时间
├─ value	object	是	上报的具体数据
│ ├─ deviceUid	string	是	设备 Uid
│ ├─ timeStamp	string	是	时间：示例：2024-06-28T12:12:12+08:00
│ ├─ version	string	是	协议版本
│ └─ data	object	是	不同接口对应的不同参数

示例：

{
  "id": "1111",
  "version": "1.0",
  "sys": {
    "ack": 1
  },
  "identifier": "deviceHeartBeat",
  "params": {
    "value": {
      "deviceUid": "RKFRT00000000090C2103EC4",
      "timeStamp": "2024-05-13T07:08:09+08:00",
      "version": "1.0",
      "data": {
        "deviceTime": "2024-05-13T07:08:09+08:00",
        "authorityCount": 1,
        "unuploadRecordsCount": 1,
        "devicePort": 8090,
        "scheme": "http"
      }
    },
    "time": 1524448722000
  },
  "method": "thing.event.up"
}

事件回复

主题：sys/{product_id}/{device_id}/thing/event/up/response
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
version	string	是	与请求参数中 version 相同
method	string	是	与请求参数中 method 相同
code	int	是	结果状态码：200- 成功，460- 物模型校验失败，400- 设备未上线
message	string	是	返回结果信息：请求成功时，返回 success
data	object	否	请求成功时，返回的数据固定为空
├─ code	int	是	返回枚举：0- 成功、1- 处理异常、2- 参数错误
├─ msg	string	是	枚举对应信息
├─ timeStamp	string	是	时间：示例：2024-06-28T12:12:12+08:00
└─ version	string	是	协议版本号

示例：

{
  "code": 200,
  "data": {
    "code": 0,
    "msg": "OK",
    "timeStamp": "2024-05-13T07:08:09+08:00",
    "version": "1.0",
    "data": {
      "serverTime": "2024-05-13T07:08:09+08:00"
    }
  },
  "id": "123",
  "message": "success",
  "method": "thing.event.up",
  "version": "1.0"
}

2.7 服务下发

服务下发

主题：sys/{product_id}/{device_id}/thing/service/set
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
version	string	是	协议版本号：目前协议版本号唯一取值为 1.0
method	string	是	请求方法：例如 thing.service.set
identifier	string	是	为物模型中定义的事件标识符，若为自定义模块，则 $t s l . f u n c t i o n Bl oc k I d :$ {tsl.event.identifier}
params	object	是	-
├─ deviceUid	string	是	设备 Uid
├─ timeStamp	string	是	时间：示例：2024-06-28T12:12:12+08:00
├─ version	string	是	协议版本
└─ data	object	是	不同接口对应的不同参数

示例：

{
  "id": "123",
  "version": "1.0",
  "identifier": "upgradeApp",
  "params": {
    "deviceUid": "RKFRT00000000090C2103EC4",
    "timeStamp": "2024-05-13T07:08:09+08:00",
    "version": "1.0",
    "data": {
      "appUrl": "http://192.168.11.100:100/download/apks/20200407160005.apk"
    }
  },
  "method": "thing.service.set"
}

服务回复

主题：sys/{product_id}/{device_id}/thing/service/set/response
参数：

参数名称	类型	是否必填	说明
id	string	是	消息 ID：用于标识每一条 Payload，每个消息 ID 在当前设备中具有唯一性
version	string	是	与请求参数中 version 相同
method	string	是	与请求参数中 method 相同
identifier	string	是	为物模型中定义的事件标识符，若为自定义模块，则 $t s l . f u n c t i o n Bl oc k I d :$ {tsl.event.identifier}
code	int	是	结果状态码：200- 成功，460- 物模型校验失败，400- 设备未上线
message	string	是	返回结果信息：请求成功时，返回 success
data	object	否	请求成功时，返回的数据固定为空
├─ code	int	是	返回枚举：0- 成功、1- 处理异常、2- 参数错误
├─ msg	string	是	枚举对应信息
├─ timeStamp	string	是	时间：示例：2024-06-28T12:12:12+08:00
└─ version	string	是	协议版本号

示例：

{
  "code": 200,
  "identifier": "upgradeApp",
  "data": {
    "code": 0,
    "msg": "OK",
    "timeStamp": "2024-05-13T07:08:09+08:00",
    "version": "1.0",
    "data": null
  },
  "id": "123",
  "message": "success",
  "method": "thing.service.set",
  "version": "1.0"
}

三、人脸门禁物模型

3.1 属性

参数名称	类型	是否必填	说明
displayName	string	是	设备名称
deviceCode	string	是	设备编号
heartBeatInterval	int	是	设备心跳时间间隔(毫秒)，默认：20*1000
appVersion	string	是	设备软件版本（只读）
hardVersion	string	是	设备硬件版本（只读）
firmwareVersion	string	是	设备固件版本（只读）
deviceUid	string	是	设备唯一标识（只读）
deviceIp	string	是	设备 ip（只读）
deviceMac	string	是	设备 mac（只读）
netmask	string	是	设备子网掩码（只读）
gateway	string	是	设备默认网关（只读）
dnsAddress	string	是	DNS 服务器地址（只读）
deviceType	int	是	设备类型（只读）：1- 仅身份识别、2- 普通门禁、3- 高级门禁、4- 消费、99- 其他
ntpAddress	string	是	ntp 地址(用于同步时间)，格式：ip:port
minFacePixelLevel	int	是	识别距离挡位：1- 最近 15- 近 25- 中 35- 远 100- 最远，建议 100
authorityCount	int	是	设备当前权限数量
unuploadRecordsCount	int	是	尚未上报的记录数

3.2 事件

设备上报事件汇总表

事件名(identifier)	说明
noticeDeviceStatus	设备级状态通知
uploadAuthResult	上报身份数据处理结果
noticeOfResetAuthorityData	设备级事件通知
uploadRecords	上报记录
acessPermissionCheck	在线判权
uploadDoorStatus	上报门磁状态
syncDeviceParams	双向同步
callElevator	呼梯
requestDeviceSecrets	请求加密密钥

1. 上报记录

场景：设备上报
事件名：uploadRecord
请求参数：

参数名称	类型	是否必填	说明
recordTime	string	是	记录时间，示例：2024-06-26T12:21:12+08:00
recordId	int	是	设备机内存储记录号
traceId	string	否	追溯 id
deviceUid	string	是	设备 uid
uniqueCode	string	是	人员唯一标识（非验权限为 0）
verifyMode	int	是	凭据验证方式：1-刷卡，2-刷脸，4-刷指纹，8-刷二维码，16-刷证件
proofs	object[]	是	凭据验证具体数据
type	int	是	凭据类型
number	string	是	凭据号
workType	int	是	设备用途：1-仅身份识别、2-普通门禁、3-高级门禁、4-消费、99-其他
personType	int	是	人员类型：0-一卡通系统员，1-访客，2-陌生人，99-其他
similarityScore	string	否	相似度分数
similarityThreshold	string	否	相似度阈值
qualityScore	string	否	质量分分数
qualityThreshold	string	否	质量分阈值
isAlive	int	否	是否活体：0-不支持 1-打开 2-关闭
inOutFlag	int	是	门点进出标记
passPhoto	string	否	抓拍照 base64：照片大小不超过 300kb
passPhotoUrl	string	否	通行抓拍照片的 url 相对路径地址
accessCode	int	否	事件代码，参见《枚举说明》事件代码
accessResult	string	否	事件代码描述

示例：

{
  "id": "123",
  "version": "1.0",
  "sys": {
    "ack": 1
  },
  "identifier": "uploadRecords",
  "params": {
    "value": {
      "data": {
        "deviceUid": "RKFRT00000000090C2103EC4",
        "timeStamp": "2024-05-13T07:08:09+08:00",
        "version": "1.0",
        "recordId": 10001,
        "recordTime": "2024-05-13T07:08:09+08:00",
        "deviceUid": "85AD0E",
        "uniqueCode": "92350231",
        "verifyMode": 1,
        "proofs": [
          {
            "type": 1,
            "number": "123465"
          }
        ],
        "deviceType": 2,
        "personType": 0,
        "similarityScore": "75.68",
        "similarityThreshold": "75.00",
        "qualityScore": "83.59",
        "qualityThreshold": "80.00",
        "isAlive": 0,
        "inOutFlag": 0,
        "passPhoto": "",
        "accessCode": "100",
        "accessResult": "开门成功",
        "passPhotoUrl": ""
      },
      "time": 1524448722000
    }
  },
  "method": "thing.event.up"
}

回复参数：无
示例：

{
  "code": 200,
  "data": {
    "code": "0",
    "msg": "OK",
    "timeStamp": "2024-05-13T07:08:09+08:00",
    "version": "1.0",
    "data": null
  },
  "id": "123",
  "message": "success",
  "method": "thing.event.up",
  "version": "1.0"
}

2. 请求加密密钥

场景：设备上报
事件名：requestDeviceSecrets
请求参数：

{
  "id": "123",
  "version": "1.0",
  "sys": {
    "ack": 1
  },
  "identifier": "requestDeviceSecrets",
  "params": {
    "deviceUniqueCode": "RKFRT00000000090C2103EC4",
    "timeStamp": "2024-05-13T07:08:09+08:00",
    "version": "1.0",
    "data": null
  },
  "method": "thing.event.up"
}

回复参数：

参数名称	类型	是否必填	说明
object[]	object	是	密钥
keyType	int	是	算法类型：0-不加密，1-3DES 加密
keyCode	int	是	算法密钥编号
keyData	string	是	算法密钥数据：Base64 格式

示例：

{
  "code": 200,
  "identifier": "requestDeviceSecrets",
  "data": {
    "code": "0",
    "msg": "OK",
    "timeStamp": "2024-05-13T07:08:09+08:00",
    "version": "1.0",
    "data": [
      {
        "keyType": 1,
        "keyCode": 0,
        "keyData": "GDJHJGJGYUWGUIFHUFSILGHIUY#IU"
      },
      {
        "keyType": 2,
        "keyCode": 1,
        "keyData": "dfkjadhfkjasdfkasdhfkj#IU"
      }
    ]
  },
  "id": "123",
  "message": "success",
  "method": "thing.event.up",
  "version": "1.0"
}

四、服务

4.1 获取设备参数

场景：服务端下发
服务名：getModuleDeviceParams
请求参数：

参数名称	类型	是否必填	说明
moduleNames	string[]	是	参数模块名称集合，当为空数组时，返回所有模块参数。

模块参数详情（部分示例）：

模块名称	说明
basic	基础
verification	身份验证
syncTime	时钟同步

请求示例：

{
  "id": "123",
  "version": "1.0",
  "identifier": "getModuleDeviceParams",
  "params": {
    "deviceUniqueCode": "RKFRT00000000090C2103EC4",
    "timeStamp": "2024-05-13T07:08:09+08:00",
    "version": "1.0",
    "data": {
      "moduleNames": [
        "basic",
        "verification"
      ]
    }
  },
  "method": "thing.service.set"
}

4.2 设置设备参数

场景：服务端下发
服务名：setModuleDeviceParams
请求参数：

参数名称	类型	是否必填	说明
xxx	object	是	取值 -> 参数模块名称，例如：basic

请求示例：

{
  "id": "123",
  "version": "1.0",
  "identifier": "setModuleDeviceParams",
  "params": {
    "deviceUniqueCode": "RKFRT00000000090C2103EC4",
    "timeStamp": "2024-05-13T07:08:09+08:00",
    "version": "1.0",
    "data": {
      "basic": {
        "deviceName": "测试设备"
      }
    }
  },
  "method": "thing.service.set"
}

五、枚举说明

5.1 事件代码

类别	AccessCode	AccessResult
刷脸	0	刷脸成功
刷脸	1	人脸过期失效
刷脸	2	刷脸活体验证失败
通用	989	开门超时
通用	990	超级密码错误
通用	991	超级密码开门成功
通用	992	开门成功
通用	993	非法人
通用	994	无权限
通用	995	过期限
通用	996	无时限
通用	997	常闭未通过
通用	998	互锁刷卡未通过
通用	999	未定义返回
刷卡	2000	刷卡成功
刷卡	2001	卡片过期失效
扫二维码	3000	扫码成功
扫二维码	3001	二维码过期失效
刷脸+刷卡	4000	卡+人脸识别成功
刷脸+刷卡	4001	卡+人脸过期失效
刷脸+刷卡	4002	卡+人脸活体验证失败
事件	5000	门磁超时事件
事件	5001	门磁超时恢复事件
事件	5002	强行闯入事件
事件	5003	超级密码开门事件
事件	5004	超级密码错误事件
事件	5005	远程开门事件
事件	5006	按键开门事件

人脸门禁终端物模型协议 V1.0

一、简介#

二、物模型约定#

2.1 心跳#

上报#

回复#

2.2 时间校准#

上报#

回复#

2.3 属性上报#

上报#

上报回复#

2.4 属性获取#

获取#

获取回复#

2.5 属性设置#

设置#

设置回复#

2.6 事件上报#

事件上报#

事件回复#

2.7 服务下发#

服务下发#

服务回复#

三、人脸门禁物模型#

3.1 属性#

3.2 事件#

设备上报事件汇总表#

1. 上报记录#

2. 请求加密密钥#

四、服务#

4.1 获取设备参数#

4.2 设置设备参数#

五、枚举说明#

5.1 事件代码#