开发底层硬件应该怎么编写接口文档
这几天在做超市RFID结算系统的上位机程序编写,用的是VB.NET。底层用的是别人开发好的SDK,为什么要写这一篇文章呢?最近因为手头设备的功能限制,我就在网上找其他的公司的RFID射频卡读写器,由于我是做上层开发,所以需要设备供应商提供底层SDK二次开发包,找了好多设备提供商 ,也跟他们索取各自提供的SDK,但总的来说,我还是觉得最先用的这个设备的厂家提供的SDK是最详细的,现在简单说明如下:
一、函数说明:
1、目录结构清晰:
2、函数返回值,参数用表格说明,清晰简洁:
3、参数类型说明详细:
4、变量在各个上位机编程环境中对应的变量类型(以VB.net为例):
5、错误码详细:
附录3. RFIDLIB API错误代码表
错误代码 | 描述 |
0 | 无错误,表示API调用成功。 |
-1 | 未知错误 |
-2 | 与读卡器硬件的通信失败 |
-3 | API的传入参数有误 |
-4 | API的传入参数的值不支持,如参数值只能是0-5,如果传入6那么会返回该错误。 |
-5 | 超时,发送到读卡器的命令,在设定时间内等不到数据返回。 |
-6 | API申请内存失败 |
-7 | 功能未开启 |
-8 | 保留 |
-9 | 保留 |
-10 | 保留 |
-11 | 保留 |
-12 | 读卡器返回的数据包长度有误 |
-13 | 保留 |
-14 | 保留 |
-15 | 保留 |
-16 | 保留 |
-17 | 读卡器返回操作失败标识数据包,可用API RDR_GetReaderLastReturnError 获取该失败的错误代码。 |
-18 | 保留 |
-19 | 保留 |
-20 | 保留 |
-21 | Inventory的停止触发器发生,举个例子:假设设定1秒为Inventory 的最大读卡时间,如果在1秒钟内还没读完所有的标签,读卡器会终止Inventory,那么API会返回该错误告诉应用程序,可能还有标签没读完。 |
-22 | 标签操作命令不支持 |
-23 | 传入RDR_SetConfig或RDR_GetConfig的配置项不支持。 |
-24 | 保留 |
-25 | TCP socket错误,API返回该错误表明TCP连接已断开。 |
-26 | 应用层传入的缓冲区太小。 |
-27 | 与读卡器返回的数据有误。 |
6、通用函数简介:
6.1. 通用函数介绍
序号 | 函数说明 | 介绍 |
1 | COMPort_Enum | 枚举windows 操作系统已加载的串口 |
2 | COMPort_GetEnumItem | 获取枚举到的串口名称 |
3 | RDR_LoadReaderDrivers | 加载所有的设备驱动库 |
4 | RDR_GetLoadedReaderDriverCount | 获取已加载的设备驱动的数量 |
5 | RDR_GetLoadedReaderDriverOpt | 获取已加载的设备驱动的参数值,包含的参数有驱动类别,名称,ID,支持的接口类型。驱动类别分为Reader(读卡器类),MTGate(会议签到门类),LSGate(图书馆安全门类) 。 |
6 | HID_Enum | 枚举已连接计算机的USB设备,需要传入设备驱动的名称。 |
7 | HID_GetEnumItem | 获取已枚举到的USB设备的信息,如系列号,驱动路径等。 |
8 | RDR_Open | 打开通信接口,并创建设备驱动实例。以下所有的API都需要传入驱动的实例句柄 |
9 | RDR_Close | 关闭通信接口,并销毁设备驱动实例。 |
10 | RDR_CreateInvenParamSpecList | 创建RDR_TagInventory的盘点参数列表的数据节点 |
11 | RDR_TagInventory | 盘点在射频感应的所有标签 |
12 | RDR_GetTagDataReportCount | 获取盘点到的标签数据报告的数量 |
13 | RDR_GetTagDataReport | 获取盘点到的标签数据报告 |
14 | RDR_TagDisconnect | 断开与标签的连接 |
15 | RDR_DisconnectAllTags | 断开所有与标签的连接 |
16 | RDR_GetReaderLastReturnError | 获取设备最后一次返回的错误代码 |
17 | RDR_SetAcessAntenna | 设置读写天线编号。对于多天线接口的读卡器,必须先调用该函数打开要读写的标签所在的天线。 |
18 | RDR_GetReaderInfor | 获取设备信息,已字符串的方式输出,信息参数的含义请查看相关设备驱动的”用户手册”。 |
19 | RDR_SystemReset | 控制设备重启,该功能不是所有设备都支持,请查看相关设备驱动的”用户手册”。 |
20 | RDR_LoadFactoryDefault | 控制设备恢复出厂设置,该功能不是所有设备都支持,请查看相关设备驱动的”用户手册” |
21 | RDR_OpenRFTransmitter | 打开射频输出,该功能不是所有设备都支持,请查看相关设备驱动的”用户手册” |
22 | RDR_CloseRFTransmitter | 关闭射频输出,该功能不是所有设备都支持,请查看相关设备驱动的”用户手册” |
23 | RDR_SetCommuImmeTimeout | 使API马上超时退出,该函数可用于线程快速退出。调用了该函数之后,在线程退出之前,需要调用RDR_ResetCommuImmeTimeout恢复超时标志。 |
24 | RDR_ResetCommuImmeTimeout | 恢复超时标志 |
25 | RDR_GetAntennaInterfaceCount | 获取天线接口数量 |
26 | RDR_GetOutputCount | 获取输出端口数量 |
27 | RDR_GetOutputName | 获取输出端口名称 |
28 | RDR_CreateSetOutputOperations | 创建输出端口的操作集数据节点,调用RDR_AddOneOutputOperation把输出端口的操作加入这操作集。 |
29 | RDR_AddOneOutputOperation | 加入输出端口的操作 |
30 | RDR_SetOutput | 根据输出端口的操作控制输出端口输出高低电平。 |
31 | RDR_ConfigBlockWrite | 配置信息写操作函数 |
32 | RDR_ConfigBlockRead | 配置信息读操作函数 |
33 | RDR_ConfigBlockSave | 配置信息保存操作函数 |
34 | RDR_CreateRS485Node | 在已打开的串口通信接口层的基础上,创建RS485的节点实例句柄。 |
35 | RDR_DetectNoise | 射频噪音检测 |
36 | RDR_GetGPICount | 获取通用输入端口的数量 |
37 | RDR_GetGPIsStatus | 获取通用输入端口的状态 |
38 | RDR_ExeSpecialControlCmd | 执行设备的特殊指令,设备支持哪些特殊指令请查阅设备的驱动的”用户手册”。 |
39 | RDR_SetEventHandler | 设置事件处理器 |
40 | DNODE_Destroy | 释放由动态库创建的内存,如:RDR_CreateInvenParamSpecList |
7、操作流程图
8、串口参数举例明白: