ZMK固件USB日志功能详解

ZMK固件USB日志功能详解

zmk ZMK Firmware Repository 项目地址: https://gitcode.com/gh_mirrors/zm/zmk

前言

在嵌入式开发过程中，日志输出是调试和问题排查的重要手段。本文将深入讲解如何在ZMK固件项目中配置和使用USB日志功能，帮助开发者高效地进行键盘固件调试。

USB日志功能概述

ZMK固件基于Zephyr RTOS开发，当开发设备没有内置UART调试接口时，可以通过配置Zephyr创建一个USB CDC ACM设备，将所有printk、控制台输出和日志消息重定向到该设备。

功耗注意事项

启用日志功能会显著增加键盘的功耗，对电池续航时间产生明显影响。建议仅在需要调试时启用日志功能，日常使用时应保持关闭状态。

启用USB日志功能

ZMK提供了zmk-usb-logging代码片段来简化日志功能的启用过程。

构建配置方法

1. 自动化构建配置： 在构建配置文件中添加snippet: zmk-usb-logging即可启用日志功能，示例如下：

include:
  - board: nice_nano_v2
    shield: corne_left
    snippet: zmk-usb-logging

2. 本地构建配置： 使用west build命令时添加-S zmk-usb-logging参数：

west build -b nice_nano_v2 -S zmk-usb-logging -- -DSHIELD="corne_left"

高级日志配置

可以通过Kconfig进一步定制日志行为，例如：

• 设置CONFIG_LOG_PROCESS_THREAD_STARTUP_DELAY_MS为较大值（如8000毫秒）可以帮助捕获键盘启动初期的日志信息
• 调整日志级别可以控制输出信息的详细程度

查看日志输出

刷写固件后，设备会创建一个USB CDC ACM虚拟串口设备，可通过终端工具连接查看日志。

Linux系统

设备通常显示为/dev/ttyACM0，可使用minicom或tio连接：

sudo tio /dev/ttyACM0

Windows系统

1. 通过设备管理器查看COM端口号
2. 使用PuTTY等串口工具连接对应端口
3. 也可使用Arduino IDE内置的串口监视器

macOS系统

设备名通常为/dev/tty.usbmodemXXXXX，可使用tio连接：

sudo tio /dev/tty.usbmodem14401

连接成功后，终端会显示ZMK和Zephyr系统的各种日志消息，具体内容取决于配置的日志级别。

自定义开发板集成

对于自行开发的主控板，需要按照以下步骤添加USB日志支持：

1. 确保设备树中USB节点标记了zephyr_udc0标签
2. 示例设备树配置：

zephyr_udc0: &usbd {
    status = "okay";
};

兼容旧版本配置

对于不支持新代码片段的旧版本自定义板，可以通过Kconfig符号手动启用：

1. 在键盘配置文件中添加：

CONFIG_ZMK_USB_LOGGING=y

2. 或者在ZMK的app/prj.conf文件中设置

最佳实践建议

1. 按需启用：仅在调试时开启日志功能，日常使用保持关闭
2. 日志分级：根据调试需求合理设置日志级别
3. 启动延迟：适当配置启动延迟以捕获初始化阶段的日志
4. 多平台测试：在不同操作系统上验证日志功能可用性

通过合理使用USB日志功能，开发者可以更高效地调试ZMK固件，快速定位和解决问题。

zmk ZMK Firmware Repository 项目地址: https://gitcode.com/gh_mirrors/zm/zmk