第6章 libmodbus使用

6.1 libmodbus开发库

6.1.1 功能概要

libmodbus是一个免费的跨平台支持RTU和TCP的Modbus库，遵循LGPL V2.1+协议。libmodbus支持Linux、Mac Os X、FreeBSD、QNX和Windows等操作系统。libmodbus可以向符合Modbus协议的设备发送和接收数据，并支持通过串口或者TCP网络进行连接。

作为一个开源项目，libmodbus库还处于开发测试阶段，代码量还不十分庞大，文档和注释也不够全面，本章通过对libmodbus源代码的阅读过程，一方面可以进一步理解Modbus协议，同时也可以学习一个好的开源项目的代码组织及开发过程。 libmodbus的官方网站为 http://libmodbus.org/，可以从 http://libmodbus.org/download/ 下载源代码。作为开源软件，还可以从GitHub网站获取最新版本的代码GitHub: https://github.com/stephane/libmodbus.git

6.1.2 源码获取

libmodbus的源码不断更新，本教程选择版本v3.1.10。打开https://github.com/stephane/libmodbus/tags ，如下图下载：

本源码也放在网盘中如下目录里：

解压后，简单查看源代码根目录的构成：

doc目录: libmodbus库的各API接口说明文档。
m4目录: 存放GNU m4文件，在这里对理解代码没有意义，可忽略。
src目录: 全部libmodbus源文件。
tests目录: 包含自带的测试代码其他文件对理解源代码关系不大，可以暂时忽略

图6-2解压libmodbus源代码：

进一步展开src代码目录，如图6-3所示：

图6-3libmodbus源码构成：

各文件作用如下：

win32: 定义在Windows下使用Visual Studio编译时的项目文件和工程文件以及相关配置选项等。其中，modbus-9.sln默认使用Visual Studio 2008。
Makefile.am: Makefile.am是Linux下AutoTool编译时读取相关编译参数的配置文件，用于生成Makefile文件，因为用于Linux下开发，所以在这里暂时忽略
modbus.c: 核心文件，实现Modbus协议层，定义共通的Modbus消息发送和接收函数各功能码对应的函数。
modbus.h: libmodbus对外暴露的接口API头文件。
modbus-data.c: 数据处理的共通函数，包括大小端相关的字节、位交换等函数
modbus-private.h: libmodbus内部使用的数据结构和函数定义。
modbus-rtu.c: 通信层实现，RTU模式相关的函数定义，主要是串口的设置、连接及消息的发送和接收等。
modbus-rtu.h: RTU模式对外提供的各API定义
modbus-rtu-private.h: RTU模式的私有定义。
modbus-tcp.c: 通信层实现，TCP模式下相关的函数定义，主要包括TCP/IP网络的设置连接、消息的发送和接收等。
modbus-tcp.h: 定义TCP模式对外提供的各API定义
modbus-tcp-private.h: TCP模式的私有定义。
modbus-version.h.in: 版本定义文件。

6.1.3 源码阅读

对比比较复杂的源码，使用sourceinsight可以很方便地阅读、分析、编辑源码。

1. 新建工程

运行source Insight，点击菜单“Project->New Project”,如下图所示：

设置工程名及工程数据目录：在弹出的New Project对话框中设置“New project name”(项目的名称)，然后设置Where do you want to store the project data file? (项目文件保存位置)，点击Browse按钮选择源码的目录即可，如下图:

指定源码目录：在上图界面中点击OK后，弹出如下图所示窗口，填入源码路径：

添加源码：在新弹出的对话框中，点击“Add”或“Add All”。“Add”是手动选择需要添加的文件，而“Add All”是添加所有文件。我们使用“Add All”,在弹出的提示框中选中“Recursively add lower sub-directories”(递归添加下级的子目录)并点击OK。同样的Remove File,Remove All是移除单个文件或者移除所有文件，如下图所示：

添加文件完成后会弹出下面窗口，点击“确定”即可：

此时界面会返回到主界面，如下图所示，点击“Close”：

2. 同步文件

同步文件的意思是让Source Insight去解析源码，生成数据库，这样有助于以后阅读源码。比如点击某个函数时就可以飞快地跳到它定义的地方。

先点击菜单“Project->Synchronize Files”，如图 2.23所示：

在弹出的对话框中选中“Force all files to be re-parsed”(强制解析所有文件)，并点击“Start”按钮开始同步，如下图所示：

3.打开工程

前面建议工程后，就会自动打开了工程。如果下次你想打开工程，启动Souce Insight后，点击菜单“Project -> Open Porject”就可以在一个列表中选择以前建立的工程，如下图所示：

