Spot Micro - Leika 复刻全流程
Spot Micro - Leika 从采购、打印、组装到装软件、标定和训练的 133 个步骤,附物料表、购买链接与官方出处。
Spot Micro - Leika 是一款基于 ESP32 的四足机器人。仓库提供 3D 打印部件、组件与物料清单、组装和配置指南,以及嵌入式固件、网页控制器和 MuJoCo 仿真器。
采购
- 从源码构建固件
尚无已发布的固件;请按照软件指南从源码构建。
打印与加工
- 使用支架顶部 STL
Use `2x_stand_top.stl` for the stand top. The file comes from stefi01’s “stronger microspot stand top”.
- 使用支架底部 STL
使用 `2x_stand_bottom.stl` 制作支架底部。该文件派生自 Nova-SM2。
- 使用支架支撑 STL
使用 `2x_stand_brace.stl` 制作支架支撑件。该文件派生自 Nova-SM2。
- 使用支架脚垫 STL
使用 `4x_stand_feet.stl` 制作四个支架脚。该文件派生自 Nova-SM2。
软件与固件
- 配置 ESP-IDF 固件构建
使用 PlatformIO,并将 platformio.ini 中的 framework 设置为 espidf。固件面向 ESP32、ESP32-S3 和 ESP32-P4。
- 使用仓库内置驱动
传感器驱动、IMU 融合、PCA9685 驱动和 I2C 总线层位于 esp32/include/peripherals,属于仓库的一部分,不是外部库。
- 安装外部软件依赖
从 ESP-IDF 组件管理器安装 espressif/mdns、joltwallet/littlefs、espressif/esp-dsp、espressif/led_strip 和 espressif/esp32-camera;ESP32-P4 除外。ESP32-P4 使用 esp_wifi_remote、esp_hosted 和 esp_cam_sensor。
- 运行控制任务
在 esp32/src/main.cpp 中使用 SpotControlLoopEntry,每 10 毫秒执行一次控制循环。
- 选择并连接 IMU 芯片
固件按 ICM-20948、BNO055、MPU6050 的顺序探测第一个应答的芯片。ICM-20948 与 MPU6050 共用地址 0x68,启动 MPU6050 会复位该地址上的芯片。
- 在外设设置中启用或禁用传感器
在外设设置中被禁用的传感器只会通过地址和芯片 ID 被识别,因此应用可显示为已检测到,但不会对其做任何配置。改变被禁用的芯片会重新探测并重启融合。
- 选择腿部几何与关节模型
变体通过 `variant.h` 选择 `kinematics.h` 中的腿部几何 `KIN_CONFIG_*` 和 `joint_model.h` 中的关节模型。
- 配置十二关节伺服输出
十二个关节由 PCA9685 驱动,输出频率为 50 Hz,振荡器频率为 27 MHz。
- 区分速度限制与命令平滑
运动状态角度与伺服之间唯一的滤波是速度限制;命令平滑由运动状态本身完成。
- 连接机器人 API
使用 /api/ws WebSocket,并采用 platform_shared/message.proto 中的 protobuf 消息。命令、定期广播、设置、文件传输和逐周期遥测均通过该连接传输;摄像头流单独使用 /api/camera/stream。
- 使用串行链路
在 USB-Serial-JTAG 端口上通过串行链路传送协议和日志,仅在控制台 UART 上接受请求。SerialLink 适配器将两个端口分别作为一个客户端处理,并通过其写入器输出日志。
- 订阅状态和数据流
在连接上订阅所需数据流;固件会在每个链路上注册处理器并向订阅者发送数据。订阅状态主题时先返回当前值,随后在每次变化时推送,未能接收的推送会在服务任务下一轮作为当前值重发。
- 连接蓝牙应用链路
On S3 boards with PSRAM, the NimbleLink adapter serves the app over a Bluetooth LE Nordic UART Service. It provides the WebSocket commands, requests, and broadcasts, but no telemetry or file or firmware transfer.
- 检查 ESP32-P4 支持状态
ESP32-P4 没有用于 ESP-NOW 的自身无线电,因此构建时不包含接收器。功能信息会将 espnow_controller_supported 报告为不支持。
- 配置固件构建选项
为每个 PlatformIO 环境构建一个支持所有变体和传感器组合的固件,并始终嵌入网页应用。将板卡固定设置写入该环境的 `build_flags`。
- 构建嵌入式控制器
运行 `pnpm build:embedded`。构建结果会作为压缩资源嵌入固件镜像,并省去 3D 视图和仿真以节省闪存空间。
- 构建托管版控制器
运行 `pnpm build` 构建托管版本。该版本同时包含 3D 视图和仿真。
- 启动 Vite 开发服务器
使用 `pnpm dev` 以 Vite 开发模式运行应用。
- 构建 GitHub Pages 静态站点
使用 `pnpm build` 生成 GitHub Pages 托管的静态站点,并用 `BASE_PATH` 设置子路径。
- 构建固件嵌入式版本
使用 `pnpm build:embedded` 生成固件要嵌入闪存的版本,该版本不包含 3D 视图和仿真。
- 安装开发环境依赖
准备 Node.js 20.19+ 或 22.12+、pnpm,并将 `protoc` 放入 `PATH`。`.npmrc` 设置了 `engine-strict`。
- 安装项目依赖
在应用目录运行 `pnpm install`。
- 生成共享协议代码
运行 `pnpm proto`,从 `../platform_shared` 生成 `src/lib/platform_shared`;生成目录会被 Git 忽略。
- 运行开发应用
运行 `pnpm dev`;它会先运行 `pnpm model`,然后在端口 5173 上启动 Vite。
- 复制仿真模型
运行 `pnpm model`,将 `../simulation/src/resources` 中的仿真模型复制到 `static/`。
- 构建并预览静态结果
`pnpm build` 会自动运行 `proto` 和 `model`。运行 `pnpm preview` 可在端口 4173 上提供构建结果。
- 运行代码检查
运行 `pnpm lint`,执行 Prettier 检查和 ESLint。
- 运行 Svelte 类型检查
运行 `pnpm check`,执行 `svelte-kit sync` 和 `svelte-check`。
- 运行单元测试
运行 `pnpm test`,使用 Vitest 对 `tests/unit` 执行一次测试。
- 格式化项目文件
运行 `pnpm format`,使用 Prettier 写入格式化结果。
- 运行监听模式单元测试
运行 `pnpm test:unit`,让 Vitest 以监听模式运行。
- 测试机器人实时显示
开启 Show on robot,在编辑器中拖动姿势,然后在姿势播放中途关闭应用。机器人应跟随拖动,并在应用消失后平缓回到站立姿势。
- 上传并播放动画片段
使用 `robot_animate.py --robot <ip> upload <clip.json>` 上传动画片段,然后通过 USB 播放该片段。
- 完整下载并重启机器人
从 GitHub Pages 下载带有 `<env>.bin` 的发行版,经过重定向后重启进入该版本。下载应完成,从另一个启动槽启动,确认镜像并报告该发行版的 ELF 哈希。
- 故意崩溃并解码转储
故意使机器人崩溃,然后从状态页下载转储,并按照 `docs/websocket.md` 中“Decoding a dump”的方法解码。最后一次崩溃卡片应显示任务和原因,说明转储来自当前运行的构建,解码结果应显示崩溃任务的后向跟踪。
- 通过 USB 连接开发板
使用数据线通过 USB 连接开发板;部分开发板需要在插入时按住 BOOT。
- 检查闪存容量
开发板必须至少具有 4 MB 闪存。
- 首次安装前了解擦除影响
首次安装会擦除开发板,包括已保存的设置。
- 关闭安装器对话框
关闭安装器对话框;在此之前它会占用端口。
- 同步 Python 环境
使用 uv 管理 Python ≥ 3.13 环境,并运行 uv sync 同步依赖。
标定与测试
- 复制最新 IMU 采样
控制任务复制最新的 IMU 采样。
- 更新运动服务
运行 MotionService::update:应用收件箱,推进当前运动状态,求解逆运动学,并应用每个关节的符号。
- 切换舵机板状态
模式改变时,激活或停用舵机板。
- 更新舵机控制器
运行 ServoController::update:限制各关节速度,将角度转换为 PWM,并在一次 I2C 突发传输中写入 PCA9685 的全部通道。
- 等待下一个控制周期
控制任务等待下一个 tick;如果某个 tick 超时,则重新开始调度,而不是追赶错过的周期。
- 启动时探测传感器
所有驱动都会构建,传感器任务在启动时探测 I2C 总线。
- 设置安装矩阵
在外设设置中填写安装矩阵,它把芯片坐标系旋转到机体坐标系(x 向前、y 向左、z 向上)。
- 开机静止测量陀螺仪零偏
开机时保持机器人静止,固件采集 200 个样本来测量陀螺仪零偏。如果机器人在此期间移动,零偏保持为零。
- 设置 Madgwick 增益
MPU6050 与 ICM-20948 使用 Madgwick 滤波融合陀螺仪、加速度计以及有新鲜读数时的指南针。增益为 IMU 设置项,默认 0.1,前两秒为 2.5。
- 把静止姿态倾角并入安装矩阵
在应用中将静止机器人的倾角并入已保存的安装矩阵,使机器人在水平面上读数为水平。倾角必须小于 15 度。
- 设置外部 HMC5883L 指南针
没有内置指南针的芯片可由独立 HMC5883L(75 Hz)提供指南针数据。其对准、硬磁偏移和软磁矩阵均为 IMU 设置项。
- 处理无响应的指南针
若指南针连续三个周期没有输出,则被忽略。被禁用的指南针不会参与融合,无论芯片自带的还是外置的。
- 设置 INA219 地址与 A0
INA219 位于舵机电源轨上。0x40 是 PCA9685 的地址,因此 INA219 的 A0 拉高,其地址在外设设置中指定。
- 校准 INA219 分流电阻与最大电流
INA219 的校准取决于分流电阻和预期最大电流两个设置项(默认 0.1 欧姆和 3.2 安培)。电流分辨率为该电流除以 2^15,分流电压量程取 40–320 mV 中能容纳的最小值。
- 设置电压与电流平均时间
总线电压在 8.5 ms 内取平均以便显示压降,分流电压在 68 ms 内取平均以便给出两次读取间的平均电流。
- 设置欠压截止保护
截止电压为一项设置,默认 0 表示关闭。低于截止电压持续 2 秒时机器人停用并记录原因,直到电压回升到截止值以上 0.2 V 才恢复;舵机失去动力卸载后只有仍有电量的电池才能恢复到位。
- 检测堵转电流
当电流超过默认堵转值 3 A 并持续默认堵转时间 1 秒时,设置堵转标志;该标志只被上报。
- 读取机器人变体
变体是 `robotSettings.pb` 中的机器人设置,在任何任务启动之前由 `app_main` 读取。
- 应用停用状态下的变体
只有机器人处于停用状态时才接受变体更改。设置会保存并发送给控制任务,在一个时钟周期内切换运动代码和关节模型,并将身体重置到新变体的默认姿态。
- 处理未配置变体的机器人
未配置变体的机器人没有腿部和关节模型;运动服务拒绝除停用状态之外的所有模式,伺服板保持休眠。
- 保持伺服板初始休眠
板卡启动时保持休眠,所有通道关闭,从而避免腿部跳到板卡在复位前保留的姿态。
- 设置关节模型参数
变体的关节模型位于 `joint_model.h`,包含各关节方向、关节处于运动学零点时的伺服角度,以及每度 PWM 计数 2.0。
- 读取关节校准与通道
机器人的校准数据位于 `servoSettings.pb`,包含各关节中心 PWM,默认 306,并可指定各关节使用的 PCA9685 通道。
- 限制伺服 PWM 范围
将每个关节的 PWM 限制在 125 至 600 个计数,这是伺服接受的范围。
- 按供电电压计算速度
6 V 时额定速度为每秒 720 度,4.8 V 时为每秒 443 度;两者之间线性插值,范围之外保持较近一侧的额定值。
- 限制时钟周期长度
一个时钟周期最多计为 20 毫秒,以防止堵转导致跳跃动作被释放。
- 同步速度限制与步行动作
新的供电值从下一个时钟周期开始生效。控制任务把同一限制交给步行状态,步行关节的上限为该限制的四分之三。
- 配置 LittleFS 设置
将 WiFi、接入点、摄像头、舵机、外设和机器人设置作为 protobuf 文件保存在 LittleFS 分区的 /config 目录中。外设设置包括引脚、I²C 频率、IMU、禁用的传感器和 LED 灯条。
- 启用 ESP-NOW 接收器
在外设设置的 Sensors 页面中开启接收器。接收器默认关闭,因为它每秒发送十次信标。
- 准备 Pico 与验收记录
等待 Pico 上电;从 `simulation/` 运行 Python 工具,方式为 `uv run python`。将所有结果(包括失败)写入上方的新章节,标题注明日期、分支和状态页中的固件 ELF 哈希,并使用现有表格格式。
- 测试蓝牙与 WiFi 缓冲
在开启 Bluetooth 的 S3 板上,读取启动日志中的 `Bluetooth took N bytes`,并测量 WiFi 文件下载时间。记录字节数以及与不含 Bluetooth 的构建相比的下载时间。
- 检查相机初始化内存
在带有 camera env 的相机板上,等待相机启动后读取状态页的内部 RAM、最大块和低水位。Pico 没有相机,因此需要另一块板。
- 验证杆件方向约定
在地板上使用小杆测试:STAND 时左杆向右应使机身向右倾;WALK 时 `+lx` 应向右平移,右杆向左(`+rx`)应使机器人从上方看逆时针转动。确认每项均符合所述,并记录结果。
- 验证里程计与目标运动
运行 `odometry_request`;`yaw` 与 `kinematic_yaw` 应同号,逆时针为正。运行 `goal_move(sideways=0.1)` 应向左,运行 `goal_move(turn_deg=90)` 应逆时针转动并停止;记录结果。
- 确认校准页前左腿
在校准页确认标为“Front left”的腿就是移动的腿。确认符合所述,并记录结果。
- 验证四连杆膝关节
在校准页将一个膝关节设为中心 PWM + 40。实际胫骨的转动量应约为 2D 图中转动量的 1.7 倍;确认结果并记录。
- 验证各关节限位
在 IDLE 模式下通过 3D 模型驱动每个关节至限位。全尺寸膝关节应在 149 度停止,Pico 膝关节在 153 度、Pico 髋关节在 -77 度停止,且不得触碰机架;这些限位是估计值。
- 从静止或行走状态站立
从 REST 和行走状态按 STAND。预期双脚在 0.5 秒内平稳抬起,不突然动作,也不拖脚。
- 测试舵机开关和 PWM
在舵机页面依次关闭、再开启舵机,然后设置一个舵机的 PWM。关闭时所有舵机应松软,开启后在设置 PWM 前不应驱动,之后只有该舵机移动;对应 757a64eb。
- 测量并设置舵机电源
测量舵机电源轨;装有 INA219 时其地址为 0x41。在舵机页面输入测量值并设置低电量截止值。状态页面应显示轨电压和电流,行走速度上限应随输入的供电值变化且无需重启。
采数据与训练
- 记录遥测数据
仅当客户端订阅遥测流时,控制任务才记录遥测 tick。
- 记录供电遥测
读数以 `PowerData` 流式传输。每个遥测网络样本包含电源轨电压、自上一个样本以来的最低电压和电流,因此记录可显示供电压降。
- 采集机器人遥测
让客户端订阅遥测后接收数据;服务任务每 100 ms 广播 IMU、超声波、舵机电源轨和 RSSI,每 2 s 广播系统分析。控制任务每周期将一个样本放入 64 周期环形缓冲区,服务任务按 10 个样本成批发送,并在前面加上固件、变体、IMU 和设置信息头。
- 记录遥测流
保持客户端订阅以记录遥测流;取消订阅后便不再记录。记录内容由服务任务发送的遥测批次组成。
- 记录站立时的横滚与俯仰
从 REST 按 STAND,同时用 record.py 记录 10 秒,然后对文件运行 report_recording.py。将最初 2 秒的横滚和俯仰与补偿前的横滚 -13 度、俯仰 +8 度比较。
- 测试目标移动
使用卷尺,在 Python 客户端执行 `goal_move(forward=0.2)` 和 `goal_move(turn_deg=90)`,并测试中途关闭客户端的目标和中途轻推摇杆的目标。距离和转角应在里程计误差范围内,关闭客户端时目标应取消,轻推摇杆时目标应移交给摇杆控制。
- 录制系统辨识数据
录制一段从静止站立开始的视频,然后对该视频运行 `identify.py`。
- 训练 PPO 残差步态策略
PPO 策略只在基础步态之上学习每只脚的小幅修正,使训练集中于稳定。
- 导出并部署训练后的策略
将训练后的策略导出到固件,并让它以 `WALK_NN` 模式运行。部署细节见仿真 README 的 deployment 部分。
- 记录遥测并比较仿真假设
使用 `record.py` 捕获真实机器人的遥测数据,再用 `report_recording.py` 将其与仿真的假设进行比较。
- 运行训练流水线冒烟测试
运行训练流水线的快速健全性检查。
- 训练随机化策略
使用随机化、零最终状态、初始标准差 0.3、课程学习、300 步重采样、500 万时间步和 16 个环境进行训练。
- 记录真实机器人遥测
以 192.168.1.39 为机器人地址记录 60 秒遥测;使用 --out 设置输出文件。
- 分析机器人记录
报告 recording.leika 的时序和 IMU 噪声,并与 domain_rand.py 比较;使用 --still 可生成静帧。
- 在不平地面上训练
使用 --terrain 0.008 在高度场地形场景上训练,每个 episode 的随机凸起最高为 0.008 米。
用起来
- 测试 AUTO 换向行走速度
让机器人在地面以摇杆略低于和略高于五分之一的速度行走,中间停住,并用卷尺测量。换向时指令速度不应跳变;Pico 的触及限制使爬行步幅约为满幅的 0.82,而行走速度仍上升约 1.2 倍。
- 行走中提高步高
向前行走时,将步高滑块从 0.25 调到 1。预期抬起的脚在约三分之一秒内逐渐升高,而不是突然跳起。
- 通过蓝牙测试摇杆控制
先让机器人站立,再在地面,通过应用和蓝牙驱动摇杆。预期机器人像使用 WiFi 时一样跟随摇杆,并在松手时停止。
- 驾驶时测试摄像头流
使用摄像头板时,打开视频流并驱动机器人。预期视频流保持同步且 WebSocket 持续响应;Pico 没有摄像头。
- 运行地面基准测试
按照 `docs/benchmark.md` 布置测试路线,然后运行该基准测试。
- 测试内置动画
这些动画已于 2026-10-28 在支架上通过测试;现在让机器人站在地面上播放。模拟中保持 26 mm 质心余量的挥手动作此前在 9 mm 时使机器人于 2026-10-28 倾倒,测试时不应使机器人倾倒或摇晃。
- 确认传感器为可选项
所有传感器都是可选的;机器人没有传感器也可以行走,但只有安装 IMU 时,站立体位才能调平机体。
- 使用姿态阶梯手势
在 `esp32/include/gesture_control.h` 中,下移依次从步行到站立、从站立播放并保持内置 `sit` 片段、再下移进入休息;上移返回站立,左右选择步行。
- 执行步行与转向目标
从站立或步行状态开始,前进和后退各走 10 厘米,逆时针和顺时针各转一整圈;这些操作通过里程计作为目标移动执行。
- 避免手势排队
当腿部片段正在移动或目标正在运行时到达的手势会被丢弃,不会加入队列。
- 按模式唤醒伺服板
选择会移动腿部的休息、站立或步行模式时,伺服板唤醒;应用激活伺服时也会唤醒。选择停用、空闲或校准等无运动状态的模式时,伺服板会重新休眠。
- 使用手持控制器驾驶
使用单独的 esp-now-controller 固件,无需应用即可驾驶机器人。ESP-NOW 没有配对机制,因此机器人会服从接收器启动后首先收到帧的控制器,并忽略其他发送者;关闭再开启接收器可让另一控制器接管,切换立即生效。
- 在仿真与实体机器人间切换
`Robot("simulation")` 与 `Robot("<robot address>")` 提供相同调用;更改目标即可让仿真脚本在机器人上运行。
- 查看基线步态
在查看器中以 vx 0.05 观看基线步态。
- 评估训练后的策略
查看训练策略的运行结果;使用 --headless 时打印跟踪指标。
- 运行机器人 API 演示
运行机器人 API 演示;提供地址时驱动真实机器人。
- 用 TensorBoard 检查策略
启动 TensorBoard 查看 runs 日志;跟踪项 terms/r_vel 应上升,残差幅度 terms/p_res 应保持较小。