Tiny Engineer(给 AI 编程助手一个身体的桌面机器人) 复刻全流程
Tiny Engineer(给 AI 编程助手一个身体的桌面机器人) 从采购、打印、组装到装软件、标定和训练的 239 个步骤,附物料表、购买链接与官方出处。
无套件或成品售价,作者也未给整机物料总价。主控板按 KiCad 文件自行找 PCB 厂下单:作者在讨论 #50 中称 JLCPCB 5 块起订,单面贴片约 75 美元、双面全贴约 150 美元(创作者估计,均不含运费);约 15–20 美元的成品主控板只是意向调查。其余为 ESP32‑C3‑Zero、5 个舵机、OLED、扬声器、M2 螺丝、5 V ≥2 A 电源与打印件,文档只给购买链接、不给价格
物料 · Shopping list
| 零件 | 数量 |
|---|---|
| Base | 1 |
| ButtonPocket | 1 |
| Bell | 1 |
| Button | 1 |
| Clamp | 4 |
| CableTunnel | 1 |
| ActionEmblem | 1 |
| 6×6 mm momentary tactile switch (4-pin) | 1 |
| Jumper wires, female DuPont end | 2 |
| M2×16 mm screws | 4 |
| M2×8 mm screws (or nearby short) | 17 |
物料 · Default cart
| 零件 | 数量 | ANY |
|---|---|---|
| Tiny Engineer main control board | 1 | |
| Waveshare ESP32-C3-Zero | 1 | |
| Tower Pro SG90 (or equivalent 9 g analog micro) | 5 | |
| Adafruit Mini Oval Speaker - 8 Ohm 1 Watt | 1 | |
| Waveshare 0.91inch OLED Module (SSD1306, 128×32, I2C) | 1 |
采购
- 购买其余机器人零件
PCB 制造商负责制作电路板,并可选择焊接选定元件。插拔式模块和购物清单中的其余机器人小车零件需要另外购买。
- 选择 PCBA 装配方式
如果自行焊接 Waveshare ESP32-C3-Zero 使用的 2.54 mm female header 插母座,请选择单面 PCBA,本设计采用两排 1×9;也可以选择双面 PCBA,由厂家完成这些插头的装配。
- 开始 JLCPCB 订单
创建或登录 JLCPCB 账户,并开始新的 PCB 订单。
- 上传 Gerber ZIP
上传 Shop 下载文件或本地导出文件中的 Gerber ZIP。
- 保留标准板卡选项
大多数板卡选项保持合理默认值。文档中的六行表格列出了这块板卡的一组典型匹配选项。
- 启用 PCB 装配
打开 PCB Assembly,并关闭钢网;在这个由厂家完成板卡装配的 PCBA 流程中不需要单独的钢网。
- 配置单面 PCBA
选择 Economic PCBA、Top 装配面和所需装配数量。厂家装配的板卡数量可以少于 PCB 数量,剩余裸板不会安装元件。
- 配置双面完整装配 PCBA
选择 Standard PCBA 和 Both sides 装配。厂家可能会添加工艺边,因此启用分板服务可获得无需自行切边的可用板卡;装配数量可以少于 PCB 数量。
- 检查板卡布局
继续进入厂家的查看器并检查板卡布局。确认外形、孔位和铜层正确后再继续。
- 上传 BOM 和贴装文件
上传 `bom.csv` 和 `positions.csv`,其中 `positions.csv` 是 CPL/贴片坐标文件,然后继续。
- 审查物料清单
逐项检查,因为库存和目录条目会发生变化。如果 ESP32 排针零件提示有多个目录条目匹配,请手动选择正确条目。付款前解决缺货或错误零件,也可以更新原理图的 LCSC 字段、重新导出、等待站点重新部署,然后再次上传。
- 审核报价并下单
查看成本报价,完成结账并跟踪货件。
- 选择 Tower Pro SG90
选择 Tower Pro SG90,这是最容易购买舵机的方案。组装后的机器人约为 13 × 15 × 12 cm 高×宽×深。
- 选择紧凑型 Feetech FS0307
如果想要更小的机器人,可以使用 Feetech FS0307。其组装尺寸约为 11 × 13 × 10 cm 高×宽×深。
- 选择 EMAX ES9051 替代方案
EMAX ES9051 可作为 Feetech FS0307 的紧凑型替代方案。组装尺寸约为 11 × 13 × 10 cm 高×宽×深,并且不能与 FS0307 混用。
- 考虑向后兼容的 HD-1370A
PowerHD HD-1370A 仍受支持,可用于向后兼容,但不建议用于新构建。
- 获取高级 USB-C 方案
高级接线方案使用 Adafruit 5993 USB 连接器,并按照链接中的接线说明操作。
- 准备三个扩展模块
默认版本使用主控制板。此高级接线方案增加独立的 PCA9685、MAX98357A 和 Adafruit 5993 USB-C 扩展板。
- 选择充足的 5 V 电源
准备 5 V、至少 2 A 的电源;如果多个舵机需要在音频播放时同时运动,应留出额外余量。实际可提供多少电流取决于充电器或端口。
- 选择 USB 或独立 5 V 电源
Adafruit 5993 不是 USB-PD 电压转换器。给它输入 5 V USB,或者用独立的 5 V、至少 2 A 电源直接接到 +5V 和 GND 电源轨。
- 查看购物清单
按照 shopping.md 选择并购买所需组件。
- 选择五伏电源
使用标称 5 V、电流不低于 2 A 并留有余量的电源。
- 从打印服务商订购打印件
如果不在家用打印机打印而是从打印服务商订购,请按照“订购打印件”链接操作。链接中的说明包含薄壁免责声明。
- 采购 ESP 插座排针
采购两个 LCSC/JLCPCB 编号 C55778388 的 Kinghelm KH-2.54FH-1X9P-H3.5,即 2.54mm 间距的 1×9 THT 母排针。ESP32-C3-Zero 插座的两个排针位置各安装一条。
- 订购主控制板
订购开源主控制板;文档说明可从任意制造服务商处订购。
打印与加工
- 核对 ESP 插槽尺寸
在依赖该载板外形前,用自己导出的桌面模型重新核对 ESP 插槽尺寸;不同伺服器预设会产生不同的桌面尺寸。
- 重新生成并订购 PCB
从 `compact-carrier-board.kicad_pcb` 重新生成 Gerber、钻孔、BOM 和 CPL 输出,不要依赖仓库中已提交的副本,然后使用这些输出订购载板。
- 制造两层载板
按 26 × 44mm、2 层板制造载板。ESP 安装槽尺寸为 25.0 × 18.5mm,槽的四个侧面中有三个距离全高外壳壁仅 3.0-3.6mm。
- 布置前区连接孔
在前区设置 J_PWR 的 4 个通孔,包括 5V、GND 和外部 USB D+/D-,并设置 J_SERVO、J_I2C_OLED、J_I2C_PCA 与 J_I2S。两个 I2C 连接器通过板载铜共享总线。
- 完成板内电源布线
将所有连接完全布在板内,不需要板外跳线。J_SERVO 直接以 5V 接到 PCA9685 的 V+,绕过 ESP 自带的 3.3V 稳压器;J_I2S 使用独立的板载 5V 供电。
- 运行 PCB DRC 检查
使用 KiCad 10.0.6 运行 DRC,不使用 `--refill-zones`,以便检查磁盘上的现有填充。结果应为 0 个违规和 0 个未连接项目。
- 核对焊盘丝印名称
确认每个焊盘都有丝印名称:外排为 `GP21`-`GP6`,内排为 `5V, GND, 3V3, GP0`-`GP5`。两个 I2C header 标为 `3V3/SDA/SCL/GND`,`J_I2S` 标为 `5V/BCLK/LRC/DIN/GND`,`J_PWR` 标为 `GND/D+/D-/5V`,`J_SERVO` 标为 `5V/GND`。
- 检查丝印几何间距
通过几何方式检查丝印位置,而不是依赖 DRC。应无丝印相互重叠,丝印到焊盘最小间距为 0.421mm,丝印到板边最小间距为 0.383mm。
- 调整丝印与连接器位置
将全部七处文本设置为 1.0mm / 0.15mm,并移动 `J_I2C_PCA`、`J_PWR` 和 `J_SERVO`,使其避开新的引脚名称带。重新核对每个标签与 0.30mm 板边距,并将位于边界的三个标签向内微调。
- 提高并重新填充 GND 间距
将铺铜区域的局部间距和 Default 网络类中的 GND 间距都从 0.20mm 提高到 0.25mm。重新填充该区域。
- 修正四个左侧参考标号
使用各封装自身的文本边界框,将 `J_ESP1`、`J_ESP2`、`J_I2C_OLED` 和 `J_I2C_PCA` 标签向右移动。调整到距离板左边缘 0.3mm 的位置,并进行目视确认。
- 验证并设置 GND 区域缩进
在修正钻孔后的板上,将 B.Cu GND 区域轮廓从板边向内 0.5mm 设置。以 1.0mm 至 0.3mm、每次 0.1mm 的步长测试并重新充电子区域;1.0mm 和 0.8mm 各自产生一个未连接焊盘,0.6mm 至 0.3mm 均通过检查,最终选择 0.5mm。
- 检查 PCBWave 制造报告
确认最细特征为 0.15mm 铜,即 GND 铺铜的最小厚度。它高于 JLCPCB 的 0.127mm 下限,但正好等于 PCBWave 的 0.15mm 下限;若使用 PCBWave,下单前检查其 DFM 报告。
- 加宽并重排 5V 走线
按 IPC-2221 的 2A、1oz 铜、10°C 温升条件,将 5V 网络最小宽度设为约 0.78mm。该网络全长 44.9mm,使用 1.0mm 宽度且没有收窄段;将 5V 焊盘移到内排,使其更靠近负载 15.24mm。
- 调整完整 CAD 装配体
在 Autodesk Fusion 中打开 cad/TinyEngineer.f3d,调整完整装配体,或使其适配不同的硬件尺寸,包括不同的舵机。
- 添加新的参数化零件
按照添加零件指南应用参数化规则和时间线,配置 PRINT_LAYOUT 与 Servo Configurator,导出零件,并可选择应用 mods。
- 根据舵机选择零件
将 parts/{servo_id}/ 文件夹与购买的舵机型号对应。可用的 3MF 文件夹包括 sg90、fs0307、es9051 和 hd1370a。
- 使用交互式打印队列
打开 Print 页面,使用 Shop 舵机选择功能,实时预览零件,并下载 .3mf 或 .stl 文件。
- 下载 3MF 零件文件
如果不使用打印队列,可从 sg90、fs0307、es9051 或 hd1370a 零件文件夹下载 .3mf 文件。
- 选择 PLA 或 PETG
使用 PLA 或 PETG,并采用无需支撑的打印方向打印零件。
- 改为订购打印零件
如果没有打印机,按照打印零件订购指南,从第三方服务订购整套打印零件。
- 从打印指南开始
按照 Print first 指南开始打印流程。
- 先打印两个适配测试件
使用家用打印机时,先打印 ServoSizingTester.3mf 和 ScrewSizingTest.3mf,再打印其余部件。两个测试件都适配前不要打印完整机器人;从打印服务商订购时可跳过此步骤。
- 不要缩放地打印 LampDiffuser
使用白色或半透明 PLA 打印 LampDiffuser,也可以使用 PETG。该部件有意设计得很薄,使用 0.4 mm 喷嘴时厚度约为 0.38 mm,且不得缩放模型。如果切片软件跳过它,请检查空层错误、预览中缺失壁面或薄壁警告。
- 下载 PCB 制造文件
从商店电路板栏或直接链接下载 gerbers.zip、bom.csv 和 positions.csv。这些文件由最新 GitHub Pages 部署中的电路板源文件生成,而不是来自发布标签。
- 创建 PCB 制造商账户
在所选的 PCB 制造商处创建账户。本指南使用 JLCPCB,但也可以使用其他制造商。
- 检查库存和元件方向
打开制造商界面,并在付款前检查元件库存和方向。对于所选的制造商和组装服务,应重新核对物料清单和零件供应情况。
- 订购主控制 PCB
使用下载的制造文件,从 JLCPCB 或其他制造商订购主控制板。可以选择使用 LCSC 零件进行组装;制造商负责制作 PCB 并焊接选定元件。
- 安装 KiCad 和 Fabrication Toolkit
Install KiCad 10 and add the Fabrication Toolkit plugin through Plugin and Content Manager.
- 打开主控板项目
在 KiCad 中打开 `hardware/boards/main-control-board/main-control-board.kicad_pro`。
- 导出生产文件
运行 Fabrication Toolkit,使文件写入板卡目录下的 `production/`,并确认 Gerber ZIP、`bom.csv` 和 `positions.csv` 已生成。`production/` 仅保留在本地,因为它已被 gitignore。
- 使用生产脚本导出文件
在安装了或可下载 KiCad Python(`pcbnew`)和 Toolkit 的机器上运行导出脚本。它会在 gitignored 的 `web/shop/fab/main-control-board/` 下写入相同的三个公共文件名。
- 检查元件放置和方向
检查元件的放置和方向,然后继续。
- 打印 SG90 机器人零件
从 3d_models/parts/sg90/3mf/ 目录打印机器人零件。
- 打印 FS0307 机器人零件
从 3d_models/parts/fs0307/3mf/ 目录打印机器人零件。
- 打印 ES9051 机器人零件
从 3d_models/parts/es9051/3mf/ 目录打印机器人零件。
- 打印 HD-1370A 机器人零件
从 3d_models/parts/hd1370a/3mf/ 目录打印机器人零件。
- 按舵机型号选择文件
在 Shop Section 中选择舵机型号;该尺寸决定 CAD 基准和整套打印文件。家用打印机优先使用 3MF,许多打印服务使用 STL。
- 打印并检查适配测试件
打印两个小型适配测试件,检查舵机凹槽和 M2 螺钉的适配情况。测试件为可选项,但如果尚不了解打印设置,建议先打印。
- 打印整套颜色模型
先订购或打印适配测试件,完成可选的适配检查,再按颜色打印整套模型:铜色、黑色或白色。
组装
- 在桌面上搭建线束
在桌面上搭建线束。此步骤安排在打印之后、烧录之前。
- 安装模块化线束
按照模块化装配页面安装线束,替代标准装配文档的第12至13节。
- 连接所有模块的公共地线
将公共 GND 连接到每个模块。不要把 5 V 和 3.3 V 电源轨短接在一起。
- 连接共享I2C总线
连接 I2C 的 SDA 和 SCL 信号线。OLED 与 PCA9685 共用这一条 I2C 总线。
- 连接MAX98357A音频信号
将 I2S 的 BCLK、LRC 和 DIN 信号接入 MAX98357A。扬声器采用 BTL 接线,SPK− 不是地线。
- 连接USB数据信号
将 USB D+ 和 D− 数据信号连接到 Adafruit 5993 USB-C 扩展板。
- 连接PCA9685使能信号
将 ESP32 的 GP5 连接到 PCA9685 的 OE。固件GPIO编号见 include/pins.h 和 pinout.md,图中的 GP0 至 GP21 分别对应 GPIO0 至 GPIO21。
- 连接3.3伏逻辑电源
将 ESP32 的 3V3 连接到 PCA9685 的 VCC 和 OLED 的 VCC。PCA9685 的 VCC 是逻辑电源,5 V 和 3.3 V 不能短接。
- 最后连接5伏电源
最后连接5 V电源:USB VBUS 到 ESP32 5V、PCA9685 5V 和 MAX98357A Vin。PCA9685 的 V+ 用于舵机供电,定心前不要插入舵机插头。
- 确认 PCA9685 电源引脚
将 V+ 视为舵机电源轨,它通常与 PCA9685 的 5V 焊盘相同;不要把 5V 当作 VCC。
- 连接所有模块公共地
按连接表连接各模块,并让 ESP32、PCA9685、OLED、MAX98357A 和舵机共用同一地线网络。
- 按图连接电源
将 USB 5V 依次连接至 ESP32 5V、PCA9685 5V 和 MAX98357A Vin,将 PCA9685 V+ 连接至舵机 5V。将 ESP32 3V3 仅连接至 PCA9685 VCC 和 OLED VCC。
- 连接舵机侧地线
将 USB GND 连接至 ESP32 GND、PCA9685 排针侧 GND、OLED GND 和 MAX98357A GND,并通过 PCA9685 舵机排针侧 GND 连接舵机 GND。
- 连接 USB 电源与编程线
使用图中的 Adafruit 5993 USB 模块提供 VBUS/GND 电源;单 USB 设计还需将 D+ 和 D− 分别连接至 GP19 和 GP18。
- 连接共享 I2C 总线
将 ESP32 GP0 连接至 PCA9685 SDA 和 OLED SDA,将 ESP32 GP1 连接至 PCA9685 SCL 和 OLED SCL。
- 连接 MAX98357A I2S
将 ESP32 GP2、GP3、GP4 分别连接至 MAX98357A 的 BCLK、LRC、DIN,并将 USB 5V 与 USB GND 分别连接至 Vin 和 GND。
- 连接 0–4 通道舵机
将五个 HD-1370A 舵机连接到 PCA9685 的 PWM 通道 0–4。图中未标出 PWM 排针编号;通道与关节的对应关系见 robot-movement.md 和 include/servos.h。
- 保留未接线 ESP32 引脚
不要给 GP6、GP7、GP8、GP9、GP10、GP20、GP21 添加图中未给出的接线。其中 GP9 是 BOOT,GP10 连接板载 WS2812。
- 连接 PCA9685 使能脚
将 ESP32-C3-Zero 的 GP5 连接到 PCA9685 breakout 的 OE,OE 为低电平有效。即使基础 PNG 漏画此线,也要在面包板和 Adafruit breakout 的 OE 引脚上补接。
- 连接 ESP32 原生 USB
从 Adafruit 5993 的 D−/D+ 连接到 ESP32-C3-Zero 的 GP18/GP19 原生 USB 引脚,即使基础 PNG 未画出也要接线。
- 不要增加额外 GPIO 接线
未画在图中的器件仍属于所选硬件,但不要为它们自行增加 ESP32 GPIO 接线。
- 保留 MAX98357A 默认配置
不要连接 MAX98357A 的 GAIN 或 SD,让 breakout 使用其默认配置。
- 正确连接 BTL 扬声器输出
MAX98357A 输出是 BTL,SPK− 和 SPK+ 都不是地线。不要将任一端接到 GND,也不要从 ESP32 GPIO 驱动扬声器。
- 安装唯一的 USB-C 连接器
使用 Adafruit 5993 作为机器人唯一的 USB-C 连接器。它是 USB Type-C 垂直向下 breakout,包含两只 5.1 kΩ CC 电阻,向上游端口请求 5 V、最高约 1.5 A。
- 连接 USB 电源与数据线
将 USB 5V 和 GND 接到机器人电源轨,同时连接 D+/D− 数据线,不要只照基础图连接电源线。
- 连接所有 GND 网络
确认 PNG 中的所有 GND 属于同一个网络,包括 USB、ESP32、PCA9685 两侧、OLED、MAX98357A 和舵机。
- 检查 PCA9685 电源
确认 PCA9685 的 VCC 约为 3.3 V,5V 或 V+ 约为 5 V,并确保这两个网络没有短路。
- 连接 OLED 时钟线
将 OLED 时钟线接到 Waveshare 的 SCL;PNG 中可能仍标为 SCK。
- 核对 I2S 接线
确认 I2S 按 GP2、GP3、GP4 分别连接到 BCLK、LRC、DIN,不要与 I2C 接线互换。
- 检查扬声器接线
如果安装了扬声器,它只使用 SPK+ 和 SPK-,而这两个端子不在 PNG 中。
- 安装载板并连接接口
将载板安装在 ESP32-C3-Zero 下方,使其穿过桌子的 ESP 插槽,并使用 `J_PWR`、`J_SERVO`、`J_I2C_OLED`、`J_I2C_PCA` 和 `J_I2S` 接口连接电源、舵机电源、OLED、PCA9685 和 I2S 设备。
- 保留其余裸通孔
不要在 J_PWR、J_SERVO、J_I2C_OLED、J_I2C_PCA 和 J_I2S 上安装连接器。这些通孔仅用于导线直接连接,并在封装层面排除于 BOM 和 CPL。
- 安装两条 ESP 排针
将 J_ESP1 放在靠导线端的内侧行,中心坐标为 (13.00, 16.89),引脚为 5V、GND、3V3、GPIO0-5。将 J_ESP2 放在靠插槽边缘的外侧行,中心坐标为 (13.00, 1.65),引脚为 GPIO21-GPIO6。
- 按正确朝向放置 C3-Zero
将 C3-Zero 元件面朝上,使其 USB-C 位于载板 5V 总线边缘,即 5V 走线沿行的长边。垫片映射必须按模块插入面的元件侧视图核对。
- 连接 J_ESP2 外侧排针
将外侧排针 J_ESP2 放在靠插槽边缘一侧(y=14.15),依次连接 GPIO21、GPIO20、GPIO19、GPIO18、GPIO10、GPIO9、GPIO8、GPIO7、GPIO6。除原生 USB 对 GP19 和 GP18 外,这些针脚为机械或无网络连接。
- 连接 J_ESP1 内侧排针
将内侧排针 J_ESP1 放在靠近线束端一侧(y=29.39),依次连接 5V、GND、3V3、GPIO0(SDA)、GPIO1(SCL)、GPIO2(BCLK)、GPIO3(LRCLK)、GPIO4(DIN)、GPIO5。
- 核对插针编号方向
确认两排的 1 脚和 18 脚都落在 5V 总线边缘,使模块 USB-C 固定在该边缘。从上方从 1 到 18 应为逆时针方向,并与 Waveshare 图示一致:1–9 沿左列向下,10–18 沿右列向上,USB-C 位于顶部。
- 连接外部 USB-C 插座
使用机器人唯一的外部 USB-C 插座(Adafruit 5993),同时接通电源和 ESP32 原生 USB D+/D−;桌面封闭后可通过该插座烧录和使用串口 CDC。C3-Zero 自带的板载 USB-C 不使用,USB 链路为直接连接,不设置 ESD 或串联电阻电路。
- 布置等长 USB 走线
让 D+/D− 沿各自焊盘的 2.54 mm 网格列向下走线,x 坐标为 20.42 和 22.96。经过内侧排针时,在 3V3 与 SDA 所在列各作一次 1.27 mm 横向偏移,使距最近焊盘边缘 0.42 mm 后返回;线路保持 F.Cu,不使用过孔。
- 组装前标记 1 脚
pour 面朝下装配会使丝印位于底面,因此组装前先标记 1 脚。
软件与固件
- 刷写机器人固件
在将 Tiny Engineer 集成到 IDE 或自定义智能体之前,先刷写 Tiny Engineer 固件。
- 加入 2.4 GHz Wi-Fi 网络
将机器人连接到电脑或 IDE 所使用的同一 2.4 GHz Wi-Fi 网络。
- 从 npm 安装统一 CLI
从 npm 安装 `tiny-engineer` 软件包,无需克隆代码仓库。
- 运行 CLI 设置
运行通用设置,或使用 `--yes` 运行 Cursor 专用设置。设置程序写入的钩子超时时间至少为 30 秒。
- 安装 IDE 事件钩子
配置 IDE 钩子,将 IDE 事件映射为机器人姿势并 POST 到 `/anim`。
- 配置用户连接偏好
在 macOS/Linux 的 `~/.config/tiny-engineer/env` 或 Windows 的 `%APPDATA%\tiny-engineer\env` 中保存传输方式、URL、端口和令牌;可通过 `TINY_ENGINEER_CONFIG_DIR` 覆盖目录。
- 设置机器人 URL
使用 `--url http://192.168.x.x`,或设置 `TINY_ENGINEER_URL`;否则 CLI 使用 `http://tiny-engineer.local`。设置程序不会修改项目的 `.env` 文件。
- 选择主机传输方式
通过 `--transport http|serial` 或 `TINY_ENGINEER_TRANSPORT` 选择 HTTP 或串口;设置程序会将该选项保存到用户配置,默认值为 HTTP。
- 配置 HTTP 身份验证
如果 HTTP 设备具有 `access_token`,请在进程环境、用户配置或项目 `.env` 中设置 `TINY_ENGINEER_TOKEN`。CLI 会发送 `Authorization: Bearer …`;串口传输不会发送 Bearer。
- 设置并诊断当前检出
在仓库检出中运行 setup 和 doctor。此检出使用 `dev` 通道,而注册表安装使用 `npm` 通道。
- 通过守护进程运行串口命令
除非守护进程已禁用或端口处于让出状态,串口命令会自动启动 `tiny-engineer daemon` 并通过本地套接字与其通信。HTTP 命令不会启动它。
- 安装持久化守护进程包装器
运行 `tiny-engineer daemon install` 可确保进程持续运行。它注册的是按用户的登录包装器,而不是系统启动服务,并会在崩溃后重启进程;安装期间,`start --port` 和 `restart --port` 会被忽略。
- 释放 USB 串口
运行 `tiny-engineer daemon release` 可释放 USB 端口,同时让守护进程继续运行。`daemon stop` 和 `stop --yield` 分别是 `release` 和 `release --yield` 的弃用别名。
- 持久禁用守护进程
运行 `tiny-engineer daemon disable` 可退出守护进程并使其保持停止状态。直到运行 `tiny-engineer daemon start` 前,它都会保持关闭。
- 临时让出串口
运行 `tiny-engineer daemon release --yield` 可保持进程运行,但会在 180 秒内拒绝自动启动,并且在该窗口结束后不会重新打开端口。随后执行 PlatformIO 的 `pio run -t upload` 会通过 `daemon start` 清除让出状态。
- 从所需检出重启守护进程
从所需检出行运行 `daemon restart`,使其替换来自其他检出的守护进程。开发检出可替换正在运行的 npm 守护进程,而 npm 命令不会停止正在运行的开发版守护进程。
- 调用动画路由
使用 Shell、JavaScript 或 Python 示例,向机器人 POST 一个动画名称。
- 选择集成方式
Cursor、Claude Code 或 Antigravity 使用统一 CLI。自定义代理、其他 IDE、CI 或没有 Node 的系统使用 REST API。
- 迁移已弃用的集成
使用统一的 `tiny-engineer`,替代已弃用的 `tiny-engineer-cursor`、`tiny-engineer-antigravity` 和 `tiny-engineer-claude-code`。先运行 setup,再运行 uninstall 清除残留钩子。
- 添加 macOS 锁屏事件
在 macOS 上可选择运行主机辅助程序,在屏幕锁定或解锁时 POST `sleep` 和 `wakeup`。机器人不需要该辅助程序。
- 打开设置向导
当启动时缺少 Wi-Fi 凭据时,加入 `TinyEngineer-XXXX` 设置热点,并打开 `http://192.168.4.1/config` 中的向导。手机加入网络后,强制门户也可以自动打开该向导。
- 选择连接模式
将连接模式选择为 `wifi` 或 `usb`。所选的 `link_mode` 会由设置、认证和健康状态接口返回。
- 启用仅 USB 控制
选择仅 USB 模式后重启 ESP32-C3。Wi-Fi 站点和 HTTP API 会被禁用,控制将使用 USB 串口协议。
- 连接 HTTP API
STA Wi-Fi 连接后,使用端口 80 上的板载 IP 或 `http://tiny-engineer.local`;mDNS 主机名仅支持 2.4 GHz Wi-Fi。如果已保存的凭据失效,设备会重新打开设置热点模式。
- 配置 API 认证
配置 `access_token` 后,每个 JSON API 请求都要发送 `Authorization: Bearer <token>`。默认的空令牌不需要认证,且 `GET /auth` 始终公开。
- 发送 JSON 请求正文
向带参数的路由发送 JSON 对象正文并设置 `Content-Type: application/json`,但 `POST /anim` 和 `/play` 除外。在这些路由上使用查询参数或表单字段,或者正文不是 JSON 对象,都会返回 `400`。
- 启用 Kaomoji 眼睛
将 `eyes_style` 设为 `kaomoji`,让 OLED 显示表情库中的循环表情。循环时长为 3 秒,共 30 帧。
- 启用 Cover 眼睛
将 `eyes_style` 设为 `cover`。每只眼睛以 64×32 的白色矩形填充 128×32 面板的一半,动画会调整高度和留白。
- 启用 Dots 眼睛
将 `eyes_style` 设为 `dots`,将每只眼睛渲染为实心圆。经典张开高度下外框为 12×12 像素,直径会随渲染高度缩放。
- 启用 Kawaii 眼睛
将 `eyes_style` 设为 `kawaii`,使用约 23 像素宽的圆眼、深色瞳孔、白色高光、小嘴和抖动腮红。`typing` 动画会阅读代码,`ring` 动画则让眼睛保持全尺寸。
- 添加自定义音频提示
在包含 `custom_audio_mod` 的文件系统中替换默认 WAV 文件,并为每个自定义音频在 LittleFS 中提供 `.cue` 文件。使用 `/welcome.cue`,并对 `attention`、`error`、`abort` 和 `dead` 采用相同命名模式。
- 安装 ESP32 模块
将 ESP32 模块推入主板插槽,并使其与板上印刷的 USB 标记对齐。
- 连接 USB-C 数据线
将 USB-C 数据线连接到主板的 USB-C 接口,不要插入 ESP32 模块上的小接口。
- 安装机器人固件
等待模型和可刷写版本加载完成,然后点击 Install,通过 USB 将机器人软件写入 ESP32。
- 确认刷写成功
主板刷写完成后,点击 Continue 并进入机械组装。
- 使用 PlatformIO CLI 刷写模块
也可以运行 CLI 上传命令来刷写模块。单独刷写的模块会闪烁并暂停,以寻找主板。
- 刷写主控制板
刷写主控制板;机器人随后加入 Wi-Fi。
- 设置编码代理集成
运行设置命令,将 Tiny Engineer 配合 Claude Code、Cursor 或 Antigravity 使用。
- 配置智能体发送姿态
使用默认客户端或钩子脚本,通过 Wi‑Fi HTTP 或 USB serial 向 ESP32-C3 发送姿态。
- 配置 USB CDC 串口
通过同一根 USB 线供电并编程,固件使用 ARDUINO_USB_MODE=1 和 ARDUINO_USB_CDC_ON_BOOT=1,串口监视器设为 115200。
标定与测试
- 校准舵机轮毂
在舵机轮毂向导步骤中,选择引导校准、跳过校准或使用装配居中。
- 设置 OLED 方向
在设置向导中配置 OLED 的方向。
- 测试 RGB LED
在设置向导中运行 RGB LED 测试。
- 测试扬声器
在设置向导中运行扬声器测试。
- 验证机器人配置状态
使用 `/anim`、`/test/*` 和 `/play` 控制 API 前,先选择连接模式。完成配置前,这些路由返回 `503` 和 `{"ok":false,"error":"not provisioned"}`。
- 检查 API 认证状态
查询认证端点,以查看是否需要 API 认证以及 Wi-Fi 是否已配置。该公开响应不会显示令牌。
- 检查机器人健康状态
查询运行时间、内存、CPU 温度、Wi-Fi 状态和 OLED 可用性等健康信息。启用认证时,请将令牌作为 Bearer 授权标头发送。
- 验证并保存机器人设置
通过 POST /settings 发送设置,省略字段即可保留已保存的值。空对象、未知字段、无效类型或范围、不完整的舵机限制、启用的扩展共用 GPIO 引脚,以及在 AP 模式之外进行仅限 AP 模式的修改,都会返回 400 且不会保存任何内容。
- 先设置主机名
在 AP 模式中测试或保存 WiFi 前,先通过 POST /settings 设置主机名,使 mDNS 注册使用已保存的主机名。
- 准备 WiFi 网络列表
准备 1 到 5 个网络,SSID 必须唯一且密码长度必须有效。新 SSID 必须提供密码,空字符串表示开放网络,省略密码则保留该网络已保存的密码。
- 替换并测试 WiFi 网络
将完整数组发送到 PUT /settings/wifi;列表顺序决定扫描未找到网络时的启动优先级。在 AP 模式之外,列表保存时不测试并在下次启动时生效;在 AP 模式中,会先测试并加入第一个网络然后再保存;启用身份验证时需使用 Bearer 令牌。
- 列出设备端 Actions
GET `/settings/actions` 列出事件到效果的绑定;启用身份验证时需要 Bearer 令牌。GET `/actions` 提供 SPA Web 界面外壳,而不是此 JSON。
- 替换 Actions 列表
发送包含 `actions` 数组的 JSON 对象,数组可有 0–16 行;启用身份验证时需使用 Bearer 令牌。每行必须包含 `on`(1–47 个字符;`*` 匹配事件类型中的任意序列)、`do`(`sound` 或 `anim`)以及对应的 `sound`(`bell`/`click`)或 `anim` 名称;多余字段会被忽略,更改立即生效,匹配的行按列表顺序运行,缺少数组、超过 16 行或行无效时返回 400,超限或无效更新时保留原列表。
- 测试 Action 事件
向 POST `/actions/test` 发送 JSON `{ "type": "button.click" }`,可运行匹配的 Actions,而不会发布 WebSocket 或串口消息包。该端点要求已配置机器人,并在启用身份验证时要求 Bearer 令牌;缺少或为空的 `type` 会返回 400。
- 将全部五个舵机移动到 90°
在 AP 模式下,将全部五个舵机缓慢移动到 90°,使用完整的 0–180° 电气范围且不应用已保存的安全范围限制。处理器会阻塞至移动完成,并且不需要 Wi-Fi 凭据。
- 将一个舵机移动到 90°
发送 `index` 和 `angle`,以约 25°/s 的速度通过完整的 0–180° 电气范围缓慢移动一个舵机。字段错误时返回 400,且不会移动任何舵机。
- STA 启动后测试舵机
STA 连接启动后,通过 `POST /test/servo` 测试舵机;该端点会将移动限制在已保存的最小值和最大值之间。
- 预览逻辑 LED 颜色
在 AP 模式下,发送逻辑 `R`、`G` 或 `B`,使用已保存的 `rgb_order` 或随请求发送的 `rgb_order` 点亮固件的红、绿或蓝通道,用于重映射预览。不要同时发送 `color` 和 `byte`。
- 预览逻辑 LED 字节
在 AP 模式下,发送逻辑字节以点亮对应通道,不受 WS2812 通道顺序影响;通道 255 会点亮该通道。不要同时发送 `color` 和 `byte`。
- 释放 LED 预览保持
发送空请求体以释放 LED 保持状态并恢复配置期间的暗蓝色显示。该设置操作不需要 Wi-Fi 凭据。
- 保存 RGB 通道顺序
在设置 AP 模式下,通过 `POST /settings` 和 `{"rgb_order":"GRB"}` 保存带标签的 RGB 排列。保存后的顺序会立即应用于动画颜色、启动状态、停止闪烁和 `POST /test/led`。
- 播放设置欢迎音频
在设置 AP 模式下发送无请求体的 POST;它会从 LittleFS 播放 `welcome.wav`,并阻塞至播放结束。它不需要 Wi-Fi 凭据,并使用与设置项 `volume` 相同的扬声器增益。
- 预览旋转后的 OLED
在设置 AP 模式下发送 `{"rotate_180": true}`,以应用 `setRotation(2)` 并绘制 `THIS WAY UP`,且不保存更改。错误字段会返回 400 响应。
- 预览正常方向的 OLED
在设置 AP 模式下发送 `{"rotate_180": false}`,以应用 `setRotation(0)` 并绘制相同的 `THIS WAY UP` 测试,且不保存。
- 恢复保存的 OLED 方向
在设置 AP 模式下发送空请求体,以恢复保存的旋转设置和配网加入 AP 文本。
- 保存 OLED 旋转设置
在设置 AP 模式下,使用 `POST /settings` 和 `{"oled_rotate_180":true}` 保存 OLED 旋转设置。保存的值会立即生效,并在下次启动时应用。
- 确认机器人健康检查端点
打开 `http://tiny-engineer.local/health` 或 OLED IP 的健康检查端点,并确认其能够响应。
- 检查 CLI 连接
运行 `doctor` 检查接线及连接配置。
- 检查守护进程和串口状态
运行状态命令,检查 `daemon install` 是否启用以及登录包装器是否正在运行。它还会报告主机串口、守护进程打开的端口、通道和软件包根目录。
- 为已启用的串口反应打开 USB
当串口反应已启用时,即 `rules.json` 中存在规则且用户传输方式为 `serial`,`daemon start` 和 `daemon restart` 会打开 USB 端口;否则端口保持关闭。
- 检查机器人状态
请求健康检查端点,验证机器人状态且不产生运动。
- 核对 BOM 数量
确认生成的 BOM 将两个相同封装合并为一行 `"J_ESP1,J_ESP2"`,并明确表示数量为 2。JLCPCB 装配工具和大多数 BOM 工具按设计ator 数量确定数量,而不是解析 Comment 文本。
- 核对 CPL 行坐标
确认 CPL 为 J_ESP1 和 J_ESP2 各生成一行,中心坐标分别为 (13.00, 16.89) 和 (13.00, 1.65)。坐标应直接从各封装原点导出,不手工推导。
- 保存区域填充并复核 DRC
每次走线变化后,使用 KiCad 的 Fill All Zones 并保存,或使用 `pcbnew.ZONE_FILLER` Python API,重新填充 GND 区域。随后运行不带 `--refill-zones` 的 `kicad-cli pcb drc`,确认磁盘上的填充已更新。
- 检查舵机测试件适配情况
将真实舵机放入 ServoSizingTester.3mf,不要强行压入。确认本体可以滑动、卡扣就位、孔位对齐且舵轴有间隙;如果过紧或过松,可打磨或扩孔,也可调整舵机 CAD 参数。
- 确定 M2 螺钉底孔尺寸
在 ScrewSizingTest.3mf 中,将 M2 螺钉旋入每个标有直径的孔,选择仍能切出螺纹且不会自由旋转或滑过的最紧孔径。将 Fusion 用户参数 `screw_thread_diameter` 设为对应的标记直径,然后在打印结构件前重新导出。
- 打开 Web 界面
在浏览器中打开 http://tiny-engineer.local/,或使用 OLED 上显示的 IP 地址。
- 检查健康状态和 ring 动画
运行健康检查并请求 ring 动画。确认 /health 为 OK,且 ring 能够运行运动;如果已上传 LittleFS,还应运行声音。如果 .local 较慢,请使用 OLED 上的 IP 地址或 curl -4。
- 配置舵机舵盘和限位
从 `include/servos.h` 中的 `SERVO_SPECS` 开始设置舵机舵盘和限位;如有必要,在安装后进行微调。
- 检查已保存的舵机运动限位
检查组装后的运动是否保持在已保存的最小值和最大值范围内。
采数据与训练
- 接收出站事件
HTTP 服务器运行时,连接端口 81 的 `/events` 出站事件 WebSocket。相同的事件 JSON 也会通过 USB 串口以 `Evt` 帧发送。
用起来
- 连接认证事件流
连接 WebSocket 事件端点,并将 YOUR_TOKEN 替换为认证令牌。
- 监视串行事件帧
使用 `tiny-engineer watch`;`http:` 基础地址对应 WebSocket 传输,`--transport serial` 对应 `Evt` 帧。串行帧与 WebSocket 文本帧使用相同的 JSON 载荷;当 CDC 发送缓冲区无法接收帧时,该串行副本会被丢弃。
- 打开端点索引
请求 HTML 索引以列出所有路由和支持的参数。该页面使用 Vite 从 `ui/` 构建,并嵌入固件中。
- 连接站点后测试音频
STA 启动后,使用 `POST /test/audio/bell` 播放铃声,或使用 `POST /test/audio` 播放音调。
- 停放并保持舵机
发送无请求体的 POST 请求,以停止当前动画、平滑地将每个关节移动到校准中点、将姿态持久化到 NVS,并在下次重启前保持 PWM 启用。启用身份验证时,该端点需要 Bearer 令牌,并可在设置 AP 和完成配网后使用。
- 连接自定义集成
对于自定义智能体、不受支持的 IDE 或脚本,可调用 REST API 或串口协议。HTTP 集成通过 `POST /anim` 发送动画请求。
- 将 IDE 事件映射到动画
将动画请求连接到 IDE 的钩子、插件或生命周期事件。映射方式可自行选择,机器人只使用 `name` 值。
- 查看可用路由
查阅 `api.md` 获取完整路由列表,包括测试、舵机、Web UI 和 `/play`。
- 返回入门检查清单
完成集成 PCB 的制作后,返回入门检查清单,继续组装和使用 Tiny Engineer。
- 将按钮事件映射到主机程序
启用扩展后,按压会通过 WebSocket 和串口发布 `button.down`、`button.up`、`button.click`、`button.double_click` 和 `button.long_click`。可使用 CLI 将事件映射到主机程序,例如在单击时打开音乐。
常见问题
物料
- Tiny Engineer 主控板(板上集成 PCA9685 舵机驱动、MAX98357A 功放与 USB‑C);进阶做法可改用这三块分立模块
- Waveshare ESP32‑C3‑Zero 主控模块
- 5 个 Tower Pro SG90 微型舵机(或同型号的 Feetech FS0307 / EMAX ES9051 紧凑版)
- Waveshare 0.91 寸 OLED(SSD1306,128×32,I²C)与 Adafruit 8 Ω 1 W 迷你椭圆扬声器
- M2 自攻螺丝:4 mm ×8、8 mm ×27、16 mm ×15,另加 6 个 M2 螺母
- 5 V ≥2 A USB 电源与 USB‑C 数据线;PLA 或 PETG 打印件(铜色组、黑色组与白色或半透明灯罩)
工具
- 3D 打印机(先打印舵机与螺丝尺寸测试件),或交给第三方打印服务
- 小螺丝刀;主控板选单面贴片时需自焊两排 1×9 的 2.54 mm 母座
- Chrome 或 Edge 浏览器用于网页刷机
技能
- 向 PCB 厂下贴片订单:KiCad 10 加 Fabrication Toolkit 导出 Gerber、BOM 与坐标文件,并逐行核对物料
- 按装配指南第 1–19 节组装,在第 20 节的设置向导中校准舵机并接入 2.4 GHz Wi‑Fi
- Node 18+ 与 npx tiny-engineer setup 配置 IDE 钩子,或用 curl 调 REST 接口
软件
- ESP32‑C3 固件(PlatformIO):动画、眼睛样式(经典、颜文字、cover、dots)、提示音与 WAV 流式播放;网页刷机与 OTA 更新
- tiny-engineer 命令行(npm):setup、hook、doctor,支持 Cursor、Claude Code、Antigravity,HTTP 或串口传输
- HTTP API(/anim、/play、/settings 等)与 USB 串口协议
- Fusion 参数化 CAD 与舵机预设插件,可为新舵机导出零件