正在连接信源…

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 年的动画仍然可用。多个动画可用时,最后启动的动画驱动灯环。

常见问题

  • Dialogflow 查询超时,语音请求无法获得响应 #5 #3
  • Electron 在 Debian 上安装或启动失败 #2 #1
  • Giphy 响应数据未定义,导致图像辅助脚本崩溃 #4

物料

  • 树莓派:开发套件为 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 唤醒词、网页面板与手机配网

文档