跳到主要内容

日志

DLL 底层运行日志通过回调推送到应用层。

日志类别​

log_category_t (定义在 ethercat_types.h) 是 log_callback_t 回调收到的 int category 取值，与 DLL 内部 LogCategory 一一对应：

typedef enum {
    LOG_CATEGORY_ERROR   = 0,    /* 系统错误和异常 */
    LOG_CATEGORY_WARNING = 1,    /* 潜在问题 */
    LOG_CATEGORY_MESSAGE = 2,    /* 一般信息（状态切换等） */
    LOG_CATEGORY_MAILBOX = 3,    /* CoE/SoE/FoE/EoE 邮箱通信（默认关闭） */
    LOG_CATEGORY_PDO     = 4,    /* PDO 数据变化日志（默认关闭） */
    LOG_CATEGORY_DEBUG   = 5     /* 详细调试信息（默认关闭） */
} log_category_t;
LOCAL 类别

DLL 经 log_callback_t 推送的类别只到 LOG_CATEGORY_DEBUG (5)。logging/logging.h 另提供扩展枚举 dx_log_category_t，额外含 LOG_LOCAL = 6（仅客户端本地日志使用，不经过 DLL），用于结构化日志条目 log_entry_t。

PDO 日志

PDO 日志只在 PDO 数据发生变化时输出，不会每个周期都产生日志。适合调试 PDO 映射问题。

日志回调​

SetLogCallback()​

void SetLogCallback(log_callback_t callback);

注册日志回调函数。所有 DLL 内部日志通过此回调输出。

回调类型:

typedef void (*log_callback_t)(int category, const char* message);

回调参数:

  • category (int) — 日志类别 (log_category_t)
  • message (const char*) — 日志消息文本

崩溃通知​

SetCrashCallback()​

void SetCrashCallback(crash_callback_t callback);

注册崩溃通知回调，用于捕获运行时库内部异常。运行时库同时会记录崩溃日志。

回调类型:

typedef void (*crash_callback_t)(int exception_code, const char* message);

回调参数:

  • exception_code (int) — 异常代码
  • message (const char*) — 异常消息

日志开关​

SetPDOLogging()​

void SetPDOLogging(BOOL enable);

启用/禁用 PDO 数据交换日志（LOG_CATEGORY_PDO）。默认禁用。

SetMailboxLogging()​

void SetMailboxLogging(BOOL enable);

启用/禁用邮箱通信日志（LOG_CATEGORY_MAILBOX）。默认禁用。

SetDebugLogging()​

void SetDebugLogging(BOOL enable);

启用/禁用调试日志（LOG_CATEGORY_DEBUG）。默认禁用。

日志性能

PDO 日志在高频 PDO 周期中产生大量输出，仅建议在调试时开启。生产环境中保持默认（仅 ERROR/WARNING/MESSAGE）。

调试日志归档​

CloseDebugLog()​

void CloseDebugLog(void);

关闭并刷新调试日志文件,用于程序退出前归档日志。

完整示例​

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

/* 日志回调 */
static void on_log(int category, const char* message)
{
    const char* tags[] = {"错误", "警告", "消息", "邮箱", "PDO", "调试"};
    const char* tag = (category >= 0 && category <= 5) ? tags[category] : "未知";
    printf("[%s] %s\n", tag, message);
}

/* 崩溃回调 */
static void on_crash(int code, const char* message)
{
    printf("[崩溃] 代码=%d: %s\n", code, message);
}

int main(void)
{
    dll_t dll;
    LOAD_DLL(&dll, "DarraEtherCAT.dll");

    /* 注册回调 */
    dll.SetLogCallback(on_log);
    dll.SetCrashCallback(on_crash);

    /* 启用详细日志（调试用） */
    dll.SetDebugLogging(TRUE);
    dll.SetMailboxLogging(TRUE);
    /* dll.SetPDOLogging(TRUE); -- 仅调试时开启 */

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

    getchar();

    dll.Stop(master);
    dll.Dispose(master);
    UNLOAD_DLL(&dll);
    return 0;
}
UI 集成

日志回调在非 UI 线程中触发,在 GUI 应用中显示日志时需要将消息投递到 UI 线程。