调试与排错#

本页提供软件环境、供电、串口、舵机、校准、相机、网络和数据采集故障的检查步骤。先找到对应现象，再按顺序操作，每次只调整一项配置，并保留机器人端和 PC 端的错误日志。

涉及接线时，先停止控制程序并断开执行器电源。舵机编号和机型参数按 AlohaMini 2 / 2 Pro 说明；其他硬件请使用对应配置。

快速定位#

现象

优先检查

本页处理步骤

命令不存在、模块导入失败

Python 环境、安装位置和版本

软件环境

找不到机械臂、串口无权限

数据线、设备节点、权限和端口占用

串口检查

缺少 8–11 号舵机、舵机灯不亮

供电、总线支路和编号

E002 / E004

校准范围相同、启动后反复要求校准

实际活动范围、设备 ID 和 profile

E001：校准检查

相机缺失、画面接反、取帧超时

供电、路径、格式和 USB 带宽

E003：相机检查

连接超时、画面和运动卡顿

Host、IP、网络和计算负载

网络与性能

续录失败、视频编码失败

数据目录、特征和编码环境

录制与视频

模型维度不匹配、评估暂停

数据特征、机型和保护日志

策略评估

更新失败或无法连接代码仓库

本地改动、分支状态和网络

软件更新

1. 确认当前软件环境#

pwd
python --version
python -c "import sys; print(sys.executable)"
python -c "import av, cv2, torch; print('av', av.__version__); print('cv2', cv2.__version__); print('torch', torch.__version__)"
git rev-parse --short HEAD

预期：当前目录是软件仓库；Python 来自已激活的项目环境；关键依赖可以导入。两台机器提交版本不一致时，先确认协议是否兼容，再定位通信层问题。

2. 串口找不到或无权限#

lerobot-find-port
ls -l /dev/ttyACM*
ls -l /dev/serial/by-id/
ls -l /dev/am_arm_*
groups

找不到设备节点#

逐个接入控制板，检查数据线、USB 连接和控制板供电。只充电的 Type-C 线不能提供串口通信；旧的 /dev/ttyACM0 编号也可能已经改变。

设备存在，但程序没有权限#

检查当前用户是否属于 dialout 组；添加组后重新登录。不要用长期以 root 运行整个机器人程序来替代权限配置。

别名存在，但左右不对#

回到 udev 规则，对照每块板子的序列号和物理位置。校准文件、遥操作和录制必须始终使用同一左右映射。

端口被占用#

停止先前运行的 Host、校准、遥操作或硬件调试程序。一个程序仍在使用串口时，另一个程序可能无法正常连接。

3. 舵机状态与编号#

查看连接总线上的舵机状态：

python examples/debug/motors.py get_motors_states \
  --port /dev/ttyACM0

检查读到的 ID、型号和状态是否符合实际接线。写入新 ID 时每次只连接目标舵机：

python examples/debug/motors.py configure_motor_id \
  --id 1 \
  --set_id 8 \
  --port /dev/ttyACM0

二代底盘目标 ID 为右后轮 8、前轮 9、左后轮 10、升降 11；左右以机器人自身朝向为准。

使用旧硬件调试脚本前先核对#

examples/debug/wheels.py 和 axis.py 是直接访问总线的工具。当前文件中的舵机型号常量仍为 sts3215，axis.py 不会根据整机二代配置自动选择 STS3095；轮组脚本也有自己的轮位命名与运动学常量。

因此，二代／Pro 首次整机检查优先采用匹配 robot_model 的 Host + 键盘客户端。只有确认脚本的型号、ID 与结构匹配后，才直接运行独立调试脚本。

改相位、重设中位、释放扭矩和执行动作脚本会改变硬件状态，不属于通用的“修复所有问题”操作。不要在未确认原因时修改相位或重设中位。

E002：左侧总线缺少 8–11 号舵机#

二代 AM-ARM 的关节为 1–7；底盘车轮为 8、9、10；升降为 11。左侧总线需要同时连通机械臂和底盘／升降支路，右侧仅连接机械臂。SO-ARM 的机械臂舵机编号为 1–6。

  1. 停止 Host 并断开执行器电源，检查左臂驱动板两条总线是否接牢。

  2. 检查底盘到升降再到左侧驱动板的连接，避免漏接支路。

  3. 重新供电后，在树莓派上读取左总线状态：

