企盾守卫者JL-IDD-Z4综合门禁控制器开发说明书
JL-IDD-Z4综合门禁控制器
开发说明书
目录
1 文档内容简介
本文主要面向JL-IDD-Z4/JL-IDD-Z4S控制器的开发人员及维护人员，主要介绍如何使用工具软件或者二次开发包实现对控制器的管理。工具软件及开发包使用VC2008开发，提供了多种使用方式
1) 通过API使用开发包。
调用接口为c语言接口，默认调用方式为cdecl。同时也提供了stdcall和fastcall的接口，具体参考jlidd.h文件。
最终使用的系统中需要安装了vc2008的支持包，可以运行"综合门禁控制器工具"安装包中的 vcredist_x86/vcredist_x86.exe 安装
接口文件为jlidd.h，库文件为jlidd.lib。
提供vc,c#,Delphi,java的调用实例供参考，其它语言请自行调用
二次开发发布时需要包含如下文件和目录：
Img 解析出来的身份证图片目录
ACE.dll 基础支持动态库
config.ini 配置文件，可用于控制接口库内部行为
jlidd.dll 开发包接口动态库
WltRS.dll 解码身份证头像图片的动态库，软件侧未使用到身份证阅读器可以不用
MasterCom.dll IC读写支持库，未使用IC卡内存储权限(梯控)时可以不用
MasterRD.dll IC读写支持库，未使用IC卡内存储权限(梯控)时可以不用
以及需要在目标计算机上安装vc2008支持包，即vcredist_x86/vcredist_x86.exe
2) 通过OCX使用开发包。
使用控件jliddctrl.ocx，通过jl_call命令调用接口，参数格式与API的call操作相同。
使用控件提供的OnEventCall（1号事件）接收数据并处理，等同与API开发包中的回调函数
使用VC调用控件的代码参考jlidd-vcocx目录，使用网页调用控件代码参考“测试.html”
使用控件前需要注册控件，可以参考“注册控件.bat”
二次开发发布时需要包含如下文件和目录：
Img 解析出来的身份证图片目录
ACE.dll 基础支持动态库
config.ini 配置文件，可用于控制接口库内部行为
jliddctrl.ocx 开发包控件
WltRS.dll 解码身份证头像图片的动态库，软件侧未使用到身份证阅读器可以不用
MasterCom.dll IC读写支持库，未使用IC卡内存储权限(梯控)时可以不用
MasterRD.dll IC读写支持库，未使用IC卡内存储权限(梯控)时可以不用
以及需要在目标计算机上安装vc2008支持包，即vcredist_x86/vcredist_x86.exe
3) 使用工具软件自动实现特定功能
参考第3章的描述。
4) 通过协议直接操作设备，不使用开发包。
参考第4章相关描述，对开发技能有较高的要求。只开放部份功能，不提供技术支持，不保证后续设备及开发包与当前情况兼容。
5) 通过一个符合要求的HTTP/WEBSOCKET服务来控制设备。
请直接参考第5章相关描述，由控制器通过HTTP协议调用指定网页服务器，网页服务器按要求回复内容控制设备工作。
1.1 特别情况说明
控制器使用一些特殊卡号
ü 小于255的卡号用于表示事件，因此系统中不能使用小于255的IC/ID卡
ü 卡号666666表示模拟刷卡，可以配置指定信号被触发后，系统将此信号转换成卡号为666666刷卡
ü 卡号7777777表示过闸超时，用于实时上报表示刷卡后指定时间范围内没有通过闸机（需要在信号配置中指定哪一路信号连接的过闸红外检测信号）
ü 卡号111111111111111110表示所有身份证，使用此号授权后，所有身份证即可有此权限
2 API操作函数接口说明
通过调用SDK开发包的API来实现对控制器的操作，这种方式适用于局域网内电脑软件主动向控制器发起命令，控制器返回响应数据的情况。
SDK底层以c语言实现，可以直接调用（提供头文件和lib文件），也提供了OCX形式的封装来被其它语言调用，对于java可通过jni来调用。
详细信息参考文档《JL-IDD-Z4二次开发说明书-使用SDK开发包.doc》
3 框架内置服务
免费工具中自带的软件UdpHostService.exe自带一些功能，通过配置后直接使用。
用户只需要按照指定格式写文本数据到权限同步文件，即可实现对设备授权、回收、清除权限。
用户只需要修改白名单.txt和黑名单.txt中的内容，当设备上刷卡后，设备可以把刷卡信息上报给服务程序，服务程序会查询黑白名单文件后，自动判断并远程开门。
详细信息参考文档《JL-IDD-Z4二次开发说明书-使用服务软件.doc》
4 基于TCP/UDP协议交互
不需要使用开发包，使用任何支持网络socket通信的语言即可开发。
使用UDP协议时，软件要向设备IP地址的65534端口发送指令，设备会将响应数据返回到发送端口
使用TCP协议时，控制器可以配置为工作在“客户端”或者“服务器”模式下，工作在客户端模式下（通常是这种模式）时，控制器会主动连接到服务器IP和50000端口（需要预先在设备上指定服务器的IP和端口），如果服务器上有软件监听了此端口，就会成功建立通信连接。对于控制器工作在“服务器”模式下时，需要软件主动连接服务器的IP和指定端口（默认为50000），建立连接后开始通信。
无论是UDP还是TCP协议，TCP协议时无论控制器是工作在客户端还是服务器模式下，都使用同样的通信数据格式。上面基于SDK开发方式中，最终SDK内部也是使用这种方式实现与控制器的通信的。
详细信息参考文档《JL-IDD-Z4二次开发说明书-通过TCP或UDP协议交互.doc》
5 基于HTTP协议交互
对于云服务器或者网页服务器，控制器可以使用HTTP/WEBSOCKET协议与其通信。
详细信息参考文档《JL-IDD-Z4二次开发说明书-通过HTTP协议交互.doc》
6 附表
6.1 身份证民族代码
身份证民族代码
01=汉族,02=蒙古族,03=回族,04=藏族,05=维吾尔族,06=苗族,07=彝族,08=壮族,09=布依族,10=朝鲜族,11=满族,12=侗族,13=瑶族,14=白族,15=土家族,16=哈尼族,17=哈萨克族,18=傣族,19=黎族,20=傈僳族,21=佤族,22=畲族,23=高山族,24=拉祜族,25=水族,26=东乡族,27=纳西族,28=景颇族,29=柯尔克孜族,30=土族,31=达斡尔族,32=仫佬族,33=羌族,34=布朗族,35=撒拉族,36=毛难族,37=仡佬族,38=锡伯族,39=阿昌族,40=普米族,41=塔吉克族,42=怒族,43=乌孜别克族,44=俄罗斯族,45=鄂温克族,46=崩龙族,47=保安族,48=裕固族,49=京族,50=塔塔尔族,51=独龙族,52=鄂伦春族,53=赫哲族,54=门巴族,55=珞巴族,56=基诺族,97=其他,98=外国血统
6.2 控制器错误码
控制器错误码，是用于实时上报消息或者刷卡日志中的错误码。
0=成功,2=时段错误,3=超次,4=无权限,5=读头错误,6=过期,7=工作模式禁止,8=内部错误,9=解析号码失败,10=过闸超时,11=反潜回,12=不支持,13=未知错误,14=失败,16=未注册或者注册过期,17=密码错误,18=错误的同步类型,19=错误的同步消息格式,20=同步数据限制,21=同步数据数量或者序号不规范,22=网络状态未知,23=网络断开,24=网络恢复,25=网络检查重启设备,26=网络检查重启芯片,27=防冲撞,28=门禁人工锁定,29=多门互锁,30=读写卡失败,31=组号错误,32=系统状态详情,33=黑名单,34=存储错误,35=未授权,36=在内人数过多,37=年龄限制,38=证件过期
6.3 控制器日期及时间结构
控制器存储及接口协议中，日期和时间分别各使用２个字节来存储，以xDate表示日期，xTime表示时间，下面介绍其各存储结构。
xDate和xTime各占用2字节，用于表示日期和时间，其内存存储方式如下
日期(YMD) /*年月日*/
|
位置 |
高位 低位 |
||
|
长度 |
7位 |
4位 |
5位 |
|
内容 |
Year(年) |
Month(月) |
Day(日) |
|
取值范围 |
0–119(relative to 2000) |
1–12 |
1–31 |
如B3 02 = 2018年4月16日
=>年=2018-2000=18，月=4，日=16，计算如下（其中<<?表示向高位移?位,即2进制时在原来的值后面补?个0）
=>18<<(5+4) + 4<<5 + 16 ，将数据转2进制表示为
=>10010<<9 + 100<<5 + 10000 ，移位后为
=>10010000000000 + 10000000 + 10000 ，计算三个二进制数据的算术和为
=>10010010010000，转成16进制为
=> 0x2490
=>我们要求低位在前，即实际按字节传输数据时，实际发送的两字节为90 24
上述步骤是为了方便理解，简单的说，照如下方式计算即可
=>(年-2000)* 512+月*32+日 算出来的值为9360，就是16进制0x2490，实际发送的两个字节为90 24
时间(HMS) /*时分秒*/
|
位置 |
高位 低位 |
||
|
长度 |
5位 |
6位 |
5位 |
|
内容 |
Hours(时) |
Minutes(分) |
2-second increments(2秒) |
|
取值范围 |
0–23 |
0–59 |
0-29 in 2-second intervals |
如0D 5D= 11时40分26秒，计算如下（其中<<?表示向高位移?位）
=>时11，分40，秒26/2=13
=>11<(5+6) + 40<<5 + 13 ，将数据转2进制表示为
=>1011<<11 + 101000<<5 + 1101，移位后为
=>101100000000000 + 10100000000 + 1101，计算
=>101110100001101，转16进制为
=> 0x5D0D
=>我们要求低位在前，即实际按字节传输数据时，实际发送的两字节为0D 5D
同样，上面的步骤实际照如下方式计算即可
=>时* 2048+分*32+秒/2 算出来的值为23821，就是16进制0x5D0D，实际发送的两个字节为0D 5D
6.4 控制器日志结构
typedef struct xLog
{
unsigned int high; //如果是刷卡记录，这里存的卡号高位
unsigned int low; //如果是刷卡记录，这里存的卡号低位
xDate rDate; //刷卡日期，参考附表日期的结构说明
xTime rTime; //刷卡时间，参考附表时间的结构说明
unsigned char door:3; //刷卡对应门号，值为1-4
unsigned char reader:5; //刷卡读头，值为1-4串口，5-8韦根
unsigned char result; //控制器验证结果。参考附表控制器错误码
unsigned char dir:2; //刷卡方向1进2出0未知
unsigned char type:6; //1事件，2刷卡日志，3操作日志。应用重点处理2
unsigned char isName:1;
unsigned char subType:5;
unsigned char extReader:2;
}xLog;
比如日志数据00 00 00 00 20 fb 6e 20 9c 24 37 5d 29 04 09 00
可以分析可以得知其对应记录信息为
卡号=00 00 00 00 20 fb 6e 20 =>0544144160
时间=9c 24 37 5d =>参考日期及时间结构，得出9c 24为018-04-28 ，37 5d为11:41:46
门号=29转二进制00101001，低3位为001，表示门1
读头=29转二进制00101001，高5位为00101，表示读头5
方向=09转二进制00001001，低2位01表示进入
类型=09转二进制00001001，高6位00010即2表示刷卡日志
控制器验证结果=04，参考控制器错误码得知其为，无权限
6.5 控制器权限结构
控制器权限的c语言结构体如下
typedef xRight {
unsigned int high; //卡号高位，对于普通ic卡，此值为0。对应上面数据的00 00 00 00。如果是身份证此值为身份证号码前8位的值（不算18位身份证号码的最后一位校验位），32位整数，低位在前，如身份证123456789012345677，high就是12345678，按顺序4个字节为4E 61 BC 00。
unsigned int low; //卡号低位，对应上面数据的d2 02 96 49。如果是身份证此值为后9位的值（不算18位身份证号码的最后一位校验位），32位整数，低位在前，如身份证123456789012345677，low就是901234567，按顺序4个字节为87 BF B7 35。
xDate bDate; //生效日期。对应上面数据的bf 20。格式见附表日期及时间结构。
xTime bTime; //生效时间。对应上面数据的00 00。格式见附表日期及时间结构。
xDate eDate; //失效日期。对应上面数据的21 3c。格式见附表日期及时间结构。
xTime eTime; //失效时间。对应上面数据的7d bf。格式见附表日期及时间结构。
unsigned char tz; //时段，默认为0。对应上面数据的00。0表示任意时段都可以通过，其它数值按位表示8个时段。
unsigned char reader; //可用读头，默认为255。对应上面数据的ff。其中由低到高共8位，分别表示串口1-4和韦根1-4共8个读头的可用状态，1表示可用，0表示不可用。即255表示全部可用，0表示全部不可用。4表示仅串口3可用其它不可用。使用综合门禁控制器工具的权限配置中的读头号后面的按钮，可以选择可用读头并计算此值。
unsigned short remain; //次数余额，默认为65535表示不限次。对应上面数据的ffff。0表示无权限；1-59999表示不分方向的总次数余额；60000到65050表示按方向限次，其中6ABCD中的AB表示进入限次值，CD表示外出限次值。如60102表示允许进1次出2次。注意，限次功能需要控制板选项19及选项（21或/和25）
unsigned int isName:1; //表示是否使用姓名替代卡号授权，默认为0。一般不使用，仅适用于刷身份证开门和车牌识别开门时，使用姓名和车牌号码当卡号使用。
unsigned int hasPackage:1; //是否有邮件，默认为0
unsigned int hasDebt:1; //是否有欠款，默认为0
unsigned int hasFlag1:1; //自定义标志，默认为0
unsigned int hasFlag2:1; //自定义标志，默认为0
unsigned int hasFlag3:1; //自定义标志，默认为0
unsigned int hasAntiback:1; //反潜回标志，默认为0
unsigned int reserved:16; //预留，默认为0
unsigned int grp:3; //人员分组，默认为0
unsigned int pos:2; //人员位置，默认为0
unsigned int manType:4; //人员类型，默认为0
}
例如：
如下控制器权限数据
00 00 00 00 d2 02 96 49 bf 20 00 00 21 3c 7d bf 00 ff ff ff 00 00 00 00
根据其结构分析可以得知其对应信息为
卡号=00 00 00 00 d2 02 96 49 =>1234567890
生效日期时间=bf 20 00 00，表示
日期0x20bf= 二进制0010000-0101-11111=16年5月15日。
时间0x0000=0点
失效日期时间=21 3c 7d bf，表示
日期0x3c21=0011110-0001-00001=30年1月1日
时间0xbf7d=10111-111011-11101=23点59分58(29*2)秒
6.6 支持的文本指令集
控制器支持如下文本指令，文本指令使用SDK的CMD_TEXT_CMD指令向设备发送，可以包含如下内容。
指令由指令前缀加上英文等号加指令内容组成，一次CMD_TEXT_CMD调用可以向控制器发送多个指令，多个指令间以英文分号间隔。指令内容大小写敏感。
下面是控制器支持的指令集合，下表中的指令前缀形如a[x-y]格式的，表示实际指令为ax到ay，如open[1-4]，实际控制器支持的是open1、open2、open3、open4这４个指令。
|
指令前缀 |
指令内容 |
说明 |
举例 |
|
open[1-4] |
开门时长，千分之一秒 |
开门（1-4号） |
1号门0.3秒,2号门0.5秒。open1=300;open2=500; |
|
time[1-4] |
开门次数 |
开门次数（1-4号门） |
1号门开５次。open1=300;time1=5; |
|
stopn |
时间间隔 |
多次开门的间隔 |
1号门开2次，间隔1秒。open1=300;time1=2;stopn=1000; |
|
sound |
语音序号 |
板载芯片放音 |
sound=1 |
|
soundNow |
存在此标签则表示要求发送的sound指令立即播放而不是放到待播队列 |
任意值 |
soundNow=1 |
|
loop |
次数 |
放音循环次数 |
1号语音放5次sound=1;loop=5; |
|
tts |
要语音播放的文本内容，以$结束 |
TTS放音 |
tts=您好，欢迎光临$ |
|
domain |
HTTP服务器主机名称。以$结束 |
指定HTTP上报主机名称 |
domain=www.abc.com$ |
|
debug |
1或者0表示开和关 |
调试开关 |
debug=1 |
|
runtimeAck |
上报消息Id |
实时上报接收确认 |
runtimeAck=2356 |
|
heartbeatAck |
1 |
收到对端心跳消息的确认 |
heartbeatAck=1 |
|
acklog或logAck |
日志Id |
日志确认 |
acklog=1237 |
|
settime或setTime |
日期时间，格式为YYY-MM-DD HH:MI:SS WEEKDAY字样的字符串（其中WEEKDAY为星期几，星期日为0，星期一到星期六为1-6 |
修改时间 |
settime=2017-11-18 23:55:55 6 |
|
setReportIp |
IP地址 |
设置上报服务器的IP地址 |
setReportIp=192.168.0.99 |
|
setReportPort |
端口 |
设置上报服务器的端口 |
setReportPort=50000 |
|
setGrpIndex |
设备组号序号值 |
设置组号序号 |
setGrpIndex=12345 |
|
setIp |
设备IP |
设置IP |
setIp=192.168.0.111 |
|
setMask |
设备子网掩码 |
设置掩码 |
setMask=255.255.255.0 |
|
setGate |
设备网关 |
设置网关 |
setGate=192.168.0.1 |
|
setIpMode |
0=TCP服务器,1=TCP客户端,2=UDP通信 |
设置IP通信方式 |
setIpMode=1 |
|
setIpAlloc |
0=固定IP,1=DHCP分配 |
设置IP分配方式 |
setIpAlloc=0 |
|
setName |
以$结束的设备名称，长度14字节内 |
设置设备名称 |
setName=北门1通道$ |
|
mask1 |
数值，范围0-0xffffffff，按位表示是否对选项1-32进行设置 |
选项掩码1-32 |
mask1=3表示对选项1和选项2进行设置，设置的新值由option1的对应位决定 |
|
mask2 |
数值，范围0-0xffffffff，按位表示是否对选项33-64进行设置 |
选项掩码33-64 |
mask=1表示对选项33进行设置，设置的值由option2的最低位决定 |
|
option1 |
数值，范围0-0xffffffff，按位表示选项1-32的是否勾选，1表示勾选，0表示不选 |
选项值1-32 |
option1=3 |
|
option2 |
数值，范围0-0xffffffff，按位表示选项33-64的是否勾选，1表示勾选，0表示不选 |
选项值33-64 |
option2=0 |
|
closeTimeout |
秒数，开门后指定秒数未关，则触发报警 |
设置关门超时时间 |
closeTimeout=15 |
|
alarmNotClose |
数字n，n=0表示未关门报警不触发继电器，n<16表示触发当前门号（继电器号）向后移n的继电器动作，n>16表示直接触发n整除16的余数的继电器（即用低4位直接指令触发的继电器号） |
设置门未关报警继电器 |
alarmNotClose=2 |
|
prompt |
提示信息内容，以^分隔多行并以$结尾的文本 |
设置显示屏提示信息 |
prompt=姓名1^性别2^卡号3^测试4^结果5^时间6^预留7^预留8$ |
|
prompt-dir |
其中1表示进入的屏显示指定内容，2表示离开的屏显示指定内容，3表示进出都显示指定内容，未指定则默认为3 |
要显示的方向 |
prompt-dir=1 |
|
prompt-page |
指定显示的页面号（页面号是迪文屏开发时设计的界面的编号，不指定则默认为1表示显示刷身份证信息的页面,注意显示身份证信息的页面中的姓名需要填UNICODE字符。0表示默认页面，2表示刷IC/条码结果显示的页面）。 |
显示页面号 |
prompt-page=2 |
|
restore-page |
数字，默认为0 |
显示超时后恢复的页面号 |
restore-page=0 |
|
restore-seconds |
数字，秒数 |
显示超时时间，即指令指定的页面会持续显示这个时长 |
restore-seconds=5 |
|
baund[1-4] |
取值为9600/19200/38400/57600/115200 |
4个串口的波特率 |
baund1=9600; baund2=115200; |
|
dev[1-4] |
0表示无设备，参考工程工具中的设备类型，取值为下拉列表内容的顺序号（从0开始） |
4个串口上接的设备的类型 |
dev1=16表示串口１外接的身份证阅读器 |
|
mode[1-8] |
参考工程工具串口设备或者韦根配置中的工作模式１，mode1-mode8表示4个串口和4个韦根读头的工作模式1的配置值 |
8个读头端口（1-4串口5-8韦根）工作模式1 |
mode1=3 表示在串口１上刷身份证直接开门，刷IC由控制器自主验证鉴权开门 |
|
dir[1-8] |
当前读头对应的出入方向,1进2出0未知 |
8个读头端口（1-4串口5-8韦根）的方向 |
dir1=1;dir2=2;dir3=1;dir4=2;指定串口读卡器1进，2出，3进，4出 |
|
door[1-8] |
当前读头对应的门（继电器）号，即是说此读头上刷卡如果鉴权成功，会触发的继电器号 |
8个读头端口（1-4串口5-8韦根）对应的门号 |
door1=1;door2=1;door3=1;door4=1;表示读头1-4刷卡成功都开继电器1 |
|
format[1-8] |
0表示默认。参考工程工具中的串口或者韦根的配置中的“韦根格式”，取值为下拉列表内容的顺序号（从0开始） |
8个端口（1-4串口5-8韦根）的韦根格式 |
format1=1表示自动将IC卡号转成WG26格式 |
|
sig[1-8] |
工程工具中的信号配置中的信号类型，取值为下拉列表内容的顺序号（从0开始） |
信号类型 |
sigdir1=2表示信号1用作开门按钮 |
|
sigdr[1-8] |
信号对应的门号 |
信号门号 |
sigdr1=1表示信号1关联1号门 |
|
sigdir[1-8] |
信号对应的方向或者门磁类型，取值为下拉列表内容的顺序号（从0开始） |
信号方向 |
sigdir=1表示进门 |
|
delay[1-4] |
继电器默认开门时长，单位为千分之一秒 |
继电器默认开门时长 |
delay1=3000;delay2=5000 |
|
powerReset_ |
固定为1 |
重新启动设备 |
powerReset_=1 |
|
clearData_ |
0清除配置，1清除权限，2清除证件缓存，3清除日志 |
清除数据 |
clearData_=1 |
|
clearRptPos |
0复位上报索引到日志起始，1复位上报索引到最新日志 |
复位上报索引 |
clearRptPos=0 |
|
clearIoStat |
固定为1 |
清除出入统计数据 |
clearIoStat=1 |
|
tztime[2-8] |
固定8位数字，前4位为起始时间时和分，后4位为结束时间时和分，如tztime2=10302300表示时段生效时间为10:30到23:00 |
设置时段的有效时间范围，时段1固定为全部禁止，2-8可自由配置 |
tztime2=10302300 |
|
tzweek[2-8] |
0-127的数字，按位表示周1到周7，0表示星期1-7都无效,127表示都有效 |
设置时段的有效工作日，时段1固定为全部禁止，2-8可自由配置 |
tzweek2=127 |