开发底层硬件应该怎么编写接口文档
这几天在做超市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、串口参数举例明白：
