openpilot Cabana 使用指南：CAN 数据查看、DBC 编辑与实时数据流接入

Cabana 是 openpilot 仓库中用于查看原始 CAN 数据的桌面工具（基于 Qt 构建），它是车辆 CAN 数据逆向、DBC 文件（CAN Dictionary）创建与编辑、以及 openpilot 支持新车型开发的核心工作台。本篇围绕 openpilot/tools/cabana/README.md 的使用说明展开，结合入口代码与数据流（stream）实现源码，讲解 Cabana 的完整命令行参数、从 route 回放、comma 设备远程流到 Panda 直连的四种数据接入方式，以及日志记录与 DBC 支持等底层机制，读完后可独立用 Cabana 完成路线回放调试、实车 CAN 数据抓取与 DBC 信号解析。

一、Cabana 定位：为什么需要它

根据官方 README（README.md），Cabana 的用途可以概括为三点：

1. 查看原始 CAN 数据：以时间轴方式回放/实时展示车辆总线上的每一帧 CAN 报文，支持按信号解码、波形绘图、历史轨迹分析；
2. 创建与编辑 DBC 文件：DBC（CAN Dictionaries）是描述 CAN 报文信号定义（位域、缩放、单位等）的标准格式，Cabana 直接支持加载 DBC 并对原始报文进行语义化解析；
3. 与 openpilot 生态打通：可以加载逗号账户（comma connect）中的路线（route）数据进行回放，也可通过 ZMQ 从正在运行的 comma 设备或从直连的 Panda 硬件中读取实时 CAN 报文。

从源码结构看，Cabana 采用“主窗口 + 可插拔数据流”的设计：cabana.cc 负责命令行解析并根据参数选择具体的数据流实现，所有数据流统一继承自 AbstractStream，分别位于 streams/ 目录：

数据流	文件	对应启动方式
DeviceStream	devicestream.cc	--msgq 或 --zmq <ip>，从设备读取
PandaStream	pandastream.cc	--panda / --panda-serial，直连 Panda
SocketCanStream	socketcanstream.cc	--socketcan <device>，Linux 专用
ReplayStream	replaystream.cc	默认，回放 route 录像

二、命令行参数全解

Cabana 的入口是 cabana.cc 中的 main()，参数由 parseArgs() 手动解析（第 74–127 行），未识别的选项会报错并打印用法。README 给出的用法如下：

$ ./cabana -h
Usage: ./cabana [options] route

Options:
  -h, --help                     Displays help on commandline options.
  --help-all                     Displays help including Qt specific options.
  --demo                         use a demo route instead of providing your own
  --auto                         Auto load the route from the best available source (no video):
                                 internal, openpilotci, comma_api, car_segments, testing_closet
  --qcam                         load qcamera
  --wide-road                    load wide road camera
  --msgq                         read can messages from msgq
  --panda                        read can messages from panda
  --panda-serial <panda-serial>  read can messages from panda with given serial
  --socketcan <socketcan>        read can messages from given SocketCAN device
  --zmq <ip-address>             read can messages from zmq at the specified ip-address
  --data_dir <data_dir>          local directory with routes
  --no-vipc                      do not output video
  --dbc <dbc>                    dbc file to open

Arguments:
  route                          the drive to replay.

对照源码中的 printUsage()（cabana.cc#L36-L61），可以补充几点 README 未完全覆盖的细节：

• 相机选项的别名：--wide-road 与 --ecam（前方宽路相机）、--cabin 与 --dcam（车内相机）等价，均用于选择回放时加载哪路视频；
• --socketcan 仅 Linux 可用：源码中该选项被 #ifdef __linux__ 包裹，非 Linux 平台传入会直接报错退出（cabana.cc#L98-L104）；
• --panda-serial 隐含启用 --panda：解析到该选项后会自动把 args.panda 置为 true（cabana.cc#L95-L97）；
• route 是唯一的位置参数：只接受第一个非选项参数作为 route，多传一个会报 unexpected argument 并退出（cabana.cc#L117-L122）。

各参数语义上按用途可分为三组：

1. 数据源选择：--msgq / --zmq / --panda / --panda-serial / --socketcan，四者互斥且优先级为 msgq > zmq > panda > socketcan（见下文流选择逻辑）；
2. 回放控制：--demo（内置演示路线）、--auto（按 internal、openpilotci、comma_api、car_segments、testing_closet 的优先级自动寻找路线）、--data_dir（本地 route 目录）；
3. 视图与解析：--qcam / --wide-road（加载哪路视频）、--no-vipc（不输出视频，纯 CAN 分析时可显著降低开销）、--dbc <file>（指定 DBC 文件进行信号解码）。

三、README 示例逐条解析

