小澔智能音响 · 快速上手

核心元件

• ESP32-S3-DevKitC-1 开发板（推荐 N16R8：16MB Flash + 8MB OPI PSRAM，小智模块同款）
• MAX98357 I2S 功放模块 + 喇叭
• SSD1306 OLED 128×32（I2C）
• Mini SD 卡模块（SPI，平台音频同步）
• IP5306 充放电模块 + 3.7V 锂电池
• 非自复位电源键、自复位音量+/−/暂停键

bread-compact-wifi 推荐接线

与 xiaozhi-esp32 面包板新版（WiFi）一致，开发板 ID：bread-compact-wifi

电源键为非自复位，由 IP5306 负责充放电与开关机；固件开机默认 SD 卡音频模式，长按暂停键切换手机 WiFi 推流模式（ESP32-S3 不支持经典蓝牙 A2DP）。

1. 在「设备管理」绑定硬件后，点击 固件编译，选择开发板类型并创建编译。
2. 推荐使用 Chrome 或 Edge，USB 连接 ESP32，在编译历史中点击 烧录。ESP32-S3-DevKitC 有两个 USB-C：优先插 UART 口（CP210x）。若插的是原生 USB 口，须先按住 BOOT → 点 RST → 再选串口。
3. 网页烧录会先全片擦除 Flash再写入；新固件首次启动会清空 SD 上的旧音频，再从 OSS 重新下载。
4. 若网页烧录不可用，可点击 下载源码 (.ino)，用 Arduino IDE 打开并烧录（需安装 esp32 开发板包及相关库）。
5. 平台地址（app.public-url）留空即可：启动时自动检测本机局域网 IP，并写入 config/application.yml。换网络后重启 Spring Boot，再重新「创建烧录包」更新 NVS。
6. 也可手动运行 ./scripts/sync-public-url.sh 同步 IP 到配置文件。
7. Arduino IDE 烧录时：Flash 16MB，PSRAM 选 OPI PSRAM（N16R8 板必选项；若选 QSPI/enabled 会报 PSRAM chip not found）。
8. 烧录后可用编译页 📟 监视器 查看实时串口日志（115200，Chrome/Edge）。

首次配网和更换网络都用手机连设备热点完成，不必拆机烧录。平台配网页仅在设备仍在线时可选。

1. 注册 / 登录 audio-system 平台。
2. 设备管理 → 绑定新设备：填写 ESP32 序列号（建议用 MAC，如 ESP32-AABBCCDDEEFF）与名称。
3. 固件编译 并烧录到 ESP32-S3（必须先烧录，固件内已写入设备令牌与平台地址）。
4. 音响上电。首次：手机连热点 XH-Setup-设备序列号，选 2.4G WiFi（无需平台网页）。
5. 需要更换 WiFi：按第五节长按音量减 5 秒，手机连热点重新选网。机壳封装后也不必拆开烧录。
6. 需要升级固件：按第六节在管理端发布已生效固件，音响联网后自动升级。
7. 连接成功后平台显示在线，音响自动拉取音频并流式播放。

音响封在机壳里之后，换路由器或改密码不必拆机、不必插线烧录。用音量减重新打开配网热点即可。

1. 音响上电。长按音量减 5 秒，屏幕显示「配网热点」。
2. 手机 WiFi 列表里连接 XH-Setup-设备序列号（无密码）。部分手机会自动弹出配网页；没有弹出时，浏览器打开 192.168.4.1。
3. 在列表里选择新的 2.4G WiFi 并输入密码。ESP32 不支持 5G，5G 网络不会出现。
4. 提交后音响去连新网络。成功会完整播放 wifi_success.mp3，失败播放 wifi_fail.mp3，可再长按音量减重试。
5. 连上后平台「设备管理」显示在线，音频继续按资源库同步播放。

旧网已经连不上时

• 上电后连旧 WiFi 失败约 40 秒，会自动再开 XH-Setup-序列号，操作与上面相同。
• 连续两次连不上也会自动开热点，不必干等。
• 平台「设备配网」页的「提交 WiFi」只在音响当前仍在线时可用；已经换环境离线时，必须用热点。

正式「设备管理」对管理员和普通用户相同，只使用已发布稳定包。本机先编译再启动，调试页只用这份预编译包。OTA 和设备调试都可以分配给管理员。

1. 改固件后先跑 ./scripts/build-prebuilt-firmware.sh，再启动服务。打开 设备调试 创建烧录包（只写 NVS，不现场编译），测稳后再把 *merged.bin 上传到 OSS。
2. 在设备调试页或 OTA 固件 点 发布。发布后，正式设备管理创建烧录包和在线音响才会用这一份。
3. 普通用户和管理员在「设备管理」看到的是同一套页面，只能拿已发布稳定包 + 设备 NVS。
4. 音响检测到新版本会完整播放 ota_upgrade.mp3，成功后播放 ota_success.mp3 再重启。升级时不要断电。

注意

• OTA 菜单和发布操作不会出现在权限分配里，也无法授权给普通管理员。
• 离线设备不会升级；下次联网后会自动补升。
• 第一次从旧分区表换成可 OTA 分区时，仍需 USB 烧录一次；之后即可只靠 OTA。
• 网页上传请选整包 *merged.bin；设备 OTA 实际下发的是从中切出的应用分区。