MindPaw

🐕 MindPaw

桌面级四足机器狗 — 语音交互·手势识别·AI对话·网页控制

v2.0 — 新增流式 3D 重建感知层（端到端 ~150 ms，ABot-Recon 思想）

总物料成本 ≈¥50，全开源

📋 目录

• 这是什么？
• 功能总览
• 你需要准备什么
• 如何复刻
• 项目结构
• AI Infra 网关
• 硬件接线图
• 文档索引
• 分支与版本
• 常见问题
• 维护与贡献
• 许可证

🎯 这是什么

MindPaw 是一个桌面四足机器人项目，基于 ESP8266 微控制器。它的特色是：

• 不只是遥控车 — 你可以和它对话、对它做手势、它会有情绪反应
• 真的能聊 AI — 接入了豆包大模型，能做智能对话
• 真的便宜 — 全部物料加起来不到 ¥50（基础版仅 ¥35）
• 真的开源 — 代码、电路图、3D 打印文件全部提供

这个项目是从零开始自己做的，不是用现成的开发板套件。所以如果你想学习怎么把 ESP8266、舵机、摄像头、语音模块、AI 全部整合在一起，这里的代码和文档应该能帮到你。

🚦 从哪里开始

这个仓库分为两条互不阻塞的路径：

初学者不需要安装 Python、Docker 或 AI Gateway；完成基础 Demo 后，再按兴趣进入研究路径。两条路径共享同一套固件和硬件，Gateway 地址留空即可回到原有直连模式。2.0 感知层默认关闭，在 aiconfig.html 里填一个 Recon Gateway URL 即可启用。

✨ 功能总览

🛒 你需要准备什么

硬件清单

以下价格来自 淘宝/拼多多 真实售价（2026年7月）。量大还能更便宜。

🏆 方案一：完整版（≈¥50，带摄像头手势识别）

🥉 方案二：基础版（≈¥35）

去掉摄像头，保留语音控制 + AI 对话 + 情感交互。适合先入门、再升级。

💡 注：¥35-¥50 是 物料裸价，不含邮费（约 ¥8）。首次购买建议一次买齐所有器件，邮费只付一次。

软件准备

需要申请的免费账号

以上两个 API 都是可选功能。不配置的话，机器狗的基本运动、表情、语音控制仍能正常工作。

🚀 如何复刻

从零开始做一台 MindPaw，按这个顺序走。

⭐ 开始前，请先支持一下这个开源项目：

1. Star ⭐ — 点击仓库右上角 ⭐ Star，收藏本项目，方便以后找到
2. Fork 🍴 — 点击 Fork，把项目复制到你自己的 GitHub，之后可自由修改并提交 PR
3. Download 📥 — 点击绿色 Code 按钮 → Download ZIP，或直接 clone：

📸 操作示意图：

git clone https://github.com/ace-trump-tech/MindPaw.git

第一步：烧录固件（先让代码跑起来）

先只买 NodeMCU + USB-TTL，花 30 分钟验证环境：

# 1. 安装 VSCode + PlatformIO 扩展
# 2. 克隆项目并打开
git clone https://github.com/你的用户名/MindPaw.git
cd MindPaw/MindPaw_main

# 3. 编译
pio run

# 4. 连接 NodeMCU（GPIO0 接地 → 上电）
# 5. 烧录固件
pio run -t upload

# 6. 上传 Web 页面
pio run -t uploadfs

# 7. 断开 GPIO0 接地 → 按 RST
# 8. 连接 WiFi "MindPaw" → 打开 192.168.4.1

详细步骤 → Docs/04_Firmware_Flashing.md

第二步：打样 PCB 和 3D 打印（做硬件）

如果你有嘉立创的免费打样券，这一步可以不花钱：

第三步：焊接和组装

收到 PCB 和 3D 打印件后：

1. 先焊接电源部分 — 测试 3.3V 和 5V 输出正常
2. 焊接 ESP12F 核心 — 烧录固件验证
3. 逐个添加模块 — OLED → 舵机 → 语音 → 摄像头 → 扬声器
4. 3D 打印件组装 — 舵机装入底盘 → 合上身体 → 安装脚部

接线图 → 05_Assembly_Guide.md

第四步：配置 API（可选）

如果你想要 AI 对话和天气查询功能：

图文步骤 → Docs/07_API_Guide.md

第四步（可选）：启动 AI Infra 网关