3.1 演示模式（Demo Mode）

cabana --demo

不带自己的路线，用内置演示路线快速体验 Cabana。在源码中，--demo 会把 route 替换为常量 DEMO_ROUTE（cabana.cc#L181-L183），后续与普通 route 回放走同一套 ReplayStream::loadRoute() 流程。

3.2 加载指定路线

cabana "5beb9b58bd12b691/0000010a--a51155e496"

route 标识形如 <设备号>/<路线名>--<路线哈希>，可把自己的路线 ID 代入。回放加载发生在 replaystream.cc#L46-L84 的 loadRoute() 中：

• 底层通过 openpilot 的 Replay 组件按 route 拉取 can、narrowRoadEncodeIdx（主路视频）、cabinEncodeIdx（车内视频）、wideRoadEncodeIdx（宽路视频）、carParams 等分片（segment）数据；
• 数据下载缓存目录被固定为 /tmp/comma_download_cache（replaystream.cc#L9-L18）；
• 鉴权失败的处理：如果 route 属于逗号账户且本地没有凭据，Cabana 会明确提示运行 python3 openpilot/tools/lib/auth.py（对应仓库中的 auth.py）完成登录，从而获得自己账户内路线的访问权限；已有凭据但权限不足时则提示“该路线可能是私有路线”；
• 网络错误与 route 不存在会分别给出可操作的错误信息，加载失败时 main() 直接以 0 退出码结束。

另外 --data_dir <dir> 可以把 data_dir 传给 loadRoute()，用于从本地目录加载路线，适合离线分析。

3.3 加载多路相机视频

cabana "5beb9b58bd12b691/0000010a--a51155e496" --cabin --wide-road

相机选项在 cabana.cc#L172-L176 被转换为 REPLAY_FLAG_* 标志位传给回放流：--wide-road → REPLAY_FLAG_WIDE_ROAD，--qcam → REPLAY_FLAG_QCAMERA，--cabin → REPLAY_FLAG_CABIN_CAMERA，--no-vipc → REPLAY_FLAG_NO_VIPC。这些标志决定回放时从路线中拉取哪几路编码视频（对应上文 loadRoute() 中的 cabinEncodeIdx / wideRoadEncodeIdx 分片）。

3.4 从 comma 设备实时流（ZMQ 方式）

README 给出的标准流程是：先 SSH 登录设备并在设备上启动消息桥，再在本地用 --zmq 连接：

# 在 comma 设备上的 shell 中
cd /data/openpilot
./openpilot/cereal/messaging/bridge &

# 在本地机器上
cabana --zmq <ipaddress>

其中 bridge 对应仓库中的 bridge.cc，它把设备内部的 msgq 消息按服务名过滤后转发到本地 ZMQ；--zmq 方式订阅的是 can 服务，因此只能看到 CAN 报文。

这里有一个 README 未展开但源码中很关键的细节：Cabana 也可以自动帮你启动 bridge。当传入 --zmq 地址后，DeviceStream::start() 会 fork() 出子进程直接 exec 本地的 bridge 可执行文件，路径取为 executableDir()/../../cereal/messaging/bridge，并传入设备地址和过滤规则 "/\"can/\""（只转发 can 服务），exec 失败时通过自管道把 errno 回传父进程并报错（devicestream.cc#L48-L94）。也就是说本地只需一条 cabana --zmq <ipaddress>，无需手动 SSH 起 bridge。

实时日志记录：流式读取时 Cabana 会把 CAN 报文落盘。默认目录为 ~/cabana_live_stream/，该默认值在 settings.cc#L501 中硬编码为 homePath() + "/cabana_live_stream/"。具体写入逻辑在 livestream.cc#L14-L37 的内部 Logger 中：

• 每收到一段数据就按“距流开始的分钟数”切分 segment；
• 每个 segment 建立形如 <log_path>/<YYYY-MM-DD--HH-MM-SS>--<分钟序号>/rlog 的文件，CAN 事件以 capnp 二进制追加写入；
• 日志开关与路径可在界面 menu -> tools -> settings 中修改（对应 settingsdialog.cc#L54-L62 中的 “Enable live stream logging” 选项，settings.log_livestream 默认为 true，见 core/settings.h#L22-L24）。

断开设备后，可以在 Cabana 的 stream selector 对话框中选择 “browse local route”，回放刚才录下的 CAN 数据——因为 rlog 文件与 openpilot 的日志格式一致。

3.5 从 Panda 硬件直连

cabana --panda
# 多 Panda 时用 --panda-serial 指定序列号

PandaStream 的实现（pandastream.cc）值得注意几点安全与稳定性设计：

