一、版本升级背景

随着工业自动化技术的快速发展，EtherCAT 协议作为实时以太网的主流标准之一，其主栈实现也在不断演进。为了提供更高效、更易用的开发体验，RT-Thread RuiChing 团队在 V1.7.2 版本对 EtherCAT 主栈进行了重要升级。 本文将详细对比版本更新前后的 API 变化，并提供完整的迁移指南。

二、核心 API 变化对比

1. 配置方式重构

变化说明： 旧版本采用了分步式配置，需要开发者手动调用一系列低级 API 来完成主站初始化、状态切换、DC 配置、PDO 映射等操作，整个过程繁琐且容易出错。开发者需要了解 EtherCAT 协议的底层细节，如状态机切换顺序、同步管理器配置等，学习成本较高。

新版本引入了统一配置模型，通过ec_slave_config_t结构体集中管理从站的所有配置参数，包括同步管理器、PDO 映射和 DC 同步设置。然后使用ecat_slave_config函数为每个从站应用配置，最后调用ecat_master_start一键完成主站启动和所有从站的配置激活。这种设计大大简化了开发流程，开发者无需关心底层实现细节，只需专注于业务逻辑的配置。

新版本优势：

• 配置代码更简洁，减少重复代码
• 降低学习门槛，无需深入了解 EtherCAT 底层协议
• 减少人为错误，提高配置的正确性
• 统一的配置结构便于维护和扩展

旧版本（复杂配置）：

// 手动配置PDO和Sync信息
ecat_config_init(&csp_master, RT_FALSE);
ecat_write_state(&csp_master, 0, EC_STATE_PRE_OP);
ecat_check_state(&csp_master, 0, &state, 2000000 * 3);
ecat_config_dc(&csp_master);
sv660n_pdo_config(&csp_master, MOTOR_NUM);
ecat_config_map_group(&csp_master, (void *)(csp_master.process_data), 0);
ecat_write_state(&csp_master, 0, EC_STATE_SAFE_OP);
ecat_write_state(&csp_master, 0, EC_STATE_OPERATIONAL);

新版本（简化配置）：

// 使用统一的设备配置结构体
static ec_slave_config_t slave_cia402_config = {
    .dc_assign_activate = 0x300,
    .dc_sync[0].cycle_time = csp_master.main_cycletime_us * 1000,
    .dc_sync[0].shift_time = 500000,
    .sync = cia402_syncs,
    .sync_count = sizeof(cia402_syncs) / sizeof(ec_sync_info_t),
};

// 设备类型识别与配置
for(int i = 0; i < slave_counts; i++) {
    ecat_slave_info(&csp_master, i, &info[i]);
    if(info[i].vendor_id == 0xee000002) {
        // IO设备配置
        ecat_slave_config(&csp_master, i, &slave_eio_config);
    } else {
        // CIA402电机配置
        ecat_slave_config(&csp_master, i, &slave_cia402_config);
    }
}

// 一键启动主栈
ecat_master_start(&csp_master);

2. DC 配置优化

变化说明： 旧版本的 DC（分布式时钟）配置是全局式的，在主站结构体ec_master_t中统一配置所有从站的 DC 参数，包括周期时间(dc_cycltime0)和偏移时间(dc_cyclshift)。这种方式限制了灵活性，所有从站必须使用相同的 DC 配置，无法针对不同设备类型或需求进行差异化设置。

新版本采用了设备级 DC 配置，将 DC 参数从主站结构体移到了从站配置结构体ec_slave_config_t中。每个从站可以拥有独立的 DC 同步设置，包括周期时间(cycle_time)和偏移时间(shift_time)。这种设计支持更精细的 DC 同步控制，不同类型的设备可以使用不同的同步参数。

新版本优势：

• 支持不同设备类型使用不同的 DC 配置
• 配置更加灵活，可针对特定设备优化同步性能
• DC 参数与从站其他配置集中管理，结构更清晰
• 支持更精确的时间同步控制

