开发底层硬件应该怎么编写接口文档

开发底层硬件应该怎么编写接口文档

这几天在做超市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、串口参数举例明白：