Sesame Robot 项目深度分析报告项目名称: Sesame Robot作者: Dorian Toddstarphee开源协议: Apache License 2.0仓库地址: https://github.com/dorianborian/sesame-robot目录项目概述业务模型分析需求清单系统架构设计代码规模统计技术栈评估组件依赖分析API 接口清单数据模型硬件架构迭代优化建议1. 项目概述Sesame 是一个开源的桌面级四足步行机器人项目基于 ESP32 微控制器系统强调表情表达与运动能力的融合。项目目标是提供一个面向各级别制造者和工程师的可访问的机器人平台让用户能够从零开始构建一个具有表情显示和远程控制能力的四足机器人。核心特征:四足步行机器人8自由度128x64 OLED 表情显示屏WiFi 网络远程控制 Captive Portal 本地控制RESTful JSON API Python SDK完全 3D 打印PLA材质硬件成本 $50-60项目对标: 类似小型教育/娱乐机器人平台如 Petoi Bittle、Otto DIY但更侧重表情表达和网络互联。2. 业务模型分析2.1 价值主张维度说明目标用户Makers创客、工程师、教育工作者、机器人爱好者、STEM教育机构核心价值低成本、全开源、完整文档的四足机器人平台降低入门门槛差异化表情交互 运动控制融合双模WiFiAPStation动画作曲家工具商业模式开源硬件 社区驱动 Build Kit 销售Sesame Build Kit PCBway 赞助2.2 业务生态┌──────────────────────────────────────────────────────┐ │ Sesame 生态 │ ├──────────────────────────────────────────────────────┤ │ 硬件层 │ 3D打印零件 标准电子元件 PCB定制(Distro Board) │ │ 固件层 │ ESP32 Arduino 固件运动/表情/WiFi/API │ │ 软件层 │ Sesame Studio(C) Companion App(Python) │ │ 社区层 │ Discord YouTube 教程 PCBway 赞助 │ │ 商业层 │ Build Kits预组装 Distro Board V2 │ └──────────────────────────────────────────────────────┘2.3 收入渠道推断Sesame Build Kit销售含预烧录 Distro Board V2PCBway 赞助合作PCB制造YouTube 内容变现教程视频社区捐赠 / Discord 会员2.4 用户旅程1. 收集零件BOM清单采购$50-60 2. 3D打印外壳11个部件PLA材质 3. 焊接组装手工接线 或 Distro Board 4. 烧录固件Arduino IDE 5. 校准测试Motor Tester 调试工具 6. 创作动画Sesame Studio 可视化工具 7. 集成扩展JSON API Companion App3. 需求清单3.1 功能需求Functional RequirementsID功能分类需求描述实现状态FR-01运动控制四足步行前进、后退、左转、右转✅ 已实现FR-02运动控制预设动作站立、休息、挥手、跳舞、游泳、指点、俯卧撑、鞠躬、可爱、怪异、蠕虫、摇晃、耸肩、装死、螃蟹步✅ 17种动作FR-03运动控制8舵机独立角度控制0-180°✅ 已实现FR-04运动控制Subtrim 微调校准-90° ~ 90°✅ 已实现FR-05表情显示128x64 OLED 位图表情渲染✅ 已实现FR-06表情显示20 预设表情含运动表情和对话表情✅ 已实现FR-07表情显示“talk_” 对话变体张嘴口型同步✅ 9种talk变体FR-08表情显示表情动画LOOP/ONCE/BOOMERANG三种模式✅ 已实现FR-09本地控制Captive Portal Web UIAP模式✅ 已实现FR-10本地控制Serial CLI 命令行控制✅ 已实现FR-11网络控制Station模式连接家庭WiFi✅ 已实现FR-12网络控制mDNS 服务发现sesame-robot.local✅ 已实现FR-13网络控制RESTful JSON APIGET /api/status, POST /api/command✅ 已实现FR-14网络控制传统 HTTP 参数接口/cmd?go, /cmd?pose✅ 已实现FR-15网络控制动态参数配置/getSettings, /setSettings✅ 已实现FR-16空闲行为自动空闲动画呼吸随机眨眼✅ 已实现FR-17空闲行为WiFi信息滚动显示30秒无输入后✅ 已实现FR-18动画创作Sesame Studio 可视化动作编排工具✅ 已实现FR-19动画创作C 代码自动生成servo角度delay✅ 已实现FR-20调试工具Motor Tester 电机测试固件✅ 已实现FR-21安全保护舵机电流延迟保护防VCC跌落✅ 已实现FR-22安全保护非阻塞控制流pressingCheck 即时中断✅ 已实现3.2 非功能需求Non-Functional RequirementsID需求类别描述当前状态NFR-01实时性舵机PWM 50Hz帧延迟可配置✅ 满足NFR-02可用性无需编程即可组装仅需基础焊接✅ 满足NFR-03可移植性支持3种MCU板型S2 Mini / ESP32-DevKitC / ESP32-S3✅ 满足NFR-04可扩展性模块化固件架构支持添加新表情/动作✅ 满足NFR-05成本控制硬件总成本 $50-60✅ 满足NFR-06安全性AP密码可配置无HTTPS局域网环境⚠️ 基本满足NFR-07低功耗电池供电支持2x10440 Li-ion⚠️ V2板电池不稳定3.3 待实现需求Backlog/RoadmapID需求优先级来源BL-01运动学算法改进逆运动学IK高README社区贡献方向BL-02传感器集成超声波、陀螺仪中README社区贡献方向BL-03Web UI/UX 改进中README社区贡献方向BL-04Distro Board V3修复V2电池问题高文档提及免费发送给V2 Kit买家BL-05更多用户自定义动画低社区贡献BL-06身份认证机制生产环境部署低固件文档安全考虑BL-07WebSocket 实时控制低延迟中文档Advanced章节提及4. 系统架构设计4.1 总体架构图┌──────────────────────────────────────────────────────────────────┐ │ Sesame Robot 系统架构 │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ │ │ Sesame Studio │ │ Companion App │ │ Web Browser │ │ │ │ (Python/Tkinter)│ │ (Python/Voice) │ │ (Captive Portal)│ │ │ └────────┬─────────┘ └────────┬─────────┘ └────────┬────────┘ │ │ │ │ │ │ │ │ Code Export │ JSON API │ HTTP │ │ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ ESP32 固件层 (Arduino C) │ │ │ │ ┌───────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ │ │ Web Server │ │ Command │ │ Face Engine │ │ │ │ │ │ /, /cmd, │ │ Dispatcher │ │ updateAnimated- │ │ │ │ │ │ /api/status, │ │ (forward/ │ │ Face() │ │ │ │ │ │ /api/command │ │ backward/ │ │ setFace() │ │ │ │ │ │ /getSettings │ │ wave/dance…) │ │ idle/blink │ │ │ │ │ └───────────────┘ └──────┬───────┘ └────────┬─────────┘ │ │ │ │ │ │ │ │ │ │ ┌─────────────────────┐ │ ┌─────────────────┴──────────┐ │ │ │ │ │ WiFi Stack │ │ │ Servo HAL │ │ │ │ │ │ - SoftAP Station │ │ │ - ESP32PWM (4 timers) │ │ │ │ │ │ - DNSServer(Captive)│ │ │ - setServoAngle(ch,deg) │ │ │ │ │ │ - mDNS responder │ │ │ - motorCurrentDelay │ │ │ │ │ └─────────────────────┘ │ │ - subtrim calibration │ │ │ │ │ │ └────────────────────────────┘ │ │ │ └───────────────────────────┘ │ │ │ │ │ │ │ │ ▼ ▼ │ │ │ ┌──────────────────┐ ┌───────────────────┐ │ │ │ │ SSD1306 OLED │ │ 8x MG90S Servos │ │ │ │ │ (I2C, 128x64) │ │ (PWM, 50Hz, 180°) │ │ │ │ └──────────────────┘ └───────────────────┘ │ │ └──────────────────────────────────────────────────────────────────┘4.2 固件模块结构sesame-firmware-main.ino (854行) ← 主入口 ├── setup() - 系统初始化WiFi/OLED/Servo/WebServer ├── loop() - 主事件循环 Serial CLI ├── handleRoot() - Captive Portal HTML ├── handleCommandWeb() - Web命令处理 ├── handleApiCommand() - JSON API命令处理 ├── handleGetStatus() - 状态查询 ├── handleGetSettings/setSettings() - 参数配置 ├── updateAnimatedFace()- 表情动画引擎 ├── updateIdleBlink() - 空闲眨眼系统 ├── updateWifiInfoScroll()- WiFi信息滚动 │ ├── face-bitmaps.h (3,158行) │ ├── FACE_LIST 宏X-Macro注册系统 │ ├── 40 表情位图数据PROGMEM存储 │ └── talk_* 对话表情变体 │ ├── movement-sequences.h (429行) │ ├── ServoName 枚举R1-R4, L1-L4 │ ├── FaceAnimMode 枚举LOOP/ONCE/BOOMERANG │ ├── 17个动作函数runWalkPose/runWavePose等 │ └── pressingCheck() 中断检测 │ ├── captive-portal.h (851行) │ ├── index_html PROGMEM 常量 │ ├── 完整 Web UIHTMLCSSJS │ └── 深色主题 橙色调 │ └── debugging-firmware/ └── sesame-motor-tester.ino (137行) └── 独立电机测试工具Serial CLI4.3 控制流程用户输入 → WiFi(HTTP)或Serial(CLI) │ ▼ Command Dispatcher (loop()) │ ├── forward/backward/... → runWalkPose() 等持续动作 │ └── 循环调用 setServoAngle() delayWithFace() │ ├── wave/dance/... → runWavePose() 等一次性动作 │ └── 动作序列 自动进入 idle │ └── face: happy → setFace(happy) → updateFaceBitmap() │ ▼ Idle System (updateIdleBlink()) └── 3-7秒随机间隔 → 眨眼 (30%概率双眨眼)4.4 硬件抽象层HAL项目通过servoPins[]数组和I2C_SDA/I2C_SCL宏实现硬件抽象支持三种MCU板型// 只需修改这两个配置即可移植到不同ESP32板型constintservoPins[8]{1,2,4,6,8,10,13,14};// S2 Mini#defineI2C_SDA33#defineI2C_SCL355. 代码规模统计5.1 概览维度数值文件总数118源代码文件73个.ino, 3个.h, 1个.py文档文件14个 .md图片资源74个 .png3D打印文件15个 .stlPCB设计文件2个 .zip (Gerber) 2个 .csv 1个 .jsonCAD文件1个 .f3z 1个 .step5.2 源代码行数明细文件行数用途复杂度firmware/face-bitmaps.h3,158表情位图数据含40表情低数据firmware/sesame-firmware-main.ino854主固件系统核心逻辑高firmware/captive-portal.h851Web UIHTMLCSSJS中firmware/movement-sequences.h429运动序列定义中software/sesame-studio/sesame_studio.py282动画创作工具GUI中firmware/debugging-firmware/sesame-motor-tester.ino137调试工具固件低总计:~5,711 行源代码含位图数据3,158行实际逻辑代码 ~2,553 行5.3 文档行数明细文档行数内容firmware/README.md830固件完整技术文档 API参考docs/build-guide/README.md2685阶段建造指南docs/wiring-guide/README.md148接线指南README.md(根)134项目总览hardware/pcb/README.md110PCB设计文档hardware/bom/README.md95物料清单hardware/printing/README.md493D打印设置software/sesame-studio/README.md48Studio工具文档其他6个README104各模块简要说明文档总计:~1,786 行5.4 规模评估评估维度评级说明代码总量小型实际逻辑代码 ~2,500 行适合单人维护模块化程度良好固件拆分为4个文件 1个独立调试工具文档完善度优秀建造指南、接线图、API文档、PCB文档齐全测试覆盖缺失无自动化测试框架CI/CD无无持续集成配置6. 技术栈评估6.1 技术选型层级技术版本/型号评价MCUESP32 (S2/S3/WROOM32)-⭐⭐⭐⭐ 成熟稳定WiFiBLE固件语言C (Arduino框架)-⭐⭐⭐ 入门友好但有局限性IDEArduino IDE2.0⭐⭐⭐ 简单易用伺服库ESP32Servov3.0.9⭐⭐⭐ 有已知bug多通道泄漏显示库Adafruit GFX SSD1306-⭐⭐⭐⭐⭐ 成熟稳定网络WiFi.h WebServer DNSServerESP32内置⭐⭐⭐⭐桌面工具Python Tkinter Pillow3.x⭐⭐⭐ Tkinter较陈旧3D打印PLA-⭐⭐⭐⭐⭐ 通用低成本PCB设计EasyEDA (v2)SCH JSON格式⭐⭐⭐⭐ 开源友好6.2 技术债务问题严重性影响ESP32Servo v3.0.9 固定版本新版有多通道泄漏bug中阻止库升级无持久化存储设置无法断电保存中每次重启需重新配置手动JSON解析未使用ArduinoJSON低健壮性风险单核事件循环无RTOS低网络运动并发受限WIFI密码硬编码未使用Preference存储低便捷性不足Tkinter GUI非跨平台最优方案低UI现代化不足7. 组件依赖分析7.1 固件依赖Arduino 核心库: ├── WiFi.h - ESP32 WiFi (STA AP) ├── WebServer.h - HTTP 服务器 ├── DNSServer.h - DNS 劫持Captive Portal ├── ESPmDNS.h - mDNS 服务发现 ├── Wire.h - I2C 通信 └── Arduino.h - 基础框架 第三方库: ├── ESP32Servo v3.0.9 - PWM伺服控制⚠️ 锁定版本 ├── Adafruit_SSD1306 - OLED显示驱动 └── Adafruit_GFX Library - 图形库 ESP32 板级支持: └── esp32 by Espressif Systems (v2.0.0)7.2 软件依赖Python: ├── Pillow - 图像缩放 └── tkinter - GUI框架系统自带 外部服务: ├── DNS Server (UDP 53) - Captive Portal ├── mDNS (5353) - 服务发现 └── HTTP (80) - Web/API 服务7.3 硬件依赖组件型号数量单价估算MCULolin S2 Mini / ESP32-DevKitC / Distro Board V21$3-15舵机MG90S 全金属微型舵机8 (2备用)~$2/个显示屏0.96 SSD1306 I2C OLED1~$3电源USB-C PD 5V 3A 或 2x10440 Li-ion1~$103D打印耗材PLA (11个部件)~150g~$5其他电线、开关、螺丝、热缩管等若干~$15总计$50-608. API 接口清单8.1 传统 HTTP APILegacy方法路径参数说明GET/-Captive Portal Web UIGET/cmd?goforward|backward|left|right持续运动GET/cmd?posewave|dance|rest|...单次动作GET/cmd?motor1value90单舵机控制GET/cmd?stop停止运动GET/getSettings-获取配置GET/setSettings?frameDelay100walkCycles10motorCurrentDelay20faceFps8设置参数8.2 JSON REST API推荐GET /api/status{currentCommand:forward,currentFace:walk,networkConnected:true,apIP:192.168.4.1,networkIP:192.168.1.100}POST /api/command// 运动表情{command:wave,face:happy}→{status:ok,message:Command executed}// 纯表情更新无运动{face:excited}→{status:ok,message:Face updated}// 停止{command:stop}→{status:ok,message:Command stopped}8.3 Serial CLI 命令命令简称说明run walkrn wf前进run walk backwardrn wb后退run leftrn tl左转run rightrn tr右转run restrn rs休息run standrn st站立rn wv/dn/sw/pt/pu/bw/ct/fk/wm/sk/sg/dd/cb-各种姿势subtrim [motor] [value]st [m] [v]设置微调subtrim savest save导出微调值all [angle]-所有舵机统一角度[motor] [angle]-单舵机控制9. 数据模型9.1 表情Face数据模型FACE_LIST (X-Macro): ├── walk, rest, swim, dance, wave, point, stand ├── cute, pushup, freaky, bow, worm, shake, shrug ├── dead, crab, defualt, idle, idle_blink ├── happy, sad, angry, surprised, sleepy, love, excited, confused, thinking └── talk_happy, talk_sad, talk_angry, talk_surprised, talk_sleepy, talk_love, talk_excited, talk_confused, talk_thinking每个表情 const unsigned char bitmap[1024](128x64 像素单色位图)动画表情 多帧位图序列最多6帧支持 LOOP/ONCE/BOOMERANG9.2 舵机Servo数据模型ServoName 枚举: ├── R10, R21, L12, L23 (髋关节) └── R44, R35, L36, L47 (膝关节) servoPins[8]: GPIO引脚映射 servoSubtrim[8]: 微调偏移 (-90 ~ 90)9.3 全局状态currentCommand:String// 当前执行的动作currentFaceName:String// 当前表情名称currentFaceFrames:bitmap[]// 当前表情帧数组idleActive:bool// 空闲状态networkConnected:bool// 网络连接状态frameDelay:int// 帧延迟 (ms)walkCycles:int// 步行周期数motorCurrentDelay:int// 舵机电流延迟 (ms)faceFps:int// 表情帧率10. 硬件架构10.1 物理结构Sesame 机器人四足 8自由度: ┌──────────────────────────────────────┐ │ Top Cover (顶盖) │ │ ┌──────────────────────────────┐ │ │ │ SSD1306 OLED (128x64) │ │ │ │ Rocker Power Switch │ │ │ └──────────────────────────────┘ │ │ Internal Frame (内框架) │ │ ┌──┐ ┌──┐ │ │ L1│ │ R1 (髋关节x4) │ │R1 │ │ L2│ │ R2 │ │R2 │ │ ├──┤ ├──┤ │ │ L3│ │ R3 (膝关节x4) │ │R3 │ │ L4│ │ R4 │ │R4 │ │ └──┘ └──┘ │ │ Battery Slot (电池槽) │ │ Bottom Cover (底盖) │ └──────────────────────────────────────┘10.2 三套硬件方案对比特性S2 Mini 手焊Distro Board V2Distro Board V1 (Legacy)MCUESP32-S2ESP32-S3ESP32-WROOM32USB-C PD✅✅❌电池供电✅⚠️ 不稳定✅组装难度中低预组装高成本~$50含Kit~$60状态推荐DIYKit标配已淘汰10.3 3D打印部件清单部件STL文件支撑Internal FrameInternal-Frame-v117.stl无Bottom CoverBottom-Cover-v117.stl无Top Cover (Cat/Enclosed/NoEars)Top-Cover-*.stl有Joint R1/R2/R3/R4R1-R4-v117.stl无Joint L1/L2/L3/L4L1-L4-v117.stl无配件帽子magnetic-*.stl可选11. 迭代优化建议11.1 短期优化立即可做序号优化项描述工作量影响1引入 ArduinoJSON替代手动字符串拼接JSON提升健壮性半日API稳定性2WiFi凭据持久化使用 ESP32 Preferences/NVS 存储SSID/密码半日用户体验3设置持久化将 frameDelay/motorCurrentDelay 等存入NVS半日用户体验4OTA固件升级通过WiFi远程更新固件无需USB1日运维便利性5Sesame Studio 升级从 Tkinter 迁移到 PyQt6 / web 版3-5日跨平台UI11.2 中期架构改进序号改进项描述工作量1FreeRTOS 多任务将运动控制/表情渲染/网络服务分到独立任务3-5日2逆运动学IK实现基于目标位置的腿部IK算法5-10日3传感器驱动层抽象超声波/陀螺仪/IMU传感器接口3-5日4固件测试框架引入单元测试Unity test framework for Arduino2-3日5WebSocket支持添加 WebSocket 端点实现低延迟实时控制2-3日11.3 长期演进方向序号方向描述1AI集成集成 ESP-SR 语音识别模块本地离线语音控制2多机器人协作Mesh网络多机同步舞蹈/编队3云后台云端表情/动作市场社区共享4ROS2支持micro-ROS 集成进入ROS生态5教育课程体系配套STEM课程包、编程教学11.4 可复用价值分析Sesame 项目具有以下可复用组件可提取为独立能力组件复用场景提取方式X-Macro 表情注册系统任何需要管理大量位图资源的嵌入式项目独立模板库Captive Portal HTML 界面ESP32 Web控制面板通用模板双模WiFi(APSTA)框架IoT设备联网独立库非阻塞动画引擎OLED/电机动画控制独立模块JSON API 架构模式机器人/IoT设备远程控制参考模式附录A文件目录完整结构sesame-robot-main/ ├── .gitignore ├── LICENSE (Apache 2.0) ├── README.md │ ├── docs/ │ ├── README.md │ ├── build-guide/ │ │ ├── README.md │ │ └── assets/ (39个建造流程PNG图) │ ├── images/ │ │ ├── README.md │ │ ├── sesame-topdown.png │ │ └── sesamefaces/ (20个表情PNG) │ └── wiring-guide/ │ ├── README.md │ ├── distro-board-wiring-guide.png │ ├── s2-mini-wiring-guide-new.png │ └── assets/ (5个接线流程PNG) │ ├── firmware/ │ ├── README.md (830行 - 完整技术文档) │ ├── sesame-firmware-main.ino (854行 - 主固件) │ ├── face-bitmaps.h (3,158行 - 表情位图) │ ├── movement-sequences.h (429行 - 运动序列) │ ├── captive-portal.h (851行 - Web UI) │ └── debugging-firmware/ │ └── sesame-motor-tester.ino (137行) │ ├── hardware/ │ ├── README.md │ ├── bom/README.md - 物料清单 │ ├── cad/ │ │ ├── README.md │ │ ├── Sesame-v117.f3z (Fusion 360) │ │ └── Sesame-v117.step (通用CAD) │ ├── pcb/ │ │ ├── README.md │ │ ├── pcbs.png │ │ ├── SDB-layout.png │ │ ├── distro-v1/ (V1 Gerber 原理图) │ │ └── distro-v2/ (V2 Gerber BOM PickAndPlace SCH) │ └── printing/ │ ├── README.md │ ├── assets/ (4个打印设置PNG) │ └── stl/ (11个基本部件 3个顶盖 2个配件) │ └── software/ ├── README.md └── sesame-studio/ ├── README.md ├── sesame_studio.py (282行) └── assets/ (4个图标/预览PNG)附录B关键设计亮点X-Macro 表情注册系统通过FACE_LIST宏实现表情的一处注册、多处自动生成引用极大降低添加新表情的维护成本非阻塞 pressingCheck()在动画帧间持续轮询网络请求实现即时中断响应避免传统 delay() 导致的控制延迟WiFi信息智能滚动30秒无人操作后自动显示WiFi连接信息新手友好设计三板支持抽象层仅修改servoPins[]和I2C_定义即可在不同ESP32板型间移植空闲眨眼系统30%概率双眨眼3-7秒随机间隔提升机器人生命力的真实感参见https://www.pcbway.com/project/shareproject/The_Sesame_Robot_Project_3a0ba90f.htmlCodeFirmware Codehttps://github.com/dorianborian/sesame-robot/tree/main/firmwareSchematic and LayoutPCB Schematic Layouthttps://github.com/dorianborian/sesame-robot/tree/main/hardware/pcbCAD-Custom parts and enclosures3D Printing Files CADhttps://github.com/dorianborian/sesame-robot/tree/main/hardware/printing