ai-infra 是可选的独立 AI 基础设施层。它负责上游模型适配、鉴权、超时和结构化输出校验，适合希望研究 Agent、模型接入和边缘设备协同的开发者。初学者可以跳过这一节，直接使用原有的 ESP8266 直连豆包模式，不会影响机器狗的基础功能和 AI 对话。

cd ai-infra
cp .env.example .env
# 编辑 .env，配置 GATEWAY_TOKEN、AI_PROVIDER 和上游 API Key
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn gateway.app:app --host 0.0.0.0 --port 8000

没有云端 Key 时，可以将 .env 中的 AI_PROVIDER 设为 mock，先验证设备链路。然后打开 http://192.168.4.1/aiconfig.html：

• API Key：填写 GATEWAY_TOKEN
• 推理端点 ID：填写 mindpaw
• AI Gateway 地址：填写 http://网关IP:8000/v1/chat/completions

Docker 用户可以运行 cd ai-infra && docker compose up --build -d。完整说明见 ai-infra/README.md。

两种使用路径

这两条路径共享同一套固件和网页功能，可以随时从直连模式切换到 Gateway 模式。

为什么先放在同一个仓库？

当前阶段保持 monorepo 的好处是：初学者只需下载一个仓库即可复现，研究者也能在同一个仓库中阅读固件、协议和 Gateway。等接口稳定、网关需要服务其他机器人后，再把 ai-infra 独立成可插拔仓库或 Python 包，并保留本仓库的版本化配置示例。

第五步：配置语音模块

HLK-V20 需要用电脑配置好之后才能用：

1. 下载 SU-03T 配置工具
2. 通过 USB-TTL 连接模块
3. 按表格添加 22 条语音命令
4. 烧录 → 断电 → 接到 MindPaw

详细命令表 → Docs/07_API_Guide.md#3-hlk-v20-语音模块配置

📁 项目结构

MindPaw/
│
├── 3Dmodel/                    ← 3D 打印件（body.stl / bottom.stl / foot.stl）
│
├── SCH&PCB/                    ← 电路设计文件（立创 EDA 专业版）
│   ├── MindPaw_SCH&PCB.epro2
│   └── README.md                ← 硬件复现、打样和排障入口
│
├── MindPaw_main/               ← 固件源代码（初学者 Demo 入口）
│   ├── README.md                ← 编译、烧录、验收和故障排查
│   ├── src/                    ← C++ 源码
│   │   ├── main.cpp            ← 主程序（入口、Web服务器、舵机动作）
│   │   ├── image.cpp           ← OLED 屏幕显示的位图数据
│   │   ├── hlkv20.*            ← HLK-V20 语音识别模块驱动
│   │   ├── ov2640.*            ← OV2640 摄像头驱动
│   │   ├── speaker.*           ← 扬声器旋律播放
│   │   ├── motion_emotion.*    ← 机器狗的情感动作（跳舞、点头等）
│   │   ├── emotion_engine.*    ← 情感状态机（PAD 模型）
│   │   ├── gesture_nn.*        ← 手势识别（轻量 MLP）
│   │   ├── multimodal_fusion.* ← 多模态输入融合
│   │   ├── doubao_agent.*      ← 豆包 AI API 客户端
│   │   └── doubao_config.h     ← AI 提示词和配置
│   ├── data/                   ← 网页控制界面（11 个 HTML 文件）
│   ├── tools/                  ← Python 工具脚本
│   │   └── distill_gesture.py  ← 手势模型训练脚本
│   ├── platformio.ini          ← 编译配置文件
│   └── PIN_WIRING.md           ← 引脚接线图
│
├── ai-infra/                   ← 独立 AI Gateway（可选，研究者教程）
│   ├── gateway/app.py          ← OpenAI 兼容入口、鉴权和上游适配
│   ├── tests/                  ← Gateway 契约单元测试
│   ├── .env.example            ← 网关配置模板
│   ├── Dockerfile              ← 容器部署
│   └── README.md               ← 研究问题、实验路线和网关启动说明
│
├── Picture/                    ← 图片资源
│   ├── MindPaw_oled/           ← 表情源文件（BMP）
│   └── PCtoLCD2002/            ← 图片转像素图工具
│
├── Docs/                       ← 文档
│   ├── 01_Hardware_Guide.md    ← 硬件设计导入指南
│   ├── 02_PCB_Fabrication.md   ← PCB 免费打样指南
│   ├── 03_Image_Conversion.md  ← OLED 表情制作指南
│   ├── 04_Firmware_Flashing.md ← 固件烧录指南
│   ├── 05_Assembly_Guide.md    ← 结构组装与接线指南
│   ├── 06_Quick_Start.md       ← 5 分钟快速上手
│   └── 07_API_Guide.md         ← API 密钥获取指南
│
├── hardware-manifest.json      ← 硬件、固件和复现路径清单
├── scripts/validate_project.py ← 自动校验清单和敏感配置
│
└── README.md                   ← 就是这个文件