4. 操作示例

在工程中打开文件：点击"P"图标打开文件列表，双击文件打开文件，也可以输入文件名查找文件，如下图所示：

在文件中查看函数或变量的定义：打开文件后，按住ctrl键的同时，用鼠标点击函数、变量，就会跳到定义它的位置，如下图所示：

查找函数或变量的引用：右键点击函数或变量，弹出对话框选择“Lookup Reference”；或者双击函数后，使用快捷键"ctrl+/"来查找引用，如下图：

5. 快捷键

快捷键	说明
Alt + ,	后退
Alt + .	前进
F8	高亮选中的字符
Ctrl+F	查找
F3或Shift+F3	往前查找
F4或Shift+F4	往后查找

6.1.4 libmodbus与应用程序的关系

libmodbus是一个免费的跨平台支持RTU和TCP的Modbus开发库，借助于libmodbus发库能够非常方便地建立自己的应用程序或者将Modbus通信协议嵌入单体设备libmodbus开发库与应用程序的基本关系如图6-4所示。

图6-4应用程序与libmodbus的关系：

在对libmodbus的接口及代码框架简单了解之后，不妨再深入细节一探究竟，看看libmodbus都实现了哪些基础功能，以及源代码中对Modbus各功能码和消息顿是如何包装的。具体内容请参看下一章。

6.2 libmodbus源代码解析

libmodbus作为一个优秀且免费开源的跨平台支持RTU和TCP模式的Modbus开发库，非常值得大家借鉴和学习。本章对libmodbus源代码进行阅读和分析。

6.2.1 核心函数

以Modbus RTU协议为例，主设备、从设备初始化后：

主设备就可以启动请求，即“发送消息”给从设备
从设备接收到请求后构造数据，启动响应即“发送回复”
主机收到响应后，会“检查响应”

如下图所示：

分析“libmodbus-3.1.10\tests\unit-test-client.c”、“libmodbus-3.1.10\tests\unit-test-server.c”，可以得到下面核心函数的使用过程：

6.2.2 框架分析与数据结构

站在APP开发的角度来说，使用上一节里介绍的libmodbus函数即可。但是，数据的传输必定涉及到底层数据传输。所以，从数据的收发过程，可以把使用libmodbus的源码分为3层：

APP：它知道要做什么，主设备要读写哪些寄存，从设备提供、接收什么数据
Modbus核心层：向上提供接口函数，向下调用底层代码构造数据包并发送、接收数据包并解析
后端（数据传输）：进行硬件相关的数据封包与发送、接收与解包

对于核心层、后端，抽象出了如下结构体：

核心层modbus_t结构体的成员含义如下：

成员	含义
int slave;	从站设备地址
int s;	RTU下是串口句柄，TCP下是Socket
int debug;	是否启动Debug模式（打印调试信息）
int error_recovery;	错误恢复模式：MODBUS_ERROR_RECOVERY_NONE：由APP处理错误MODBUS_ERROR_RECOVERY_LINK：如果有连接错误，则重连MODBUS_ERROR_RECOVERY_PROTOCOL：如果数据不符合协议要求，则清空所有数据
int quirks;	一些奇怪的功能，比如：MODBUS_QUIRK_MAX_SLAVE：从站地址最大值可以到达255MODBUS_QUIRK_REPLY_TO_BROADCAST：回应广播包
struct timeval response_timeout;	等待回应的超时时间，默认是0.5S
struct timeval byte_timeout;	接收一个字节的超时时间，默认是0.5S
struct timeval indication_timeout;	等待请求的超时时间
const modbus_backend_t *backend;	硬件传输层的结构体
void *backend_data;	硬件传输层的私有数据

后端modbus_backend_t结构体的成员含义如下：

成员	含义
unsigned int backend_type;	后端类型，是RTU还是TCP
unsigned int header_length;	头部长度，比如RTU数据包前面需要有1字节的设备地址，头部长度就是1
unsigned int checksum_length;	校验码长度，RTU的校验码是2字节
unsigned int max_adu_length;	ADU（数据包）最大长度
set_slave	设置从站地址
build_request_basis	设置RTU请求包的基本数据，这些数据的格式是一样的，比如req[0]是从设备地址，req[1]是功能码，req[2]和req[3]是寄存器地址，req[4]和req[5]是寄存器数量
build_response_basis	设置RTU回应包的基本数据，这些数据的格式是一样的，比如req[0]是从设备地址，req[1]是功能码
prepare_response_tid	生产传输标识TID，在TCP中使用
send_msg_pre	发送消息前的准备工作，对于RTU是填充CRC检验码，对于TCP是填充头部的Length
send	发送数据包
receive	接收数据包
recv	接收原始数据，receive会调用recv得到原始数据然后解析出数据包
check_integrity	检查数据包的完整性
pre_check_confirmation	检查响应数据包是否有效时，先执行pre_check_confirmation做一些简单的检查
connect	硬件相关的连接，对于RTU就是打开串口、设置串口波特率等；对于TCP则是连接对端
is_connected	判断是否已经连接
close	关闭连接
flush	清空接收到的、未处理的数据
select	阻塞一段时间以等待数据
free	释放分配的modbus_t等结构体

