Peeqo GIF 桌面陪伴机器人 复刻全流程
Peeqo GIF 桌面陪伴机器人 从采购、打印、组装到装软件、标定和训练的 111 个步骤,附物料表、购买链接与官方出处。
开发套件已售罄(peeqo.com,2026‑11‑01,只有候补名单),无现价;仓库与 wiki 未给物料清单或总价
采购
- 加入 Peeqo 开发套件等候名单
打开等候名单页面,输入邮箱,加入 Peeqo 开发套件等候名单。
组装
- 按照维基百科装配 Peeqo
打开 Assembly 维基页面,按照其中的完整装配说明进行组装。
- 定位颈部舵机
将舵机轴定位在中心外 27.32 mm、向上 42 mm 处。每个舵机安装带轮毂的 U 形角。
- 固定颈部腿杆
将每条腿固定在距其舵机轴 7 mm 处。每条腿由两条臂组成。
- 定位颈部杆端
将杆端定位在中心外 34.32 mm、向上 100.1 mm 处。每个眼环可在螺钉上自由转动,最大倾斜 18°,达到 23.7° 时会接触凸耳。
- 确认舵机通道与 LED 位置
确认哪个 PCA9685 通道驱动哪个舵机,并确定 LED 0 的位置。
软件与固件
- 安装工作区依赖
在项目根目录运行一次 npm install。
- 设置唤醒词环境
使用 Python 3.10 或更高版本,为 @peeqo/wakeword 工作区运行一次设置命令。
- 检查代码与构建
运行类型检查、单元测试和生产构建。
- 部署机器人软件到树莓派
Flash Raspberry Pi OS Lite 64-bit with SSH enabled, then run `npm run deploy -w @peeqo/robot` from a laptop. The installer sets up everything else.
- 通过手机设置 Wi-Fi
使用手机设置 Wi-Fi。当 Peeqo 不知道任何 Wi-Fi 网络时,会显示其设置网络的二维码。
- 设置 Wi-Fi 网络
如果 Peeqo 不知道任何 Wi-Fi 网络,它会启动自己的网络“Peeqo-Setup-XXXX”,并在脸上显示二维码。
- 用手机或电脑连接设置网络
手机:用相机扫描二维码,手机会加入网络并打开设置页面。电脑:加入屏幕上显示的网络,然后打开 `http://10.42.0.1`。
- 在设置页面配置 Wi-Fi
在页面上选择你的 Wi-Fi,设置面板 PIN,并可选填写 API 密钥。Peeqo 会加入你的网络并显示其地址。
- 重新打开 Wi-Fi 设置
如果密码错误,设置网络会再次出现,页面和 Peeqo 的脸都会说明原因。按住按钮 10 秒可以再次执行此操作,例如搬家后。
- 创建自定义命令
打开 creating-a-custom-command 教程,即使没有 Peeqo,也可以按照教程创建自己的命令。
- 安装模拟器依赖
在仓库根目录运行一次 npm install。安装模拟器的包依赖后再启动它。
- 配置在线大脑
在线大脑通过 OpenRouter 工作,默认模型为 `google/gemini-3.8-flash`,支持音频和工具。
- 填写环境变量并启动
在仓库的 `.env` 中设置 `OPENROUTER_API_KEY`,需要 GIF 时再设置 `KLIPY_API`;该文件会被 Git 忽略。然后运行模拟器。
- 录制并发送语音
你的语音会作为录音直接发送给模型,不经过转录步骤。模型写下听到的内容,并在对话记录中显示。
- 安装唤醒词模型
唤醒词功能需要 Python 3.10 或更高版本。只需运行一次工作区安装命令,模型位于 `packages/wakeword`。
- 保存最近对话
将最近 12 到 16 轮交流保存在 `conversation.json` 中,使页面重新加载后仍可继续;清除聊天会重新开始,但会保留记忆。
- 管理对话记忆
旧交流每次淘汰四轮,并先让模型保存其中持久的信息;两次交流相隔超过半小时时,告诉 Peeqo 经过的时间。
- 仅在本地保存事实
每条消息都通过 OpenRouter 将事实发送给模型,但事实只存储在本机;没有开发服务器时,事实保存在浏览器中。
- 配置 GIF 搜索缓存
在磁盘上缓存 GIF 搜索结果,并将每小时预算设为 90,使用量低于密钥的 100 次上限。
- 通过开发服务器提供媒体
通过开发服务器提供媒体,让机器人的面部能够绘制该媒体。
- 在机器人上连接模型
让机器人上的同一个 `Brain` 使用自身 `.env` 中的密钥,直接调用 OpenRouter 和 Klipy。
- 启用机器人唤醒词
让同一个唤醒词检测器监听机器人的麦克风。
- 设置 Peeqo 角色
在 `packages/character` 中实现 `Character`,通过它驱动头部、面部、灯环和声音。
- 实现角色状态
实现 idle、listening、thinking、speaking 和 sleeping 状态;每个状态设置静止面部、视线、LED 灯环和头部活跃程度,并在进入时做小幅问候动作。
- 实现角色表情
实现 23 种表情:happy、excited、laugh、love、sad、grumpy、surprised、scared、sleepy、curious、confused、thinking、yes、no、hello、bye、shy、wink、celebrate、alert、oops、sigh、wonder。
- 同步头部眼睛灯环声音
每个表情由若干定时步骤组成,同时移动头部、眼睛、灯环和声音;表情结束后,恢复当前状态原有的各项设置。
- 实现空闲生活行为
空闲时让 Peeqo 偶尔自行进行好奇注视或小幅 wonder,独自停留过久时先叹气再打哈欠;五分钟没有交互后入睡,任何涉及它的活动都会让它突然醒来。
- 保护活跃对话状态
确保空闲生活行为不会打断 listening、thinking 或 speaking 状态。
- 合成角色声音
在普通 TypeScript 文件 `sounds.ts` 中合成短促的 chirps、coos 和 bloops;模拟器通过 Web Audio 播放,机器人播放相同样本。
- 接入头部动画驱动器
在 packages/core 中使用 HeadAnimator,把手势转换为供 governor 使用的平滑目标;动画以每秒100次的频率更新,同一代码将驱动机器人。
- 定义十六种头部手势
在 headAnimations.ts 中定义 nod、shake、tilt、look-up、look-down、droop、perk-up、bounce、wiggle、think、listen、doze、sigh、startle、groove 和 hello。每个手势使用关键帧和曲线连接所有转折,使其平滑缓动且不越过关键点;大幅动作前的反向小动作用于预判。
- 加入弹簧跟随效果
让所有动作经过略微欠阻尼的弹簧,使动作带有少量重量感并自然停止。每次播放的手势会有几个百分点的变化,因此完全相同的动作不会重复出现。
- 构建生命感活动层
加入呼吸、缓慢游移、偶尔的一瞥和好奇侧倾。能量级别范围为0–1,用于控制活动层的大小和速度;手势出现时会缩小,也可以将其关闭。
- 实现十六种面部情绪
在 packages/face 的 ExpressiveFace 中实现 neutral、happy、excited、love、sad、angry、surprised、scared、sleepy、curious、confused、thinking、listening、shy、wink 和 skeptical,保持 Peeqo 2019 年外观中位于同一位置的黑眼白底设计。
- 塑造眼睛并混合情绪
通过眼睛尺寸、睁开程度、弯曲且倾斜的上眼睑、微笑状下眼睑和眼神光来塑造每只眼睛;love 表情使用跳动的心形。使用弹簧在情绪之间混合,使变化先突出再稳定。
- 添加自动面部活动
加入变化丰富的眨眼,有时连续眨眼两次,并常在大幅转视时发生;加入眼球跳动及其间的微跳动。视线会跟随当前情绪,也可以指定它看向的位置。
标定与测试
- 准备并开始校准
校准只需从面板进行一次。取下布罩,让三个舵机臂可见。整个过程大约需要 10 分钟。
- 识别每个舵机臂及方向
对于舵机板上的每个插头,点击 ▲,直到看到某个臂移动,然后说明它是哪个臂以及向上还是向下移动。每次点击约 1°,由于臂较短,需要点击几次才能看到移动。
- 调平每个舵机臂
微调每个臂,直到它指向水平。单独一个臂只能移动一点,因为这些臂通过头部连接,一个臂倾斜会使整体倾斜。
- 测量整体运动范围
整个头部上下移动,同时保持水平。每个 ▲/▼ 都会让三个臂一起移动 0.5°。
- 标记最低位置
向下移动,直到某个部分快要接触,然后标记该位置。
- 标记最高位置
向上移动,直到达到应有高度但尚未卡住,然后标记该位置。必须为 Peeqo 的正常高度留出空间。
- 用水平仪校准水平
Peeqo 回到正常高度,臂保持水平(1500 µs)。把手机平放在它头上,打开水平应用,点击直到读数为 0°;此步骤可选。
- 检查并修正刻度
让 Peeqo 后仰 3°。输入水平仪显示的读数,用来修正刻度;此步骤可选。
- 确认舵机行程限制
校准本身没有额外的限制,只有舵机的行程范围 500–2500 µs。每次动作都是你要求的缓慢小步,因此要在任何接触前停止。它从 1500 µs 开始,这与 2019 年软件始终留下的舵机位置相同。
- 配置麦克风和扬声器
使用板载 WM8960 声音芯片;首次安装后启用 `dtoverlay=wm8960-soundcard` 并重启机器人。安装器通过 `/etc/asound.conf` 以 48 kHz 共享模式同时播放和录音,并用 `system/sound-levels.sh` 设置一次电平。
- 使用 HDMI CEC 遥控器
显示屏没有鼠标指针,可通过 HDMI 端口的 CEC 遥控器代替。`system/hdmi-cec.rules` 中的 udev 规则使 libinput 忽略该遥控器。
- 检查屏幕分辨率与旋转
在真实机器人上检查屏幕分辨率和旋转。
- 试听扬声器与麦克风
用耳朵检查扬声器和麦克风电平,以及唤醒词。
- 确认环上的 LED 0 位置
确认 LED 0 在环上的位置。
- 用真实手机测试配网与门户
在真实手机上检查设置网络和强制门户。
- 执行校准检查
在真实机器人上完成并检查校准。
- 启动模拟器
启动模拟器,并在浏览器访问 http://localhost:5173。
- 运行虚拟硬件服务
运行机器人的假硬件服务,并在浏览器访问 http://localhost:8080。
- 验证构建后的模拟器
运行验证命令,让 Chrome 操作构建后的模拟器。
- 将所有姿态交给 MotionGovernor
所有来自滑块、动画、大脑或后续功能的头部姿态都必须经过 MotionGovernor。
- 拒绝部件间距不足的姿态
拒绝会使两个部件间距小于 0.5 mm 的姿态;间距依据 Fusion 装配体预先计算,并使用 `npm run check:clearance -w @peeqo/sim` 独立复测。
- 拒绝其他危险姿态
还要拒绝角与腿几乎成一直线的姿态,以及杆端倾斜超过 18° 的姿态。
- 设置运动速度限制
为速度、加速度及舵机速度设置上限。
- 规划安全直线路径
移动路径使用直线;直线路径被阻挡时,机器人绕行经过中立姿态。
- 保留颈部活动空间
每个手势都必须至少保留颈部活动空间的 30%。
- 通过真实调速器测试手势
测试时,让每个手势和表情都通过真实的 MotionGovernor 执行。
- 从面板开始引导校准
取下布罩,然后从面板开始进行引导式校准。
- 目视校准手臂通道与电平
通过目视确定每条手臂的通道、方向和水平状态。
- 测量整条手臂的安全范围
让整个头部一起移动并保持水平,因为两条手臂是联动的;其最低和最高安全点用于确定每个舵机的范围。
- 调平头部并检查三度倾角
使用手机水平仪将头部调平,并通过 3° 倾角检查刻度;完成这些操作前,舵机保持松弛。
- 将测量范围设为硬限制
测得的范围成为硬限制:调速器在范围内 1.5° 以内规划,驱动器绝不越界;真机上的手臂仅受这些范围限制,并能在约 85° 范围内自由摆动。
- 完成其余硬件检查
检查屏幕的分辨率与旋转、扬声器和麦克风音量、LED 0 的位置、各按钮的对应关系,以及杆端的回程间隙和旷量;声音芯片已设置好,但仍需试用唤醒词。
- 使用默认离线大脑
离线大脑是默认模式,使用 Peeqo 口吻的预设书面回答,不需要 API 密钥或网络,但无法理解语音。
- 检查开发服务器代理
开发服务器通过 `apps/sim/server/api.ts` 代理调用,因此密钥不会传到页面。代理只允许模拟器页面访问,其他站点会被拒绝。
- 确认模型限制
代理只转发 Claude 和 Gemini 模型,回复上限为 1,000 个 token。
- 测试唤醒词和语音停止检测
勾选 **Wake word** 并说“hey jarvis”可使用现成的 openWakeWord 模型;“hey Peeqo”需要训练。页面把麦克风流发送到开发服务器的 `/api/voice`,检测器也在那里判断何时停止说话。
- 验证未配置时的麦克风
未配置唤醒词时,**Mic** 仍然可用,并根据响度判断说话是否结束。
- 实时检查真实模型
在终端运行实时检查脚本,以 "hello" 与真实模型通信。
- 朗读实时检查内容
在 macOS 上使用 `--speak`,将每一行作为语音发送。
- 测试表情安全限制
从多个状态播放每一种表情并通过真实 governor 运行,检查 governor 从不需要强制阻止头部动作。
用起来
- 使用运动控制器驱动舵机
校准后,运动控制器驱动舵机。Peeqo 站立时臂保持水平,头部移动会根据标记范围调整;标记之间留出约十分之一的余量。控制器在每个标记内侧 1.5° 处规划运动,并遵守颈部几何形状、倾斜范围和速度上限。
- 查看 Peeqo 数据文件
打开 `~/.peeqo` 查看 `config.json`、`memory.md`、`conversation.json`、`alarms.json` 和 `sessions.json`。`config.json` 保存密钥、PIN 哈希和校准数据,仅 Peeqo 用户可读。
- 检查 Peeqo 服务
确认 `peeqo` 服务正在端口 80 上运行。确认 `peeqo-face` 在显示屏上以全屏 Chromium 显示 `/face`。
- 实时查看服务日志
使用 `journalctl -u peeqo -f` 实时查看 `peeqo` 服务日志。
- 观察实体机性能
在实体 3 B+ 1 GB 板上观察屏幕性能;脸部以每秒 30 帧绘制,Chromium 使用低内存模式。该服务在 Mac 上约占 130 MB,运动循环占 Pi 单核不到 3%。
- 检查 Wi-Fi 看门狗
关闭 Wi-Fi 节能,因为节能会让 Pi 掉线。若路由器连续 2 分钟无响应,Peeqo 会关闭再开启 Wi-Fi。
- 查看上次启动日志
日志会跨重启保留,并限制为 64 MB。使用 `journalctl -u peeqo -b -1` 查看上一次启动的日志。
- 监控温度和供电
在面板上查看 Pi 的温度,并使用 `vcgencmd get_throttled` 检查降频状态。日志会说明机器人何时为降温而降速,或供电何时过低。
- 安全关闭 Peeqo
收到关机请求后等待 30 秒;若系统仍未停止 Peeqo,则强制停止。即使强制停止失败,脸部也会提示可以安全拔掉电源。
- 操作机器人的硬件
硬件助手 `python/hardware.py` 驱动 PCA9685 舵机板(I²C 总线 1,地址 0x40)、SPI 0.0 上 4 MHz 的 12 个 APA102 LED 灯环,以及四个按钮。按钮按下时为高电平:GPIO 17 左前、4 右前、23 右后、16 左后。
- 启动浏览器模拟器
运行 npm run sim,然后打开终端打印的网址 http://localhost:5173。浏览器模拟器包含颈部机构、面部、LED 环和头部运动,所有动作都使用机器人将要采用的安全控制器。
- 与 Peeqo 对话
在模拟器中使用 **Talk to Peeqo** 输入框,或直接大声与 Peeqo 交谈。
- 体验一次完整对话
Peeqo 先思考,然后通过一次 `respond` 调用返回一个或两个表情、一个反应 GIF,以及不超过六个词的字幕。
- 查看表情屏幕反馈
Peeqo 先显示自己的感受,随后在面部屏幕上播放 GIF,并像梗图一样叠加字幕。没有 GIF 时,字幕显示在眼睛上方。
- 启用语音回答
启用 **Speak aloud** 后,浏览器改用语音回答,并偶尔显示 GIF。Peeqo 的状态依次变为 listening、thinking、idle,idle 表示正在以语音模式说话。
- 使用麦克风输入
选择 **Mic** 后,浏览器会持续录音,直到你停止说话。
- 使用时间和提醒工具
模型可以查询时间,设置、列出和取消计时器与提醒。计时器和提醒保存在页面中,重新加载后仍会保留。
- 接收到期提醒
计时器或提醒到期时,Peeqo 会伴随 GIF 发出通知。
- 查询天气
天气数据来自免费且无需密钥的 Open-Meteo。提问时不指定地点,如果 Peeqo 记得你的所在地,就会使用该地点。
- 管理 Peeqo 的记忆
Peeqo 会在 `apps/sim/.data/memory.md` 中保存值得长久保留的信息,例如你的名字、居住地、身边的人、喜好和重要日期。该列表可以读取和编辑。
- 删除已保存的信息
让 Peeqo 忘记某项信息,或者在面板中使用 **Forget everything**。模型会根据 remember 和 forget 工具决定保留内容,并跳过闲聊。
- 选择经典眼睛外观
可从面板选择 Peeqo 的2019年经典眼睛,也可使用 `?face=classic` 选择该外观。
- 使用 LED 动画模式
让 packages/core 中的 LedAnimator 驱动 12 个 DotStar LED。循环模式包括 glow、breathe、heartbeat、spin、listen、speak 和 rainbow;Sparkle 会随机闪烁并达到白色峰值,success、error 和 wake 是一次性动画,结束后返回之前的循环模式。
- 保留 2019 年动画
2019 年的动画仍然可用。多个动画可用时,最后启动的动画驱动灯环。
常见问题
物料
- 树莓派:开发套件为 Raspberry Pi 3 B+(1 GB),新一代软件也支持更新型号
- 3 个舵机组成的 Stewart 式头部平台,PCA9685 舵机驱动板(I²C 0x40)
- 头部屏幕(HDMI,全屏 Chromium 显示脸)、12 颗 APA102 LED 灯环(SPI)、4 个按键
- 声音:开发套件用 WM8960 声卡芯片;2017 版有 Knowles 麦克风板,打印件含 Sabrent USB 声卡外壳与扬声器夹
- 2017 版打印件:头与头盖、LED 环、底座环与脚、Stewart 底座与顶板、3 个舵机支架与滑动夹、扬声器夹、摄像头支架、电源插座支架等
- 12 V 直流电源适配器与布套(wiki 装配步骤)
工具
- 自制 2017 版:3D 打印机,以及按 Eagle 文件制板与焊接的工具
- 烧录系统用的电脑与 microSD 卡
- 校准时可用手机水平仪 App 调平头部(新一代软件文档)
技能
- 树莓派 OS Lite、SSH 与 npm 部署;首次安装约 15 分钟
- 引导式舵机校准:逐臂确认通道与方向、标定上下限(约 10 分钟)
- JavaScript / TypeScript:自定义命令与舵机动画(wiki 教程)
软件
- 2019 版 Electron 应用:snowboy 离线唤醒词、Dialogflow 意图、Giphy / Vlipsy GIF 与视频回应、计时器、天气、Spotify
- 新一代 TypeScript 工作区(next 分支):浏览器仿真器、按 CAD 碰撞表约束的运动调度器、16 种情绪的表情眼睛、LED 灯环图案与合成音效
- OpenRouter 大脑 + Klipy GIF、记忆、计时与提醒、Open‑Meteo 天气、microWakeWord 唤醒词、网页面板与手机配网