多拉丁 Duolading · 设计书

0 · 文档信息

1 · 项目定位

1.1 一句话

做一台能看、能听、能说、能走、能上台面的桌面伙伴，而不是一台实验板。

1.2 与巴拉丁的关系

1.3 四条设计原则（不可妥协）

2 · 需求与范围

2.1 用户故事

• 我按下它头上的说话键，说「往前一点」，它看着我、答一句话，然后真的向前走 20 厘米。
• 我把它放在桌上，它待机时会左右张望、眨眼、打盹；我在键盘上敲字，它脸上的表情变。
• 它往前走遇到桌沿或障碍会自己停，不会掉下去。
• 换电池或者插充电宝都能用，不能因为切电源把它重启了。

2.2 MVP 范围（第一版必须有）

2.3 明确的非目标（这一版不做）

• 不做双足 / 平衡机器人——microduck 类形态是具身智能课题，不是本项目目标。
• 不做本地大模型推理——Pi 3B 没有 NPU、只有 1GB 内存，本地 LLM 不可行。
• 不做机械臂 / 抓取。
• 不做语音唤醒词——第一版一律按键触发（push-to-talk），唤醒词留到第二版。
• 不把机器人暴露到公网——只在局域网内通信。

3 · 系统架构

3.1 三层架构

┌──────────────────────────────┐        ┌───────────────────────────────┐
│   身体 · 多拉丁（Pi 3B）      │        │   算力坞 · PC（Windows）       │
│                              │ 局域网 │                               │
│   · 屏幕（脸）                │WebSocket│  · Whisper（语音转文字）      │
│   · 麦克风 / 按键（耳与嘴）    │◄──────►│  · DSH / LLM（决策与人格）     │
│   · 摄像头（眼）              │  JSON  │  · edge-tts（文字转语音）      │
│   · 电机 + 轮子（腿）         │        │  · 行为策略 / 记忆            │
│   · 超声波 / IMU（触觉）      │        │  · 网页式遥操作台              │
│                              │        │                               │
│   只做「执行 + 感知」         │        │   只做「思考 + 说话」          │
└──────────────────────────────┘        └───────────────────────────────┘
          可选上行：云端 API（仅当 PC 不在线时的降级方案）

3.2 数据流

3.3 分层边界（谁能碰 GPIO）

• 只有 Pi 上的 body 服务碰 GPIO / SPI / ALSA。
• PC 上的任何代码（含 DSH）只能调 body 的 API，不许 SSH 进去直接点灯。
• 这条边界保证：换板子（3B → Pi 5 → Jetson）时，上层一行不改。

4 · 硬件设计

4.1 树莓派 3B 能力边界（先认清手里的牌）

4.2 采购清单（第一批 · 目标 ≤ ¥200）

假设已有：树莓派 3B、TF 卡、充电宝；3D 打印机（结构件自打印）。价格为大致的电商估算，需以实际下单为准。

不含摄像头（阶段 0 先用旧件）、音箱（用旧耳机）、电池（先用充电宝）。这几项进第二批。

第二批（后续再加）

4.3 供电架构

阶段 A（MVP）：充电宝供电

充电宝 5V/2A+ ──┬──► Pi 3B（USB 口，或焊到板上的 5V 端子）
                │
                └──► TB6612 VM（电机低速可用 5V，扭矩偏小）

结论：零成本、能跑通，先用它把软件闭环做完。

阶段 B（扩展）：2S 电池 + 双路自动切换

        ┌── 充电宝 5V ───────────────┐
        │                            ▼
        │                     [理想二极管 OR] ──► 5V 轨 ──► Pi 3B
2S 18650 ──► DC-DC 5V/3A ────────────┘          │
  (7.4V)  │                                    └── 1000µF 电容（抗瞬时掉压）
          └──► TB6612 VM（7.4V 直供，扭矩充足）──► 电机

充电：2S 保护板 + 8.4V 充电器，或直接买带 BMS 的成品电池组。

4.4 引脚分配表（定版，禁止随意改动）

本表是焊接与 PCB 布线的唯一依据。改动前必须先改本表，再改板子。

4.5 屏幕子系统（STM32 那种 SPI 屏怎么接到 Pi 上）

选型

驱动路线

路线 B：不占 GPIO 的替代（零成本）

用旧手机 / 旧平板当脸：Pi 起一个本地网页服务，手机浏览器全屏打开就是机器人的表情屏。优点是不占一根 GPIO、分辨率高、还能顺手放视频；缺点是多了个设备和一根充电线。建议：阶段 0 先用路线 B 把 AI 闭环跑通，屏幕到货再切路线 A。

4.6 焊接与装配工艺（三条路线）

焊接规范