python examples/debug/motors.py get_motors_states \
  --port /dev/am_arm_follower_left

  1. 若只读到 1–7，核对是否将左右 USB 端口认反，再检查底盘／升降支路。

  2. 按各控制板的序列号重新绑定左右串口别名；确认所需舵机均能读取后再启动匹配机型的 Host。

E004：无法读取舵机状态或指示灯不亮#

  1. 确认驱动板有独立电源，并核对该臂对应的电压；USB 连接本身不等于舵机已供电。

  2. 检查数据线、端口权限和串口别名，关闭占用同一串口的其他程序。

  3. 断电后重新检查接头，逐段核对串联线路。

  4. 需要隔离故障时，每次断电后只接一个已确认兼容的舵机，再进行读取测试。

  5. 在电源、数据线、端口和已知正常舵机都验证后仍失败，再联系支持方判断是否需要更换驱动板。

可将兼容的夹爪舵机单独接入驱动板进行排查。一次通信失败并不能单独证明控制板损坏。

4. 校准范围与设备匹配（E001）#

常见原因：触发重新校准后，没有实际移动关节，就确认保存了范围。

  1. 停止遥操作，确认当前终端连接的确实是目标机械臂。

  2. 核对主臂 am-leader-6dof；标准 2 从臂 am-follower-6dof；Pro 从臂 am-follower-6dof-hd。

  3. 启动对应设备的校准流程，重新记录零位和活动范围。在程序要求手动采集范围时，缓慢移动每个关节到允许的行程范围，避免强行顶住机械限位。

  4. 确认所有关节都记录到变化，再按程序提示保存。

  5. 使用与校准相同的设备路径和 ID，先验证单臂小幅动作，再启用整机。

校准数据不能从另一只机械臂直接复制。范围异常时重新完成测量，不要手工填数值来绕过检查。

启动重新校准#

先退出占用串口的 Host、遥操作和调试程序。在树莓派上，按机型选择一条命令校准从臂：

AlohaMini 2

python -m lerobot.robots.alohamini.alohamini_calibrate --robot_model alohamini2

AlohaMini 2 Pro

python -m lerobot.robots.alohamini.alohamini_calibrate --robot_model alohamini2pro

在 PC 上校准 AM 双主臂：

python examples/alohamini/calibrate_bi.py \
  --teleop.id am_leader_bi \
  --teleop.arm_profile am-leader-6dof

按终端提示选择重新校准，完成中位和活动范围记录。完成后对主从臂断电重启，使用相同设备 ID 与 profile 进行小幅动作检查。

反复要求校准或从臂方向异常#

  1. 核对当前设备 ID、左右串口与校准时一致。

  2. 主臂使用 am-leader-6dof；2 从臂使用 am-follower-6dof，2 Pro 从臂使用 am-follower-6dof-hd。

  3. 树莓派与 PC 的 robot_model 保持一致：2 为 alohamini2，2 Pro 为 alohamini2pro。

  4. 更换舵机、调整装配或 profile 后，重新测量对应设备的校准范围。

  5. 从单侧机械臂的小幅动作开始检查，确认左右、方向和行程正确后再启用整机。

5. 相机无法打开或缺图（E003）#

lerobot-find-cameras
v4l2-ctl --list-devices
v4l2-ctl -d /dev/video0 --list-formats-ext

按以下顺序检查：

  1. 相机是否被系统识别，index_or_path 是否指向它。

  2. 配置要求的分辨率和帧率是否受设备支持。

  3. 相机是否被另一个程序占用。

  4. Host 配置启用了哪些相机，设备是否都已连接。

  5. 当前画面对应哪个物理位置，左右腕是否接反。

  6. 是否存在 USB 带宽、供电或多设备共用 Hub 的问题。

修改相机配置后重启两端相关程序。默认仅启用两路，看到五只物理相机不代表程序会自动使用五路。

多路相机启动超时#

供电不足可能导致多个摄像头无法同时启动。 Timed out waiting for frame 也可能来自错误端口、被其他进程占用、USB 带宽或不受支持的分辨率。

  1. 检查电池电量、电源板接口和线缆，核对供电电压与设备铭牌一致。

  2. 先停止 Host，确认摄像头没有被其他预览程序占用。

  3. 使用本节的相机发现与格式查询命令，单独检查每一路设备。

  4. 先启用一台相机，稳定后逐路增加；记录哪一路或哪种组合触发错误。

  5. 树莓派与 PC 使用一致的相机配置，修改后重启两端程序。

