从站事件

所有事件回调包含 master_index 和 slave_index 参数，由调用方自行过滤。

完整回调注册列表详见 事件。

协议专属事件

FSoE 安全事件通过独立回调注册，请参考 FSoE。

功能概览

类别	注册函数	读写	说明
状态变化	RegisterSlaveStateChangeCallbackSync/Async	只写（注册）	从站 EtherCAT 状态变化
紧急消息	RegisterEmergencyEventCallback	只写（注册）	CoE Emergency 紧急消息
热插拔	RegisterSlaveDiscoveryCallbackSync/Async	只写（注册）	从站上线/离线
DC 同步丢失	SetDCSyncLostCallback	只写（注册）	DC 同步偏差超过阈值
PreOP 重配置	RegisterSlavePreOpReconfigCallback	只写（注册）	热插拔后自动恢复

输入 PDO 数据变化回调已停用

PDO 过程数据为纯内核 RT 收发。逐周期检测输入数据变化并回调的机制已移除，本 SDK 不再提供 RegisterInputDataChangedCallback。读从站输入的金路径是进 OP 后 GetIO 一次把 packed 结构体钉在过程映像上，回调或任意线程直接读字段；CopySlaveInputPdo 是快照备选，见 PDO 输入输出。

状态变化

void RegisterSlaveStateChangeCallbackSync(state_change_callback_t callback);
void RegisterSlaveStateChangeCallbackAsync(state_change_callback_t callback);

从站 EtherCAT 状态变化通知。

回调类型：

typedef void (*state_change_callback_t)(uint16_t master_index, uint16_t slave_index,
    int old_state, int new_state);

紧急消息

void RegisterEmergencyEventCallback(emergency_callback_t callback);

CoE Emergency 消息通知。

回调类型：

typedef void (*emergency_callback_t)(uint16_t master_index, uint16_t slave_index,
    uint16_t error_code, uint16_t error_reg, uint8_t b1, uint16_t w1, uint16_t w2);

回调参数说明：

• error_code (uint16_t) — 错误代码（CANopen Emergency Error Code）
• error_reg (uint16_t) — 错误寄存器（对象 0x1001）
• b1 (uint8_t) — 制造商特定数据（字节 3）
• w1 (uint16_t) — 制造商特定数据（字节 4-5）
• w2 (uint16_t) — 制造商特定数据（字节 6-7）

从站发现/移除（热插拔）

void RegisterSlaveDiscoveryCallbackSync(discovery_callback_t callback);
void RegisterSlaveDiscoveryCallbackAsync(discovery_callback_t callback);

从站上线/离线通知。

回调类型：

typedef void (*discovery_callback_t)(uint16_t master_index, uint16_t slave_index, BOOL is_found);

DC 同步丢失

void SetDCSyncLostCallback(dc_sync_lost_callback_t callback);

DC 同步偏差超过阈值时通知。

回调类型：

typedef void (*dc_sync_lost_callback_t)(uint16_t master_index, uint16_t slave_index, int diff_ns);

PreOP 重配置

void RegisterSlavePreOpReconfigCallback(preop_reconfig_callback_t callback);

从站需要 PreOP 重配置时通知（热插拔后自动恢复）。

回调类型：

typedef void (*preop_reconfig_callback_t)(uint16_t master_index, uint16_t slave_index);

线程安全

同步 vs 异步回调

同步回调 (*Sync) 在实时 PDO 线程中直接执行，不要执行耗时操作（如文件IO、网络请求、锁竞争）。 异步回调 (*Async) 在独立线程中执行，延迟略高但更安全。

回调中避免执行耗时操作。如需处理大量数据，将数据放入队列异步处理：

static void on_state_sync(uint16_t mi, uint16_t si, int old_s, int new_s) {
    /* 快速入队，不做耗时操作 */
    enqueue_event(mi, si, old_s, new_s);
}

完整示例

#include "ethercat.h"
#include <stdio.h>

/* ===== 状态事件 ===== */
static void on_state(uint16_t mi, uint16_t si, int old_s, int new_s) {
    printf("从站 %d 状态变化: %d -> %d\n", si, old_s, new_s);
}

/* ===== 热插拔事件 ===== */
static void on_discovery(uint16_t mi, uint16_t si, BOOL found) {
    printf("从站 %d %s\n", si, found ? "上线" : "离线");
}

/* ===== 紧急消息事件 ===== */
static void on_emcy(uint16_t mi, uint16_t si,
    uint16_t code, uint16_t reg, uint8_t b1, uint16_t w1, uint16_t w2) {
    printf("从站 %d 紧急消息: 错误码=0x%04X, 寄存器=0x%04X\n", si, code, reg);
}

/* ===== DC 同步丢失事件 ===== */
static void on_dc_sync_lost(uint16_t mi, uint16_t si, int diff_ns) {
    printf("从站 %d DC 同步丢失: 偏差 %d ns\n", si, diff_ns);
}

/* ===== PreOP 重配置事件 ===== */
static void on_preop_reconfig(uint16_t mi, uint16_t si) {
    printf("从站 %d 需要 PreOP 重配置\n", si);
}

int main(void) {
    /* 注册所有从站事件回调 */
    RegisterSlaveStateChangeCallbackSync(on_state);
    RegisterSlaveDiscoveryCallbackSync(on_discovery);
    RegisterEmergencyEventCallback(on_emcy);
    SetDCSyncLostCallback(on_dc_sync_lost);
    RegisterSlavePreOpReconfigCallback(on_preop_reconfig);

    uint16_t master = Initialize();
    SetNetwork(master, "\\Device\\NPF_{...}", "");
    SetStateSequence(master, EC_STATE_OPERATIONAL, 10000);
    Start(master);

    printf("按回车退出...\n");
    getchar();

    Stop(master);
    Dispose(master);
    return 0;
}