扩展libmodbus：实现Modbus TCP/RTU协议下的文件记录传输

1. 为什么需要Modbus文件传输功能？

在工业自动化领域，Modbus协议就像设备之间的"普通话"，但大多数人只用它来读写简单的寄存器值。想象一下，你每次想给PLC更新程序，都得把固件拆成无数个16位数据块，再用传统的寄存器写入功能一个个传输——这就像用快递寄送一本百科全书，却要求每页单独包装。

文件记录传输功能（功能码0x14和0x15）就是为解决这类问题而生的。我曾在汽车生产线项目中遇到过真实案例：需要定期更新200多台PLC的配方参数，传统方法每次要花3小时，改用文件传输后缩短到15分钟。这种功能特别适合：

• 固件升级：直接将二进制文件分段传输
• 配方管理：批量下发生产参数配置文件
• 数据备份：读取设备中的日志文件
• 批量配置：同时更新多个设备参数集

2. 协议深度解析：文件记录传输的奥秘

2.1 协议帧结构解剖

Modbus文件记录请求就像精心设计的快递包裹，每个字段都有特定作用。以写文件请求为例（功能码0x15）：

code复制[ 设备地址 ] [ 功能码0x15 ] [ 字节计数 ] [ 子请求数 ]
[ 引用类型 ] [ 文件号Hi ] [ 文件号Lo ] [ 记录号Hi ] [ 记录号Lo ]
[ 记录长度Hi ] [ 记录长度Lo ] [ 数据Hi ] [ 数据Lo ]...

关键字段的玄机在于：

• 引用类型：必须固定为0x06，这是协议规定的"文件操作身份证"
• 文件号：相当于文件目录索引，范围1-65535
• 记录号：文件内部的"页码"，最大9999（0x270F）
• 记录长度：每次最多传输122个16位数据（244字节）

我曾踩过坑：某设备厂商的文件号从100开始，直接写死文件号1导致操作失败。建议在代码中加入文件号有效性检查，就像这样：

c复制if(fileNumber < MIN_FILE_NUM || fileNumber > MAX_FILE_NUM) {
    errno = EINVAL;
    return -1;
}

2.2 数据分片策略

大文件传输需要分片处理，就像快递大件要拆箱运输。这里有个实用技巧：

c复制#define MAX_RECORD_LEN 122  // 协议限制单次最大传输量
uint16_t buffer[MAX_RECORD_LEN];
size_t total_records = file_size / sizeof(uint16_t);

for(size_t i=0; i<total_records; i+=MAX_RECORD_LEN) {
    size_t chunk_size = MIN(MAX_RECORD_LEN, total_records-i);
    // 读取文件片段到buffer...
    modbus_write_file_record(ctx, file_num, start_rec+i, buffer, chunk_size);
}

注意记录号要连续递增，就像快递单号不能重复。我曾遇到设备要求记录号必须从0开始，否则会返回非法地址错误。

3. libmodbus库扩展实战

3.1 函数声明与宏定义

在modbus.h中添加这些核心定义就像给工具箱新增两把专用扳手：

c复制/* 文件记录操作功能码 */
#define MODBUS_FC_READ_FILE_RECORD  0x14
#define MODBUS_FC_WRITE_FILE_RECORD 0x15

/* 写文件记录
 * ctx: modbus上下文
 * fileNumber: 目标文件编号
 * startRecordNumber: 起始记录号
 * fileData: 要写入的数据数组
 * length: 数据长度(以16位为单位) */
MODBUS_API int modbus_write_file_record(
    modbus_t *ctx, uint16_t fileNumber, 
    uint16_t startRecordNumber, 
    const uint16_t *fileData, 
    uint8_t length);

/* 读文件记录
 * dest: 读取数据的存放缓冲区 */
MODBUS_API int modbus_read_file_record(
    modbus_t *ctx, uint16_t fileNumber,
    uint16_t startRecordNumber,
    uint16_t length,
    uint16_t *dest);

3.2 核心函数实现细节

写文件函数的构建就像组装精密仪器，每个字节都不能错位：