旧版本：

static ec_master_t csp_master = {
    .dc_active = 1,
    .dc_cycltime0 = 50000000,  // 50ms
    .dc_cyclshift = 10000,      // 10μs
    .dc_index = 1,
};

新版本：

// 设备级DC配置
slave_cia402_config.dc_sync[0].cycle_time = csp_master.main_cycletime_us * 1000;
slave_cia402_config.dc_sync[0].shift_time = 500000;

3. 同步配置分离

变化说明： 旧版本中，所有从站共享同一个同步配置数组(slave_syncs)，这种设计假设所有设备具有相同的同步管理器配置和 PDO 映射需求。然而，在实际应用中，不同类型的设备（如电机驱动器和 IO 模块）通常具有不同的同步特性和数据交换需求。

新版本引入了按设备类型分离的同步配置，为每种设备类型创建独立的同步配置数组（如cia402_syncs用于电机驱动器，eio_syncs用于 IO 模块）。每个配置数组针对特定设备类型的特性进行优化，包括同步管理器索引、数据方向、PDO 映射等。然后通过ecat_slave_config函数将对应的配置应用到相应类型的从站。

新版本优势：

• 支持不同设备类型使用最适合的同步配置
• 配置更加清晰，便于维护和调试
• 提高系统兼容性，支持更多类型的设备
• 减少配置冲突，提高系统稳定性

旧版本：

// 所有设备共享同一个同步配置数组
ecat_sync_info_t slave_syncs[] = {
    { 1, EC_DIR_OUTPUT, 1, &slave_pdos[0], EC_WD_DISABLE },
    { 1, EC_DIR_INPUT, 1, &slave_pdos[1], EC_WD_DISABLE },
    { 2, EC_DIR_OUTPUT, 1, &slave_pdos[2], EC_WD_DISABLE },
    { 2, EC_DIR_INPUT, 1, &slave_pdos[3], EC_WD_DISABLE },
};

新版本：

// 按设备类型分离同步配置
ecat_sync_info_t cia402_syncs[] = {
    { 2, EC_DIR_OUTPUT, 1, &slave_pdos[0], EC_WD_DISABLE },
    { 3, EC_DIR_INPUT, 1, &slave_pdos[1], EC_WD_DISABLE },
};

ecat_sync_info_t eio_syncs[] = {
    { 0, EC_DIR_OUTPUT, 1, &eio_pdos[0], EC_WD_DISABLE },
    { 1, EC_DIR_OUTPUT, 1, &eio_pdos[1], EC_WD_DISABLE },
    { 2, EC_DIR_INPUT, 2, &eio_pdos[2], EC_WD_DISABLE },
};

4. 数据处理简化

变化说明： 旧版本中，开发者需要在主循环中手动调用ecat_send_processdata_group和ecat_receive_processdata_group函数来处理过程数据的发送和接收。这种方式要求开发者严格控制数据处理的时序和频率，确保实时性能，同时还要处理业务逻辑，代码结构复杂。

新版本将数据处理逻辑完全封装到ecat_master_start函数内部，由主栈自动处理过程数据的循环发送和接收。开发者只需要实现ecat_master_usr_process回调函数来处理业务逻辑，主栈会在适当的时机自动调用该函数。这种设计将数据传输层与业务逻辑层分离，使代码结构更清晰。

新版本优势：

• 减少样板代码，专注于业务逻辑开发
• 数据处理时序由主栈统一管理，提高实时性能
• 降低开发难度，减少因时序控制不当导致的错误
• 代码结构更清晰，便于维护和调试

旧版本：

// 手动发送和接收过程数据
ecat_send_processdata_group(&csp_master, 0);
ecat_receive_processdata_group(&csp_master, 0, 2000000 * 3);

新版本：

// 数据处理被封装到ecat_master_start中
// 主循环只需要处理业务逻辑
export RT_WEAK int ecat_master_usr_process(void *arg)
{
    // 业务逻辑处理
    return RT_EOK;
}