• 构造即连接：连接失败会抛出异常，main() 捕获后打印错误并退出（cabana.cc#L160-L166）；
• 强制 NO_OUTPUT 安全模式：连接后先 set_safety_model(SafetyModel::NO_OUTPUT)，确保 Cabana 只做读取、绝不会向总线发出任何报文（pandastream.cc#L13-L38）；
• 三总线 + CAN-FD 处理：固定配置 3 个 bus，并对 Red Panda / Red Panda V2 支持 CAN-FD 数据速率设置（未启用 FD 时会把 data speed 压到 10kbps 作为禁用手段）；
• 断线自动重连：streamThread() 每秒轮询一次 can_receive()，检测到连接丢失会打印提示并尝试重新 connect()（pandastream.cc#L40-L72），期间通过 send_heartbeat(false) 维持心跳。

3.6 流选择对话框

cabana

不带任何参数直接运行 Cabana 时，main() 中 stream 保持为 nullptr，随后 mainwin.cc 弹出 stream selector 对话框，允许在“演示路线 / 输入 route / 浏览本地路线 / 连接 Panda / 连接 SocketCAN / ZMQ 设备”等来源之间切换，适合不熟悉命令行的场景。相关 UI 代码见 streamselector.cc。

四、启动时的数据流选择逻辑

把上述行为串起来，main() 中按以下优先级构造数据流（cabana.cc#L154-L192）：

1. --msgq → DeviceStream（本机 msgq，设备端调试用）；
2. --zmq <ip> → DeviceStream(ip)（远程 ZMQ）；
3. --panda 或 --panda-serial → PandaStream（USB 直连）；
4. --socketcan（仅 Linux 且平台可用）→ SocketCanStream；
5. 其余情况 → 若提供了 route 或 --demo，创建 ReplayStream 并 loadRoute()；都没有则交给主窗口的流选择对话框处理。

构造完成后统一 MainWindow w(stream, dbc)，即以观察者模式把数据流挂到界面：消息列表（messageswidget.cc）、信号视图（signalview.cc）、历史日志（historylog.cc）、二进制视图（binaryview.cc）、波形图（chart/）等组件订阅同一份 CanData（core/can_data.h）。

回放流的推进机制同样值得了解：ReplayStream::eventFilter() 在回放线程中被逐事件调用，提取每个 cereal::Event 中的 can 数组并通过 updateEvent() 更新到 CanData，同时按 settings.fps 限频触发界面刷新（replaystream.cc#L86-L105）。实时流（LiveStream）则维护 streamThread（收包）与 updateThread（按 fps 合并刷新）两个线程，并支持暂停、变速与 seek（livestream.cc#L63-L144）。

五、DBC 文件支持

Cabana 的 DBC 子系统位于 dbc/ 目录：

• dbcfile.cc / dbcmanager.cc：DBC 文件的解析与多文件管理，启动时通过 --dbc 传入的文件会作为参数传给 MainWindow 并在那里加载；
• generate_dbc_json.py：DBC 到 JSON 的转换脚本，配合仓库中的 DBC 生成流程使用；
• 核心类型（CAN 帧数据、报文 ID、信号颜色等）定义在 core/can_data.h 与 core/color.h。

加载 DBC 后，界面中的信号名、缩放系数、单位均来自 DBC 定义，这是用它“创建和编辑 DBC”的主要工作方式：先用裸报文观察总线上未定义信号，再对照 tools/car_porting 目录下的示例（如 tools/car_porting 中的 notebook）定位信号含义，最后把定义补进 DBC。

六、相关路径速查

内容	仓库路径
Cabana 使用说明	openpilot/tools/cabana/README.md
命令行入口与参数解析	openpilot/tools/cabana/cabana.cc
主窗口（含流选择对话框接入）	openpilot/tools/cabana/mainwin.cc
四种数据流实现	openpilot/tools/cabana/streams/
DBC 解析与管理	openpilot/tools/cabana/dbc/
设置项（日志开关/路径/fps 等）	openpilot/tools/cabana/settings.cc、openpilot/tools/cabana/core/settings.h
消息桥（设备端 ZMQ 转发）	openpilot/openpilot/cereal/messaging/bridge.cc
账户鉴权脚本（加载私有路线需要）	openpilot/tools/lib/auth.py
车型移植与 CAN 分析示例	openpilot/tools/car_porting/
Cabana 测试	openpilot/tools/cabana/tests/test_cabana.cc

注意事项：Cabana 是依赖 Qt 的桌面程序，构建方式遵循 openpilot 整体的 SCons 构建体系（见 SConscript）；--zmq 方式要求能访问设备所在的局域网且设备上的 bridge 可正常启动；--panda 要求 Panda 以 USB 直连本机，且期间 openpilot 不应同时占用该设备；--socketcan 仅 Linux 平台编译支持。