c复制int modbus_write_file_record(modbus_t *ctx, uint16_t fileNumber, 
                           uint16_t startRecordNumber,
                           const uint16_t *fileData, uint8_t length) 
{
    uint8_t req[MAX_MESSAGE_LENGTH];
    // 参数校验(实战中这里最容易出问题)
    if (length > 122 || startRecordNumber > 0x270F) {
        errno = EINVAL;
        return -1;
    }
    
    int req_length = ctx->backend->build_request_basis(
        ctx, MODBUS_FC_WRITE_FILE_RECORD, 0, 0, req);
    
    // 构建专用字段
    req[req_length++] = 7 + length*2;  // 字节计数
    req[req_length++] = 0x06;          // 引用类型
    req[req_length++] = fileNumber >> 8;
    req[req_length++] = fileNumber & 0xFF;
    req[req_length++] = startRecordNumber >> 8;
    req[req_length++] = startRecordNumber & 0xFF;
    req[req_length++] = length >> 8;
    req[req_length++] = length & 0xFF;
    
    // 填充数据(注意字节序处理)
    for(int i=0; i<length; i++) {
        req[req_length++] = fileData[i] >> 8;
        req[req_length++] = fileData[i] & 0xFF;
    }
    
    // 发送并处理响应
    int rc = send_msg(ctx, req, req_length);
    if (rc > 0) {
        uint8_t rsp[MAX_MESSAGE_LENGTH];
        rc = _modbus_receive_msg(ctx, rsp, MSG_CONFIRMATION);
        // ... 校验响应 ...
    }
    return rc;
}

读文件函数的关键在于解析响应数据：

c复制int modbus_read_file_record(modbus_t *ctx, uint16_t fileNumber,
                          uint16_t startRecordNumber,
                          uint16_t length, uint16_t *dest)
{
    uint8_t req[MAX_MESSAGE_LENGTH];
    // ... 类似写操作的请求构建 ...
    
    // 接收响应时的特殊处理
    uint8_t rsp[MAX_MESSAGE_LENGTH];
    int rc = _modbus_receive_msg(ctx, rsp, MSG_CONFIRMATION);
    if (rc > 0) {
        int offset = ctx->backend->header_length;
        // 跳过响应头部的4个字节
        for (int i = 0; i < length; i++) {
            dest[i] = (rsp[offset + 4 + 2*i] << 8) | 
                       rsp[offset + 5 + 2*i];
        }
    }
    return rc;
}

4. 工业级应用中的坑与解决方案

4.1 超时与重试机制

现场环境网络不稳定就像在颠簸路上开车。建议这样增强鲁棒性：

c复制#define MAX_RETRY 3
int retry_count = 0;
int rc = -1;

while (retry_count < MAX_RETRY && rc == -1) {
    rc = modbus_read_file_record(ctx, file_num, rec_num, len, buf);
    if (rc == -1) {
        usleep(500000); // 500ms延迟
        modbus_clear_errors(ctx); // 清除错误状态
        retry_count++;
    }
}
if (rc == -1) {
    // 记录错误日志
    syslog(LOG_ERR, "File read failed after %d retries", MAX_RETRY);
}

4.2 数据校验策略

工业现场电磁干扰就像通话时的杂音。我推荐两种校验方式：

1. CRC追加法：在文件末尾添加校验数据

c复制uint16_t calculate_crc(const uint16_t *data, size_t len) {
    uint32_t crc = 0;
    for(size_t i=0; i<len; i++) {
        crc += data[i];
    }
    return (uint16_t)(crc & 0xFFFF);
}

// 发送时追加CRC
uint16_t crc = calculate_crc(fileData, data_len);
modbus_write_file_record(ctx, file_num, rec_num, fileData, data_len);
modbus_write_file_record(ctx, file_num, rec_num+data_len, &crc, 1);

2. 回读比对法：写入后立即读取验证

c复制uint16_t write_buf[DATA_LEN], read_buf[DATA_LEN];
// ...填充write_buf...
modbus_write_file_record(ctx, file_num, 0, write_buf, DATA_LEN);
modbus_read_file_record(ctx, file_num, 0, DATA_LEN, read_buf);

