RYMCU BigSmart
English
概览

用户详细使用手册

BigSmart 开发环境、固件烧录、交互、SD 卡、媒体和外设使用手册。

1. 使用前准备

1.1 物品清单

项目用途
RYMCU BigSmart AI助手主设备
USB Type-C 数据线供电、串口日志、固件烧录
5V USB 电源或电脑 USB 口供电
MicroSD 卡存放 MP3、视频和其他资源
蓝牙 HID 手柄游戏控制，可选
2.4G Wi-Fi 网络小智联网、网络电台、MQTT 等功能

1.2 注意事项

  • 使用可传输数据的 USB 线，只有充电功能的线无法烧录或查看串口。
  • MicroSD 卡建议格式化为 FAT32。
  • ESP32-S3 只支持 2.4G Wi-Fi，请不要选择 5G-only 网络。
  • 摄像头、音频、屏幕和 Wi-Fi 都会占用较多内存，开发调试时建议先验证基础功能，再逐项打开高级功能。
  • 本手册的软件操作以 E:\RYMCU\xiaozhi 中的 BigSmart 小智固件为参考；如果你使用其他固件，按键和菜单行为可能不同。

2. 开发环境

2.1 推荐环境

工具建议版本/说明
ESP-IDF5.4 及以上
IDEVSCode、Cursor 或命令行
串口工具ESP-IDF Monitor、PuTTY、MobaXterm 或其他串口终端
固件工程当前仓库
硬件资料当前仓库

3. 固件烧录

3.1 使用仓库内合并固件烧录

当前仓库已提供 BigSmart 合并固件：

firmware/rymcu-V2.3.28-merged.bin
firmware/rymcu-V2.3.19-merged.bin
firmware/xiaozhi-esp32-merged.bin
firmware/espressif-brookesia-merged.bin

默认建议先烧录 RYMCU 官方固件 rymcu-V2.3.28-merged.bin。旧版 rymcu-V2.3.19-merged.bin 仍保留用于回退。

V2.3.28 预编译固件包含天气、日历、Codex 状态应用、Smart Home MQTT/Endpoint、NES 启动器和 NES 专用启动模式。该文件不包含 2026-07-28 提交 b1d1c08 中后续的 NES 显示、音频和音量控制调整。

可使用 ESP-IDF、esptool 或图形化烧录工具写入 ESP32-S3。若使用命令行，常见方式为：

esptool.py --chip esp32s3 -p COM端口 -b 460800 write_flash 0x0 firmware\rymcu-V2.3.28-merged.bin

3.2 进入下载模式

如果自动下载失败，可按以下方式手动进入下载模式：

  1. 按住 Boot 键。
  2. 复位或重新上电。
  3. 松开 Boot 键。
  4. 重新执行烧录命令。

4. 首次启动与配网

4.1 启动检查

烧录完成后设备会重启。正常情况下可以看到：

  • 屏幕亮起并显示小智相关界面。
  • 串口日志打印板级初始化信息。
  • SD 卡存在时，日志显示挂载到 /sdcard。
  • Wi-Fi 未配置时，设备进入配网流程。

4.2 Wi-Fi 配网

小智参考工程包含 BluFi 配网文档。典型流程：

  1. 编译时启用 WiFi Configuration Method -> Esp Blufi。
  2. 设备首次启动且没有保存的 Wi-Fi 时自动进入配网。
  3. 手机使用 EspBlufi App 或兼容 BluFi 客户端搜索设备。
  4. 连接设备后输入 2.4G Wi-Fi 的 SSID 和密码。
  5. 设备连接成功后会保存配置，后续自动联网。

如果固件进入运行态后需要重新配网，可使用以下方式之一：

  • 设备启动阶段单击 Boot 键进入配网。
  • 通过 MCP 工具 self.system.reconfigure_wifi 请求重新配网。
  • 清除 NVS 或重新烧录擦除数据后重新启动。

5. 按键与基础交互

