本页面向具备中等经验的开发者，系统梳理 atom01_firmware 多仓库工程中各子模块的典型故障现象、根因定位方法与修复步骤。内容覆盖 USB2CAN 固件运行时异常、Zephyr 编译环境配置、OrangePi / RDK X5 镜像构建失败 以及 多仓库协同与 CI 流水线 四大维度，力求通过可观测的日志与硬件指示快速缩小问题范围。

USB2CAN 固件运行时故障

LED 状态诊断法

roboto_usb2can 通过三色 LED 以不同闪烁模式外化系统状态，这是最快速的现场诊断手段。蓝灯（PC11）反映 USB 协议栈健康度，黄灯（PA7）映射 CAN 总线状态，绿灯（PA1）指示数据收发活动。各状态对应的闪烁周期在源码中以 led_pattern 结构体明确定义：蓝灯就绪状态为 500ms 等周期闪烁，错误状态加速至 100ms；黄灯在正常工作时同样保持 500ms 周期，进入警告后变为 200ms 亮 / 1800ms 灭，而总线关闭或错误洪水时则与蓝灯错误模式一致。

若现场观察到蓝灯与黄灯同时快速闪烁，说明固件已触发错误保护机制：在 1 秒统计窗口内检测到超过 50 个错误帧，或连续 10 次进入 ERROR_PASSIVE 后，主动调用 can_stop() 强制 Bus-Off，以防止总线被异常流量冻结。

Sources: roboto_usb2can.h, main.c

Windows 免驱识别失败

该固件依赖 MSOS 2.0 BOS 描述符实现 WinUSB 自动绑定，无需手动安装驱动。若设备管理器出现黄色感叹号，首先排除物理层问题：Type-C 线缆必须支持数据传输（部分充电线无 D+/D-），随后检查设备管理器中设备 VID/PID 是否为 1D50:606F。若仍被识别为未知设备，可借助 Zadig 工具手动绑定 WinUSB 驱动。

上位机 Python 工具启动时若抛出 Device not found (VID=0x1D50, PID=0x606F)，则确认工作目录下存在 libusb-1.0.dll（Windows）或系统已安装 libusb（Linux），并检查当前用户是否对 USB 设备具有访问权限。

Sources: readme.md, roboto_usb2can_tool.py

Linux SocketCAN 接口异常

插入设备后执行 ip link show type can 若未出现 can0，按以下顺序排查：

1. 内核驱动加载：dmesg | grep gs_usb 应输出 Configuring for 1 channels；若无输出，确认内核版本 ≥ 3.16 且已编译 gs_usb 模块。
2. udev 规则生效：项目提供 99-roboto-usb2can.rules，将其复制到 /etc/udev/rules.d/ 后执行 sudo udevadm control --reload-rules && sudo udevadm trigger，随后重新插拔设备。规则文件权限必须为 644，否则 systemd-udev 可能忽略。
3. 权限不足：非 root 用户需加入 plugdev 与 dialout 组，重新登录后生效；临时验证可执行 sudo chmod 666 /dev/bus/usb/XXX/YYY。

Sources: 99-roboto-usb2can.rules, readme_cn.md

CAN 总线高负载丢包与 Bus-Off 恢复

在高波特率或多设备并联场景下，若出现间歇性丢包或“重新插拔后无法发送”，根本原因在于 Linux 默认 CAN 驱动在 Bus-Off 后不会自动恢复，且 USB 全速带宽有限，长帧零填充可能加剧传输抖动。

项目测试脚本 test_roboto_usb2can.sh 中给出了两项关键修复：

• 强制 MTU 为 16：ip link set $IF mtu 16 抑制驱动零填充，提升 USB 传输效率。
• 启用自动恢复：ip link set $IF type can bitrate 1000000 restart-ms 100 在 Bus-Off 后 100ms 自动重启，避免死锁。

此外，多设备并发测试时，绝对避免使用 cangen -g 0（零间隔发送），否则最小 ID 设备将垄断总线；应改用 -g 0.5 -I R 引入随机 ID，实现统计意义上的公平竞争。