5. 设备管理改进

变化说明： 旧版本中，开发者通常使用固定的 slave 编号来区分不同类型的设备（如示例中的 slave 3 代表 IO 设备）。这种方式存在严重的局限性，当设备拓扑结构发生变化（如添加或移除设备）时，所有依赖 slave 编号的代码都需要修改，维护成本很高。

新版本推荐使用vendor_id（厂商 ID）来区分设备类型，通过ecat_slave_info函数获取每个从站的详细信息，包括 vendor_id，然后根据 vendor_id 来判断设备类型并执行相应的处理逻辑。这种方式不依赖于设备在总线上的位置，提高了代码的灵活性和可移植性。

新版本优势：

• 设备识别不依赖于物理位置，拓扑结构变化时无需修改代码
• 提高代码的可移植性，便于在不同项目中复用
• 设备类型识别更准确可靠
• 支持动态添加或移除设备，提高系统灵活性

旧版本：

// 使用固定的slave编号区分设备
if (slave != 3)
{
    // 电机处理逻辑
}
else
{
    // IO处理逻辑
}

新版本：

// 使用vendor_id区分设备类型
if (info[slave].vendor_id != 0xee000002)
{
    // 电机处理逻辑
}
else
{
    // IO处理逻辑
}

三、迁移步骤指南

步骤 1：更新头文件和依赖

确保使用最新版本的 EtherCAT 主栈组件，并更新相关头文件包含。

步骤 2：重构 DC 配置

1. 为每种设备类型创建 ec_slave_config_t 结构体
2. 配置设备级 DC 同步参数

步骤 3：分离同步配置

1. 按设备类型创建独立的 ec_sync_info_t 数组
2. 为每种设备类型定义专属的 PDO 配置
3. 将 sync 配置关联到对应的 ec_slave_config_t 结构体

步骤 4：简化主站初始化流程

1. 移除 ecat_config_init, ecat_config_dc 等低级 API 调用
2. 使用 ecat_slave_config 为每个从站配置参数
3. 调用 ecat_master_start 启动主站

步骤 5：重构业务逻辑

1. 移除手动的 ecat_send/receive_processdata 调用
2. 使用 vendor_id 替代固定 slave 编号
3. 调整主循环结构，专注于业务逻辑

四、迁移示例

旧版本主站初始化

ecat_service_init();
ecat_master_init(&csp_master);
ecat_config_init(&csp_master, RT_FALSE);
ecat_write_state(&csp_master, 0, EC_STATE_PRE_OP);
ecat_check_state(&csp_master, 0, &state, 2000000 * 3);
ecat_config_dc(&csp_master);
sv660n_pdo_config(&csp_master, MOTOR_NUM);
ecat_config_map_group(&csp_master, (void *)(csp_master.process_data), 0);
ecat_write_state(&csp_master, 0, EC_STATE_SAFE_OP);
ecat_write_state(&csp_master, 0, EC_STATE_OPERATIONAL);

新版本主站初始化

ecat_service_init();
ecat_master_init(&csp_master);

// 配置从站参数
for(int i = 0; i < slave_counts; i++) {
    ecat_slave_info(&csp_master, i, &info[i]);
    if(info[i].vendor_id == 0xee000002) {
        ecat_slave_config(&csp_master, i, &slave_eio_config);
    } else {
        ecat_slave_config(&csp_master, i, &slave_cia402_config);
    }
}

// 启动主站
ecat_master_start(&csp_master);

五、常见问题与解决方案

Q1：迁移后 DC 同步异常

解决方案：检查 dc_cycltime0 和 dc_sync[0].cycle_time 的单位是否一致，确保配置值在合理范围内。

Q2：设备无法进入 OP 状态

解决方案：验证 ec_slave_config_t 结构体的 sync_count 参数是否正确，检查 sync 配置的索引是否与从站实际支持的 sync 管理器匹配。