MODBUS SDK用户手册.docx

1、MODBUS SDK用户手册1 函数库说明 31.1 简介： 31.2 提供的函数接口 31.2.1 以太网链路连接 31.2.2 串口链路连接 41.2.3 以太网与串口链路断开连接 51.2.4 以太网与串口链路的数据采集（读写） 52 错误代码 111函数库说明 1.1简介： ZModbusSdk函数库为标准的MODBUS(主机)协议提供函数接口。开发人员可以使用此函数库方便开发出遵循MODBUS协议的程序。如果需要开发MODBUS从机程序，开发人员需要使用其他的函数库或方法。 函数库在连接时使用对不同的链路层提供不同的函数接口如：以太网的为：ZMB_TCPConnectMDBServe

2、r,串口的为：ZMB_SerConnectMDBServer。其他的函数接口都相同，不区分连接链路。 （本文档中使用的术语服务器对应MODBUS协议里的从机模块，客户机对应MODBUS协议里的主机模块） 1.2提供的函数接口 ZModbusSdk提供了连接到从机（服务器）和读写线圈与寄存器的函数接口。 1.2.1以太网链路连接 ZMB_TCPConnectMDBServer 描述 调用此函数连接到从机模块（或服务器）。 HANDLE ZMB_TCPConnectMDBServer( char * szIp, int nDstPort, int nConnTimeout); 参数 szIp 指定

3、要进行连接的从机（服务器）的IP地址。 nDstPort 指定从机的端口号。 nConnTimeout 指定连接超时。 返回值 返回“非NULL”表示成功，否则为错误。 1.2.2串口链路连接 ZMB_SerConnectMDBServer（串口主机使用） 描述 调用此函数连接到从机模块（或服务器）。使用者应该注意对于串口的操作每个串口在同一时间只能打开一次，因此在操作串口时应该控制号程序使它每次只打开一次。 HANDLE ZMB_SerConnectMDBServer ( int iRtuAscii, char *szCom, int iBautRate, int iByteSize, in

4、t iParity, int iStopBits, int iDtrCtl, int iRtsCtl, int iCtsCtl, int iDsrCtl, int iResponse); 参数 iRtuAscii 模块工作方式：RTU:0, ASCII:1 szCom 需要打开的计算机串口。”COM1”,”COM2”, iBautRate 模块工作的波特率。9600,19200, iByteSize 模块工作的数据位。数据位数（字节表示4-8位） iParity 模块工作的校验位，奇偶校验 0-4：表示：不校验，奇校验，偶校验，标号，空格 iStopBits 模块工作的停止位，0(ONESTO

5、PBIT)表示1个停止位，1(ONE5STOPBITS)表示1.5个停止位，2(TWOSTOPBITS)表示2个停止位 iDtrCtl 模块是否需要DTR控制，0 不需要，1 需要 iRtsCtl 模块是否需要RTS控制，0 不需要，1 需要 iCtsCtl 模块是否需要CTS控制，0 不需要，1 需要 iDsrCtl 模块是否需要Dsr控制，0 不需要，1 需要 iResponse 模块的超时响应，默认 1000 ms 返回值 返回“非NULL”表示成功，否则为失败。 1.2.3以太网与串口链路断开连接 ZMB_DisConnectMDBServer 描述 调用此函数断开和从机的连接。 vo

6、id ZMB_DisConnectMDBServer(HANDLE hHand); 参数 hHand 此handle是ConnectMDBServer操作的返回值。 返回值 无。 1.2.4以太网与串口链路的数据采集（读写） ZMB_ReadCoil 描述 调用此函数按参数中的ID号和地址读取线圈状态。 long ZMB_ReadCoil( HANDLE hand, BYTE serID, int nStart, int nCount, BYTE * bRet/*arr of coils*/, WORD TranID ); 参数hand此handle是ConnectMDBServer操作的返回

