openpilot 设备连接指南：comma 3X/4 的串口控制台、SSH 与 ADB 实战

openpilot 设备连接指南：comma 3X/4 的串口控制台、SSH 与 ADB 实战

【免费下载链接】openpilotopenpilot is an operating system for robotics. Currently, it upgrades the driver assistance system on 300+ supported cars.项目地址: https://gitcode.com/GitHub_Trending/op/openpilot

本篇基于 openpilot 仓库中的 connect-to-comma 文档 展开，系统讲解如何与运行 openpilot 的 comma 硬件设备（comma 3X / comma four）建立三种调试连接：通过 panda 转发的串口控制台、基于 GitHub 公钥的 SSH，以及 USB/WiFi 方式的 ADB。读完后你将掌握每种连接方式的启用步骤、完整命令与底层参数实现（SshEnabled、AdbEnabled、GithubSshKeys等），并能结合 ssh.comma.ai 代理 从任意网络远程接入设备。

前置概念：comma 设备就是一台普通 Linux 计算机

在 openpilot 的架构中，comma 设备是一台运行 Agnos Linux 的正常 Linux 计算机，它对外暴露两类标准通道：

• SSH（Secure Shell，端口 22）；
• 串口控制台（serial console）。

这一基本定位决定了后文所有连接手段都可以用你熟悉的 Linux 远程调试工具完成，openpilot 只是在认证与开关控制上做了定制。

串口控制台（Serial Console）

串口控制台主要用于设备异常、无法通过网络接入时的底层调试。

comma 3X：从 OBD-C 口经 panda 转发

在 comma 3X 上，串口控制台从主机OBD-C 端口引出，并通过 panda 转发到 PC 侧。接入方式是在 PC 上执行：

panda/scripts/som_debug.sh

该脚本位于仓库的panda子模块内（panda/scripts/som_debug.sh）。如果已经配置好 openpilot 的开发环境，也可以直接用仓库自带的op.sh包装命令触发同一脚本，从 op.sh 的路由逻辑 可以看到som-debug子命令会被转发为op_run_command panda/scripts/som_debug.sh ...：

op.sh som-debug

登录串口控制台

接入串口后，使用默认用户登录：

项目	值
用户名	comma
密码	comma

comma four

comma four 同样暴露串口控制台，但走的是机内调试连接器（internal debug connector），而非 OBD-C 口；原文档注明专用调试硬件即将在官方渠道提供。因此对 comma four 而言，日常调试更推荐优先使用后文的 SSH 与 ADB 通道。

SSH 连接

认证机制：GitHub 公钥

SSH 接入设备需要一个配置了 SSH 公钥的 GitHub 账号。这是 openpilot 特有的认证设计：设备不让你手动粘贴密钥，而是根据你的 GitHub 用户名自动拉取你账号下所有公钥作为授权密钥。

在设备设置（Developer 页）中完成两步操作，对应源码中的两个持久化参数（见 params_keys.h 中的AdbEnabled/SshEnabled声明）：

1. Enable SSH：切换SshEnabled参数为真。在 旧版设置页 与 Mici 设置页 中，该开关的回调都会执行params.put_bool("SshEnabled", state, block=True)；
2. 填入 GitHub 用户名：触发公钥拉取流程。

源码视角：公钥是如何拉取并下发的

公钥拉取逻辑集中在 SshKeyFetcher 中：

• 在后台线程执行GET github.com/{username}.keys（15 秒超时，HTTP_TIMEOUT = 15）；
• 拉取成功后，把用户名与公钥文本分别写入两个持久化参数：
  • GithubUsername
  • GithubSshKeys
• 拉取失败（超时、HTTP 错误、账号下无密钥）时，UI 会弹出错误提示（如 "No SSH keys found for user ..."），且不写入任何参数。

点击 "REMOVE"（清除）时，SshKeyFetcher.clear()会同时删除GithubUsername与GithubSshKeys两个参数，即设备侧的授权立即失效。

此外仓库还提供等价的命令行脚本 setup_ssh_keys.py，它直接requests.get同一公钥端点后写入相同的三个参数，适合在设备上手工执行：

python tools/scripts/setup_ssh_keys.py <github username>

一个值得注意的细节：installer.cc 在安装阶段会预置一个默认的 ed25519 公钥（写入GithubSshKeys）并开启SshEnabled。这就是后文 "Notes" 中提到的默认id_rsa密钥能登录的原因——它只在安装前的 setup 状态有效。

建立 SSH 连接

完成上述设置后，通过 USB tethered 网络（设备与 PC 直连的局域网，设备地址为192.168.43.1）连接：