6.2.3 情景分析

以“modbus_write_bits”函数为例，分析下图的执行流程：

1. 初始化

2. 主设备发送请求

3. 从设备接收请求

4.从设备回应

6.2.4 常用接口函数

下面分析 libmodbus开发库提供的所有接口API函数。其主要对象文括 modbus.h 和 modbus.c ,接口函数大致可分为3类,以下分别进行介绍。

1. 各类辅助接口函数

MODBUS_API int modbus_set_slave(modbus t * ctx,int slave)

此函数的功能是设置从站地址，但是由于传输方式不同而意义稍有不同。

RTU模式 :

如果 libmodbus应用于主站设备端，则相当于定义远端设备ID ；如果libmodbus应用于从站设备端，则相当于定义自身设备 ID ；在 RTU 模式下参数 slave 取值范围为 0~247 ，其中 0(MODBUS_BROADCAST_ADDRESS) 为广播地址。

TCP模式:

通常，TCP 模式下此函数不需要使用。在某些特殊场合，例如串行 Modbus设备转换为 TCP模式传输的情况下,此函数才被使用。此种情况下,参数 slave取值范围为 0~247 ，0 为广播地址;如果不进行设置,则 TCP 模式下采用默认值 MODBUS TCP SLAVE(OXFF) 。

下面的代码以 RTU模式、主设备(MASTER)端为例：

modbus_t * ctx;

ctx=modbus_new_rtu("COM4"，115200，'N'，8，1);

if (ctx ==NULL)

{

  fprintf(stderr，"Unable to create the libmodbus context\n");

  return -1;

}

rc =modbus_set_slave(ctx，YOUR DEVICE ID);

if (rc==-1)

{

  fprintf(stderr，"Invalid slave ID\n");

  modbus free(ctx);

  return -1;

}

if (modbus connect(ctx)==-1)

{

  fprintf(stderr,"Connection failed:sn",modbus strerror(errno));

  modbus free(ctx);

  return -1;

}

MODBUS_APIintmodbus_set_error_recovery(modbus_t*ctx，modbus_error_recovery_mode error_recovery)：

此函数用于在连接失败或者传输异常的情况下,设置错误恢复模式。有 3种错误恢复模式可选。

typedef enum

{

  MODBUS_ERROR_RECOVERY_NONE        =0,             //不恢复

  MODBUS_ERROR_RECOVERY_LINK        =(1<<1),           //链路层恢复

  MODBUS_ERROR_RECOVERY_PROTOCOL      =(1<<2)           //协议层恢复

}modbus error recovery mode;

默认情况下，设置为 MODBUS_ERROR_RECOVERY_NONE ，由应用程序自身处理错误；若设置为 MODBUS_ERROR_RECOVERY_LINK ，则经过一段延时 libmodbus 内部自动尝试进行断开/连接；若设置为 MODBUS_ERROR_RECOVERY_PROTOCOL ，则在传输数据 CRC 错误或功能码错误的情况下,传输会进入延时状态，同时数据直接被清除。在 SLAVE/SERVER 端，不推荐使用此函数。

基本用法举例:

modbus_set_error_recovery(ctx,MODBUS_ERROR_RECOVERY_LINK|MODBUS_ERROR_RECOVERY_PROTOCOL)；

MODBUS_API int modbus_set_socket(modbus t * ctx,int s)

此函数设置当前 SOCKET 或串口句柄要用于多客户端连接到单一服务器的场合。简单用法举例如下，后续介绍函数 modbus_tcp_listen() 时将会进一步介绍相关用法。

#define NB_CONNECTION 5

modbus_t * ctx;

ctx=modbus_new_tcp("127.0.0.1", 1502)

server_socket = modbus_tcp_listen(ctx,NB_CONNECTION);

FD_ZERO(&rdset);

