# API-libmodbus — Modbus 协议栈模块

> 版本: v1.0  
> 日期: 2026-07-08  
> 来源: libmodbus v3.1.12（LGPL-2.1-or-later）  
> 状态: 导入完成（开源库，未重构）  
> 修改: 日志输出改为调用 `myLog.h` LOG_I/LOG_E

---

## 1. 模块概述

libmodbus 是工业标准 Modbus 协议的开源实现（[libmodbus.org](https://libmodbus.org)），支持：

| 功能 | 说明 |
|------|------|
| Modbus RTU（串行） | RS-232 / RS-485，CRC 校验 |
| Modbus TCP（以太网） | TCP/IP，MBAP 报文头 |
| 主站 / 从站 | 同一套 API 支持主站请求和从站响应 |
| 全功能码覆盖 | 读线圈/读离散量/读保持寄存器/读输入寄存器/写单/写多/掩码/读写组合 |

### 版本信息

```
libmodbus v3.1.12
Copyright © Stéphane Raimbault
SPDX-License-Identifier: LGPL-2.1-or-later
```

### 项目适配

原 RTU 项目对 libmodbus 做了两处适配：
1. **日志系统**：源码中 `fprintf(stderr, ...)` → `LOG_I` / `LOG_E`（调用项目 liblog 模块）
2. **config.h**：配置头文件，启用 `HAVE_DECL_TIOCSRS485` 等宏

---

## 2. 源文件结构

```
libmodbus/
├── inc/
│   ├── modbus.h              # 主接口 — API、错误码、功能码、数据结构
│   ├── modbus-rtu.h          # RTU 后端接口 — 创建/串口参数/RTS
│   ├── modbus-tcp.h          # TCP 后端接口 — 创建/listen/accept
│   ├── modbus-version.h      # 版本号宏
│   ├── modbus-private.h      # 内部数据结构（不对外暴露）
│   ├── modbus-rtu-private.h  # RTU 后端内部数据
│   ├── modbus-tcp-private.h  # TCP 后端内部数据
│   └── config.h              # 平台配置宏
└── src/
    ├── modbus.c              # 主协议逻辑 — 帧构建/解析/收发
    ├── modbus-data.c         # 位/寄存器数据转换工具
    ├── modbus-rtu.c          # RTU 后端 — 串口读写 + CRC
    └── modbus-tcp.c          # TCP 后端 — socket 读写 + MBAP
```

---

## 3. 核心数据结构

### 3.1 modbus_t（不透明上下文句柄）

```c
typedef struct _modbus modbus_t;
```

通过 `modbus_new_rtu()` 或 `modbus_new_tcp()` 创建，所有 API 的第一个参数。

### 3.2 数据映射表

```c
typedef struct _modbus_mapping_t {
    int nb_bits;                  // Coil 数量
    int start_bits;               // Coil 起始地址
    int nb_input_bits;            // 离散输入数量
    int start_input_bits;         // 离散输入起始地址
    int nb_input_registers;       // 输入寄存器数量
    int start_input_registers;    // 输入寄存器起始地址
    int nb_registers;             // 保持寄存器数量
    int start_registers;          // 保持寄存器起始地址
    uint8_t  *tab_bits;           // Coil 数组
    uint8_t  *tab_input_bits;     // 离散输入数组
    uint16_t *tab_input_registers;// 输入寄存器数组
    uint16_t *tab_registers;      // 保持寄存器数组
} modbus_mapping_t;
```

### 3.3 功能码

| 宏 | 值 | 说明 |
|------|:--:|------|
| `MODBUS_FC_READ_COILS` | 0x01 | 读线圈 |
| `MODBUS_FC_READ_DISCRETE_INPUTS` | 0x02 | 读离散输入 |
| `MODBUS_FC_READ_HOLDING_REGISTERS` | 0x03 | 读保持寄存器 |
| `MODBUS_FC_READ_INPUT_REGISTERS` | 0x04 | 读输入寄存器 |
| `MODBUS_FC_WRITE_SINGLE_COIL` | 0x05 | 写单线圈 |
| `MODBUS_FC_WRITE_SINGLE_REGISTER` | 0x06 | 写单寄存器 |
| `MODBUS_FC_WRITE_MULTIPLE_COILS` | 0x0F | 写多线圈 |
| `MODBUS_FC_WRITE_MULTIPLE_REGISTERS` | 0x10 | 写多寄存器 |
| `MODBUS_FC_MASK_WRITE_REGISTER` | 0x16 | 掩码写寄存器 |
| `MODBUS_FC_WRITE_AND_READ_REGISTERS` | 0x17 | 读写多寄存器 |

### 3.4 协议异常码

| 错误宏 | 说明 |
|------|------|
| `EMBXILFUN` | 非法功能码 |
| `EMBXILADD` | 非法数据地址 |
| `EMBXILVAL` | 非法数据值 |
| `EMBXSFAIL` | 从站设备故障 |
| `EMBXACK` | 确认 |
| `EMBXSBUSY` | 从站繁忙 |
| `EMBMDATA` | 数据太多（本地错误） |
| `EMBBADCRC` | CRC 校验失败 |

---

## 4. 公共 API 接口

### 4.1 创建与销毁

```c
/* RTU 模式 */
modbus_t *modbus_new_rtu(const char *device, int baud, char parity, int data_bit, int stop_bit);

/* TCP 模式 */
modbus_t *modbus_new_tcp(const char *ip_address, int port);

/* TCP PI（协议无关，支持 IPv4/IPv6） */
modbus_t *modbus_new_tcp_pi(const char *node, const char *service);

/* 释放资源 */
void modbus_free(modbus_t *ctx);
```

---

### 4.2 连接管理

```c
/* 建立连接 */
int modbus_connect(modbus_t *ctx);

/* 关闭连接 */
void modbus_close(modbus_t *ctx);

/* 清空缓冲区 */
int modbus_flush(modbus_t *ctx);

/* TCP 服务器端: 监听 */
int modbus_tcp_listen(modbus_t *ctx, int nb_connection);

/* TCP 服务器端: accept */
int modbus_tcp_accept(modbus_t *ctx, int *s);
```

---

### 4.3 参数配置

```c
/* 从站地址 */
int modbus_set_slave(modbus_t *ctx, int slave);
int modbus_get_slave(modbus_t *ctx);

/* 响应超时（秒 + 微秒） */
int modbus_set_response_timeout(modbus_t *ctx, uint32_t to_sec, uint32_t to_usec);
int modbus_get_response_timeout(modbus_t *ctx, uint32_t *to_sec, uint32_t *to_usec);

/* 字节间超时 */
int modbus_set_byte_timeout(modbus_t *ctx, uint32_t to_sec, uint32_t to_usec);

/* 错误恢复模式 */
int modbus_set_error_recovery(modbus_t *ctx, modbus_error_recovery_mode mode);

/* 调试开关 */
int modbus_set_debug(modbus_t *ctx, int flag);

/* 错误消息 */
const char *modbus_strerror(int errnum);
```

---

### 4.4 数据读写（主站模式）

```c
/* 读线圈 0x01 */
int modbus_read_bits(modbus_t *ctx, int addr, int nb, uint8_t *dest);

/* 读离散输入 0x02 */
int modbus_read_input_bits(modbus_t *ctx, int addr, int nb, uint8_t *dest);

/* 读保持寄存器 0x03 */
int modbus_read_registers(modbus_t *ctx, int addr, int nb, uint16_t *dest);

/* 读输入寄存器 0x04 */
int modbus_read_input_registers(modbus_t *ctx, int addr, int nb, uint16_t *dest);

/* 写单线圈 0x05 */
int modbus_write_bit(modbus_t *ctx, int coil_addr, int status);

/* 写单寄存器 0x06 */
int modbus_write_register(modbus_t *ctx, int reg_addr, const uint16_t value);

/* 写多线圈 0x0F */
int modbus_write_bits(modbus_t *ctx, int addr, int nb, const uint8_t *data);

/* 写多寄存器 0x10 */
int modbus_write_registers(modbus_t *ctx, int addr, int nb, const uint16_t *data);

/* 掩码写寄存器 0x16 */
int modbus_mask_write_register(modbus_t *ctx, int addr, uint16_t and_mask, uint16_t or_mask);

/* 读写多寄存器 0x17 */
int modbus_write_and_read_registers(modbus_t *ctx,
    int write_addr, int write_nb, const uint16_t *src,
    int read_addr, int read_nb, uint16_t *dest);
```

---

### 4.5 从站模式

```c
/* 创建数据映射表 */
modbus_mapping_t *modbus_mapping_new(int nb_bits, int nb_input_bits,
    int nb_registers, int nb_input_registers);

/* 创建带起始地址的映射表 */
modbus_mapping_t *modbus_mapping_new_start_address(
    unsigned int start_bits, unsigned int nb_bits,
    unsigned int start_input_bits, unsigned int nb_input_bits,
    unsigned int start_registers, unsigned int nb_registers,
    unsigned int start_input_registers, unsigned int nb_input_registers);

/* 释放映射表 */
void modbus_mapping_free(modbus_mapping_t *mb_mapping);

/* 接收请求（阻塞） */
int modbus_receive(modbus_t *ctx, uint8_t *req);

/* 从映射表自动回复 */
int modbus_reply(modbus_t *ctx, const uint8_t *req, int req_length, modbus_mapping_t *mb_mapping);

/* 手动回复异常 */
int modbus_reply_exception(modbus_t *ctx, const uint8_t *req, unsigned int exception_code);
```

---

### 4.6 原始帧操作

```c
/* 发送原始请求帧 */
int modbus_send_raw_request(modbus_t *ctx, const uint8_t *raw_req, int raw_req_length);

/* 带事务 ID 的原始请求（TCP 多主站） */
int modbus_send_raw_request_tid(modbus_t *ctx, const uint8_t *raw_req, int raw_req_length, int tid);
```

---

## 5. 使用示例

### 5.1 Modbus TCP 客户端读取保持寄存器

```c
#include "modbus.h"

modbus_t *ctx = modbus_new_tcp("192.168.1.100", 502);
if (ctx == NULL) { /* error */ }

modbus_set_slave(ctx, 1);

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

uint16_t tab_reg[32];
int rc = modbus_read_registers(ctx, 0, 10, tab_reg);
if (rc == -1) {
    fprintf(stderr, "Read failed: %s\n", modbus_strerror(errno));
} else {
    for (int i = 0; i < rc; i++) {
        printf("reg[%d]=%d\n", i, tab_reg[i]);
    }
}

modbus_close(ctx);
modbus_free(ctx);
```

### 5.2 Modbus RTU 从站

```c
#include "modbus.h"

modbus_t *ctx = modbus_new_rtu("/dev/ttyS0", 9600, 'N', 8, 1);
modbus_set_slave(ctx, 1);

modbus_mapping_t *mb_mapping = modbus_mapping_new(100, 100, 100, 100);
if (mb_mapping == NULL) { /* error */ }

if (modbus_connect(ctx) == -1) { /* error */ }

uint8_t query[MODBUS_TCP_MAX_ADU_LENGTH];
for (;;) {
    int rc = modbus_receive(ctx, query);
    if (rc > 0) {
        modbus_reply(ctx, query, rc, mb_mapping);
    }
}

modbus_mapping_free(mb_mapping);
modbus_close(ctx);
modbus_free(ctx);
```

---

## 6. 依赖关系

```
myLog.h → libmodbus
  (libmodbus 源码修改: fprintf → LOG_I/LOG_E)
```

libmodbus 是独立的开源库，仅依赖标准 POSIX（socket / termios / pthread）和项目日志模块。

---

## 7. 代码审查要点

| 项 | 状态 | 说明 |
|------|:--:|------|
| 许可证 | LGPL-2.1+ | 兼容项目 |
| 版本 | v3.1.12 | 稳定发布版 |
| 源码改动 | 2 处 | 日志宏替换（fprintf → LOG_I/E） |
| 线程安全 | 否 | 每个 modbus_t 独立，不共享 |
| 内存管理 | 手动 | modbus_free() / modbus_mapping_free() |
| RTU CRC | 查表法 | 同 func_cal_crc16 |
| TCP MBAP | 7 字节头 | 事务 ID + 协议 ID + 长度 + 单元 ID |