了解你的开发板

开始使用 ESP-MOSAICO

ESP-Mosaico 是一款用于 AIoT 和嵌入式创作的开发设备。你可以用它探索对话编程、屏幕图形、技能、外设扩展，以及从零构建完整的嵌入式应用。

按键说明

按键	操作	功能
电源	短按	切换设备开关。
BOOT	开机时按住 BOOT	进入下载模式，以刷写固件或下载程序。
AI KEY	短按	返回。
AI KEY	长按	打开 AI Create。

扩展 I/O

接口	说明
IN	5 V 输入，可通过外部电源为 ESP-Mosaico 供电。
5V	5 V 输出，最大 100 mA。
3V	3.3 V 输出，最大 100 mA。
USJ	USB-Serial-JTAG；可初始化为通用 GPIO。开发板上的引脚顺序：3V、IN、DP (IO34)、DN (IO33)、IO15。
UART	UART；可初始化为通用 GPIO。接口上的引脚顺序：3V、IN、TX (IO58)、RX (IO59)、IO38。
CODEC	只有在禁用内部 ES8311 后，才能用作通用 I/O。

扩展板

ESP-Mosaico 通过扩展板支持不同的外设。插入前请确认插槽和方向。

摄像头扩展板：只能使用左侧插槽，并确保连接器方向正确。

↳ 扩展板插入方向——开机前请确认连接器已对齐。

首次启动

首次启动设备

首次使用时，请按照设备屏幕上的 Guide 完成基本设置，也可以花一点时间熟悉必要的屏幕手势。

看不到 Guide？请确认设备正在供电，然后尝试短按电源按钮再次开机。

配置使用体验

使用控制面板

ESP-Mosaico 提供基于 Web 的控制面板，可配置 Wi-Fi、LLM 和其他服务参数。

设备连接网络后，使用设备屏幕或 Guide 中显示的地址打开控制面板。它通常用于：

查看或修改 Wi-Fi 设置
配置 LLM 服务
配置 ASR 服务
配置网络 API 服务
查看设备状态
调整技能和 Lua 选项
在线聊天

修改后重启。在控制面板中修改设置后，请手动重启设备使其生效。

出厂设置包含 ASR 和 LLM 密钥，可用于快速体验基本问答和简单编程。如果内置额度用尽，或你需要更强的编程效果，请在控制面板中配置自己的模型凭据。

和你的硬件对话

尝试 ChatCoding

ChatCoding 让你通过自然语言体验嵌入式编程的乐趣。描述你希望 ESP-Mosaico 做什么，Agent 就会生成并运行相应的代码。

开始之前

已完成 Wi-Fi 配置。
已将微信或其他受支持的平台绑定到设备。
ASR 和 LLM 服务可用。
设备屏幕工作正常。

在微信中发送文字

打开与你的设备绑定的微信对话，直接输入请求。

请简单介绍一下自己。

每 30 分钟提醒我喝水。

在 Claw 中使用语音输入

从主屏幕打开 Claw 应用，长按输入框，说出你希望设备执行的操作。

Claw 的六项内置技能

模式	技能	用途	示例
快速提问	`ai_create_quick`	快速直接地回答一个明确的问题。	“如果每个选择都由过去决定，自由意志还存在吗？”
AI Create	`skill_creator`	创建或更新设备功能、工作流、技能或 Lua 自动化。	“在屏幕上绘制一朵旋转的小花，持续 30 秒。”
安装技能	`skills_lab_search`	在 ESP-Claw Skills Lab 中搜索适合 ESP-Mosaico 的技能，并引导你完成安装。	“帮我找一个天气技能。”
记忆	`memory_ops`	保存、查找、更新或删除设备的长期记忆。	“记住，你现在是我家庭花园的植物养护专家。”
规划	`plan_mode`	分析复杂目标，检查硬件和能力要求，并生成可执行的计划。	“我想把 ESP-Mosaico 做成舵机机器人。请规划最快的构建方式。”
计划任务	`cap_scheduler`	创建和管理一次性、重复性或 Cron 定时任务。	“每天晚上 8 点打开扩展灯板。”

保留你的成果

在 Work 中管理技能

Work 用于存储 Agent 完成的技能。当 ChatCoding 或其他工作流帮助你创建功能后，将其保存到 Work，便于再次运行或继续改进。

01已完成的能力会变成可复用的技能。