FD_SET(server_socket,&rdset);

/* ... */

if (FD_ISSET(master_socket,&rdset))

{

  modbus_set_socket(ctx,master_socket);

  rc =modbus_receive(ctx,query);

  if(rc!=-1)

  {

  modbus_reply(ctx,query, rc,mb_mapping);

  }

}

MODBUS_API int modbus_get_response_timeout (modbus_t * ctx, uint32_t * to_sec, uint32_t * to_usec)；

MODBUS_API int modbus_set_response_timeout (modbus_t * ctx, uint32_t * to_sec, uint32_t * to_usec)；

用于获取或设置响应超时,注意时间单位分别是秒和微秒。

MODBUS_API int modbus_get_byte_timeout (modbus_t * ctx, uint32_t * to_sec，uint32_t * to_usec);

MODBUS_API int modbus_set_byte_timeout (modbus_t * ctx, uint32_t * to_sec，uint32_t * to_usec)；

用于获取或设置连续字节之间的超时时间,注意时间单位分别是秒和微秒。

MODBUS_API intmodbus_get_header_length (modbus_t * ctx)；

获取报文头长度。

MODBUS_API int modbus_connect (modbus_t * ctx)；

此函数用于主站设备与从站设备建立连接。

在 RTU 模式下，它实质调用了文件 modbus_rtu.c 中的函数 static int modbus_rtu_connect (modbus_t * ctx) ；在此函数中进行了串口波特率校验位、数据位、停止位等的设置。

在 TCP 模式下，modbus_connect() 调用了文件 modbus_tcp.c 中的函数 static int_modbus_tcp_connect (modbus_t * ctx ) ；在函数 _modbus_tcp_connect() 中，对 TCP/IP 各参数进行了设置和连接。

MODBUS_API void modbus_close (modbus_t * ctx)；

关闭 Modbus 连接。在应用程序结束之前，一定记得调用此函数关闭连接在 RTU 模式下,实质是调用函数 _modbus_rtu_close(modbus_t * ctx) 关闭串口句柄；在 TCP 模式下,实质是调用函数 _modbus_tcp_close(modbust * ctx) 关闭 Socket 句柄。

MODBUS_API void modbus_free (modbus_t * ctx)；

释放结构体 modbus_t 占用的内存。在应用程序结束之前，一定记得调用此函数

MODBUS_API int modbus_set_debug (modbust * ctx, int flag)；

此函数用于是否设置为DEBUG模式。

若参数 flag 设置为TRUE,则进入 DEBUG模式。若设置为FALSE,则切换为非 DEBUG模式。在 DEBUG模式下所有通信数据将按十六进制方式显示在屏幕上，以方便调试。

