MODBUSSDK用户基础手册专业资料.doc

V1.00ZModbusSdk配备函数库使用手册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_TCPConnectMDBServer,串口为：ZMB_SerConnectMDBServer。其她函数接口都相似，不区别连接链路。 （本文档中使用术语服务器相应MODBUS合同里从机模块，客户机相应MODBUS合同里主机模块） 1.2 提供函数接口 ZModbusSdk提供了连接到从机（服务器）和读写线圈与寄存器函数接口。 1.2.1 以太网链路连接 ZMB_TCPConnectMDBServer 描述 调用此函数连接到从机模块（或服务器）。 HANDLE ZMB_TCPConnectMDBServer( char * szIp，int nDstPort，int nConnTimeout)；参数 szIp 指定要进行连接从机（服务器）IP地址。 nDstPort 指定从机端标语。 nConnTimeout 指定连接超时。 返回值 返回“非NULL”表达到功，否则为错误。 1.2.2 串口链路连接 ZMB_SerConnectMDBServer（串口主机使用） 描述 调用此函数连接到从机模块（或服务器）。使用者应当注意对于串口操作每个串口在同一时间只能打开一次，因而在操作串口时应当控制号程序使它每次只打开一次。 HANDLE ZMB_SerConnectMDBServer (int iRtuAscii，char *szCom，int iBautRate，int iByteSize，int 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(ONESTOPBIT)表达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 描述 调用此函数断开和从机连接。 void 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操作返回值。serID设备ID号。nStart线圈起始地址。nCount线圈个数。bRet 返回线圈状态，已分派号数组地址。TranID在TCPMODBUS合同里需要用到任务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)；参数 hand 此handle是ConnectMDBServer操作返回值。 serID 设备ID号。 nStart 线圈起始地址。 nCount 线圈个数。 bRet 返回线圈状态，已分派号数组地址，此数组大小应当和nCount指定大小相似。 TranID 在TCPMODBUS合同里需要用到任务ID号，如果为0使用系统自生成，串口MODBUS此参数无效。 返回值 返回0表达到功，否则为错误码。 ZMB_ReadHoldReg 描述 调用此函数按参数中ID号和地址读取保持寄存器数据。 long ZMB_ReadHoldReg (HANDLE hand，BYTE serID，int nStart，int nCount，WORD * bRet/*arr of reg*/，WORD TranID)；参数 hand 此handle是ConnectMDBServer操作返回值。 serID 设备ID号。 nStart 寄存器起始地址。 nCount 寄存器个数。 bRet 返回寄存器数据，已分派号数组地址，此数组大小应当和nCount 同样。 TranID 在TCPMODBUS合同里需要用到任务ID号，如果为0使用系统自生成，串口MODBUS此参数无效。 返回值 返回0表达到功，否则为错误码。 ZMB_ReadInputReg 描述 调用此函数按参数中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 在TCPMODBUS合同里需要用到任务ID号，如果为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 在TCPMODBUS合同里需要用到任务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 设备ID号。 nAddress 线圈起始地址。 nCount 写入线圈个数。 bWriteDataArr 写入线圈数据数组，数组每个构造保存一种线圈状态，此数组大小应当和nCount指定大小相似。 TranID 在TCPMODBUS合同里需要用到任务ID号，如果为0使用系统自生成，串口MODBUS此参数无效。 返回值 返回0表达到功，否则为错误码。 ZMB_WriteRegSingle 描述 调用此函数按参数中ID号和地址修改单个保持寄存器数据。 long ZMB_WriteRegSingle (HANDLE hand，BYTE serID，int nAddress，WORD wWriteData，WORD TranID)；参数 hand 此handle是ConnectMDBServer操作返回值。 serID 设备ID号。 nAddress 保持寄存器地址。 wWriteData 写入寄存器数据。 TranID 在TCPMODBUS合同里需要用到任务ID号，如果为0使用系统自生成，串口 MODBUS此参数无效。 返回值 返回0表达到功，否则为错误码。 ZMB_WriteRegMulitiple 描述 调用此函数按参数中ID号和地址修改nCount指定各种保持寄存器。 long ZMB_WriteRegMulitiple (HANDLE hand，BYTE serID，int nAddress，int nCount，WORD * writeDataArr，WORD TranID)；参数 hand 此handle是ConnectMDBServer操作返回值。 serID 设备ID号。 nAddress 保持寄存器起始地址。 nCount 写入寄存器个数。 bWriteDataArr 写入寄存器数据数组，数组每个构造保存一种寄存器值，此数组个数应当和nCount指定个数相似，大小应当等于 nCount * 2 个字节。 TranID 在TCPMODBUS合同里需要用到任务ID号，如果为0使用系统自生成，串口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操作返回值。 pBuf 写数据缓冲区。 iLen 缓冲区长度。 nAddCheck 与否添加校验，只在串口中有效，如果打开时为RUT，且使用了添加校验，则添加CRC校验。如果打开时为ASCII，且使用了添加校验，则添加LRC校验。 TranID 在TCPMODBUS合同里需要用到任务ID号，如果为0使用系统自生成，串口MODBUS此参数无效。 返回值 返回写成功长度。 ZMB_ReadRecBuf 描述 调用此函数读取设备响应数据。 long ZMB_ReadRecBuf (HANDLE hand，BYTE *pBuf，int iBufLen，int *iRecedLen )；参数 hand 此handle是ConnectMDBServer操作返回值。 pBuf 读数据缓冲区。 iBufLens 缓冲区大小。 iRecedLen 接受到数据长度，（输出参数）。 TranID 在TCPMODBUS合同里需要用到任务ID号，如果为0使用系统自生成，串口MODBUS此参数无效。 返回值 返回读取到长度。 2 错误代码 ZModbusSdk使用了原则MODBUS错误代码和自定义错误代码来描述SDK在操作过程中会浮现错误。在使用过程中应当注意错误定义，有些使用0作为成功标志，而有些使用0作为错误标志。原则MODBUS读写操作都以ERROR_SUCCESS（0）表达对的，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 写各种寄存器出错