02技能可以再次打开并运行。

03可以在后续对话中继续完善技能。

从想法开始构建

尝试 VibeCoding

VibeCoding 用于从零构建自己的想法。在 PC 上，将 AI 编码 Agent 与 ESP-Mosaico 模拟器、调试工具和实体设备配合使用，创建更具挑战性的嵌入式应用。

你需要准备什么

在 PC 上准备一个 AI 编码 Agent，例如：

Codex
Claude Code
OpenCode
Trae

你还需要一条支持数据传输的 USB 数据线，以及 ESP-Mosaico 与电脑之间的连接。

进入下载模式

关闭设备后，使用 USB 数据线将 ESP-Mosaico 连接到 PC。按住 BOOT 按钮，再短按电源按钮开机。设备会进入下载模式，用于刷写固件或下载程序。

给 Agent 分配任务

可以尝试这样的提示词：

下载这个项目的代码。

配置环境并构建一个贪吃蛇游戏。

如果可以，请提供项目仓库 URL，这样 Agent 就能获取代码并自动配置环境。

迭代成果

Agent 完成第一个版本后，根据设备或模拟器上的实际效果指导下一次修改：

贪吃蛇移动太快了。请降低速度并添加暂停功能。

添加开始界面和游戏结束界面。

让 AI KEY 返回主菜单。

提示

使用 Plan Mode。VibeCoding 依赖共同理解。当一个请求难以一次表达完整时，先让 Agent 的 Plan Mode 重述它的理解，再在实现前进行修正。
在 ESP-GSP 模拟器中制作 UI 原型。在刷写到实体设备前，先在模拟器中验证布局、交互逻辑和视觉效果。
使用调试工具进行多模态测试。本仓库中的工具可以捕获屏幕并支持交互式测试。

故障排查

常见问题

设备无法开机怎么办？

检查电池电量或 USB 供电。电源按钮通过短按切换设备开关；长按不会开机。

如何进入下载模式？

关闭设备后，使用 USB 数据线将其连接到 PC。按住 BOOT，再短按电源按钮开机。

Wi-Fi 设置失败怎么办？

检查网络名称和密码，并确认路由器信号稳定。如果问题仍然存在，请恢复出厂设置后重新配置设备。

微信二维码绑定失败是为什么？

确认设备已联网。微信目前只支持绑定一个 Claw 设备；绑定 ClawBot 会接管之前的设备绑定。

控制面板设置为什么没有生效？

在控制面板修改设置后手动重启设备。

LLM 或语音功能为什么运行不正常？

确认设备已联网，并且控制面板中的 LLM 和 ASR 设置可用。出厂密钥仅用于快速试用；内置额度用尽后，请配置自己的模型凭据。

为什么没有摄像头画面？

确保摄像头扩展板位于左侧插槽，并且插入方向正确。

Agent 生成的程序不符合预期怎么办？

向 Agent 描述问题和下一步修改方向。一次提供一条具体反馈，例如速度、按键行为、屏幕布局或交互。

共同词汇

术语表

术语	含义
ESP-Mosaico	用于 AIoT 和嵌入式创作的开发设备。
ESP-Claw	运行在 ESP-Mosaico 出厂固件中的设备端 Agent。
Guide	用于配置 Wi-Fi 和微信的首次启动流程。
ChatCoding	通过聊天或语音描述请求，由 Agent 为你生成并运行代码的体验。
VibeCoding	使用 AI 编码 Agent 从零构建创意项目的开发方式。
Work	存储已完成 Agent 技能的区域。
Agent	能够理解请求、生成代码、调用工具并帮助完成任务的 AI 编码 Agent。
ASR	自动语音识别，用于将语音转换为文字。
LLM	大语言模型，用于理解请求、生成答案或编写代码。
下载模式	用于刷写固件或下载程序的设备模式。
ESP-GSP emulator	用于快速验证 ESP-Mosaico UI 原型和交互的 PC 工具。

开始构建之前

安全与维护

连接或移除扩展板前请关闭设备。
摄像头扩展板只能使用左侧插槽。
插入扩展板前请确认方向，避免反向插入。
通过 USB 连接 PC 时，请确保数据线支持数据传输。
刷写或下载程序时请勿断开电源或 USB 连接。
让金属物体远离裸露的连接器，防止短路。
如果设备异常发热，请立即断开电源并停止使用。