7、值。serID设备ID号。nStart线圈的起始地址。nCount线圈的个数。bRet 返回的线圈状态，已分配号的数组地址。TranID在TCP的MODBUS协议里需要用到任务ID号，如果为0使用系统自生成的，串口MODBUS此参数无效。返回值返回0表示成功，否则为错误码。ZMB_ReadInput描述调用此函数按参数中的ID号和地址读取线圈状态（离散输入量数据）。long ZMB_ReadInput( HANDLE hand,BYTE serID, int nStart, int nCount, BYTE * bRet /*arr of coils*/, WORD TranID ); 参数

8、hand 此handle是ConnectMDBServer操作的返回值。 serID 设备ID号。 nStart 线圈的起始地址。 nCount 线圈的个数。 bRet 返回的线圈状态，已分配号的数组地址，此数组的大小应该和nCount指定的大小相同。 TranID 在TCP的MODBUS协议里需要用到任务ID号，如果为0使用系统自生成的，串口MODBUS此参数无效。 返回值 返回0表示成功，否则为错误码。 ZMB_ReadHoldReg 描述 调用此函数按参数中的ID号和地址读取保持寄存器的数据。 long ZMB_ReadHoldReg ( HANDLE hand, BYTE serID,

9、 int nStart, int nCount, WORD * bRet/*arr of reg*/, WORD TranID ); 参数 hand 此handle是ConnectMDBServer操作的返回值。 serID 设备ID号。 nStart 寄存器的起始地址。 nCount 寄存器的个数。 bRet 返回的寄存器数据，已分配号的数组地址，此数组的大小应该和nCount 一样。 TranID 在TCP的MODBUS协议里需要用到任务ID号，如果为0使用系统自生成的，串口MODBUS此参数无效。 返回值 返回0表示成功，否则为错误码。 ZMB_ReadInputReg 描述 调用此函数

10、按参数中的ID号和地址读取输入寄存器的数据。 long ZMB_ReadInputReg ( HANDLE hand, BYTE serID, int nStart, int nCount, WORD * Ret/*arr of reg*/, WORD TranID ); 参数 hand 此handle是ConnectMDBServer操作的返回值。 serID 设备ID号。 nStart 寄存器的起始地址。 nCount 寄存器的个数。 bRet 返回的输入寄存器数据，已分配号的数组地址，此数组的大小应该和nCount一样大。 TranID 在TCP的MODBUS协议里需要用到任务ID号，如

11、果为0使用系统自生成的，串口MODBUS此参数无效。 返回值 返回0表示成功，否则为错误码。 ZMB_WriteCoilSingle 描述 调用此函数按参数中的ID号和地址修改单个线圈状态。 long ZMB_WriteCoilSingle ( HANDLE hand, BYTE serID, int nAddress, WORD wWriteData, WORD TranID ); 参数 hand 此handle是ConnectMDBServer操作的返回值。 serID 设备ID号。 nAddress 线圈的起始地址。 wWriteData 写入的线圈数据：“0”，“1”。 TranID

12、在TCP的MODBUS协议里需要用到任务ID号，如果为0使用系统自生成的，串口MODBUS此参数无效。 返回值 返回0表示成功，否则为错误码。 ZMB_WriteCoilMulitiple 描述 调用此函数按参数中的ID号和地址修改nCount指定的多个线圈状态。 long ZMB_WriteCoilMulitiple ( HANDLE hand, BYTE serID, int nAddress, int nCount, BYTE * bWriteDataArr, WORD TranID ); 参数 hand 此handle是ConnectMDBServer操作的返回值。 serID 设备I