• 烙铁 320–350℃，0.8mm 锡丝配助焊剂。
• 模块先焊电源脚和大电容 / 端子台，再焊信号线，避免返工时烫坏模块。
• 所有对外线（电机、电源、传感器）进 KF301 螺钉端子，可拆可换，不直接焊死在板上。
• 线束用热缩管 + 扎带固定；电机线双绞，减少对信号的干扰。
• 焊完先用万用表蜂鸣档逐个量：5V 对 GND 不能短路，确认后再上电。

4.7 机械结构与 3D 打印件

• 材料：PLA+ 或 PETG；底盘受力件建议 PETG 或加厚壁。
• 预留 M3 热熔铜螺母孔（孔径约 4.0–4.2mm），方便反复拆装。
• 先买电机再建模，孔位以实物为准；打印公差按 0.2mm 放。
• 建模由 AI 用参数化脚本（OpenSCAD）生成，轩轩复核尺寸后打印。

5 · 软件设计

5.1 身体 API 契约（唯一对外接口）

Pi 上跑一个 body 服务，对外只暴露下面这些能力。上层（DSH、行为脚本、遥操作台）只能调它们。

事件（身体主动上报）

5.2 进程与目录

/opt/duolading/
├── body/                 身体服务（Pi，唯一碰 GPIO 的地方）
│   ├── server.py         WebSocket / HTTP 服务
│   ├── hardware/         gpio.py  motor.py  sonar.py  keys.py  lcd.py
│   ├── audio/            rec.py  play.py
│   └── config.yaml       引脚表、标定值
├── face/                 表情渲染（画到帧缓冲，或提供给网页）
└── recordings/           录音落盘（可选保留最近 N 条）

systemd 单元：
  duolading-body.service     开机自启，崩溃自动重启
  duolading-fbcp.service     屏幕镜像（用路线 A 时）

5.3 语音链路（一次对话的完整时序）

  轩轩            多拉丁(Pi)                          算力坞(PC)
   │                 │                                   │
   │  按下说话键      │                                   │
   ├────────────────►│  KEY_TALK down                    │
   │  说一句话        │  arecord 16kHz 单声道 开录         │
   │                 │  face = listen（屏幕竖耳）          │
   │  松开           │                                   │
   ├────────────────►│  停录 → out.wav                    │
   │                 │──── 上传音频 + listen_stop ───────►│
   │                 │                                   │ faster-whisper 识别
   │                 │                                   │ → "往前一点"
   │                 │                                   │ DSH / LLM 决策
   │                 │                                   │ → 回复 + 动作意图
   │                 │◄─── move(speed=0.5,dur=800) ───────│
   │                 │◄─── face(think) / speak(text) ─────│
   │                 │  edge-tts 生成 mp3 并回传           │
   │   听到回答       │  aplay 播放                        │
   │   它往前走       │  电机转动                          │
   │◄────────────────│                                   │
   │                 │──── sonar 10Hz 持续上报 ──────────►│
   │                 │◄─── stop（前方 20cm 有障碍）────────│

5.4 行为状态机

        ┌─────────┐  上电   ┌────────┐
        │  BOOT   ├────────►│  IDLE  │◄───────────────┐
        └─────────┘         └───┬────┘                │
                    按键         │      超时 60s       │
              ┌─────────────────┼──────────────┐      │
              ▼                 ▼              ▼      │
        ┌──────────┐      ┌──────────┐   ┌────────┐   │
        │LISTENING │      │  MOVING  │   │ SLEEP  ├───┘
        └────┬─────┘      └────┬─────┘   └────────┘
             │ 录音结束         │ 障碍 <20cm
             ▼                 ▼
        ┌──────────┐      ┌──────────┐
        │ THINKING │      │  AVOID   │
        └────┬─────┘      └────┬─────┘
             │ 收到回复         │ 障碍解除
             ▼                 └──────► IDLE
        ┌──────────┐
        │ SPEAKING │──── 说完 ────► IDLE
        └──────────┘

5.5 显示子系统

两条路线的表情资源与状态机是同一份：定义一组表情矢量（眼睛形状、瞳孔位置、嘴型、颜色），只换渲染层。

表情清单（v0.1）

idle 待机 · blink 眨眼 · listen 竖耳 · think 思考 · speak 说话 · happy 高兴 · alert 惊讶 · sleep 打盹 · lowbat 低电量 · error 出错

5.6 通信协议（WebSocket + JSON）

// 大脑 → 身体
{"type":"cmd","id":12,"action":"move","params":{"speed":0.5,"duration_ms":800}}
{"type":"cmd","id":13,"action":"face","params":{"emotion":"listen"}}
{"type":"cmd","id":14,"action":"speak","params":{"text":"好，我往前走一点"}}

