概述

    MQTT 是一种基于发布/订阅模式的通讯协议，该协议构是轻量、简单、开放，是低开销、低带宽占用的即时通讯协议。实名制考勤设备接口要求采用 MQTT 协议,协议版本为 v3.1.1。本文档主要用于实名制考勤设备和实名制平台交互数据的 mqtt 协议文档, 主要适用于集成开发与维护人员。

协议借鉴了德拓平台MQTT协议


通讯协议说明

MQTT 主题 Topic 主要有下面几个:

topic说明备注

mqtt/device/{CODE}/{ID}

指令下发主题, 考勤设备订阅,接收到之后处理命令;同时处理 mqtt 发送过来的回复信息


mqtt/device/{CODE}/{ID}/Ack

指令回复主题, 考勤设备处理指令后,返回值发往该主题


mqtt/device/{CODE}/{ID}/Rec

考勤机考勤记录发往该主题


mqtt/device/{CODE}/{ID}/heartbeat

考勤机心跳通知发往该主题


mqtt/device/{CODE}/{ID}/basic

上线,离线通知发往该主题



其中 CODE 表示对接设备类型编码（face 人脸机/crane 塔吊/lift 升降机/dust 扬尘）; ID 表示考勤设备的唯一 ID 号

每个对接厂商申请后,实名制平台会提供一个固定的代码 CODE +设备 ID 前缀码 + MQTT 信息(地址,账户和密码) + 实名制平台公钥;同时厂商需随机生成一个 RSA 密钥对,并将公钥提供给实名制平台, 私钥设备自己保留,用于加签

Mqtt 数据载体来回传输的数据格式均为标准的 JSON 格式;MQTT 连接的 clientID 需要和 mqtt/device/{CODE}/{ID} 中的 ID一致,注意前缀 也需要添加.


设备心跳

考勤设备主动增加心跳信息，将主动每间隔 60 秒左右推送心跳消息到主题 mqtt/device/{CODE}/{ID}/heartbeat 中。

心跳通知 => TOPIC= mqtt/device/{CODE}/{ID}/heartbeat

字段类型描述

operator

string

固定值 Basic

messageId

string

消息 id(最长 128 字符),回复会带回该值

info.deviceCode

string

设备号

info.time

string

心跳时间 2022-07-06 10:02:16

设备信息

设备上线后会主动发送

获取设备信息

指令下发<= mqtt/device/{CODE}/{ID}

字段类型描述

operator

string

固定值 Basic

messageId

string

消息 id(最长 128 字符),回复会带回该值


{
    "operator": "Basic",
    "messageId": "233333331111113"
}

设备信息

指令回复 => mqtt/device/{CODE}/{ID}/basic

字段类型描述

operator

string

Basic-Ack

messageId

string

消息 id

info.deviceCode

string

考勤设备号

info.version

string

版本名称

info.time

string

 2022-07-06 10:02:16
info.ip

string

设备ip

info.log

int

0 关闭 1 开启


{
    "info": {
        "deviceCode": "N71LA34430040",
        "ip": "172.16.3.32",
        "time": "2024-07-10 05:39:40",
        "version": "1.0.0.0"
    },
    "messageId": "123123123123",
    "operator": "Basic-Ack"
}

人员下发

人员增加或修改指令（单个）

指令下发 <= mqtt/device/{CODE}/{ID}

字段类型描述

operator

string

EditPerson

messageId

string

消息 id(最长 128 字符),回复会带回该值

info.id

string

人员id

info.name

string

姓名

info.idCard

string

身份证号码

info.picURI

string

图片url 二选一

info.picBase

string

图片base64 二选一

指令回复 => mqtt/device/{CODE}/{ID}/Ack

字段类型描述

operator

string

EditPerson-Ack

messageId

string

消息 id

info.deviceCode

string

考勤设备号 id

info.id

string

人员id

info.code

int

指令结果 200 非200则失败
info.msg

string

错误信息(code为 200有效)

人员增加或修改指令(批量)

指令下发 <= mqtt/device/{CODE}/{ID}

字段类型描述

operator

string

EditPersons

messageId

string

消息 id(最长 128 字符),回复会带回该值

info

array


info.id

string

人员id

info.name

string

姓名

info.idCard

string

身份证号码

info.picURI

string

图片url 二选一

info.picBase

string

图片base64 二选一

指令回复 => mqtt/device/{CODE}/{ID}/Ack