🔌 硬件接线图

快速接线表

⚠ 最重要的两条规则：

1. GPIO15 必须接 10KΩ 下拉电阻到 GND — 否则 ESP8266 无法启动
2. OV2640 的 SCK/MISO/MOSI 与舵机共享时串联 1KΩ — 防止信号冲突

完整接线图 → Docs/05_Assembly_Guide.md

📚 文档索引

🌿 分支与版本

仓库当前有两条远程分支，分别承担不同角色：

推荐的 main 保护规则

GitHub 网页会提示 "Your main branch isn't protected"。建议在 Settings → Branches → Add rule 加：

• ✅ Require a pull request before merging
• ✅ Require status checks to pass before merging（至少勾上 docs-and-manifest + gateway-tests + recon-tests 三个 job）
• ✅ Do not allow force pushes
• ✅ Do not allow deletions
• ✅ Require linear history（可选；如果想保留 --no-ff merge commit 就不要勾这个）

清理已合并的 feature 分支

git push origin --delete feature/2.0-streaming-recon
git branch -d feature/2.0-streaming-recon       # 本地

发布历史

详细 changelog 见 RELEASE_NOTES.md。

❓ 常见问题

我不会编程，能做出这个吗？

如果你没有嵌入式开发经验，建议至少先了解 Arduino 的基本用法（点亮 LED、串口输出）。然后跟着文档一步步来，遇到问题可以在 GitHub 提 Issue。

一定要用嘉立创打样 PCB 吗？

不是。你也可以用**洞洞板（万用板）**手焊。PCB 文件只是更方便、更可靠。第一次做建议用手焊，成功后再打样。

一定要 3D 打印外壳吗？

不是。你也可以用纸板、亚克力、积木搭一个身体。3D 模型只是我设计的参考外形。

可以用 ESP32 代替吗？

当然，而且推荐。 ESP32 引脚更多、内存更大、还有蓝牙。迁移方法：

1. platformio.ini 中改 board = nodemcu-32s
2. 引脚分配按 ESP32 重新调整
3. 大部分代码无需修改

语音模块一定要用 HLK-V20 吗？

如果你已经有 LD3320，也可以接（需要 5 个 SPI 引脚）。但 HLK-V20 只需要 1 个引脚，识别率更高，推荐用它。

为什么 GPIO15 要下拉到 GND？

这是 ESP8266 的硬件要求：GPIO15 在启动时如果为 HIGH，芯片会进入测试模式导致无法正常工作。10KΩ 电阻下拉确保启动时是 LOW。

🧰 维护与贡献

MindPaw 同时包含固件、真实硬件、3D 模型和可选 AI Gateway。为了让贡献可以复现，提交前请先阅读：

• 贡献指南：变更范围、证据和人工验证要求
• 支持与排障：按固件、接线、PCB、Gateway 分流问题
• 安全策略：物理执行器、API 密钥和漏洞报告
• 硬件清单：固件、接线、原理图和模型的权威路径

Issue 不能只是一段无法验证的 AI 生成文本；作者必须亲自复现、提供日志或测量结果，并能回答维护者追问。AI 可以辅助检索、翻译和排版，但不能替代硬件安全审查和实验验证。

仓库的 Quality、Firmware build 和 Link check 工作流会自动检查项目清单、Gateway 契约、固件编译和文档链接。涉及舵机、供电、引脚或动作协议的改动必须附上断电措施和兼容性说明。

📜 许可证

• 软件代码（MindPaw_main/src/）：MIT License
• 硬件设计（SCH&PCB/）：CC BY-NC 4.0
• 3D 模型（3Dmodel/）：CC BY-NC 4.0
• 文档（Docs/ 和 README.md）：CC BY 4.0

简单说：代码随便用，硬件和 3D 模型可以个人使用、修改，但不要商用。

Made with ❤️ and a lot of coffee

如果你也做了这个项目，欢迎在 GitHub 上 @ 我！