// 身体 → 大脑
{"type":"ack","id":12,"ok":true,"took_ms":3}
{"type":"evt","name":"button","data":{"key":"talk","edge":"down"}}
{"type":"evt","name":"sonar","data":{"cm":42.3,"ts":1730000000}}
{"type":"evt","name":"heartbeat","data":{"uptime_s":812,"cpu_temp":54.2}}

// 出错
{"type":"ack","id":12,"ok":false,"error":"motor_busy"}

• 所有指令带 id，必须有 ack；超时 1s 未 ack 视为失败。
• 安全优先级：stop 与避障永远高于其它指令，可打断正在执行的动作。
• 断线重连：身体每 2s 发心跳，大脑 6s 收不到就认为掉线并降级（屏幕显示「失联」表情）。

5.7 安全与运维

• 不暴露公网：body 服务只监听局域网地址，禁止端口映射到 VPS。
• 握手令牌：WebSocket 连接需携带 token（写在 Pi 的配置文件里，不进任何仓库）。
• 看门狗：body 服务崩溃由 systemd 自动拉起；电机有独立的软超时（单次动作最长 10s，到点强制停）。
• 急停：复位键长按 3 秒 = 断电级急停（拉低 STBY）。

6 · 路线图与验收

四个阶段，每阶段都必须能当场看到结果。验收按三档证据走：自动检查 → 真实运行 → 轩轩手测；只有第三档通过才算交付。

6.1 里程碑登记约定

每阶段完成时在本设计书对应位置与项目 PROGRESS.md 上各记一条；里程碑只有四种状态：未开始 / 进行中 / 待轩轩验收 / 已完成，「已完成」只能由轩轩验收后改写。

7 · 风险与对策

8 · 参考项目

9 · 附录

附录 A · 40 针速查

脚 1  3V3           脚 2  5V
脚 3  GPIO2  SDA    脚 4  5V
脚 5  GPIO3  SCL    脚 6  GND
脚 7  GPIO4  TALK   脚 8  GPIO14 TXD
脚 9  GND           脚 10 GPIO15 RXD
脚 11 GPIO17 MODE   脚 12 GPIO18 LCD_BL
脚 13 GPIO27 RESET  脚 14 GND
脚 15 GPIO22 (空)   脚 16 GPIO23 SONAR_TRIG
脚 17 3V3           脚 18 GPIO24 LCD_RST
脚 19 GPIO10 MOSI   脚 20 GND
脚 21 GPIO9  MISO   脚 22 GPIO25 LCD_DC
脚 23 GPIO11 SCLK   脚 24 GPIO8  LCD_CS
脚 25 GND           脚 26 GPIO7  TOUCH_CS
脚 27 GPIO0         脚 28 GPIO1
脚 29 GPIO5  AIN1   脚 30 GND
脚 31 GPIO6  AIN2   脚 32 GPIO12 PWMA
脚 33 GPIO13 PWMB   脚 34 GND
脚 35 GPIO19 T_IRQ  脚 36 GPIO16 BIN1
脚 37 GPIO26 BIN2   脚 38 GPIO20 STBY
脚 39 GND           脚 40 GPIO21 SONAR_ECHO

附录 B · 命令速查

# 开 SPI
sudo raspi-config nonint do_spi 0

# 硬件 PWM（避开 GPIO18 / 19，见 4.4 说明）
# /boot/firmware/config.txt 里加：
dtoverlay=pwm-2chan,pin=12,func=4,pin2=13,func2=4

# 列录音设备 / 录一段
arecord -l
arecord -D plughw:1,0 -f S16_LE -r 16000 -c 1 -d 5 test.wav

# 播放
aplay -D plughw:0,0 test.wav

# 读一个按键（gpiozero）
python3 -c "from gpiozero import Button; b=Button(4,pull_up=True); b.wait_for_press(); print('talk pressed')"

# CPU 温度与内存
vcgencmd measure_temp; free -h

# 屏幕镜像（路线 A，编译后）
git clone https://github.com/juj/fbcp-ili9341 && cd fbcp-ili9341
cmake -DSPI_BUS_CLOCK_DIVISOR=6 -DILI9341=ON .. && make -j
sudo ./fbcp-ili9341

附录 C · 采购备忘

• 马达轮子注意是「双轴」还是「单轴」，双轴更好焊。
• 替代件：HC-SR04 → VL53L0X（贵一点但 3.3V 原生、更准、不用分压）；TB6612 → DRV8833（更小）或 L298N（便宜但发热大）。
• 省法：旧手机当屏、旧耳机当喇叭、旧 USB 摄像头当眼、旧充电宝当电源，可再省 ¥70。
• 打样：HAT 尺寸按 65×56.5mm、四个 M2.5 孔与树莓派对齐，第二版才打。

附录 D · 术语

10 · 待定决策（需轩轩拍板）