操作功能
电源键长按约 3 秒开机/关机，取决于电源管理电路状态
Boot 键单击启动阶段进入配网；运行时切换对话状态
Boot 键双击在空闲状态切换设备侧 AEC 开关，需固件启用 CONFIG_USE_DEVICE_AEC
GPIO10/PTT 键按下开始监听语音
GPIO10/PTT 键松开结束监听语音
触摸屏点击/滑动取决于当前固件界面和应用逻辑

6. 语音助手使用

6.1 对话

  1. 确保设备已连接 Wi-Fi。
  2. 单击 Boot 键切换到对话/监听状态，或按住 GPIO10 PTT 键开始说话。
  3. 对设备说出问题或指令。
  4. 松开 PTT 键或等待设备结束监听。
  5. 设备通过扬声器播报回复，屏幕同步显示状态。

6.2 AEC 切换

设备侧 AEC 用于抑制扬声器回声。固件启用后，在空闲状态双击 Boot 键可切换 AEC。若语音识别时设备自己的播报声容易被再次采集，可尝试开启 AEC；若环境较简单，也可以关闭以降低处理开销。

7. SD 卡使用

7.1 格式与目录

推荐将 MicroSD 卡格式化为 FAT32，并按需创建目录：

/sdcard
├── music
│   ├── song1.mp3
│   └── song2.mp3
└── test.mp3

7.2 SD 卡挂载检查

启动日志中若出现 SD card mounted at /sdcard，说明挂载成功。也可以调用 self.media.list_mp3_files 检查是否能读取 MP3 文件。

8. 本地 MP3 播放

8.1 支持能力

功能MCP 工具
播放指定 MP3self.media.play_mp3
停止播放self.media.stop_mp3
列出 MP3 文件self.media.list_mp3_files
播放测试文件self.media.play_test_mp3
查询播放状态self.media.get_mp3_state
下一首self.media.play_next
上一首self.media.play_previous

8.2 示例

播放 SD 卡中的音乐：

{
  "tool": "self.media.play_mp3",
  "arguments": {
    "filepath": "/sdcard/music/song1.mp3"
  }
}

列出 /sdcard 下的 MP3 文件：

{
  "tool": "self.media.list_mp3_files",
  "arguments": {
    "directory": "/sdcard"
  }
}

9. 网络电台

联网后可使用网络电台功能。常用工具：

功能MCP 工具
播放电台self.radio.play_url
停止电台self.radio.stop
查询状态self.radio.get_status

示例：

{
  "tool": "self.radio.play_url",
  "arguments": {
    "station_name": "动感101"
  }
}

10. 天气、日历、Codex 与 NES

V2.3.28 固件在 Launcher 中新增或完善了多个应用入口：

应用说明
Weather查看联网天气信息
Calendar查看日历信息
Codex查看 Codex 运行状态和桥接设置入口
NES从 SD 卡选择 .nes ROM，并重启进入 NES 专用启动模式

Codex 应用只提供设备端状态和桥接设置入口；PC 端桥接脚本不随 BigSmart-Open 仓库发布。NES 相关体验以 V2.3.28 预编译固件为准，不包含 2026-07-28 提交 b1d1c08 中后续的 NES 显示、音频和音量控制调整。

11. RGB 灯与 Smart Home MQTT/Endpoint

11.1 直接控制 RGB

设置 RGB LED：

{
  "tool": "self.light.set_rgb_color",
  "arguments": {
    "red": 255,
    "green": 100,
    "blue": 50
  }
}

关闭 RGB LED：

{
  "tool": "self.light.turn_off",
  "arguments": {}
}

11.2 Smart Home MQTT 概览

V2.3.28 固件使用 RYMCU Smart Home MQTT 协议控制第三方智能家居设备。底层 MQTT topic 根前缀为 rymcu/home/v1，设备需要通过配对码、发现广播、状态上报和命令 topic 与 BigSmart 交互。

上层控制入口有两种：

  • 本地小智会话 MCP：语音服务直接调用设备上的 self.smart_home.* 工具。
  • 外部 MCP Endpoint Bridge：通过配网写入的 Endpoint 调用同一批 self.smart_home.* 工具，最终仍由 Smart Home MQTT 下发。

常用工具：