项目	值
用户名	comma
端口	22

示例命令：

ssh comma@192.168.43.1 -i ~/.ssh/my_github_key

对于需要在设备上进行开发（clone、push 等 Git 操作）的场景，原文档推荐使用SSH agent forwarding，这样设备端可以复用你 PC 上 agent 中的密钥完成 Git 认证。

ADB 连接

ADB（Android Debug Bridge）是第三种接入通道，适合快速进入 shell 或使用 Android 工具链。操作顺序（配合上文设备背部接口图）：

1. 用port 2（常电口）给设备上电，等待开机；
2. 在设备设置中Enable ADB（Developer 页的 ADB 开关，写入持久化参数AdbEnabled）；
3. 用port 1（USB 口）将设备连接 PC；
4. 连接设备：
   • USB 方式：adb shell
   • WiFi / 网络方式：adb connect <地址>:5555
   • tethered 连接示例：

adb connect 192.168.43.1:5555

注意：ADB over network 的默认端口是5555，这与 SSH 的 22 端口相互独立。

源码侧可以看到 ADB 开关的额外约束：在 developer.py 中，"Enable ADB" 开关设置了enabled=ui_state.is_offroad，即只有在 offroad（未上驾驶状态）时才允许切换；Mici 设置页同样把 ADB 开关放进了onroad_blocked_toggles集合（代码位置）。如果你发现 ADB 开关灰着，先确认设备处于 offroad。

注意事项（Notes）

原文档明确了两条容易踩坑的规则，均有源码佐证：

1. 公钥只拉取一次：设备只在你填写 GitHub 用户名时抓取一次公钥。若你在 GitHub 账号里增删了密钥，需要在设备设置中重新输入你的 GitHub 用户名触发再次拉取（即重新执行SshKeyFetcher.fetch流程）；
2. 默认id_rsa密钥的时效性：仓库中 common/hardware/comma/id_rsa 对应的默认密钥，只在设备处于setup 状态（尚未安装软件）时有效；一旦完成安装，该默认密钥会被移除。这也解释了为何安装后必须改用你自己的 GitHub 公钥登录。

ssh.comma.ai 远程代理

订阅 comma prime 后，无需设备在线局域网，即可从任意网络通过ssh.comma.ai中转接入设备。

推荐：写进 SSH 配置

将以下配置加入~/.ssh/config后，直接ssh comma-{dongleid}即可：

Host comma-* Port 22 User comma IdentityFile ~/.ssh/my_github_key ProxyCommand ssh [e-mail] -W %h:%p Host ssh.comma.ai Hostname ssh.comma.ai Port 22 IdentityFile ~/.ssh/my_github_key

一次性连接（不写配置）

ssh -i ~/.ssh/my_github_key -o ProxyCommand="ssh -i ~/.ssh/my_github_key -W %h:%p -p %p [e-mail]" comma@ffffffffffffffff

把ffffffffffffffff替换为你的dongle_id。

校验 ssh.comma.ai 主机指纹

为避免中间人攻击，原文档给出了中转主机的指纹，连接时应核对：

Host key fingerprint is SHA256:X22GOmfjGb9J04IA2+egtdaJ7vW9Fbtmpz9/x8/W1X4 +---[RSA 4096]----+ | | | | | . | | + o | | S = + +..| | + @ = .=| | . B @ ++=| | o * B XE| | .o o OB/| +----[SHA256]-----+

三种通道速查

通道	适用场景	认证	关键参数/命令
串口控制台	设备无网络、系统异常时兜底	默认账户comma/comma	panda/scripts/som_debug.sh、op.sh som-debug
SSH	日常开发、Git 操作	GitHub 公钥（GithubSshKeys）	ssh comma@192.168.43.1，SshEnabled
ADB	Android 工具链、快速 shell	ADB 协议	adb shell、adb connect 192.168.43.1:5555，AdbEnabled（仅 offroad 可切换）
ssh.comma.ai	任意网络远程接入（需 prime 订阅）	GitHub 密钥 + 中转主机	ssh comma-{dongleid}

排查连接问题时，建议按"串口（确认系统活着）→ 检查SshEnabled/AdbEnabled/GithubSshKeys参数 → 核对 GitHub 账号密钥是否更新"的顺序定位；其中参数读写行为可在 params_keys.h 与 params 测试 中查证各参数的持久化与类型定义。

【免费下载链接】openpilotopenpilot is an operating system for robotics. Currently, it upgrades the driver assistance system on 300+ supported cars.项目地址: https://gitcode.com/GitHub_Trending/op/openpilot