Sources: test_roboto_usb2can.sh

Zephyr 编译环境问题

west workspace 初始化失败

roboto_usb2can 依赖 cannectivity 模块提供的 GS-USB 协议栈。若 west build 报错找不到 cannectivity/usb/class/gs_usb.h，说明 west.yml 中的 cannectivity 项目未正确同步。标准修复流程如下：

# 1. 确认 manifest 包含 cannectivity
cat zephyr/submanifests/cannectivity.yaml

# 2. 若缺失，手动创建并写入项目定义
# 3. 重新同步
west update

当前 west.yml 已将 cannectivity 声明为外部项目并指定 path: custom/cannectivity，因此必须在 Zephyr 工作区内执行 west update 拉取，而非仅克隆本仓库。

Sources: west.yml

新旧 USB 协议栈切换异常

固件默认启用 Zephyr 新一代 USB 设备栈 CONFIG_USB_DEVICE_STACK_NEXT=y。若在旧版 Zephyr SDK 中强行使用旧栈配置（CONFIG_USB_DEVICE_STACK=y），会导致 GS-USB 类驱动注册符号冲突或枚举失败。prj.conf 中旧栈相关行已被注释，请勿同时取消注释新旧两组配置。若确需回退旧栈，必须同步关闭 CONFIG_USBD_GS_USB 系列选项，并在 CMakeLists.txt 中确认未引用 usbd 相关头文件路径。

Sources: prj.conf

Release 二进制未生成

执行 west build 后仅在 build/zephyr/ 下得到 zephyr.bin，而未生成带版本号的 roboto_usb2can_vX.Y.Z_YYYYMMDD.bin，原因是 CMake 的 Release 产物目标 release_files 不会自动触发。正确步骤为：

west build -b roboto_usb2can -- -DCMAKE_BUILD_TYPE=Release
cd build
cmake --build . --target release_files

Sources: CMakeLists.txt

OrangePi 构建系统故障

路径含空格导致构建中断

orangepi-build/build.sh 在启动时会强制检查 ${SRC} 是否包含空格字符，一旦命中即立即退出。这是为了避免 shell 变量扩展在多处编译脚本中引发路径断裂。请将仓库克隆到不含空格、中文或特殊符号的绝对路径下，例如 /opt/orangepi-build。

Sources: build.sh

非 root 权限与 Docker 切换

OrangePi 构建脚本强制要求 root 权限运行。若当前用户非 root，脚本会自动尝试通过 sudo 重新调用自身。对于 Docker 构建场景，脚本额外检测用户是否属于 docker 组；若未安装 Docker 且传入 docker 参数，脚本会在 Debian 系主机上自动配置官方仓库并安装 docker-ce。建议首次在裸机 Ubuntu 22.04 上直接以 sudo ./build.sh 运行，避免嵌套 sudo 导致环境变量丢失。

Sources: build.sh

内核编译缓存与 Git 状态冲突

build.sh 默认在启动时尝试 git pull 更新脚本自身。若本地已对仓库进行修改，CHANGED_FILES 检测会中断构建流程，提示用户选择 diff、exit 或回车忽略。CI 场景下可通过设置 IGNORE_UPDATES=yes 跳过此步骤；本地开发若需固定版本，可创建 .ignore_changes 空文件阻止自动更新。

Sources: build.sh

CI 磁盘空间不足

GitHub Actions 运行 OrangePi 内核编译时，由于需要下载大量源码与生成 DEB 包，极易触发 No space left on device。官方工作流使用 easimon/maximize-build-space@v10 动作预先清理 dotnet、android、haskell、codeql 与 Docker 镜像，仅保留 1GB 根分区余量与 1GB Swap。若自行搭建 Runner，请确保工作目录所在分区剩余空间 ≥ 50GB。

Sources: build-kernel.yml

RDK X5 镜像构建故障

子命令执行顺序依赖