功能MCP 工具
设置 MQTT brokerself.smart_home.set_mqtt_endpoint
连接 Smart Home MQTTself.smart_home.connect
断开连接self.smart_home.disconnect
查询状态self.smart_home.get_status
扫描设备self.smart_home.scan_devices
列出设备self.smart_home.list_devices
控制设备self.smart_home.control_device

设置 broker：

{
  "tool": "self.smart_home.set_mqtt_endpoint",
  "arguments": {
    "endpoint": "broker-cn.emqx.io:1883",
    "confirm": true
  }
}

连接并扫描设备：

{
  "tool": "self.smart_home.connect",
  "arguments": {}
}

{
  "tool": "self.smart_home.scan_devices",
  "arguments": {}
}

控制已发现设备：

{
  "tool": "self.smart_home.control_device",
  "arguments": {
    "device_id": "lamp-bedroom-01",
    "action": "turn_on",
    "entity_id": "main",
    "params": "{}"
  }
}

配网自定义数据也支持两个前缀：

  • mqtt:<host[:port]>：保存 Smart Home MQTT broker。
  • mcp:<endpoint>：保存外部 MCP Endpoint 地址。

12. IMU 姿态与晃动检测

BigSmart 板载 QMI8658 六轴传感器。固件启动后会周期读取传感器数据，并启动晃动检测。可通过 MCP 工具读取姿态角、加速度和陀螺仪数据：

{
  "tool": "self.imu.get_attitude_angles",
  "arguments": {}
}

可用于以下场景：

  • 晃动唤醒或切换界面。
  • 体感控制小游戏。
  • 设备姿态显示。
  • 交互装置触发条件。

13. 摄像头使用

BigSmart 使用 GC0308 摄像头，硬件支持 640 x 480 @ 16 FPS。参考固件采用懒加载方式：启动阶段不立即初始化摄像头，首次请求摄像头能力时才初始化，以降低启动阶段内存压力。

使用建议：

  • 确保固件启用 GC0308 相关配置。
  • 需要图像能力时再调用摄像头，避免与音频、Wi-Fi、大型 UI 同时抢占内存。
  • 若画面方向异常，可检查固件中的镜像和翻转设置。

14. 常见问题

问题可能原因处理方法
电脑识别不到串口USB 线仅供电、驱动缺失、设备未上电更换数据线，安装驱动，检查电源
烧录失败未进入下载模式或串口被占用按 Boot + 复位进入下载模式，关闭串口终端后重试
连不上 Wi-Fi使用 5G 网络、密码错误、信号弱使用 2.4G Wi-Fi，重新配网，靠近路由器
无声音音量过低、功放未使能、音频初始化失败查看串口日志，确认 ES8311/ES7210 初始化正常
语音识别差环境噪声大、离麦克风太远、AEC 状态不合适靠近设备说话，尝试双击 Boot 切换 AEC
SD 卡无法挂载未格式化 FAT32、接触不良、卡损坏重新格式化，重新插拔，更换 SD 卡
找不到 MP3路径错误或文件格式不支持使用绝对路径，确认文件后缀为 .mp3
Smart Home MQTT 连接失败broker 地址错误、端口错误、网络不可达或未启用查询 self.smart_home.get_status，在 Settings > Advanced 或 MCP 工具中重新配置 broker
NES 看不到游戏SD 卡未挂载、目录不符合固件扫描规则或 ROM 后缀不正确确认 SD 卡 FAT32 可读，并放入 .nes ROM
Codex 状态无法连接PC 端桥接服务未运行、桥接地址错误或不在同一局域网确认设备和 PC 网络连通，并在 Codex 应用中配置正确桥接地址

15. 硬件维护

  • 插拔屏幕、摄像头、麦克风板或其他排线前先断电。
  • 使用电池供电时注意电池极性和充电安全。
  • 外壳文件位于 enclosure/，修改结构时注意屏幕、按键、麦克风开孔和扬声器声腔。
  • 二次开发新外设前，先查阅 硬件配置说明 避免 GPIO 冲突。

16. 参考资料

产品介绍书

BigSmart 产品定位、硬件组成、软件能力和典型应用。

硬件配置说明

BigSmart 硬件组件、接口、电源、外设和 GPIO 分配说明。