13、D号。 nAddress 线圈的起始地址。 nCount 写入的线圈的个数。 bWriteDataArr 写入的线圈数据的数组，数组的每个结构保存一个线圈状态，此数组大小应该和nCount指定的大小相同。 TranID 在TCP的MODBUS协议里需要用到任务ID号，如果为0使用系统自生成的，串口MODBUS此参数无效。 返回值 返回0表示成功，否则为错误码。 ZMB_WriteRegSingle 描述 调用此函数按参数中的ID号和地址修改单个保持寄存器数据。 long ZMB_WriteRegSingle ( HANDLE hand, BYTE serID, int nAddress, WO

14、RD wWriteData, WORD TranID ); 参数 hand 此handle是ConnectMDBServer操作的返回值。 serID 设备ID号。 nAddress 保持寄存器的地址。 wWriteData 写入的寄存器数据。 TranID 在TCP的MODBUS协议里需要用到任务ID号，如果为0使用系统自生成的，串口 MODBUS此参数无效。 返回值 返回0表示成功，否则为错误码。 ZMB_WriteRegMulitiple 描述 调用此函数按参数中的ID号和地址修改nCount指定多个保持寄存器。 long ZMB_WriteRegMulitiple ( HANDLE h

15、and, BYTE serID, int nAddress, int nCount, WORD * writeDataArr, WORD TranID ); 参数 hand 此handle是ConnectMDBServer操作的返回值。 serID 设备ID号。 nAddress 保持寄存器的起始地址。 nCount 写入的寄存器的个数。 bWriteDataArr 写入的寄存器数据的数组，数组的每个结构保存一个寄存器的值，此数组个数应该和nCount指定的个数相同，大小应该等于 nCount * 2 个字节。 TranID 在TCP的MODBUS协议里需要用到任务ID号，如果为0使用系统自生

16、成的，串口MODBUS此参数无效。 返回值 返回0表示成功，否则为错误码。ZMB_WriteCmdBuf描述 调用此函数写命令串，根据nAddCheck参数决定是否添加校验。其中TCP Modbus协议不会添加必要的头部，而串口Modbus则可以根据nAddCheck指定是否添加校验，校验的格式（CRC或LRC）由打开参数iRtuAscii指定，这里不需要再指定。 long ZMB_WriteCmdBuf ( HANDLE hand, BYTE *pBuf, int iLen, int nAddCheck ); 参数 hand 此handle是ConnectMDBServer操作的返回值。 p

17、Buf 写数据的缓冲区。 iLen 缓冲区长度。 nAddCheck 是否添加校验，只在串口中有效，如果打开时为RUT，且使用了添加校验，则添加CRC校验。如果打开时为ASCII，且使用了添加校验，则添加LRC校验。 TranID 在TCP的MODBUS协议里需要用到任务ID号，如果为0使用系统自生成的，串口MODBUS此参数无效。 返回值 返回写成功的长度。 ZMB_ReadRecBuf 描述 调用此函数读取设备的响应数据。 long ZMB_ReadRecBuf ( HANDLE hand, BYTE *pBuf, int iBufLen, int *iRecedLen ); 参数 han

18、d 此handle是ConnectMDBServer操作的返回值。 pBuf 读数据的缓冲区。 iBufLens 缓冲区的大小。 iRecedLen 接收到的数据的长度，（输出参数）。 TranID 在TCP的MODBUS协议里需要用到任务ID号，如果为0使用系统自生成的，串口MODBUS此参数无效。 返回值 返回读取到的长度。 2错误代码 ZModbusSdk使用了标准的MODBUS错误代码和自定义错误代码来描述SDK在操作过程中会出现的错误。在使用的过程中应该注意错误的定义，有些使用0作为成功的标志，而有些使用0作为错误的标志。标准MODBUS的读写操作都以ERROR_SUCCESS（0）

19、表示正确，Connect却以NULL（0）表示错误，特殊命令的读写返回的读写的数据长度。 错误码 错误含义 自定义错误码 0 成功 100 普通错误，未定义 101 不是MODBUS协议 102 TCP连接出错（可能主机不存在或本地网络有问题） 103 TCP发送命令出错（发送不成功，可能为网络问题） 104 TCP接收响应出错（可能指示不正确或网络有问题） 105 TCP发送命令超时未完成 106 TCP接收响应超时未完成 107 串口写出错 108 串口读出错 109 返回的功能码不是发出请求的功能码 200 发送不成功，如果出现这个错误，需要重新连接 201 读超时，可能是下位机响应不过，也可能是其他原因，需要具体分析 202 接收到非标准的MODBUS协议数据 标准MODBUS错误 1 未定义的功能码 2 地址出错 3 数据出错 0x81 读线圈出错 0x82 读离散输入量出错 0x83 读保持寄存器出错 0x84 读输入寄存器出错 0x85 写单个线圈出错 0x86 写单个寄存器出错 0x8F 写多个线圈出错 0x90 写多个寄存器出错