字段类型描述

operator

string

EditPersons-Ack

messageId

string

消息 id

info.deviceCode

string

考勤设备号 id

info.addErrNum

int

失败数量

info.addErrInfo

array


info.addErrInfo.id

int

人员id

info.addErrInfo.code

int

错误码

info.addErrInfo.msg

string

错误信息

info.addSucNum

array


info.addSucInfo.id

string

人员id

info.code

int

指令结果 200 非200则失败
info.msg

string

错误信息(code为 200有效)

清空人员指令

指令下发 <= mqtt/device/{CODE}/{ID}

字段类型描述

operator

string

DeleteAllPerson

messageId

string

消息 id(最长 128 字符),回复会带回该值

指令回复 => mqtt/device/{CODE}/{ID}/Ack

字段类型描述

operator

string

DeleteAllPerson-Ack

messageId

string

消息 id

info.deviceCode

string

考勤设备号 id

info.code

int

指令结果 200 非200则失败
info.msg

string

错误信息(code为 200有效)

删除人员指令

指令下发 <= mqtt/device/{CODE}/{ID}

字段类型描述

operator

string

DeletePersons

messageId

string

消息 id(最长 128 字符),回复会带回该值

info.id

array

人员唯一 ID,数组格式

指令回复 => mqtt/device/{CODE}/{ID}/Ack

字段类型描述

operator

string

DeletePersons-Ack

messageId

string

消息 id

info.deviceCode

string

考勤设备号 id

info.delErrNum

int

失败数量

info.delErrInfo

object


info.delErrInfo.id

int

人员id

info.delErrInfo.code

int

错误码

info.delErrInfo.msg

string

错误信息

info.delSucNum

object


infodelSucInfo.id

string

人员id

info.code

int

指令结果 200 非200则失败
info.msg

string

错误信息(code为 200有效)

远程升级

指令下发 <= mqtt/device/{CODE}/{ID}

字段类型描述

operator

string

Upgrade

messageId

string

消息 id(最长 128 字符),回复会带回该值

info.name

string

版本名称

info.path

string

 升级文件的下载 URI


{
    "operator": "Upgrade",
    "messageId": "233333333",
    "info": {
        "name": "1.0.0",
        "path": "http://file.jsske.com/face-app/2024_07_10_11_45_27/face-app"
    }
}


指令回复 => mqtt/device/{CODE}/{ID}/Ack

字段类型描述

operator

string

Upgrade-Ack

messageId

string

消息 id

info.deviceCode

string

考勤设备号 id

info.name

string

版本名称

info.code

int

指令结果 200 非200则失败
info.msg

string

错误信息(code为 200有效)


{
    "info": {
        "msg": "文件下载成功",
        "deviceCode": "N71LA34430040",
        "name": "1.0.0",
        "code": 200
    },
    "messageId": "1212121212",
    "operator": "Upgrade-Ack"
}


考勤推送

推送记录<= mqtt/device/{CODE}/{ID}/Rec

字段类型描述

operator

string

固定值  RecPush

messageId

string

消息 id(最长 128 字符),回复会带回该值

info.deviceCode

string

设备号

info.personID

string

人员id

info.personName

string

人员姓名

info.recordPicture

string

考勤图片

info.recordTime

string

考勤时间 2022-07-06 10:02:16

远程升级

指令下发 <= mqtt/device/{CODE}/{ID}

字段

类型

描述

operator

string

Upgrade

messageId

string

消息 id(最长 128 字符),回复会带回该值

info.name

string

版本名称

info.path

string

 升级文件的下载 URI


{
    "operator": "Upgrade",
    "messageId": "233333333",
    "info": {
        "name": "1.0.0",
        "path": "http://file.jsske.com/face-app/2024_07_10_11_45_27/face-app"
    }
}


指令回复 => mqtt/device/{CODE}/{ID}/Ack

字段

类型

描述

operator

string

Upgrade-Ack

messageId

string

消息 id

info.deviceCode

string

考勤设备号 id

info.name

string

版本名称

info.code

int

指令结果 200 非200则失败
info.msg

string

错误信息(code为 200有效)


{
    "info": {
        "msg": "文件下载成功",
        "deviceCode": "N71LA34430040",
        "name": "1.0.0",
        "code": 200
    },
    "messageId": "1212121212",
    "operator": "Upgrade-Ack"
}



参考协议