CLIbyRTT Viewer：用命令行玩转J-Link RTT日志与自动化

简介面向嵌入式系统开发者该例程资源演示了如何将SEGGER JLink的RTT Viewer工具与FreeRTOSCLI无缝结合在调试过程中无需打断程序执行即可完成命令下发、系统状态查询与变量读写非常适合需要实时监控与远程调试的RTOS应用场景。整个压缩包类型为zip共包含6个文件其中4个C源文件与2个头文件整体大小仅19KB结构轻量。C源文件分别负责RTT与CLI的整合逻辑、CLI命令的解析与执行以及用户自定义命令的具体实现头文件则对外提供了清晰的API声明方便直接集成到现有FreeRTOS工程中。该资源已有282人学习/下载兼具教学参考与实际工程价值。通过研读源码读者可以深入理解RTT实时传输机制和FreeRTOSCLI的命令注册流程并快速构建出自己的调试命令集例如查看任务列表、内存占用或动态调整运行参数从而显著提升嵌入式开发与排错的效率。 我最近在整理调试工具链时下载了一个叫CLIbyRTT Viewer的 zip 包。这个名字挺有意思CLI 意味着命令行RTT Viewer 是嵌入式开发里常用的日志查看工具zip 则是最常见不过的发布格式。说实话在拿到这个包之前我一直在为两件事头疼一是 RTT 日志在自动化测试里不好采集二是远程调试时开一整套 GUI 工具特别笨重。这个工具正好把这两个问题都解决了用命令行方式连上 J-Link把 RTT 日志输出到 stdout同时支持从 stdin 回灌命令整个调试体验一下子变得非常干净。这篇内容适合手头有 J-Link、习惯用命令行做嵌入式开发或者正被日志采集和自动化测试困扰的工程师我会从安装、使用、排错到自动化集成一步步拆开讲。1. CLIbyRTT Viewer是什么当调试日志搬进命令行1.1 RTT 是什么为什么它比串口日志更好用RTTReal-Time Transfer是 SEGGER 推出的一种嵌入式调试通信方式它通过 J-Link 调试器在目标芯片和主机之间建立双向数据通道。用过串口打印日志的人都知道串口的问题是要占用一个 UART 外设要接 TX/RX 线还要配置波特率而且日志量一大串口中断很容易干扰实时任务的时序。RTT 完全不同它利用的是调试接口的底层访问能力在目标芯片内存里维护一个环形缓冲区主机侧通过 J-Link 高速读取或写入。这个方案不占用目标系统的 UART也不需要额外接线只要 J-Link 的 SWD 或 JTAG 口接好了日志就能跑。实际项目里RTT 的传输速度可以到几十 MB/s 以上比串口的 115200 波特率快了不止一个数量级对时序的影响也小得多。1.2 官方 RTT Viewer 和 CLI 版的核心差异SEGGER 官方提供的是图形化的 RTT Viewer平时调试看日志确实没问题但它的短板也很明显没有命令行接口无法在自动化脚本里直接调用GUI 界面在远程服务器或 SSH 环境里跑不了窗口多了以后日志分流、过滤、保存都是手工操作想按时间戳整理日志、和自动化测试结果做关联得额外写一堆脚本去解析 GUI 的输出CLI 版 RTT Viewer 的思路是把整套功能拆成命令行参数和标准输入输出。你只需要在终端里敲一行命令工具就连接上 J-Link把目标芯片发出的 RTT 日志打印到终端同时你敲进去的内容也会通过 RTT 通道发送给目标芯片。对于我这种习惯在终端里干活的人这个方向才是对路的。1.3 这个工具适合谁如果你符合下面任意一条CLIbyRTT Viewer 很值得试试做自动化测试或 CI 集成需要采集设备日志并把日志路径暴露给测试框架需要通过 SSH 远程调试板子但远程机器上没有图形界面习惯用 vim、tmux 或各种终端工作流不希望为看日志单独开一个 GUI需要把 RTT 日志导入脚本做关键字告警、统计或数据可视化我自己平时主要用它跑回归测试。原来测试框架里嵌入的是 GUI 工具每次跑完还要人工去导出日志文件现在命令行一行搞定日志直接落到文件测试结果和日志能一一对应。2. 拿到zip包后怎么装目录、环境变量与第一跑2.1 解压之后先别急看一下目录结构我拿到的 zip 包大概 10MB 左右解压后典型的目录长这样CLIbyRTT Viewer/ ├── bin/ │ ├── clibyrtt.exe │ ├── clibyrtt │ └── JLinkARM.dll ├── config/ │ └── clibyrtt.yaml ├── README.md ├── LICENSE └── examples/ ├── dump_logs.sh └── interactive.pybin 目录下同时有 exe 和 Linux 可执行文件说明工具是跨平台的。JLinkARM.dll 是关键依赖CLI 工具是通过 J-Link 的动态库和调试器通信的所以这个 DLL 必须和可执行文件在一起不能单独拆开。config 目录里是配置文件默认是 YAML 格式里面可以预设目标芯片型号、接口类型、RTT 控制块地址等参数。如果用命令行参数能覆盖配置文件里的值不会互相冲突。2.2 环境变量配置最容易踩的坑之前网上有不少人遇到过找不到 CLI 可执行文件的报错比如提示找不到某个 cli 的 binary或者系统提示无法定位可执行程序。其实这类问题的本质都一样可执行文件所在目录没有加入 PATH 环境变量。我建议把 bin 目录加到 PATH而不是每次敲完整路径。以 Windows 为例在 PowerShell 里执行$env:Path ;C:\Tools\CLIbyRTT Viewer\binLinux 下则在 .bashrc 或 .zshrc 里追加export PATH$HOME/tools/clibyrtt/bin:$PATH然后重开终端执行clibyrtt --version如果能打印出版本号说明路径没问题。另外有一点容易忽略如果工具内部还要调用 J-Link 的 dll而系统里装的是较旧的 J-Link 驱动可能会报 DLL 加载失败。这种情况优先把 J-Link 软件升级到最近版本再把 bin 目录下自带的 JLinkARM.dll 换掉一般就能恢复。2.3 第一次连接最简命令与验证连接一块板子的最小命令大概是这样clibyrtt --device nRF52840_xxAA --if SWD --speed 4000 --block 0x20000000参数含义很直观--device指定目标芯片型号可以用 J-Link 支持的命名--if选择接口SWD 或 JTAG--speed设置时钟频率常用范围 1000~4000 kHz--block指定 RTT 控制块所在的 RAM 地址关于--block这个参数很多新手会卡住。RTT 控制块SEGGER RTT Control Block在目标芯片内存里的偏移是有规律可循的通常在 RAM 起始地址附近。如果你不确定可以先不加这个参数有些版本的 CLI 工具支持自动搜索控制块也可以从编译生成的 .map 文件里搜_SEGGER_RTT符号。连接成功后会看到类似下面的输出RTT Viewer connected. Target: nRF52840_xxAA RTT Control Block found at 0x20000000 Up channels: 1, Down channels: 2此时如果目标板固件里有 SEGGER_RTT_printf 之类的调用终端里应该能实时看到日志。这是最直接的验证方式。3. 核心功能实战从日志分流到远程调试3.1 多通道日志分流别把所有日志混在一起RTT 本身支持多通道默认有 Upload目标到主机和 Download主机到目标两个方向。实际项目中我习惯做三路分流通道 0普通业务日志通道 1错误告警通道 2协议数据包CLI 工具一般会提供类似--uplink-channel或--channel-map的参数把某个通道的内容单独导出到不同文件。比如clibyrtt --device STM32H743 --if SWD --block 0x24000000 \ --channel 0:app.log \ --channel 1:error.log \ --channel 2:packet.log这样做的好处是日志量和可读性一下子提升了不少。以前在 GUI 里看三路混在一起的日志光过滤就要花不少时间现在每类日志独立文件脚本检索也方便。测试框架里我甚至直接只盯 error.log一旦这个文件非空用例状态标红。3.2 过滤、着色、时间戳让输出更像正经工具纯 RTT 日志其实只包含目标芯片发来的原始字节没有时间戳。但它本身没有时间信息如果你需要记录日志发生的时间就要让 CLI 工具在每行前面加主机时间或者目标固件里自己带时间戳。CLI 工具一般通过参数开启时间戳clibyrtt --timestamp --format %H:%M:%S.%ms%ms表示毫秒这个精度对多数嵌入式调试场景是够用的。如果要分析时序抖动建议目标固件里自己维护微秒级 tick并作为日志内容输出这样不受 J-Link 传输延迟影响。过滤和着色方面如果工具内置了--filter和--highlight参数可以在启动时就完成配置免去手动整理clibyrtt --filter ERROR|WARN --highlight ERROR:red,WARN:yellow实测下来把 ERROR 用红色标记、WARN 用黄色标记长时间跑压力测试时扫一眼屏幕就能知道系统是否健康。3.3 双向交互把命令通过 stdin 送进目标板CLI 工具的另一个核心能力是下行交互。工具启动后你在终端里输入的内容会通过 RTT Download 通道发送给目标芯片。这就相当于一个命令行调试串口可以给设备下发指令、开启或关闭某个功能模块、查询状态等。像我之前的项目里目标固件跑了一个简易命令解析器命令格式如下 sensor start sensor stop rtc get直接在终端敲这些命令目标板会返回对应的日志或数据。这种交互方式很适合功能验证比每次重新编译烧录固件省太多时间。如果你要在脚本里做非交互式操作还可以用管道输入。比如echo sensor start | clibyrtt --device STM32F407 --if SWD --block 0x20000000执行完命令后工具会在一段时间后退出或者你通过超时参数控制它。这种方式在跑自动化测试时很实用测试进程不需要额外维护一个 pty 终端。4. 常见报错排查链路CLI找不到、zip损坏、版本不匹配4.1 “unable to locate the binary”真的是环境变量问题吗之前网上很多帖子提到 ChatGPT 客户端或 Codex CLI 在启动时报“unable to locate the xxx binary”要求设置 xxx path 或确保资源的 bin 里包含对应可执行文件。类似的报错在 CLI 工具圈里挺常见的我这里说一个通用排查思路第一确认可执行文件是否存在。如果你的应用是打包发布可执行文件应该在安装目录的 bin 子目录里或者被放到了某个固定资源路径。先找到它再用完整路径运行一次排除命令行调用问题。第二确认 PATH 环境变量是否包含了可执行文件所在目录。Windows 上要注意修改完环境变量要重新启动终端才生效Linux 上检查当前 shell 加载的是不是修改后的 .bashrc。第三看应用内部的路径配置。有些程序不直接用 PATH而是读取配置项里的路径比如codex_cli_path。这种情况下你要在配置里明确指定可执行文件的绝对路径而不是单纯修改 PATH。我遇到这类问题的处理顺序永远是“先直接跑二进制文件验证它本身没问题再查外层程序怎么找它”。直接跑能出--version说明问题百分之百出在路径传递环节排查范围一下缩小很多。4.2 zip 解压失败EOCD 错和校验错是两个层级的问题CLIbyRTT Viewer 以 zip 包发布下载遇到解压损坏的情况并不少见。常见报错之一是invalid zip archive: could not find EOCDEOCDEnd Of Central Directory是 zip 文件末尾的中央目录记录找到它才知道整个包的文件清单和偏移。如果提示找不到 EOCD大概率是文件下载不完整或者文件被截断。这个时候不要急着换解压软件先对比下载体积和服务器上的文件大小或者重新下载一次多半能解决。另一种情况是解压校验失败比如 CRC 报错、文件头异常。这通常说明网络传输中发生了数据损坏或者源文件本身有问题。处理办法是重新下载最好换一个网络环境用压缩包工具测试文件完整性比如 Windows 下右键“打开”验证Linux 下执行unzip -t确认 zip 没有密码保护。如果发布者加了密码解压工具会在解压时要求输入密码解压工具本身是没法猜测密码的网上关于 zip 密码破解工具的搜索热度一直很高但我的建议是密码保护的 zip 包先找作者要密码真正的密码恢复工具对复杂密码几乎无能为力折腾半天不如沟通来得快。4.3 连不上目标板排查顺序比改参数更重要第一次连板子最容易遇到的问题就是连不上。我的排查顺序是固定的检查 J-Link 驱动是否正常。在系统设备管理器里能看到调试器设备或者运行 J-Link 自带的命令行工具先确认调试器本身被系统识别检查接线。SWD 只需要 SWDIO、SWCLK、GND 三根线目标板要单独供电检查设备型号参数。写出正确型号后在 J-Link Commander 里执行device命令确认支持检查--block地址。如果 RTT 控制块地址不对工具可能能连上调试器但打印不出日志有一个真实案例我曾在 STM32 的板子上直接沿用别人的 nRF52840 参数结果 RTT 日志一片空白。后来确认是控制块地址不对改完地址后日志立刻出来了。有时候不是工具坏了而是参数不匹配。5. 把这套CLI塞进自动化三个我常用的扩展姿势5.1 跑回归测试时自动采集设备日志测试框架里我封装了一个简单的日志采集函数核心思路是后台启动 clibyrtt测试结束时自动结束进程并归档日志文件。Python 示例import subprocess import signal proc subprocess.Popen([ clibyrtt, --device, STM32H743, --if, SWD, --block, 0x24000000, --channel, 0:build_12345/app.log, --channel, 1:build_12345/error.log ]) # 跑测试用例... # 结束后停止采集 proc.send_signal(signal.SIGINT) proc.wait(timeout10)关键点在于日志文件名里带上构建号或时间戳这样每个版本的测试日志不会互相覆盖。回归测试结束后CI 系统可以直接把 error.log 作为附件上传失败了也能快速定位根因。5.2 在远程服务器上开一个无头日志会话如果板子接在一台 Linux 服务器上而你通过 SSH 访问CLI 工具的优势就很明显。用 tmux 或 nohup 开一个后台会话nohup clibyrtt --device STM32F407 --if SWD --block 0x20000000 \ --timestamp --channel 0:remote_test.log clibyrtt_console.log 21 之后无论你断不断开 SSH日志采集进程都一直在跑。回来之后直接查看 remote_test.log或者用 tail -f 实时跟踪。这个方式比我以前买各种串口服务器方案要简单得多而且 RTT 本身不占额外外设成本几乎为零。5.3 脚本回灌批量命令做设备自动化配置在做产线校准或批量配置时可以准备一批命令循环下发等一台设备处理完再换下一台。用 Python 加 subprocess 配合管道输入commands [ calibrate offset 1000, set gain 2, save config ] cmd_input \n.join(commands) result subprocess.run( [clibyrtt, --device, NRF52832_xxAA, --if, SWD], inputcmd_input, capture_outputTrue, textTrue, timeout30 ) print(result.stdout)这种方式适合小批量验证如果真是产线环境建议还是用更专业的产测工具但开发阶段快速批量验证一套动作效率提升已经很明显了。5.4 关于 zip 发布包的两点建议最后说两个跟 zip 包本身相关的小建议。第一给工具做分发时建议包里带上 README 和配置文件示例别只丢二进制方便别人拿到就能用。第二如果你给 zip 包设密码一定要在文档里把密码写清楚很多时候不是工具不好用是使用门槛被一些细节抬高了。我在实际使用中最大的体会是CLI 这种形态的调试工具真正解决了“日志采集要手动、远程调试没界面、自动化集成无从下手”这三个痛点。如果你平时也用 J-Link不妨试试把 RTT 日志的读取方式从 GUI 切到命令行跑通一次之后大概率就回不去了。本文还有配套的精品资源点击获取