舵机校准与安全

目标：学会给 LeLamp 的 5 个舵机做完整校准（连接→回零→释放→摆 home→记录行程），了解安全范围限制，掌握方向定标（--wizard）与默认动画设置，避免舵机超行程损坏

一、校准是什么、为什么重要

LeLamp 的 5 个舵机（Feetech STS 系列，12bit 编码器，中心 2048）需要一份校准文件才能工作：

• 记录每个关节的中立位（home）——舵机"0 度"在哪
• 记录每个关节的物理行程边界（range_min / range_max）——防止超行程损坏

没有校准文件，舵机服务直接不启动——因为系统不知道 home 在哪。新装舵机、更换舵机、动作"跑偏"时都需要重新校准。

二、校准前准备

1. 灯体放在桌面，周围留出活动空间，确认无机械干涉、无卡阻
2. 通过 SSH 登录设备（网络与远程访问）或使用 WebUI 校准页面
3. 校准过程中舵机会释放扭矩，请用手扶住灯体，防止突然坠落

三、校准流程（五步）

以下为 calibration_service 的标准流程（WebUI 校准页面/CLI 均按此执行）。

第 1 步：连接并回到 0 位

系统连接舵机总线，所有关节移动到 0°。

你应看到什么：5 个舵机轻微动作，回到当前校准的零位。

第 2 步：逐关节释放扭矩

按顺序（base_yaw → base_pitch → elbow_pitch → wrist_roll → wrist_pitch）逐个释放舵机扭矩。

你应看到什么：被释放的关节可以用手自由转动（无阻力）；未释放的关节仍然锁死。

每释放一个就立刻用手扶住，避免灯体因重力下垂。

第 3 步：手动摆到 home 姿势

用手把每个关节摆到你想要的"中立/待机"姿势（参考：灯体直立、灯头朝前）。

你应看到什么：摆好后系统记录该位置为 home（对应 homing_offset，写回舵机 EEPROM 与校准文件）。

第 4 步：批量记录全行程

逐个关节手动掰到物理极限两端，系统记录 range_min / range_max。

你应看到什么：每个关节记录到两个边界值；感到明显阻力就停，不要硬掰。

第 5 步：保存校准

校准写入 ~/.lelamp/calibration/lelamp.json，并自动生成 home 动画。

你应看到什么：校准文件出现且内容完整（每关节含 id、homing_offset、range_min、range_max）；重启后舵机服务正常启动，先回 home 再播 idle 动画。

校准文件位置与结构

~/.lelamp/calibration/lelamp.json

补充：CLI 录 home

# 把当前姿势录成新的 home（更新标定并写入）
uv run scripts/go_home.py --save

# 回到校准录制的姿势
uv run scripts/go_home.py

四、安全范围（软范围表）

系统在动画层还有一层软范围（归一化值，home=0，总线硬边界 ±100），任何动画/动作都不会超出：

物理行程（校准记录值）比软范围宽：base_yaw / wrist_roll 约 ±180，其余约 ±90。软范围是安全缓冲——动画最多走到 ±50 以内，不会顶到机械极限。 另外动画单帧最大步进 10，超出会自动插值分解，保证动作顺滑不甩头。

五、默认动画设置（idle / home）

校准完成后，系统启动顺序固定为：

回家（home）→ 停留 3.5 秒 → 播放 idle 动画

你应看到什么：开机后灯体先平滑回到 home 姿势，停 3.5 秒，然后开始轻微 idle 摆动。

想改待机姿势？把灯手动摆好 → 用 go_home.py --save 或 WebUI 校准页面重新录制即可。

六、方向定标（--wizard）

校准管"位置"，定标管"方向"——确认每个关节的正方向符合标准。换舵机/重装后必做：

python3 scripts/test_servo_angle.py --real --wizard

向导对每个关节依次执行：转到 +30 → 观察 → 转到 -30 → 观察 → 回 home (0) → 人工确认"正值方向是什么"。

你应看到什么：按提示逐个回答后，结果写入 ~/.lelamp/calibration/direction_map.json；中途 Ctrl+C 可中断，已确认的关节保留。

方向标准（2026-08-01 实测固化）

定标结果与上表不符 → 按 舵机安装规范 返工重装，不允许改软件"凑对"。

安装后验证（强制）

# 1. 一键自测（mock 总线，先确认软件链路）
bash scripts/test_motion_all.sh

# 2. 真机方向自检（逐动作观察物理方向）
python3 scripts/test_motion_interactive.py --real --dir-test

你应看到什么：forward 灯体前倾、right 俯视顺时针、nod 灯头向前点、wave 腕部摆动……任何一项不符 → 检查该关节安装方向 → 返工重装 → 重跑验证。

常见问题