JL-IDD-Z4综合门禁控制器开发说明书2
JL-IDD-Z4综合门禁控制器
开发说明书-通过HTTP协议交互
目录
1 文档内容简介
通过一个符合要求的HTTP/WEBSOCKET服务来控制设备。
控制器通过HTTP协议调用指定网页服务器,网页服务器按要求回复内容控制设备工作。
1.1 特别情况说明
控制器使用一些特殊卡号
ü 小于255的卡号用于表示事件,因此系统中不能使用小于255的IC/ID卡
ü 卡号666666表示模拟刷卡,可以配置指定信号被触发后,系统将此信号转换成卡号为666666刷卡
ü 卡号7777777表示过闸超时,用于实时上报表示刷卡后指定时间范围内没有通过闸机(需要在信号配置中指定哪一路信号连接的过闸红外检测信号)
ü 卡号111111111111111110表示所有身份证,使用此号授权后,所有身份证即可有此权限
2 API操作函数接口说明
详细信息参考文档《JL-IDD-Z4二次开发说明书-使用SDK开发包.doc》
3 框架内置服务
详细信息参考文档《JL-IDD-Z4二次开发说明书-使用服务软件.doc》
4 基于TCP/UDP协议交互
详细信息参考文档《JL-IDD-Z4二次开发说明书-通过TCP或UDP协议交互.doc》
5 基于HTTP/WEBSOCKET服务器交互
控制器支持通过HTTP或者WEBSOCKET通信来与服务器通信,从而实现使用局域网的网页服务器或者WEBSOCKET服务器或者互联网云上的服务器来管理设备。实现通过互联网向设备授权或者在线验证。
开发范例可参考如下目录
Php开发参考.php (重点关注processReq函数)
更多开源代码请联系销售人员
5.1 消息上报
1. 通过综合门禁控制器配置工具,做如下配置操作:
ü 根据要使用的协议选择配置控制器的通信方式,选择TCP客户端,并在“门禁配置”中启动选项38或者选项53。
ü 在TCP/UDP通信情况下,或者HTTP模式的长连接情况下,可勾选“08.网络连接检测”,启动控制器心跳检测功能。此时应用可以接收控制板上报的连接检测消息,来判断设备是否在线。
ü 如果只接收同步消息,则关闭选项“05允许设备自动主动上报刷卡记录”
ü 关闭选项“26.允许设备自动从计算机拉取权限记录”
ü 修改“电脑地址”为运行软件的地址,端口为软件监听的服务端口,默认为50000,通常需要将端口修改实际服务器端口,如80。
5.1.1 实时上报
5.1.1.1 HTTP实时上报
特定固件版本的控制器(或者v1486以后版本的固件通过配置“选项38-使用WEB服务器实时验证”,注意:只有打开此开关后本小节所述功能才会被启用,建议控制器使用固定IP地址不要使用DHCP动态分配)支持通过HTTP协议向指定IP和端口发送请求,请求URL格式为:
/dr/?d=0011631262|1|24884|7|2013-05-20 18:44:31|6|1|2|24884
控制器的这个上报请求和在浏览器地址栏输入如下地址效果类似
http://ip:port/dr/?d=0011631262|1|24884|7|2013-05-20 18:44:31|6|1|2|24884
其中ip和port为网页服务器的ip和端口
请求方式为GET,其中/dr/为请求的地址,参数d即是上报数据内容,不同的上报有不同的数据内容,详细信息参考本小节下各种上报的详细说明。
服务器可以返回特殊的文本来指示控制器做各种处理,具体参考后面的详细说明。
上报内容中的中文内容默认编码为GBK。
注意:HTTP1.1默认会保持长连接,如果网页服务器可以配置,请配置WEB服务器的TCP连接使用长连接,以保持控制器和服务器间的连接可以长期保持,否则在连接断开及恢复期间可能出现丢包的现象,实时上报消息只上报一次上报失败不会重传(需要确保上传成功请参考异步日志上报)。对于不能保证长连接的情况下,可尝试启动选项44缓解此问题。
注意:对于上报请求不建议返回空消息或者异常状态码,因为网页服务器可能因此自动断开与设备的长连接。如果没有需要返回的数据,可以在返回消息中包含heartbeatAck=1。
网页服务器的IP和端口由“综合门禁控制器工具”的“电脑地址”和“端口”来指定,并且要求控制板通信模式设置为“TCP客户端”(见下图)。其子地址固定为/dr/不可更改,因此需要网页服务器按此要求实现,如创建一个dr子目录,并在其下实现一个默认页面,此页面可接收并处理d参数,并返回包含特定指令的文本内容。注意网页服务器提供的请求地址内部实现不能使用HTTP状态码(如301)来指示客户端重定向跳转到新的地址,控制器不是普通浏览器,暂不支持此功能。
如果网页服务器的接口不能按本小节的要求实现,或者对数据有更多要求(如要求接收完整的身份证信息),则可以使用3.2章节描述的方式,通过软件转发调用的方式来实现间接与HTTP服务器交互。
5.1.1.1.1 HTTP刷卡实时上报
刷卡实时上报在控制器上刷卡后立即上报给服务器,上报的数据详细信息如下
/dr/?d=0011631262|1|24884|7|2013-05-20 18:44:31|6|1|2|24884
请求方式为GET,其中/dr/为请求的地址,参数d即是上报数据内容,以|分隔的各字段值为
卡号或者条码内容|类型标志1|控制器序号|控制器验证结果0表示控制器已经直接开门其它表示错误|刷卡时间|读头号|门号|方向1进2出|设备名称
ü 网页服务器可以通过返回指定内容来指示控制器开门。
open1=1000表示开启1号继电器1000毫秒
open1=0表示开启1号继电器,时长由控制器继电器的默认配置决定
open4=500 表示开启4号继电器500毫秒
open2=100;open3=100; 表示同时开启2号3号继电器100毫秒
控制器会搜索网页服务器返回的内容,寻找形如open?=n的内容(其中?为1-4,n为30-60000)作为开门指令进行处理,为了减少控制器处理压力,尽量减少不必要的返回数据。
在有openN参数的情况下,可以使用timeN=X表示连续开继电器N共X次,多次开关间的时间间隔可以用stopn=Y来控制(Y的单位为毫秒,没有stopn时默认使用200毫秒)。如
open1=1000;time1=5;stopn=500;
表示连续开继电器5次,每次开1秒,间隔时间500毫秒),从而实现刷一次卡或者条码连续进多人的团体票(此功能需要闸机设备支持计数,即控制器开N次继电器后,闸机能够自动放行N人)。
ü 如果控制板上外接了迪文DGUS显示屏,则可以将网页服务器返回的数据显示到屏幕上,通过如下方式指定显示内容
prompt=以^分隔多行并以$结尾的文本
默认同时在进出显示屏上显示指定内容,如果要指定显示内容的屏,可以通过
prompt-dir=?
其中1表示进入的屏显示指定内容,2表示离开的屏显示指定内容,3表示进出都显示指定内容,未指定则默认为3。另外,以
prompt-page=?
指定显示的页面号(页面号是迪文屏开发时设计的界面的编号,不指定则默认为1表示显示刷身份证信息的页面,注意显示身份证信息的页面中的姓名需要填UNICODE字符。0表示默认页面,2表示刷IC/条码结果显示的页面)。以
restore-page=?
指定显示超时后恢复到哪个显示页面号,通常是默认页面0,。以
restore-seconds=?
指定显示超时时间。
如restore-seconds=5& restore-page=0& prompt-page=2&prompt-dir=3&prompt=姓名1^性别2^卡号3^测试4^结果5^时间6^预留7^预留8$
表示在进和出两个屏上以页面2为背景显示数据并持续5秒,5秒后切换到页面0
ü 如果控制板是语音板(JL-IDD-Z4S)则可以指定播放板载语音,通过
sound=?
指定要播放的语音的索引号(从1开始),可以通过
loop=?
指定要播放的次数,如果不指定则默认为1次
如 sound=1&loop=2 表示播放“刷卡成功”2次。(默认序号1是刷卡成功)
ü 如果板上外接了TTS的语音芯片,则可以通过
tts=以$结束的文本
来指定TTS内容,指定的内容将被发送给语音芯片朗读播放
如 tts=您好,欢迎光临,今天是2016年3月25日$
ü 如果开门后应用想要知道是否有人过闸,可以通过判断过闸超时通知来实现。通过控制板的信号配置指定当前通道人员通过后的反馈信号,控制器在开门后指定时间内没有检测到人员通过信号,就会触发“过闸超时”通知。此通知将被模拟为特殊卡号7777777的刷卡实时通知上报给HTTP服务器。
ü 网页服务器返回控制文本给控制器后,默认情况下控制器执行完成操作后不会再给网页服务器发送结果,如果需要控制器发送执行结果,可以要返回内容是加入
cmdseq=xxxx
其中xxxx为1- 2147483647间的任意数字,表示当前消息的序号,可以由网页服务器任意指定。控制器收到的消息中如果包含此值,则控制器会在执行操作后向服务器发送操作结果通知消息,操作结果通知消息中将包含与请求消息一致的消息序号。
更多指令参考《JL-IDD-Z4二次开发说明书-使用SDK开发包.doc》中的 “支持的文本指令集”小节。
5.1.1.1.2 HTTP连接检测消息
启用选项45后,控制器可以定时向服务器发送连接心跳检测消息。连接检测请求使用 .heartbeat.标签头与普通刷卡区分,其后为连接检测消息内容。请求格式为:
GET /dr/?d=.heartbeat.控制器标志|超时配置时间|超时余时|已超时次数|控制器名称|控制器全局标志|固件版本
服务端可以通过返回含heartbeatAck=1字样的内容来对连接检测进行确认,向设备确认当前的通信连接是正常的。返回消息也可以包含其它任何控制指令。
具体可参考上面的TCP/UDP的连接检测消息说明
5.1.1.1.3 HTTP信号变化消息
启用选项45后,控制器可以在信号变化时可以向服务器发送连接信号变化消息。信号变化通知消息使用.signal.标签头与普通刷卡区分,其后为消息内容。请求格式为:
GET /dr/?d=.signal.变化前信号总值: 变化后信号总值|控制器标志|时间|信息配置1|信息配置2|信息配置3|信息配置4|信息配置5|信息配置6|信息配置7|信息配置8|设备名称|对端通信地址
具体可参考上面的TCP/UDP的信号变化消息说明。返回任意控制指令,如果没有需要返回的数据,可以返回heartbeatAck=1。
5.1.1.1.4 HTTP权限拉取消息
启用选项“26-允许设备自动从计算机拉取权限记录”后,控制器会定时向服务器发送权限拉取消息。权限拉取请求使用.getright.标签头与普通刷卡区分,其后为消息内容。请求格式为:
GET /dr/?d=.getright.设备全局标志|设备标志|设备名称|操作批次号
服务器收到消息后,返回需要下发的权限数据,如果没有数据需要返回,忽略此消息。权限数据的格式参考“3.1.2权限同步”小节的说明。
注意:权限信息的返回不能与其它控制信息混在一起。服务器不能在其它请求消息中回应权限信息。可以一次返回多条权限数据,数据直接合并在一起即可,一次返回的权限数据总数不能超过8条,或者以实际测试能够成功的数量为限。
5.1.1.1.5 HTTP权限处理结果消息
权限处理请求是拉取权限,服务器返回权限信息给控制器,控制器处理完成后发送通知给服务器。此通知使用.ackright.标签头与普通刷卡区分,其后为消息内容。请求格式为:
GET /dr/?d=.ackright.设备全局标志|设备标志|设备名称||操作批次号|结果码0表示成功
服务器收到消息后,才确认消息成功下发到控制器,如果没有收到此消息,则认为权限没有成功下发,下次控制器使用权限拉取消息获取权限信息时,需要继续返回未成功的权限信息。消息批次号与其对应的权限拉取消息的批次号相同。
返回任意控制指令,如果没有需要返回的数据,可以返回heartbeatAck=1。
5.1.1.1.6 HTTP取系统时间消息
取时间使用.gettime.标签头与普通刷卡区分,其后为消息内容。请求格式为:
GET /dr/?d=.gettime.控制器当前时间
如果控制器时间不需要调整,则忽略此消息,如果需要进行调整,则服务器可以通过返回如settime=YYY-MM-DD HH:MI:SS WEEKDAY字样的字符串(其中WEEKDAY为星期几,星期日为0,星期一到星期六为1-6),对控制器时间进行修改。比如
settime=2017-11-18 23:55:55 6
settime=2017-11-26 23:55:55 0
5.1.1.1.7 HTTP操作结果通知消息
如果服务器在返回给控制器的指示中使用cmdesq指定了消息序号,则控制器在执行命令后会向服务器发送操作结果通知消息。
操作结果通知使用.cmdret.标签头与普通刷卡区分,其后为消息内容。请求格式为:
GET /dr/?d=.cmdret.操作序号|success(0失败1成功)|设备时间|设备标志|设备名称|设备全局标志
返回任意控制指令,如果没有需要返回的数据,可以返回heartbeatAck=1。
5.1.1.1.8 其它HTTP消息
对于HTTP消息,约定请求参数以.XXXX.格式的内容开头(其中XXXX为任意小写英文字母),则表示是维护类消息,需要进行忽略或者特殊处理,以防止后面控制器添加新的消息时,WEB服务器出现处理异常。
建议对于符合此格式的消息,除正常处理的消息外,其它消息默认处理为返回heartbeatAck=1。
5.1.2 异步日志上报
5.1.2.1 HTTP异步日志上报
如果异步上报日志开关(选项05)打开,并且启用了选项38和选项45,则控制器会使用HTTP协议上报控制器上的历史日志。此上报使用.sendlog.标签头与普通刷卡区分,其后为消息内容。请求格式为:
n GET /dr/?d=.sendlog.日志序号|卡号|日志类型|设备标志|日志结果|时间|读头号|门号|方向|设备名称|日志类型|日志子类型|身份证芯片号|设备全局标志|身份证信息base64编码数据|身份证头像base64编码数据
服务器收到消息后,返回acklog=日志序号 确认消息成功处理,控制器才会开始下一条日志的上报,否则不停上报当前记录。
5.1.3 WEBSOCKET接口
Webscoket能够保证连接为长连接。控制器支持与websocket服务器交互,启动控制器连接到websocket需要进行如下配置:
n 配置控制器的区域服务器的ip地址和端口号为websocket的ip和端口
n 启用选项53则开启websocket相关功能。根据情况配置选项45,54,55。
启用websocket接口后,设备会尝试与区域服务器建立websocket连接。Websocket连接建立步骤如下:
n (Websocket规范)控制器向指定服务器发起请求建立HTTP连接
n (Websocket规范)服务器接收并建立连接
n (Websocket规范)控制器发送HTTP请求,要求切换协议
n (Websocket规范)服务器返回协议切换成功。此后的通信即以websocket协议交互。
n 成功切换协议后,控制器会发送一个“自我介绍”的消息包,格式如下:
device=00255|测试|1050195437276669|v1.1846-10|00001|20180620
各字段含义为 设备组号序号|设备名称|设备全局序号|固件版本信息|设备短序号|出厂日期
服务器可以回应heartbeatAck=1确认这个消息
根据选项情况,设备会以websocket方式发送其它消息数据给服务器。
n 如果启用了选项54,则刷卡时默认会发送实时上报消息,除非启用了选项07禁止。
n 如果启用了选项45,并在打开选项08的情况下,会发送连接检测信息
n 如果启用了选项45,并在打开选项05的情况下,会上报控制器上的异步日志
n 发送信息变化等其它控制器消息
Websocket消息除了有websocket特有的消息头外,消息内容与HTTP消息相同(包含HTTP消息头,使用 GET方式请求)。如:
GET /dr/?d=0135635499|1|00255|4|2018-05-31%2016:09:48|5|1|1|%B2%E2%CA%D4
HTTP/1.1
Host: 192.168.0.99
服务程序可以拆分字符串获取参数后进行处理。和处理HTTP请求一样,可以直接返回包含操作指示的字符串来指示控制器执行指定操作。如,返回open1=300表示开继电器1共300毫秒。
5.1.4 HTTP连接超时问题
对于服务器与控制器使用TCP或者HTTP协议交互的情况,为了判断控制器与服务器间的连接状况,控制器(v1868后的版本,不含v1868)可启用了TCP内置的Keep-alive机制(默认启用或者配置选项57启用),在连接成功建立并进行过一次收发数据后,控制器的网络芯片会在最后一次数据交互后的120秒(由配置的设备网络超时秒数决定,最大支持255*5=1275秒)后,发送Keep-alive包,对端服务在线则会自动回应ACK包(tcp内部自动实现不需要编写代码),控制器网络芯片会自动检测对端是否有回应包来判断网络连接是否正常。如果检测到网络连接异常,控制器会断开当前连接并尝试重连。超时时长配置值小于NAT的tcp连接超时时间时,启用此开关可用于防止NAT设备在连接未活动时主动清除连接信息。
n 对于一般TCP服务器,建议实现为长连接,并且在服务器scoket上启用TCP协议内置的Keep-Alive处理,从而实现:
u 防止网络中的NAT设备要连接没有活动时断开连接
u 防止异常断开的客户端占用服务器侧的端口
u 同时避免客户端端口重用后不能连接到服务器(服务器不知道客户端已经断开,认为当前已经存在与客户端指定端口的连接,这种情况下可能连接不上,或者连接上以后服务器主动断开连接,需要等待、或者客户端换其它端口连接、或者重新启动服务器才能正常连接)。v1883后的控制器会尝试以随机端口来连接服务器以规避此问题。
n 对于WEB服务器(常用的都是HTTP1.1,默认都是长连接,但服务器在指定时间内未收到请求数据则会自动断开连接),因此建议配置连接超时时间为120-3600秒,同时在控制器上启用“选项08.网络连接检测”,此选项启用后,控制器会定时发送HTTP的连接检测消息到服务器,在发送间隔小于服务器连接超时时间的情况下(同时也小于网络中所有NAT超时时间时),即可长期保持连接。控制器修改“网络连接检测发送时间间隔”的步骤如下:
ü 配置工具中点击“配置选项”,修改“网络”-“设备网络超时秒数”
ü 选择控制器后,点“保存配置”,新的配置值即会下发到控制器。
n 对于服务压力比较大的服务器,连接超时时间过大将影响性能,此时建议使用单独的websocket长连接来处理与控制器的数据交互。
n 常见WEB服务器连接超时时间配置方法
IIS配置:
网站-高级设置
修改httpd.conf文件
1. KeepAlive On
2. MaxKeepAliveRequests 300
重新启动
apachectl -k graceful
nginx本身仅支持一个keepalive_timeout 指令,其使用0值来停用keep-alive。
在http、server、location指令中添加指令
1. location /cqjt/ {
2. alias /url/var/www/html/;
3. keepalive_timeout 75;
4. expires 5m;
5. }
6 附表
详细信息参考文档《JL-IDD-Z4二次开发说明书.doc》