PUSH-SDK通信协议V2.3-2013-02

深圳市中控生物识别技术有限公司ZKZKSoftwareBiometricIdentificationTechnologyCo.,LTD(Shenzhen)第1页共37页PUSHPUSHPUSHPUSHSDKSDKSDKSDK通信协议通信协议通信协议通信协议V2.V2.V2.V2.3333.X.X.X.X编制：杨小龙日期：2013-02-18审核：日期：案卷号案卷号案卷号案卷号日期日期日期日期深圳市中控生物识别技术有限公司ZKZKSoftwareBiometricIdentificationTechnologyCo.,LTD(Shenzhen)第2页共37页批准：日期：深圳市中控生物识别技术有限公司ZKZKSoftwareBiometricIdentificationTechnologyCo.,LTD(Shenzhen)第3页共37页修修修修订订订订记记记记录录录录修订人修订日期版本/次页次修订章节内容生效日期饶家志2010-10-23V2.0饶家志2010-12-13V2.0.1第7页向服务器发送设备语言标识第8页【允许传输数据种类】恢复为固件，服务器与文档的统一杨小龙杨小龙杨小龙杨小龙2011-07-252011-07-252011-07-252011-07-25V2.1.1V2.1.1V2.1.1V2.1.1第第第第8888页页页页支持软件与固件绑定功能，向服务器发送支持软件与固件绑定功能，向服务器发送支持软件与固件绑定功能，向服务器发送支持软件与固件绑定功能，向服务器发送绑定密钥绑定密钥绑定密钥绑定密钥杨小龙2011-08-12V2.2.0BS考勤固件完善新增功能杨小龙2013-02-18V2.3.0新增对账命令深圳市中控生物识别技术有限公司ZKZKSoftwareBiometricIdentificationTechnologyCo.,LTD(Shenzhen)第4页共37页1111引言引言引言引言1111....1111编写目的编写目的编写目的编写目的本说明书是客户和开发者对原型设计说明，是开发者进行后续软件开发工作的依据。1.21.21.21.2设计原则设计原则设计原则设计原则以原来PUSHSDK协议及ADMS，ZKTime7.0，ZKECO服务器为基础。并进行适当优化，完善并新增部分功能。1.31.31.31.3术语说明术语说明术语说明术语说明上传：本文档的上传是指从设备发送数据到服务器中。下载：本文档的下载是指从服务器下载数据到设备中。深圳市中控生物识别技术有限公司ZKZKSoftwareBiometricIdentificationTechnologyCo.,LTD(Shenzhen)第5页共37页2222总体设计总体设计总体设计总体设计2.12.12.12.1系统结构系统结构系统结构系统结构服务器：支持ADMS，ZKNET，ZKTime7.0,Att2008等软件指标：�支持目前黑白屏/3.5/3/8寸彩屏主流固件�规范和完善服务器端访问接口深圳市中控生物识别技术有限公司ZKZKSoftwareBiometricIdentificationTechnologyCo.,LTD(Shenzhen)第6页共37页�支持自适应不同固件的数据库访问接口�支持所有时区（包括半时区）�支持考勤记录自动上传�支持考勤照片自动上传�支持系统日志自动上传�支持修改/新增用户信息自动上传（包括用户基本信息，指纹，指纹图片指纹图片指纹图片指纹图片等）�支持考勤记录（照片照片照片照片）溢出时自动删除部分最久数据（删除数量可配置）�支持服务器端通知命令接收功能（UDP命令通知，需网络支持）�支持服务器下发系统命令（如ls等）�支持服务器端检查设备数据更新情况�支持服务器端清除设备上的考勤记录，考勤照片及所有数据信息（包括考勤记录，考勤照片，用户信息等）�支持服务器端获取设备的基本信息�支持服务器端设置设备选项�支持服务器端重新启动设备�支持服务器端控制设备重新加载设备选项�支持从服务器端控制设备开门锁�支持服务器取消设备的报警信息�支持服务器检测并传送新数据�支持服务器读取设备内文件�支持服务器下载文件到设备（包括固件升级）深圳市中控生物识别技术有限公司ZKZKSoftwareBiometricIdentificationTechnologyCo.,LTD(Shenzhen)第7页共37页�支持从服务器端新增/修改/删除设备上的用户信息及指纹�支持从服务器操作设备登记用户指纹(暂不包括人脸识别系列机器)�支持域名解析����支持设备访问认证机制支持设备访问认证机制支持设备访问认证机制支持设备访问认证机制����支持服务器设置设备的组合开门及时间段支持服务器设置设备的组合开门及时间段支持服务器设置设备的组合开门及时间段支持服务器设置设备的组合开门及时间段����支持支持支持支持HTTPSHTTPSHTTPSHTTPS����支持指纹图片自动上传支持指纹图片自动上传支持指纹图片自动上传支持指纹图片自动上传����支持从服务器下载短信到设备（修改）����支持考勤数据自动校对功能�支持从服务器下载/删除用户照片�支持上传设备上某时间段内的考勤记录或考勤照片�支持从服务器查询设备上的用户基本信息，不包含指纹和人脸等其他信息�支持异地考勤�支持人脸模板上传和下载及删除�支持后台比对（卡和指纹）�支持对账命令注意：注意：注意：注意：1.1.1.1.本文档斜体加粗部分为后续版本将新增加（即设计文档包含但未实现）的功能本文档斜体加粗部分为后续版本将新增加（即设计文档包含但未实现）的功能本文档斜体加粗部分为后续版本将新增加（即设计文档包含但未实现）的功能本文档斜体加粗部分为后续版本将新增加（即设计文档包含但未实现）的功能2.本文档蓝色字体为BS考勤固件完善项目新增或修改功能。3.本文档深红色字体为增加对账命令深圳市中控生物识别技术有限公司ZKZKSoftwareBiometricIdentificationTechnologyCo.,LTD(Shenzhen)第8页共37页2.22.22.22.2运行环境运行环境运行环境运行环境详细说明参见《需求分析说明书》。深圳市中控生物识别技术有限公司ZKZKSoftwareBiometricIdentificationTechnologyCo.,LTD(Shenzhen)第9页共37页3333功能详述功能详述功能详述功能详述3.13.13.13.1PUSHPUSHPUSHPUSHSDKSDKSDKSDK协议流程图协议流程图协议流程图协议流程图3.23.23.23.2PUSHPUSHPUSHPUSHSDKSDKSDKSDK通信协议通信协议通信协议通信协议PUSHSDK是我们基于HTTP协议自主开发的一种通信协议，以设备主动访问服务器的机制进行数据传输。主要适应环境：网络较稳定，支持TCP/IP协议，例如普遍使用的局域网、万维网等。优点：优点：优点：优点：深圳市中控生物识别技术有限公司ZKZKSoftwareBiometricIdentificationTechnologyCo.,LTD(Shenzhen)第10页共37页1.新数据主动上传。2.有断点续传功能。3.基于该协议开发或开发扩展功能快捷、方便。缺点：缺点：缺点：缺点：仅支持TCP/IP通讯方式。注意：注意：注意：注意：所选用机型须带PUSHSDK功能。LEVELLEVELLEVELLEVEL：：：：WEB开发工程师。3.2.13.2.13.2.13.2.1设备与服务器通信设备与服务器通信设备与服务器通信设备与服务器通信设备与服务器之间的通信以HTTP协议进行，设备GET或POST数据到服务器，服务器则返回结果。除了发送特定文件内容以外，所有数据以纯文本的方式传送，多项内容之间以换行符“\n”分成多行，每项内容以换行符“\n”作为结束标记。在解析接收的文本时，如果以FieldName=Value的形式赋值内容，请根据FieldName读取Value值。接收文本包含的FieldName字段根据设备功能不同而不同。例如纯指纹机器在接收用户信息文本里面不包含卡信息，如果是支持射频卡功能的机器在接收用户信息文本中包含卡信息，示例如下。纯指纹机器用户信息：USERPIN=982Name=RichardPasswd=9822Grp=1TZ=支持射频卡指纹机器用户信息：USERPIN=982Name=RichardPasswd=9822Card=[09E4812202]Card=[09E4812202]Card=[09E4812202]Card=[09E4812202]Grp=1TZ=由于设备会根据HTTP头信息确认服务器是否正确回应和同步设备时间，因此服务器返回的数据必须具有标准HTTP头信息，例如:HTTP/1.1200OKContent-Type:text/plainDate:Thu,19Feb200815:52:10GMT下面的说明中，涉及到数据的格式化时，通常使用C语言格式化字符串进行表达，以%开始格式化规定字符，其中用到的格式如下：%d十进制有符号整数%s字符串%x,%X无符号以十六进制表示的整数可以在%和格式化规定字符之间插进数字（表示数据所占的最大位数）。例如:%3d表示输出3位十进制整型数，不够3位在前面填充空格，%8s表示输出8个字符的字符串，不够8个字符在前面填充空格。如果字符串的长度、或整型数位数超过说明的场宽,将按其实际长度输出。另外，若想在输出使用0填充，就应在场宽项前加个0，例如:%04d表示在输出一个小于4位的数值时,将在前面补0使其总宽度为4位。进行填充时，默认情况是在前面，如果想要在后面填充，场宽使用负数即可。3.2.23.2.23.2.23.2.2设备读取服务器上的配置信息设备读取服务器上的配置信息设备读取服务器上的配置信息设备读取服务器上的配置信息设备在开始与服务器进行数据通信前，需要读取服务器上的配置信息，然后根据服务器的要求进行通信。深圳市中控生物识别技术有限公司ZKZKSoftwareBiometricIdentificationTechnologyCo.,LTD(Shenzhen)第11页共37页设备发送：GET/iclock/cdata?SN=xxxxxx&options=all&pushver=2.1.1pushver=2.1.1pushver=2.1.1pushver=2.1.1&language=XX&pushcommkey=XXpushcommkey=XXpushcommkey=XXpushcommkey=XX其中，xxxxxx为设备序列号。2.1.1为当前PUSHSDK库协议版本，旧版本不支持协议版本号。XX表示语言标识，具体请参考固件语言标识说明。Pushcommkey为固件和软件绑定密码，通过专有工具写入机器中。如何判断支持固件和软件功能：根据pushver（pushsdk版本号），如果为2.1.1以上版本（包括2.1.1），则支持该功能。只需要通过专有工具写入密钥，该功能自动开启。语言标识说明参考如下：标识符说明83中文69英语……服务器返回（例）：GETOPTIONFROM:123456Stamp=82983982OpStamp=9238883PhotoStamp=9238833ErrorDelay=60Delay=30TransTimes=00:00;14:05TransInterval=1TransFlag=1111000000Realtime=1Encrypt=0ServerVer=3.4.12010-06-07TableNameStamp=XXXXXX其中：GETOPTIONFROM:后为对应设备的序列号Stamp为设备最后上传考勤记录的最新记录时间戳标记（旧版协议固件使用，新版保留未用）OpStamp为设备最后上传人员数据的最新操作记录时间戳标记（旧版协议固件使用，新版保留未用）PhotoStamp为设备最后上传验证现场照片的记录时间戳标记（旧版协议固件使用，新版保留未用）Er