if(memcmp(write_buf, read_buf, sizeof(write_buf)) != 0) {
    // 触发重传机制
}

5. 完整示例：PLC固件更新实战

假设我们要通过Modbus TCP更新PLC固件，下面是完整流程：

c复制int update_plc_firmware(modbus_t *ctx, const char *firmware_path) {
    FILE *fp = fopen(firmware_path, "rb");
    if (!fp) return -1;

    fseek(fp, 0, SEEK_END);
    long file_size = ftell(fp);
    fseek(fp, 0, SEEK_SET);
    
    uint16_t file_num = 1; // 固件存储区文件编号
    uint16_t rec_num = 0;
    uint16_t buffer[122];
    size_t total_transferred = 0;
    
    while (!feof(fp)) {
        size_t read_size = fread(buffer, sizeof(uint16_t), 122, fp);
        if (read_size == 0) break;
        
        int rc = modbus_write_file_record(ctx, file_num, rec_num, 
                                        buffer, read_size);
        if (rc == -1) {
            fclose(fp);
            return -1;
        }
        
        total_transferred += read_size * sizeof(uint16_t);
        rec_num += read_size;
        printf("Progress: %.1f%%\r", 
              (float)total_transferred/file_size*100);
    }
    
    fclose(fp);
    return 0;
}

测试时建议先用小文件验证，比如创建一个测试文件：

bash复制# 生成1KB测试文件
dd if=/dev/urandom of=test.bin bs=1024 count=1

6. 性能优化技巧

在传输大型配置文件时，这些技巧能显著提升速度：

1. 批量传输：尽量每次传满122个记录

c复制// 不好的做法：单记录传输
for(int i=0; i<1000; i++) {
    modbus_write_file_record(ctx, 1, i, &data[i], 1);
}

// 优化做法：批量传输
int batch_size = 122;
for(int i=0; i<1000; i+=batch_size) {
    int len = MIN(batch_size, 1000-i);
    modbus_write_file_record(ctx, 1, i, &data[i], len);
}

2. 并行连接：对支持多连接的设备

c复制// 主连接传前半部分
modbus_write_file_record(ctx1, 1, 0, data, 500);
// 从连接传后半部分
modbus_write_file_record(ctx2, 1, 500, data+500, 500);

3. 压缩传输：在MCU端实现简单压缩算法

c复制// 行程编码压缩示例
void rle_compress(const uint16_t *input, uint16_t *output, size_t len) {
    uint16_t current = input[0];
    size_t count = 1, out_idx = 0;
    
    for(size_t i=1; i<len; i++) {
        if(input[i] == current && count < 65535) {
            count++;
        } else {
            output[out_idx++] = current;
            output[out_idx++] = count;
            current = input[i];
            count = 1;
        }
    }
    output[out_idx++] = current;
    output[out_idx++] = count;
}

7. 跨平台兼容性处理

不同设备厂商对协议实现常有差异，就像方言变化。常见问题包括：

1. 字节序问题：某些设备要求大端序优先

c复制// 兼容性写法
uint16_t swap_bytes(uint16_t value) {
    return (value << 8) | (value >> 8);
}

void prepare_data(uint16_t *data, size_t len, int need_swap) {
    if (!need_swap) return;
    for(size_t i=0; i<len; i++) {
        data[i] = swap_bytes(data[i]);
    }
}

2. 文件编号偏移：有的设备从0开始，有的从100开始

c复制int resolve_file_number(int logical_num, int vendor_type) {
    switch(vendor_type) {
        case VENDOR_A: return logical_num + 100;
        case VENDOR_B: return logical_num;
        default: return logical_num;
    }
}

3. 超时设置：大文件传输需要延长超时

c复制// 根据数据量动态设置超时
void set_adaptive_timeout(modbus_t *ctx, size_t data_size) {
    uint32_t timeout = 1000 + data_size * 10; // 基础1秒 + 每字节10us
    modbus_set_response_timeout(ctx, timeout / 1000, 
                              (timeout % 1000) * 1000);
}

实际项目中，建议先通过设备信息读取功能识别设备类型：

c复制uint8_t info[256];
modbus_report_slave_id(ctx, info);
// 解析厂商ID等信息...