MODBUS_API const char * modbus_strerror (int errnum）；

此函数用于获取当前错误字符串。

2. 各类Modbus功能接口函数

MODBUS_API int modbus_read_bits (modbus t * ctx, int addr, int nb, uint8_t * dest)；

此函数对应于功能码 01(0x01) 读取线圈/离散量输出状态(Read Coil Status/DOs)，其中，所读取的值存放于参数 uint8_t * dest 指向的数组空间因此 dest 指向的空间必须足够大,其大小至少为 nb * sizeof(uint8_t) 个字节。

用法举例:

#define SERVER ID        1
#define ADDRESS START      0
#define ADDRESS END       99

modbus_t * ctx;

uint8_t * tab_rp_bits;
int rc;
int nb;

ctx=modbus_new_tcp("127.0.0.1",502);
modbus_set_debug(ctx，TRUE);
if (modbus_connect(ctx)==-1)

{
  fprintf(stderr,"Connection failed:%s\n", modbus_strerror(errno));
  modbus free(ctx);
  return -1;
}

//申请存储空间并初始化
int nb = ADDRESS_END - ADDRESS_START;
tab_rp_bits = (uint8_t * ) malloc (nb * sizeof(uint8_t));
memset(tab_rp_bits, 0, nb * sizeof(uint8_t));

//读取一个线圈
int addr =1;
rc =modbus_read_bits(ctx,addr,1,tab_rp_bits);
if (rc !=1)
{
  printf("ERROR modbus_read_bits_single (%d)\n", rc);
  printf("address =%d\n", addr);
}

//读取多个线圈

rc =modbus_read_bits(ctx,addr,nb,tab_rp_bits);
if (rc !=nb)
{
  printf("ERROR modbus_read_bits\n");
  printf("Address =%d,nb =%d\n", addr, nb);
}

//释放空间关闭连接

free(tab_rp_bits);
modbus_close(ctx);
modbus_free(ctx);

MODBUS_API int modbus_read_input_bits (modbus_t * ctx, int addr, int nb,uint8_t * dest)；

此函数对应于功能码 02(0x02) 读取离散量输入值(Read Input Status/DIs)，各参数的意义与用法，类似于函数 modbus_read_bits() 。

MODBUS_API int modbus_read_registers (modbus_t * ctx, int addr, int nb，uint16_t * dest)；

此函数对应于功能码 03(0x03) 读取保持寄存器(Read Holding Register),其中,所读取的值存放于参数 uint16_t * dest 指向的数组空间因此 dest 指向的空间必须足够大,其大小至少为 nb * sizeof(uint16_t) 个字节。

当读取成功后,返回值为读取的寄存器个数;若读取失败,则返回-1。此函数调用依赖关系如下图6-5所示。

用法举例:

modbust * ctx;
uint16_t tab_reg[64];
int rc;
int i;

ctx=modbus_new_tcp("127.0.0.1",502);
if (modbusconnect(ctx)==-1)
{
  fprintf(stderr,"Connection failed:%s\n", modbus_strerror(errno));
  modbus_free(ctx);
  return -1;
}

//从地址0开始连续读取10个

rc =modbus_read_registers(ctx,0,10,tab_reg);
if (rc ==-1)
{
  fprintf(stderr,"%s\n",modbus_strerror(errno));
  return -1;
}

for (i=0;i<rc;i++)
{
  printf("reg[%d]=%d(0x%X)\n",i,tab_reg[i],tab_reg[i]);
}

modbus_close(ctx);
modbus_free(ctx);

MODBUS_API int modbus_read_input_registers (modbus_t * ctx，int addr, int nb, uint16_t * dest )；

此函数对应于功能码 04(0x04) 读取输人寄存器(Read Iput Register)，各参数的意义与用法,类似于函数 modbus_read_registers() 。

此函数的调用依赖关系如下图 6-6 所示。

图6-6函数 modbus_read input_registers()的调用依赖关系：

MODBUS_API int modbus_write_bit (modbus_t * ctx, int coil_addr, int status)：

该函数对应于功能码 05(0x05) 写单个线圈或单个离散输出(Force SingleCoil)。其中参数 coil_addr 代表线圈地址；参数 status 代表写值取值只能是TRUE(1)或 FALSE(0) 。

MODBUS_API int modbus_write_register (modbus_t * ctx，int reg_addr, int value)：

该函数对应于功能码 06(0x06) 写单个保持寄存器(Preset Single Register)。

MODBUS_API int modbus_write_bits (modbus_t * ctx, int addr, int nb, const uint8_t * data)：

该函数对应于功能码 15(0x0F) 写多个线圈(Force Multiple Coils)

参数 addr 代表寄存器起始地址,参数 nb 表示线圈个数，而参数 const uint8_t * data 表示待写入的数据块。一般情况下,可以使用数组存储写入数据,数组的各元素取值范围只能是 TRUE(1)或 FALSE(0) 。

MODBUS_API int modbus_write_registers (modbus_t * ctx, int addr, int nb, const uint16_t * data)：

该函数对应于功能码 16(0x10) 写多个保持存器(Preset MultipleRegisters)

参数 addr 代表寄存器起始地址,参数 nb 表示存器的个数而参数 const uint16_t * data 表示待写人的数据块。一般情况下,可以使用数组存储写入数据数组的各元素取值范围是 0~0xFFFF 即数据类型 uint16_t 的取值范围。

MODBUS_API int modbus_mask_registers (modbus_t * ctx, int addr, uint16_t and_mask, uint16_t or_mask )：

modbus_mask_write_register() 函数应使用以下算法修改远程设备地址“addr”处的保持寄存器的值：

新值 = (current value AND ‘and’) OR (‘or’ AND (NOT ‘and’)) 。

该功能使用 Modbus 功能代码 0x16（掩码单个寄存器）。

MODBUS_API int modbus_write_and_read_registers (mobus_t * ctx ,

int writer_addr,

int writer_nb,

const uint16_t * src,

int read_addr,

int read_nb,

uint16_t * dest);

modbus_write_and_read_registers() 函数应将 write_nb 保持寄存器的内容从数组 “src” 写入远程设备的地址 write_addr ，然后将 read_nb 保持寄存器的内容读取到远程设备的地址 read_addr 。读取结果作为字值（16 位）存储在 dest 数组中。

必须注意分配足够的内存来存储结果 dest (至少 nb * sizeof(uint16_t)）。该功能使用 Modbus 功能代码 0x17（写/读寄存器）。

MODBUS_API int modbus_report_slave_id (modbus_t * ctx, int max_dest, uint8_t * dest)：

该函数对应于功能码 17(0x11) 报告从站ID。参数 max_dest 代表最大的存储空间,参数 dest 用于存储返回数据。返回数据可以包括如下内容:从站 ID状态值(0x00= OFF状态, 0xFF=ON状态) 以及其他附加信息，具体的各参数意义由开发者指定。

用法举例:

uint8_t tab_bytes[MODBUS_MAX_PDU_LENGTH];

...

rc =modbus_report_slave_id(ctx, MODBUS_MAX_PDU_LENGTH, tab_bytes);

if (rc>1)
{
  printf("Run Status Indicator: %s\n",tab_bytes[1] ?"ON":"OFF");
}

3. 数据处理的相关函数或宏定义

在libmodbus开发库中，为了方便数据处理在 modbus.h 文件中定义了一系列数据处理宏。

例如获取数据的高低字节序宏定义：

#define MODBUS_GET_HIGH_BYTE (data) (((data) >>8) & 0xFF)
#define MODBUS_GET_LOW_BYTE (data) ((data) & 0xFF)

对于浮点数等多字节数据而言,由于存在字节序与大小端处理等的问题，所以辅助定义了一些特殊函数:

MODBUS_API float modbus_get_float (const uint16_t * src);

MODBUS_API float modbus_get_float_abcd (const uint16_t * src);

MODBUS_API float modbus_get_float_dcba (const uint16_t * src);

MODBUS_API float modbus_get_float_badc (const uint16_t * src);

MODBUS_API float modbus_get_float_cdab (const uint16_t * src);

MODBUS_API void modbus_set_float (float f,uint16_t * dest);

MODBUS_API void modbus_set_float_abcd (float f,uint16_t * dest);

MODBUS_API void modbus_set_float_dcba (float f,uint16_t * dest);

MODBUS_API void modbus_set_float_badc (float f,uint16_t * dest);

MODBUS_API void modbus_set_float_cdab (float f,uint16_t * dest);

当然,可以参照 float 类型的处理方法,继续定义其他多字节类型的数据例如int32_t、uint32_t、 int64_t、uint64_t 以及 double 类型的读写函数。

6.2.5 RTU/TCP关联接口函数

在文件 modbus.h 的最后位置,有如下语句

#include "modbus-tcp.h"

#include "modbus-rtu.h"

可以发现,除了 modbus.h 包含的接口函数之外，modbus-rtu.h 和 modbus-tcp.h 也包含了必要的接口函数。

1. RTU模式关联函数

MODBUS_API modbus_t * modbus_new_rtu (const char * device, int baud, char parity, int data_bit, int stop_bit)：

此函数的功能是创建一个 RTU 类型的 modbus_t 结构体。参数 const char * device 代表串口字符串，在 Windows 操作系统下形态如 “COMx” ，有一点需要注意的是，对于串口1串口9来说,，传递 “COM1”“COM9” 可以成功，但是如果操作对象为 COM10及以上端口，则会出现错误。

产生这种奇怪现象的原因是:微软预定义的标准设备中含有 “COM1”~~“COM9” 。所以，“COM1”~~“COM9” 作为文件名传递给函数时操作系统会自动地将之解析为相应的设备。但对于 COM10 及以上的串口，“COM10” 之类的文件名系统只视之为一般意义上的文件,而非串行设备。为了增加对 COM10 及以上串行端口的支持,微软规定,如果要访问这样的设备,应使用这样的文件名(以COM10 为例):\\.\ COM10。

所以,使用时在代码中可以如此定义:.

const char * device = “\\.\COM10”;

在Linux操作系统下可以使用”/dev/ttySo”或”/dev/ttyUSB0”等形式的字符串来表示。而参数 int baud 表示串口波特率的设置值，例如:9600、19200、57600、115200等。

参数char parity 表示奇偶校验位，取值范围：

‘N’:无奇偶校验；
‘E’:偶校验；
‘O’:奇校验。

参数 int data_bit 表示数据位的长度,取值范围为 5、6、7和8。

参数int stop_bit 表示停止位长度，取值范围为1或2。

用法举例:

modbus t *ctx;

ctx=modbus_new_rtu("\\\\.\\COM10",115200,'N',8,1);

if (ctx ==NULL)
{
  fprintf(stderr,"Unable to create the libmodbus context\n");
  return -1;
}

modbus_set_slave(ctx,SLAVE_DEVICE_ID);

if (modbus connect(ctx)==-1)
{
  fprintf(stderr,"Connection failed:%s\n",modbus_strerror(errno));
  modbus_free(ctx);
  return -1;
}

MODBUS_API int modbus_rtu_set_serial_mode (modbus_t * ctx, int mode)：

该函数用于设置串口为 MODBUS RTU RS232或MODBUSRTU_RS485模式,此函数只适用于 Linux 操作系统下。

MODBUS_API int modbus_rtu_set_rts (modbus_t * ctx, int mode)。

MODBUS_API int modbus_rtu_set_custom_rts (modbus_t * ctx, void ( * set_rts) (modbus_t * ctx, int on))。

MODBUS_API int modbus_rtu_set_rts_delay (modbus_t * ctx, int us)。

以上函数只适用于 Linux 操作系统下,RTS 即Request ToSend 的缩写，具体的意义可通过网络搜索，一般情况下，此类函数可忽略。

2. TCP模式关联函数

MODBUS_API modbus_t * modbus_new_tcp (const char *ip_address, int port)。

此函数的功能是创建一个TCP/IPv4 类型的modbus_t 结构体。

参数 const char * ip_address 为IP地址,port 表示远端设备的端口号。

MODBUS_API int modbus_tcp_listen (modbus_t * ctx, int nb_connection)。

此函数创建并监听一个 TCP/IPv4 上的套接字。

参数int nb_connection 代表最大的监听数量,在调用此函数之前，必须首先调用modbus_new_tcp() 创建modbus_t结构体。

MODBUS_API int modbus_tcp_accept (modbus_t * ctx，int * s)。

此函数接收一个 TCP/IPv4 类型的连接请求,如果成功将进入数据接收状态。

6.3 libmodbus移植与使用

6.3.1 移植方法

以串口为例，libmodbus支持了windows系统、Linux系统。如果要在Freertos或者裸机上使用libmodbus，需要移植libmodbus里操作硬件的代码。

根据下图的层次，要移植libmodbus的“后端”，就是构造自己的modbus_backend_t结构体：

后端modbus_backend_t结构体的成员含义如下：

成员	含义
unsigned int backend_type;	后端类型，是RTU还是TCP
unsigned int header_length;	头部长度，比如RTU数据包前面需要有1字节的设备地址，头部长度就是1
unsigned int checksum_length;	校验码长度，RTU的校验码是2字节
unsigned int max_adu_length;	ADU（数据包）最大长度
set_slave	设置从站地址
build_request_basis	设置RTU请求包的基本数据，这些数据的格式是一样的，比如req[0]是从设备地址，req[1]是功能码，req[2]和req[3]是寄存器地址，req[4]和req[5]是寄存器数量
build_response_basis	设置RTU回应包的基本数据，这些数据的格式是一样的，比如req[0]是从设备地址，req[1]是功能码
prepare_response_tid	生产传输标识TID，在TCP中使用
send_msg_pre	发送消息前的准备工作，对于RTU是填充CRC检验码，对于TCP是填充头部的Length
send	发送数据包
receive	接收数据包
recv	接收原始数据，receive会调用recv得到原始数据然后解析出数据包
check_integrity	检查数据包的完整性
pre_check_confirmation	检查响应数据包是否有效时，先执行pre_check_confirmation做一些简单的检查
connect	硬件相关的连接，对于RTU就是打开串口、设置串口波特率等；对于TCP则是连接对端
is_connected	判断是否已经连接
close	关闭连接
flush	清空接收到的、未处理的数据
select	阻塞一段时间以等待数据
free	释放分配的modbus_t等结构体

本节先写出模板：

根据这个源码：

改出：

6.3.2 使用USB串口作为后端

基于这2个程序：

第1步：合并上述2个源码，并修改到能编译成功（但是libmodbus里对USB串口的操作），结果放在如下目录：

第2步，继续修改上图的代码，实现USB串口作为后端，得到以下代码：

USB串口的操作函数：

/* 发送数据 */

int ux_device_cdc_acm_send(uint8_t *datas, uint32_t len, uint32_t timeout);

/* 接收数据 */

int ux_device_cdc_acm_getchar(uint8_t *pData, uint32_t timeout);

6.3.3 libmodbus从机实验(USB串口)

本节源码为：

参考“libmodbus-3.1.10\tests\unit-test-server.c”，把开发板当做从机，使用PC上Modbus Poll软件读写开发板：控制LED。

要点：

① printf、fprintf、vfprintf都不能使用，改成空的宏

6.3.4 libmodbus主机实验(USB串口)

本节源码为：

参考“libmodbus-3.1.10\tests\unit-test-client.c”，把开发板当做主机，去读写PC上Modbus Slave软件模拟的从机。

6.3.5 使用板载串口作为后端

学习本节课程前，先观看《3.5.3 面向对象封装UART》，并且观看对应视频《3-9-1_面向对象封装UART_完善收发功能》、《3-9-2_面向对象封装UART_实现结构体》。

本节代码如下：

按照下图连线：调试、供电、两个485互连，使用CH1（左边的RS485接口）作为主设备，访问CH2（右边的RS485接口）：

1. 使用UART_Device

这2个视频，是在开始本节课程之前才补录的：《3-9-1_面向对象封装UART_完善收发功能》、《3-9-2_面向对象封装UART_实现结构体》。这两个视频里，把UART2、UART4的发送、接收功能都补全了，并且构造了对应的UART_Device结构体，里面实现了初始化、发送、接收一个自己的的函数，如下：

把UART2、UART4封装为UART_Device的代码为：“3_程序源码\01_视频配套的源码\3-9_面向对象封装UART\uart_rtos_all_ok.7z”。需要把它的代码移植到本节的工程里：

使用STM32CubeMX配置UART2、UART4：发送、接收都使用DMA
复制代码：Core\Src\usart.c、Drivers\Module_driver\uart_device.c/h

使用STM32CubeMX配置的过程如下：

使能DMA通道：

各个DMA通道的配置如下：

2. 用作后端

把UART2、UART4用作libmodbus后端时，只需要修改这几个函数即可：

有两个UART_Device，调用哪个UART_Device？在使用“modbus_new_st_rtu”创建modbus_t时，根据传入的设备名在modbus_t结构体里记录对应的UART_Device。_modbus_rtu_connect、_modbus_rtu_send、_modbus_rtu_recv这三个函数，就可以直接调用modbus_t结构体里的UART_Device函数了。

6.3.6 libmodbus实验(板载串口)

本节源码为：

按照下图连线：调试、供电、两个485互连：

创建一个ClientTask，使用CH2（右边的RS485接口）对外通信。

第6章 libmodbus使用

6.1 libmodbus开发库​

6.1.1 功能概要​

6.1.2 源码获取​

6.1.3 源码阅读​

1. 新建工程​

2. 同步文件​

3.打开工程​

4. 操作示例​

5. 快捷键​

6.1.4 libmodbus与应用程序的关系​

6.2 libmodbus源代码解析​

6.2.1 核心函数​

6.2.2 框架分析与数据结构​

6.2.3 情景分析​

1. 初始化​

2. 主设备发送请求​

3. 从设备接收请求​

4.从设备回应​

6.2.4 常用接口函数​

1. 各类辅助接口函数​

2. 各类Modbus功能接口函数​

3. 数据处理的相关函数或宏定义​

6.2.5 RTU/TCP关联接口函数​

1. RTU模式关联函数​

2. TCP模式关联函数​

6.3 libmodbus移植与使用​

6.3.1 移植方法​

6.3.2 使用USB串口作为后端​

6.3.3 libmodbus从机实验(USB串口)​

6.3.4 libmodbus主机实验(USB串口)​

6.3.5 使用板载串口作为后端​

1. 使用UART_Device​

2. 用作后端​

6.3.6 libmodbus实验(板载串口)​

6.1 libmodbus开发库

6.1.1 功能概要

6.1.2 源码获取

6.1.3 源码阅读

1. 新建工程

2. 同步文件

3.打开工程

4. 操作示例

5. 快捷键

6.1.4 libmodbus与应用程序的关系

6.2 libmodbus源代码解析

6.2.1 核心函数

6.2.2 框架分析与数据结构

6.2.3 情景分析

1. 初始化

2. 主设备发送请求

3. 从设备接收请求

4.从设备回应

6.2.4 常用接口函数

1. 各类辅助接口函数

2. 各类Modbus功能接口函数

3. 数据处理的相关函数或宏定义

6.2.5 RTU/TCP关联接口函数

1. RTU模式关联函数

2. TCP模式关联函数

6.3 libmodbus移植与使用

6.3.1 移植方法

6.3.2 使用USB串口作为后端

6.3.3 libmodbus从机实验(USB串口)

6.3.4 libmodbus主机实验(USB串口)

6.3.5 使用板载串口作为后端

1. 使用UART_Device

2. 用作后端

6.3.6 libmodbus实验(板载串口)