跟着 Sesame Robot 项目学习

Sesame Robot 项目深度分析报告

项目名称: Sesame Robot
作者: Dorian Todd（starphee）
开源协议: Apache License 2.0
仓库地址: https://github.com/dorianborian/sesame-robot

目录

1. 项目概述
2. 业务模型分析
3. 需求清单
4. 系统架构设计
5. 代码规模统计
6. 技术栈评估
7. 组件依赖分析
8. API 接口清单
9. 数据模型
10. 硬件架构
11. 迭代优化建议

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 价值主张

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 收入渠道推断

1. Sesame Build Kit销售（含预烧录 Distro Board V2）
2. PCBway 赞助合作（PCB制造）
3. YouTube 内容变现（教程视频）
4. 社区捐赠 / 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 App）

3. 需求清单

3.1 功能需求（Functional Requirements）

3.2 非功能需求（Non-Functional Requirements）

3.3 待实现需求（Backlog/Roadmap）

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 UI（HTML+CSS+JS） │ └── 深色主题 + 橙色调 │ └── debugging-firmware/ └── sesame-motor-tester.ino (137行) └── 独立电机测试工具（Serial CLI）

4.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_SCL35

5. 代码规模统计

5.1 概览

5.2 源代码行数明细

总计:~5,711 行源代码（含位图数据3,158行，实际逻辑代码 ~2,553 行）

5.3 文档行数明细

文档总计:~1,786 行

5.4 规模评估

6. 技术栈评估

6.1 技术选型

6.2 技术债务

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 硬件依赖

8. API 接口清单

8.1 传统 HTTP API（Legacy）

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 命令

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/BOOMERANG

9.2 舵机（Servo）数据模型

ServoName 枚举: ├── R1=0, R2=1, L1=2, L2=3 (髋关节) └── R4=4, R3=5, L3=6, L4=7 (膝关节) 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 三套硬件方案对比

10.3 3D打印部件清单

11. 迭代优化建议

11.1 短期优化（立即可做）

11.2 中期架构改进

11.3 长期演进方向

11.4 可复用价值分析

Sesame 项目具有以下可复用组件，可提取为独立能力：

附录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：关键设计亮点

1. X-Macro 表情注册系统：通过FACE_LIST宏实现表情的一处注册、多处自动生成引用，极大降低添加新表情的维护成本
2. 非阻塞 pressingCheck()：在动画帧间持续轮询网络请求，实现即时中断响应，避免传统 delay() 导致的控制延迟
3. WiFi信息智能滚动：30秒无人操作后自动显示WiFi连接信息，新手友好设计
4. 三板支持抽象层：仅修改servoPins[]和I2C_定义即可在不同ESP32板型间移植
5. 空闲眨眼系统：30%概率双眨眼，3-7秒随机间隔，提升机器人"生命力"的真实感

参见：
https://www.pcbway.com/project/shareproject/The_Sesame_Robot_Project_3a0ba90f.html

Code
Firmware & Code
https://github.com/dorianborian/sesame-robot/tree/main/firmware

Schematic and Layout
PCB Schematic & Layout
https://github.com/dorianborian/sesame-robot/tree/main/hardware/pcb

CAD-Custom parts and enclosures
3D Printing Files & CAD
https://github.com/dorianborian/sesame-robot/tree/main/hardware/printing