Coglet 桌面陪伴机器人 复刻全流程
Coglet 桌面陪伴机器人 从采购、打印、组装到装软件、标定和训练的 133 个步骤,附物料表、购买链接与官方出处。
Coglet Complete Kit 143.57 英镑起,加内部打印件、外壳与仿真眼球最高 392.83 英镑(NMRobotics 官方商店,2026‑11‑01,页面标含税,站点横幅称多数国家配送 10 英镑);基础套件含 CogNog 主板、两个摄像头、9 个舵机、9 个 TorqueStar、65 颗 M2 螺丝、电源板、麦克风板与扬声器,不含打印件。仓库未给自购物料总价
采购
- 准备相关资源文件
准备唤醒网络模型、文本字体文件和表情符号图片集合。
- 准备额定 5V 3A 电源
使用额定输出为 5V、3A 的电源,例如额定功率为 5V 3A 的 USB 充电器。如果使用 Coglet USB > JST XH 适配器,应使用 USBA > USBC 数据线。
组装
- 连接双 MCU 的 UART
将 ESP32-s3 的 GPIO18 连接到 RP2040 的 GPIO04,将 ESP32-s3 的 GPIO17 连接到 RP2040 的 GPIO05。两块 MCU 通过 UART 传送对应预置动画的简单字符串命令。
- 连接 JST-XH 电源输入
通过板子左下角的 JST-XH 连接器接入电源。该输入通过 3V3 LDO 为两块 MCU 供电,并通过隔离的 5V 线路为舵机供电。
- 按照飞书教程完成面包板实践
参阅链接的飞书文档教程,完成面包板 DIY 实践。
软件与固件
- 定义单次动作行为
动作会临时覆盖说话过程,运行 3 个周期后返回之前的状态。
- 添加 RP2040 动画
在 RP2040 一侧的 animation.py 中添加小型动作动画。
- 注册动作名称
在 RP2040/main.py 中添加新的动作名称,使主程序能够识别它。
- 添加 ESP32 MCP 工具
在 ESP32 板级文件中添加一个可供 LLM 调用的 MCP 工具。
- 通过 UART 发送动作
发送简单的 UART 字符串,例如 action:nod,以触发动作。
- 保持主循环不阻塞
避免长时间调用 sleep(),并且不要在状态动画内部使用 while True 循环。
- 使用基于时间的动画步骤
让 main.py 重复调用状态,以逐步推进动画。
- 选择简单的动作名称
使用简短的小写动作名称,例如 excited 或 shy。
- 安装 ESP-IDF 5.5
按照 Espressif 官方入门指南,为你的操作系统下载并安装 ESP-IDF 5.5。然后在终端中激活已安装的环境。
- 克隆 Coglet 仓库
使用 Git 下载 Coglet 项目源代码。
- 配置自定义唤醒词
在 ESP 项目中打开 menuconfig,进入 XiaoZhi Companion > Wakeword 并输入自定义唤醒词。按 S 保存,按 Enter 确认,再按 Q 退出;Wakeword Display 用于设置助手自身的发音。
- 构建、烧录并监视固件
通过 USB 连接 Xiaozhi AI 板,然后编译并烧录固件。监视器会自动打开串口监视界面,用于验证板卡启动和新的唤醒词。
- 打开最新的 NMWorkbench 指南
使用链接中的 NMWorkbench 仓库获取最新设置说明。
- 使用 WSL2 安装 Ubuntu
以管理员身份打开 PowerShell,并使用 WSL2 安装 Ubuntu 24.04。
- 创建 Ubuntu 用户
如果系统要求则重启 Windows,从开始菜单打开 Ubuntu 并创建用户。
- 启用 WSL 镜像网络
在 C:\Users\<you>\.wslconfig 的 wsl2 配置段中启用镜像网络,使 Coglet 能访问服务器。
- 重启 WSL 环境
在 PowerShell 中关闭 WSL,然后重新打开 Ubuntu。
- 允许 Coglet 的防火墙端口
添加 Windows 防火墙规则,允许端口 18000 上的入站 TCP 流量。
- 完成 Ubuntu 设置
在 Ubuntu 中按照 docs/GETTING_STARTED.md 操作。可在 Windows 中原生安装 Ollama 以获得最简单的 GPU 方案,也可以在 Ubuntu 中安装。
- 使用本地 Ollama 端点
使用镜像网络时,无论 Ollama 安装在 Windows 还是 Ubuntu 中,都可通过 http://127.0.0.1:11434/v1 访问。
- 设置 Ollama 上下文长度
使用 OLLAMA_CONTEXT_LENGTH 将 Ollama 上下文长度设置为 16384。Windows 版应将其设为 Windows 环境变量,Ubuntu 版则按指南设置。
- 保持开发板标识唯一
自定义 IO 配置与原开发板不同时,不要覆盖原开发板的配置编译固件;应创建新的开发板类型,或在 config.json 的 builds 中使用不同的 name 和 sdkconfig 宏定义。
- 了解开发板目录文件
开发板目录通常包含 xxx_board.cc、config.h、config.json 和 README.md;它们分别用于板级初始化代码、硬件配置、编译配置和开发板说明。
- 创建自定义开发板目录
在 boards/ 下创建新目录,并使用“品牌名-开发板类型”的命名形式;示例名称为 m5stack-tab5。
- 定义硬件引脚配置
在 config.h 中设置 24000 的输入和输出采样率,I2S MCLK/WS/BCLK/DIN/DOUT 为 GPIO 10/12/8/7/11,PA 为 GPIO 13,I2C SDA/SCL 为 GPIO 0/1,编解码器为 ES8311 默认地址,BOOT 按钮为 GPIO 9。显示配置为 SCK GPIO 3、MOSI GPIO 5、DC GPIO 6、CS GPIO 4、320×240、镜像 X=true、镜像 Y=false、交换 XY=true、偏移 X/Y 为 0、背光 GPIO 2、背光反相=true。
- 创建开发板编译配置
在 config.json 中将 target 设为 esp32s3,并在 builds 中添加 name 为 my-custom-board 的构建;sdkconfig_append 追加 8MB Flash 配置和 partitions/v2/8m.csv 分区表。target 必须与硬件匹配,name 建议与目录名一致,sdkconfig_append 会追加到默认配置。
- 选择 Flash 和分区配置
根据硬件在 sdkconfig_append 中选择 CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y、CONFIG_ESPTOOLPY_FLASHSIZE_8MB=y 或 CONFIG_ESPTOOLPY_FLASHSIZE_16MB=y,并可选择 partitions/v2/4m.csv 或 partitions/v2/8m.csv 分区表。
- 编译并打包开发板固件
完成自定义开发板的配置后,运行 scripts/release.py,并传入开发板目录名字,以编译和打包该开发板的固件。
- 创建自定义开发板文件
创建 `my_custom_board.cc`,并在其中实现开发板的所有初始化逻辑。
- 定义自定义开发板类
在 `my_custom_board.cc` 中定义开发板类,并继承 `WifiBoard` 或 `Ml307Board`。
- 实现各组件初始化函数
实现 I2C、SPI、显示屏、按钮及 IoT 等组件的初始化函数。代码中的显示初始化使用 ST7789,并通过 SPI2_HOST 初始化面板接口。
- 重写开发板虚函数
在开发板类中重写 `GetAudioCodec()`、`GetDisplay()`、`GetBacklight()` 等虚函数。
- 注册自定义开发板
使用 `DECLARE_BOARD` 宏注册自定义开发板。
- 添加自定义开发板选项
在 `main/Kconfig.projbuild` 的 `choice BOARD_TYPE` 中添加 `BOARD_TYPE_MY_CUSTOM_BOARD`,并根据目标芯片设置 `depends on`。
- 添加 CMake 板级配置
在 `main/CMakeLists.txt` 的 `elseif` 链中添加自定义开发板配置,将 `BOARD_TYPE` 设为与目录名一致的 `my-custom-board`。
- 按屏幕选择字体
128x64 OLED 使用 `font_puhui_basic_14_1` 和 `font_awesome_14_1`,240x240 使用 16_4 字体,240x320 使用 20_4 字体,480x320 以上使用 30_4 字体。
- 选择表情集合
`twemoji_32` 是 32x32 像素的小屏幕表情,`twemoji_64` 是 64x64 像素的大屏幕表情。
- 设置 ESP32 目标芯片
首次配置或更换芯片时,根据开发板使用 ESP32-S3、ESP32-C3 或 ESP32 目标运行 `idf.py set-target`。
- 清理旧配置
运行 `idf.py fullclean` 清理旧配置。
- 选择自定义开发板
运行 `idf.py menuconfig`,然后进入 `Xiaozhi Assistant` -> `Board Type` 并选择自定义开发板。
标定与测试
- 检查收到的 UART 名称
如果没有任何动作,请检查通过 UART 到达的字符串名称是否完全正确。
- 检查舵机缩写
如果移动了错误的部件,请检查舵机缩写,例如 EAL 或 EAR。
- 恢复安全舵机角度
如果动作幅度过大,请返回现有动画中已知安全的角度。
- 使用高优先级动作路径
确保 MCP Action 使用高优先级动作路径,从而避免与 Speaking 冲突。
- 检查控制台 OTA URL
打开控制台的 Overview 页面,确认 OTA URL 显示电脑的局域网 IP,例如 192.168.x.x。
- 配置 Coglet 的 OTA URL
在 Coglet 中输入 Overview 页面显示的 OTA URL。
- 输出声波测试信号
通过 `sonic_wifi_config.html` 输出声波 `demod`,或将其上传至 PinMe 的小智声波配网(https://iqf7jnhi.pinit.eth.limo)进行输出。
- 按板卡配置调整降噪
部分 ADC 需要在 I2C 配置阶段进行更精细的降噪调整;由于设备不通用,目前只按照 boards 内提供的 config 测试。
- 配置 lichuang-dev 接收
lichuang-dev 使用 ES7210 ADC,测试时需要关闭 `INPUT_REFERENCE`。
- 配置 kevin-box-2 接收
kevin-box-2 使用 ES7210 ADC,测试时需要关闭 `INPUT_REFERENCE`。
- 配置 m5stack-core-s3 接收
m5stack-core-s3 使用 ES7210 ADC,测试时需要关闭 `INPUT_REFERENCE`。
- 刷写构建后的固件
将构建后的固件刷写到 Coglet。刷写后,可以让 Coglet 跳舞播放指定歌曲或用户的一首歌曲。
- 在文件名中覆盖预设和节奏速度
Coglet 会自动选择预设;当检测不准确时,可以在文件名中加入标签来强制指定预设和节奏速度。示例包括“Night Rain.calm.mp3”、“Drop It.energetic.wav”和“Free Fall.calm.68bpm.m4a”。
- 检查构建输出
确认 build/assets/ 包含所有资源文件,build/output/ 包含中间输出文件,build/ 包含 assets.bin、config.json 和 assets/。
- 检查资源文件大小
确认生成的 `assets.bin` 文件大小不超过 SPIFFS 分区容量。
采数据与训练
- 将普通音频转换为P3
运行 convert_audio_to_p3.py,指定输入音频文件、输出 P3 文件;默认响度标准化目标为 -16 LUFS。
- 按需禁用响度标准化
音频过短、已经调整过响度,或来自默认 TTS 时使用 `-d`;默认 TTS 的响度已经是 -16 LUFS。
- 将P3转换回普通音频
运行 convert_p3_to_audio.py,指定输入 P3 文件和输出音频文件;输出音频文件必须带有扩展名。
- 运行批量转换图形工具
运行 batch_convert_gui.py,打开支持音频转 P3 和 P3 转音频的图形化批量转换工具。
- 保存并分析接收声音
保存窗口长度的声音,用于判断噪音频率分布和测试声波传输 ASCII 的准确度。
- 测试 atk-dnesp32s3-box0 解码
atk-dnesp32s3-box0 使用 ES8311 ADC,能够接收并解码,但丢包率很高。
- 测试 movecall-moji-esp32s3 解码
movecall-moji-esp32s3 使用 ES8311 ADC,能够接收并解码,但丢包率很高。
- 通过网络发送 Opus 音频
让应用层从 `audio_send_queue_` 取出 Opus 包,并通过网络将其发送到云服务器。
用起来
- 让 Coglet 跳舞
Say "dance to <song name>" for a particular song. Say "dance to one of my songs" to request one of the songs added by the user.
- 使用 energetic 预设
整个机器人会跳舞,包括头部点动、耳朵动作、摇摆、底座转动、眼睛动作和眨眼。
- 使用 calm 预设
只有耳朵、头部和底座会随着感受到的节拍轻柔移动。播放歌曲期间,眼睑和眼睛舵机保持放松,不施加扭矩。
- 播放P3音频文件
运行 play_p3.py 并指定 P3 文件路径,工具会解码播放该文件,并在播放结束或用户中断时应用淡出。
常见问题
物料
- CogNog 主板:ESP32‑S3(Wi‑Fi/BLE、AI 加速)+ RP2040(实时舵机动画),PCA9685 16 路 PWM、MAX98357A 功放、CH343P USB 串口;72×81 mm 四层板,最多带 12 个舵机
- 9 个金属齿微型舵机:双耳、眼睑、嘴、双眼、颈部俯仰与横滚、底座转向(数据手册链接 TiankongRC TS90MD,README 称 MG90S 也可能可用)+ 9 个 TorqueStar 花键转接件(可用树脂打印)
- GC0308 摄像头(定制反向引脚)、Grove Vision AI V2 + OV5647 高清摄像头与 15 针排线
- I2S 麦克风板(6 针 PicoBlade 反向线)、4 Ω 3 W 扬声器
- 5V 3A USB 供电,经 USB 转 JST‑XH 电源板(须用 USB‑A 转 USB‑C 线);编程口供电时舵机不通电
- FDM 打印的内部结构与外壳(拓竹 3MF,0.4 mm 喷嘴),可选 SLA 树脂外壳与仿真眼球
工具
- 0.4 mm 喷嘴 FDM 3D 打印机,或向商店购买打印件
- 5V 3A USB 充电器与 USB‑A 转 USB‑C 线
- 二次开发:ESP‑IDF 5.5、MicroPython 与 Thonny(RP2040)、SenseCraft 部署人脸检测模型
技能
- 3D 打印与狭小空间内的舵机装配,用板载校准开关摆正舵机
- 配网与小智 AI 控制台设置
- 进阶:ESP‑IDF C++(小智框架与 MCP 工具)、RP2040 MicroPython 动画(animation.py)
软件
- CogletESP:基于小智 AI 的 ESP32‑S3 固件,流式语音识别 + 大模型 + 语音合成,MCP 设备控制,唤醒词可改
- RP2040 MicroPython 动画程序:表情状态(开心、难过、聆听、说话)与一次性动作(摇头、眨眼)
- Grove Vision AI V2 本地人脸检测(SenseCraft 模型);板载舵机测试按钮与人脸追踪开关