正在连接信源…

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

零件数量
Base1
ButtonPocket1
Bell1
Button1
Clamp4
CableTunnel1
ActionEmblem1
6×6 mm momentary tactile switch (4-pin)1
Jumper wires, female DuPont end2
M2×16 mm screws4
M2×8 mm screws (or nearby short)17

物料 · Default cart

零件数量ANY
Tiny Engineer main control board1
Waveshare ESP32-C3-Zero1
Tower Pro SG90 (or equivalent 9 g analog micro)5
Adafruit Mini Oval Speaker - 8 Ohm 1 Watt1
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 将事件映射到主机程序,例如在单击时打开音乐。

常见问题

  • SG90 模型尺寸不准确,导致舵机无法正确装配。 #30 #93
  • OLED 模块的尺寸、引脚和安装要求不一致。 #6
  • 参考舵机缺少全球可获得且经过验证的标准型号。 #5
  • 装配文档未说明 M2 螺钉的准确长度和所需数量。 #15
  • 找不到 ESP32 NVS 存储,导致固件烧录失败。 #81
  • 参数化头部与颈部无法正确连接。 #38

物料

  • 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 与舵机预设插件,可为新舵机导出零件

文档