ESP32S3多功能手柄

---

---

1. 视频演示

2. 实物展示

3. 功能一览

✨ 十二大核心功能

功能	说明
🖥️ LVGL 图形界面	1.69寸 240×280 ST7789 屏幕，状态栏、主屏、菜单、设置一应俱全
🎮 游戏模拟器	内置 NES(FC) 模拟器，支持 Retro-Go 独立系统（FC/GB/GBC/SMS/PCE/SFC）
🤖 AI 语音助手	一键切换到 XiaoZhi AI 语音助手系统
🌤️ 天气预报	和风天气 API，7天预报 + 实时天气（需自行注册 API Key）
⌨️ BLE 蓝牙键盘	蓝牙 HID 键盘/鼠标，可连接手机、平板、电脑
🎙️ WiFi 音频	按住 RIGHT 键通话，通过 UDP 实时推送到 PC
🎵 频谱分析	FFT 实时音频频谱可视化，参数可调
🎲 占卜工具	易经六十四卦 + 小六壬，指尖解惑
🎨 主题系统	6 种内置配色，5 色槽自定义，随心换装
🔄 双固件切换	三个系统（主系统/游戏/AI）独立运行，菜单一键切换
💤 电源管理	Light Sleep 待机（~5-10mA），按键唤醒
🎚️ 音频系统	MAX98357 数字功放 + MSM261 数字麦克风

4. 超强可扩展性

🧩 有想法，直接让 AI 加入框架！

5. 硬件参数

📋 硬件规格

组件	型号/规格
主控	ESP32-S3，8MB Octal PSRAM
Flash	16MB
屏幕	1.69寸 240×280 RGB，ST7789 驱动，SPI 接口
功放	MAX98357，I2S 数字输入
麦克风	MSM261，I2S 数字麦克风
IMU	LSM6DS3TR-C 六轴陀螺仪+加速度计
温湿度	AHT20
SD 卡	SPI 模式，独立 SPI3_HOST 总线
按键	7 个：UP / DOWN / LEFT / RIGHT + A / B / START
LED	GPIO18 指示灯
天线	IPEX 1代外接天线

6. 分区布局

📦 16MB Flash 分区布局

分区	偏移	大小	系统
factory	0x10000	4MB	ESP-Handheld（主系统）
ota_0	0x410000	4MB	Retro-Go（游戏模拟器）
ota_1	0x810000	4MB	小智 AI（语音助手）
assets	0xC10000	~4MB	SPIFFS 资源

> 🔄 切换方式： 菜单 → "游戏" / "小智"，或按住 START+B 返回主系统。

7. 软件架构

🔧 项目结构

main/
├── main.c              — 入口、初始化、按键分发
├── bsp/                — 板级支持（屏幕、SD卡、按键驱动）
├── app/                — 应用框架（菜单、启动器）
├── modules/            — 功能模块
│   ├── audio/          — MAX98357 + MSM261 音频驱动
│   ├── imu/            — LSM6DS3TR-C 姿态传感器
│   ├── sensor/         — AHT20 温湿度
│   ├── weather/        — 和风天气 API
│   ├── pc_remote/      — BLE HID + 空中飞鼠 + WiFi 音频
│   ├── wifi_manager/   — WiFi 配置
│   ├── settings/       — NVS 设置
│   ├── theme/          — 主题系统
│   ├── spectrum/       — FFT 频谱
│   ├── iching/         — 易经 + 小六壬
│   └── retro_go/       — NES 模拟器桥接
└── ui/                 — LVGL 界面

8. 快速开始

🚀 快速开始

✅ 你需要准备

#	项目	说明
1	🔧 硬件	打板焊接
2	💻 软件环境	AI Agent + ESP-IDF v5.5.4 + Git

🤖 一键构建（让 AI 帮你）

git clone --recursive https://github.com/zistar001/ESP-Handheld.git
cd ESP-Handheld
## 🧠 AI 会帮你完成剩下的所有步骤

🛠️ 手动构建

git clone --recursive https://github.com/zistar001/ESP-Handheld.git
cd ESP-Handheld
. $IDF_PATH/export.sh            # 设置 ESP-IDF 环境
idf.py set-target esp32s3
idf.py menuconfig                # 可选：配置天气 API Key
idf.py build
## 烧录到 factory 分区
python -m esptool --chip esp32s3 -p (PORT) -b 921600 \
  write_flash 0x10000 build/esp_handheld.bin

9. 文档索引

📚 文档索引

文档	说明
📖 功能使用说明	完整操作手册（按键、APP、WiFi、蓝牙等）
🔨 编译指南	Windows / Linux / macOS 编译步骤
🔥 烧录指南	全量烧录、OTA 更新、系统切换
🔌 硬件适配	引脚定义、PCB 适配方法
🔑 API 密钥	和风天气注册与配置
🤖 小智 AI 编译	在 xiaozhi-zistar-main 目录中编译

10. 注意事项

⚠️ 我也是新手，个人踩坑经验，希望能帮到你！

💻 软件方面

• 让 AI 帮你 —— 项目里的 CLAUDE.md 和 AGENTS.md 是为 AI 编程工具准备的配置说明。用 Claude Code、TRAE、CODEX等打开项目，让AI读取并引导你编译、烧录，不懂代码也能玩。
• 扩展性强 —— 基于 ESP-BSP 框架，有什么需求直接跟 AI 说，让它帮你集成到菜单卡片里。甚至可以把 esp-claw 也加进去（但要删掉小智或游戏系统）。
• 有问题问 AI —— 代码相关的问题，问 AI 比问我有用多了 😂

🔧 硬件方面

• PCB 与外壳固定：用 M1.6×2.5×2.5 热熔螺母 + M1.6 × 4 平头螺丝（PLA 打印适用，光固化树脂不能用热熔螺母）。外壳还不完善，可自行修改。
• 天线：ESP32-S3 用外接天线，型号 1U-N16R8，WiFi 天线用短款 IPEX 1代，别买错了。（外置天线单纯就是为了省点空间，以及方便布局和焊接，看到别人都是板载，心虚得很😂）。
• 屏幕：1.69寸裸屏很脆弱，非常容易被压碎！ 用 2mm 泡沫双面胶粘贴到主板上，操作时要格外小心。
• 喇叭：买 2828 腔体喇叭（去掉后壳），或其他厚度不超过 6-7mm 的小喇叭。电池厚度也大概 6mm 左右。
• 按键：用 3×3×1.5H 四脚 + 2×3×1.5H 二脚 微动开关，声音比较大。但锅仔片感觉都是坑，我是不想用了。
• 焊接：淘宝上 10 块钱的 200W 加热台（灯珠拆焊台）就能用；锡膏可以多挤一些，防止虚焊；QFN 封装的芯片，化锡后用镊子压一下，把多余焊锡挤出来，防止连锡；务必买一管针管装助焊剂 + 一管锡膏，两支可以用很久。
• 通电前，务必测量所有电源与 GND 是否短路，模组的相邻引脚是否短路！IO18 有接了一颗 LED，可以先刷入点灯代码测试是否正常，再焊接背面。
• 休眠：目前休眠功能还有点问题，休眠后会睡死唤不醒，可以按 RESET 键重启。

11. 许可证

📜 开源协议

本项目基于 GNU General Public License v2.0 开源。

组件	协议	说明
nofrendo	GPL v2	NES 模拟器核心
Retro-Go	GPL v2	游戏系统
LVGL	MIT	图形界面
esp-wifi-connect	子模块引用	WiFi 连接
XiaoZhi AI	MIT	语音助手
和风天气	免费 API	天气数据

12. 致谢

🙏 致谢