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

简介：面向嵌入式系统开发者，该例程资源演示了如何将SEGGER JLink的RTT Viewer工具与FreeRTOS+CLI无缝结合，在调试过程中无需打断程序执行即可完成命令下发、系统状态查询与变量读写，非常适合需要实时监控与远程调试的RTOS应用场景。整个压缩包类型为zip，共包含6个文件，其中4个C源文件与2个头文件，整体大小仅19KB，结构轻量。C源文件分别负责RTT与CLI的整合逻辑、CLI命令的解析与执行，以及用户自定义命令的具体实现；头文件则对外提供了清晰的API声明，方便直接集成到现有FreeRTOS工程中。该资源已有282人学习/下载，兼具教学参考与实际工程价值。通过研读源码，读者可以深入理解RTT实时传输机制和FreeRTOS+CLI的命令注册流程，并快速构建出自己的调试命令集，例如查看任务列表、内存占用或动态调整运行参数，从而显著提升嵌入式开发与排错的效率。 我最近在整理调试工具链时，下载了一个叫CLIbyRTT Viewer的 zip 包。这个名字挺有意思：CLI 意味着命令行，RTT Viewer 是嵌入式开发里常用的日志查看工具，zip 则是最常见不过的发布格式。说实话，在拿到这个包之前，我一直在为两件事头疼：一是 RTT 日志在自动化测试里不好采集，二是远程调试时开一整套 GUI 工具特别笨重。这个工具正好把这两个问题都解决了，用命令行方式连上 J-Link，把 RTT 日志输出到 stdout，同时支持从 stdin 回灌命令，整个调试体验一下子变得非常干净。这篇内容适合手头有 J-Link、习惯用命令行做嵌入式开发，或者正被日志采集和自动化测试困扰的工程师，我会从安装、使用、排错到自动化集成一步步拆开讲。

1. CLIbyRTT Viewer是什么：当调试日志搬进命令行

1.1 RTT 是什么，为什么它比串口日志更好用

RTT（Real-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.py

bin 目录下同时有 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\bin"

Linux 下则在 .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 EOCD

EOCD（End Of Central Directory）是 zip 文件末尾的中央目录记录，找到它才知道整个包的文件清单和偏移。如果提示找不到 EOCD，大概率是文件下载不完整，或者文件被截断。这个时候不要急着换解压软件，先对比下载体积和服务器上的文件大小，或者重新下载一次，多半能解决。

另一种情况是解压校验失败，比如 CRC 报错、文件头异常。这通常说明网络传输中发生了数据损坏，或者源文件本身有问题。处理办法是：

1. 重新下载，最好换一个网络环境
2. 用压缩包工具测试文件完整性，比如 Windows 下右键“打开”验证，Linux 下执行unzip -t
3. 确认 zip 没有密码保护。如果发布者加了密码，解压工具会在解压时要求输入密码，解压工具本身是没法猜测密码的

网上关于 zip 密码破解工具的搜索热度一直很高，但我的建议是：密码保护的 zip 包，先找作者要密码，真正的密码恢复工具对复杂密码几乎无能为力，折腾半天不如沟通来得快。

4.3 连不上目标板：排查顺序比改参数更重要

第一次连板子最容易遇到的问题就是连不上。我的排查顺序是固定的：

1. 检查 J-Link 驱动是否正常。在系统设备管理器里能看到调试器设备，或者运行 J-Link 自带的命令行工具，先确认调试器本身被系统识别
2. 检查接线。SWD 只需要 SWDIO、SWCLK、GND 三根线，目标板要单独供电
3. 检查设备型号参数。写出正确型号后，在 J-Link Commander 里执行device命令确认支持
4. 检查--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(timeout=10)

关键点在于，日志文件名里带上构建号或时间戳，这样每个版本的测试日志不会互相覆盖。回归测试结束后，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 2>&1 &

之后无论你断不断开 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"], input=cmd_input, capture_output=True, text=True, timeout=30 ) print(result.stdout)

这种方式适合小批量验证，如果真是产线环境，建议还是用更专业的产测工具，但开发阶段快速批量验证一套动作，效率提升已经很明显了。

5.4 关于 zip 发布包的两点建议

最后说两个跟 zip 包本身相关的小建议。第一，给工具做分发时，建议包里带上 README 和配置文件示例，别只丢二进制，方便别人拿到就能用。第二，如果你给 zip 包设密码，一定要在文档里把密码写清楚；很多时候不是工具不好用，是使用门槛被一些细节抬高了。

我在实际使用中最大的体会是：CLI 这种形态的调试工具，真正解决了“日志采集要手动、远程调试没界面、自动化集成无从下手”这三个痛点。如果你平时也用 J-Link，不妨试试把 RTT 日志的读取方式从 GUI 切到命令行，跑通一次之后，大概率就回不去了。

本文还有配套的精品资源，点击获取