head_top 与 forward 是不同软件配置中的相机命名，必须核对实际数据键和设备别名。不能把一套名称的数据直接交给另一套配置训练或推理。

6. 网络连接与性能#

PC 检查 Pi：

ping <Pi_IP>

在使用无线网络的机器上检查链路：

iw dev
iw dev wlan0 link

wlan0 需换为实际无线网卡名称。需要测量吞吐量且已安装 iperf3 时，在 Host 上运行：

iperf3 -s

在 PC 上运行：

iperf3 -c <Pi_IP>

测试结束后退出 iperf3 服务。网络延迟或吞吐正常仍不代表整个控制链路正常，还需结合设备采集和 CPU 负载。

观察计算负载#

top

训练 PC 若使用 NVIDIA GPU，可查看：

nvidia-smi

遥操作卡顿时，先将启动参数设为 --fps 10 --camera-fps 10，临时降低控制和相机请求频率。检查 CPU、网络与相机后再恢复正式采集配置。

7. 录制与视频问题#

数据集目录已经存在#

核对这是新建还是续录。续录使用同一数据标识和目录并加入 --resume；新实验使用新名称。不要直接删除旧数据来消除报错。

多频采集时间比设定更长#

该入口需要收集足够的新鲜帧，实际相机帧率稍低时会延长时间。如果明确中止，检查日志是相机停滞、跨相机时间差、状态对齐还是帧率不足。

视频编码／解码失败#

ffmpeg -version
ffmpeg -hide_banner -encoders
python -c "import av; print(av.__version__)"

确认环境一致、视频文件已完整保存，再按错误定位缺少的编码器或后端。不要在写入尚未结束时复制半成品数据集。

8. 策略评估与模型维度#

模型输入或动作维度不匹配#

  1. 确认模型训练使用的数据集对应当前机型。2 / 2 Pro 整机接口为 18 维；不能直接使用不同维度的单臂或仿真数据。

  2. 核对相机名称、顺序和启用数量。head_top 与 forward 等名称必须和训练特征一致。

  3. 核对关节顺序、单位、profile 和校准配置；仅维度数量相同仍不足以证明兼容。

  4. 完成配置匹配后先运行短时测试，确认观测有效、动作方向正确。

评估不动作或突然暂停#

  • 先确认没有遥操作或录制客户端仍持有控制权。

  • 核对 Pi 与 PC 的机型是否一致，模型目录是否正确。

  • 查看 Host 是否触发电流保护、看门狗或发生重启。

  • 查看客户端是否缺少新鲜反馈，或策略推理耗时使 Host 超时。

  • ACT 使用 sync；RTC 必须由模型接口支持。

暂停后的旧动作队列不会自动继续执行。处理故障后按程序流程重新开始，避免把“没有继续动作”误当作单纯网络丢包。

9. 软件更新与网络访问#

先保存本机配置，再更新。不要把 git restore . 当成常规更新步骤，它会丢弃未提交的工作区修改。

cd lerobot_alohamini
git status
git diff

如果有本机配置改动，先备份或提交并确认用途；工作区准备好后再执行：

git pull --ff-only

提示无法快进时，先处理本地提交与远端的差异，避免直接覆盖。更新完成后核对 Pi 与 PC 的软件版本、机型和相机配置。

若使用自己局域网内的代理，可以在当前终端设置：

# 替换为你自己的代理服务器地址和端口
export http_proxy=http://192.168.50.XXX:7890
export https_proxy=http://192.168.50.XXX:7890
curl -I https://github.com

代理程序需要允许该局域网客户端连接。以上占位 IP 不能直接运行，也不应沿用截图中的他人地址。

10. 提交可复现问题#

将以下内容一起提交到 软件 Issues：

机型：AlohaMini 1 / 2 / 2 Pro
主臂与从臂型号：
PC 系统、CPU/GPU：
Pi 系统与架构：
两端软件提交版本：
操作阶段：安装 / 校准 / 遥操作 / 录制 / 训练 / 评估
完整命令（移除访问令牌等秘密）：
预期结果：
实际结果：
Host 日志：
PC 日志：
最近修改过的配置：

硬件装配问题请补充局部照片、零件名称和材料，并提交到 硬件 Issues。