x5-rdk-gen/build.sh 采用子命令式设计，但各阶段存在严格的隐式依赖。典型错误场景包括：在未执行 ./build.sh rootfs 的情况下直接运行 ./build.sh debs，导致 deploy/rootfs sysroot 缺失，交叉编译 hobot-spdev 等包时找不到 string.h 或 aarch64 架构 stubs。do_debs() 函数已内置检测逻辑：若 sysroot 头文件不存在且 rootfs/ 下无 samplefs 压缩包，则显式报错并提示先执行 rootfs 阶段。

Sources: build.sh

交叉编译工具链下载失败

setup 阶段需要从 archive.d-robotics.cc 下载 gcc-arm-11.2 工具链。若因网络超时或证书问题导致 curl 失败，可手动下载并解压到 /opt/gcc-arm-11.2-2022.02-x86_64-aarch64-none-linux-gnu/，随后重新运行 ./build.sh setup，脚本会检测到目录已存在并跳过下载。

Sources: build.sh

repo sync 部分失败

x5-rdk-gen 依赖 repo 工具拉取 D-Robotics 官方 manifest 下的数十个源码仓库。do_setup() 中已对用户可能遇到的 x5-rdk-gen 自身 checkout 冲突做容错：repo sync 返回值非零时仅打印警告而不终止流程。若其他关键仓库（如 kernel、bootloader）同步失败，建议单独执行：

export REPO_URL='https://mirrors.tuna.tsinghua.edu.cn/git/git-repo/'
repo sync --fail-fast kernel bootloader

或切换至国内镜像加速。

Sources: build.sh

losetup / loop 设备争抢

镜像打包阶段 pack_image.sh 通过 losetup --find --partscan 申请 loop 设备。在构建服务器或容器中，若前期异常退出未清理 loop 绑定，可能导致 losetup 失败。脚本已实现 5 次重试机制（每次间隔 5 秒），超过阈值后退出。手动修复可执行：

losetup -D  # 释放所有未使用的 loop 设备

若仍失败，检查 /dev/loop* 是否被其他进程占用。

Sources: pack_image.sh

多仓库协同与子模块

子模块目录为空

初次克隆 atom01_firmware 后，若 roboto_usb2can/、orangepi-build/、x5-rdk-gen/ 目录为空，说明未携带 --recursive 参数。修复命令为：

git submodule update --init --recursive

由于三个子模块分别指向不同上游仓库，任意一个上游更新后，主仓库需执行 git submodule update --remote 并提交指针变更，否则开发者本地会继续停留在旧提交。

Sources: .gitmodules, readme_cn.md

上位机工具与脚本问题

Python 依赖缺失

roboto_usb2can_tool.py 依赖 pyusb 与系统 tkinter。Linux 用户若遇到 ModuleNotFoundError: No module named 'tkinter'，需安装系统级 tk 库而非仅通过 pip：

sudo apt install python3-tk
pip install pyusb

Windows 用户需确保 libusb-1.0.dll 与 .py 脚本位于同一目录，或已加入系统 PATH。

Sources: readme_cn.md

打包 EXE 后图标或 DLL 缺失

使用 PyInstaller 打包时，--add-data "icon.ico;." 参数确保运行时资源路径正确；若省略此参数，打包后的 EXE 在启动时可能因找不到图标文件而闪退。建议在 CI 环境（windows-latest）中复现官方工作流的打包命令，避免本地 Python 版本差异导致依赖解析不一致。

Sources: build-tool-exe.yml

延伸阅读与排查路径

若本节内容未能覆盖您的具体问题，建议按工程维度深入对应专题页面：

• USB2CAN 固件深入理解：硬件架构与接口规范 → Zephyr RTOS 与 USB 协议栈 → CAN 总线监控与错误保护机制
• OrangePi 构建排障：构建流程与脚本编排 → 板卡配置与内核编译
• RDK X5 构建排障：全量构建与子命令解析 → 镜像打包与系统定制
• 工程化基础设施：多仓库协同与子模块管理 → 交叉编译环境深度配置