# 🎵 ESP32 智能音响控制系统 (AirPlay 2 & Bluetooth & AUX)

[![ESP-IDF](https://img.shields.io/badge/ESP--IDF-v5.x-red?style=flat-square)](https://docs.espressif.com/projects/esp-idf/)
[![Platform](https://img.shields.io/badge/platform-ESP32-green?style=flat-square)](https://www.espressif.com/en/products/socs/esp32)

**将您的 ESP32 打造成一台支持 Apple AirPlay 2、蓝牙 A2DP 和 AUX 模拟输入的高端智能无线音响中控！**

---

## ✨ 核心特性

本项目基于开源的 `airplay-esp32` 深度定制，针对专用音响硬件进行了全面升级：

1. **多音源无缝切换**：
   - 🍏 **AirPlay 2**：原生支持苹果生态无损串流，手机/Mac 直接控制。
   - 📶 **Bluetooth A2DP**：支持任何手机/平板蓝牙直连播放，完美处理蓝牙意外断开与回连。
   - 🔌 **AUX 模拟输入**：支持传统有线音源输入。
2. **专业级音频控制 (NJW1195A)**：
   - 通过 SPI 总线深度集成 `NJW1195A` 音频处理芯片。
   - 支持硬件级的主音量控制（0~100级）。
   - 支持高低音 (Bass/Treble) EQ 独立调节。
3. **UART 外部面板通信协议**：
   - 内置完整的串口通信协议 (`panel_uart.c`)，可与外部屏幕、按键面板或 MCU 进行双向通信。
   - 支持同步电量、充电状态、播放状态、音源切换等。
4. **极致体验的 Web UI (PWA 原生应用级体验)**：
   - **暗黑鎏金主题**：高级质感的深色系 UI 设计。
   - **PWA 支持**：在 iOS Safari 中点击“添加到主屏幕”，即可拥有完美适配刘海屏/灵动岛的全屏原生 App 体验，沉浸式操控！
   - **实时状态同步**：毫秒级同步当前播放歌曲、艺术家、专辑进度条，以及电池电量和网络状态。
   - **OTA 在线升级**：支持直接通过网页后台一键升级固件。

---

## 🛠️ 硬件与引脚配置

该固件专为搭配了 `NJW1195A` 芯片和外部通信串口的定制 ESP32 硬件设计：

- **I2S 音频输出**：用于连接 DAC 解码音频数据。
- **SPI 总线 (NJW1195A)**：
  - `SPI_CLK` / `SPI_DATA` / `SPI_CS`：用于控制 NJW1195A 的音量和通道切换。
- **UART 控制面板**：
  - 默认使用 `UART2` (TX: GPIO4, RX: GPIO5)，波特率 `115200`，用于与外部控制板交互。

---

## 🚀 快速上手与编译

项目使用 **ESP-IDF v5.x** 进行构建。

### 1. 编译与烧录

确保您已经正确安装并配置了 ESP-IDF 环境：

```bash
# 1. 激活 ESP-IDF 环境
. $HOME/esp/esp-idf/export.sh

# 2. 设置目标芯片为 ESP32 (或 ESP32-S3，取决于您的实际硬件)
idf.py set-target esp32

# 3. 编译并烧录固件
idf.py build
idf.py -p /dev/ttyUSB0 flash monitor
```

*(注意：如果是首次烧录，或者修改了网页文件 `data/www/index.html`，需要同步烧录 SPIFFS 分区)*

### 2. 首次配网 (Setup)

1. 给 ESP32 上电开机。
2. 拿出手机，连接名为 **`ESP32-AirPlay-Setup`** 的 Wi-Fi 热点。
3. 手机会自动弹出配置页面（如果没有，请浏览器访问 `192.168.4.1`）。
4. 在页面中输入您家的 Wi-Fi 密码，并为您的高级音响起一个名字（比如“客厅音响”）。
5. 保存后 ESP32 会自动重启并连入您家路由器的网络。

### 3. 使用原生 Web 控制面板 (PWA)

为了获得最佳体验，强烈建议您在苹果手机上将其安装为原生应用：
1. 确保手机和音响在同一局域网下。
2. 打开 iPhone 上的 **Safari 浏览器**，在地址栏输入：`http://您的音响名称.local`（例如 `http://musicbox.local`，无需查找复杂且会变动的 IP 地址！借助苹果原生的 mDNS 即可秒连）。
3. 点击浏览器底部的 **“分享”** 图标 ➡️ 选择 **“添加到主屏幕”**。
4. 回到桌面，点击新添加的独立 App 图标，即可享受沉浸式、无刘海遮挡的丝滑控制体验！

---

## 📝 固件版本修改

如果您需要发布新版本固件，只需修改项目根目录下的 `version.txt` 文件内容（例如修改为 `1.2.0`）。
在下次执行 `idf.py build` 时，CMake 会自动将该版本号编译进固件中，并在网页控制台的右上角同步展示。

---

## ⚖️ 许可 (License)

本项目基于原 `airplay-esp32` 开发，遵循非商业开源协议。禁止未经授权用于任何商业盈利用途。