常见问题（FAQ）
通用
应该选 SCS0009 还是 PWM？ 需要位置反馈、精度、LeRobot/SO-ARM101 数据采集选 SCS0009；独立演示、手势交互、网页/桌面快速上手选 PWM。详见 版本对比。
两套舵机能同时接吗？ 不能。供电、协议和固件都不同，同一时刻只接一套。
机械手能直接上电吗？ 首次上电前把机械手摆到中位，按中位安装舵机臂；外部电源与驱动板/ESP32 必须共地。
舵机型号能换吗？ SCS0009 版使用总线舵机；PWM 版固件按 PTK 7452 MG-D（333 Hz 数字舵机）标定。SG90 等 50 Hz 模拟舵机不能直接替换 PWM 版，需改 LEDC_FREQ 和脉宽标定。
SCS0009 串口总线版
动作方向反了 → 检查是否按“奇数 ID 在前”接线；左手确认 angle_offset_deg = -35.16。
左手握拳幅度不够 / 舵机叫 → 检查 config.json 限位是否已放到 ±120°（默认 ±90 会削掉左手握拳）。
手指不动 / 提示“需要 N 个电机检测到 M 个” → 运行 tools/scan_servos.py；左手 ID 最容易接错（11–18，不是 9–16）。
中位不对 → 中位值 -17.578125 对应官方 raw 451/571；按机械装配标定就改 config.json 的 middle.positions。
舵机 ID 怎么设？ → 用 SCS0009 调试工具 扫描并修改 ID；右手 1–8，左手 11–18。
Linux 打不开串口 → 当前用户加入 dialout 组并重新登录。
能读位置/温度/电压吗？ → 可以，SCS0009 支持位置、速度、电压、温度回读；协议内存表见 scs_servo_protocol.md。
PWM 舵机版
连接失败 / ESP32 无响应 → 确认 115200 波特率、ESP32 的 COM 口、5V/3A 供电和共地；打开串口可能复位，页面会自动重试 NOP。
舵机不动或抖动 → 确认是 333 Hz 数字舵机（PTK 7452 MG-D 或同类），电源足够；SG90 需改固件。
方向反了 → 在网页 config.json 的 pwm.calibration 里把对应手指 scale 改为 -1。
中位不对 → 调对应通道的 offset_deg；详见 PWM 协议、命令与标定。
提示“忙（手势执行中）” → 固件正在执行内置手势，等待完成或发送停止（0xFF）。
PWM 版有反馈吗？ → 没有位置/温度/电压回读，无法检测堵转或失步。
PWM 舵机有波特率吗？ → 舵机本身没有；上位机↔ESP32 串口固定 115200 8N1。
只接了部分舵机可以测试吗？ → 可以。未接通道空着不影响其他通道；注意空插头绝缘。
摄像头有画面但手不跟随 / 反应迟钝 → 光线均匀、手掌距镜头约 40–80 cm 并正对镜头；关闭占用摄像头的其他程序；确认串口已连接。GUI 追踪参数见 PWM 手势追踪。
切换左右手不生效 → 固件用 0xF1 切换左手/右手（网页连接时会自动发送）；该设置主要影响固件内置手势的拇指方向，网页姿态则按当前控制对象使用各自的映射。
追踪画面卡住 / 日志停住 → 停止追踪后重新开始；仍无响应时关闭 GUI 重开，并确认摄像头没有被其他程序占用。
换 USB 口后找不到串口 → 到设备管理器确认新的 COM 号，在 GUI 或网页里点“刷新”后重新选择。
网页控制
模型失败 / 摄像头追踪加载失败 → 确认页面由本地服务提供（非 file:// 直接打开），MediaPipe 资源路径可访问；本地教程已修复服务端 MediaPipe 路由。仍失败时看浏览器 Console/Network 的 404 或权限错误。
摄像头识别不准 → 光线均匀、手掌正对镜头；tracking.js 的 SMOOTH（默认 0.35）越大越平滑但越迟钝。
某根手指不跟手 → 重新采集三个姿势；方向反了重采对应姿势；大拇指只做屈伸，不参与侧摆。
握拳到一半某舵机反转 → 侧摆应随弯曲衰减到 0（side *= (1 - curl)）；检查侧摆控制量的符号和大小是否异常。
网页驱动怎么切换？ → 顶部“驱动”下拉选 SCS0009 或 PWM；PWM 需选 115200 串口，详见 网页控制总览。
桌面上位机
SCS0009 GUI 未列出串口 → 重新插拔 USB 适配器、安装驱动或重启 GUI；Linux 检查 dialout。
Connect 按钮变灰 → 已连接，先点 Disconnect。
序列未驱动所有手指 → 检查每步速度，确保每个姿态包含全部 8 个舵机值。
阻塞指示持续存在 → 检查机械卡阻；目标与实际位置差异大且无运动会触发阻塞。
PWM GUI 启动报 mediapipe 缺失 → 用 tools/tracking_env 的 Python 启动，或重跑 tools/setup_tracking.bat。
手势追踪
mediapipe 缺 solutions 子模块 → 安装 mediapipe==0.10.14，并确认 Python 3.12 为 64 位。
dora 版本不兼容 → 按 pyproject.toml 和日志对齐 dora 版本；清理后重装。
模型加载失败（中文路径） → 把项目/模型放到全英文路径。
摄像头没画面 / 权限 → 允许系统摄像头权限；虚拟机需 USB 直通摄像头。
SCS0009 官方 Demo 与 PWM GUI 追踪有什么区别？ → SCS0009 使用 dora + MuJoCo IK 完整链路；PWM 版提供 GUI 内置 MediaPipe 轻量追踪，dora Demo 不在模块内。详见 SCS0009 手势追踪 / PWM 手势追踪。