正在连接信源…

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 应保持较小。

常见问题

  • 缺少清单、路径错误或说明不完整导致配置失败 #42 #73 #176 #178
  • PlatformIO 固件无法成功构建或上传 #1 #36
  • 引脚映射与接线图文档不足 #2 #45
  • 固件中的舵机校准与步态行为不清楚 #175
  • 连接硬件后 I2C 传感器仍无法通信 #51 #58
  • 摄像头上传成功但实时视频流失败 #37
  • 网页控制器请求返回方法无效的 HTTP 错误 #180
  • ESP32 固件初始化时耗尽内存 #179

文档