244 lines
12 KiB
Markdown
244 lines
12 KiB
Markdown
# 音频板开发需求对照与实现状态
|
||
|
||
> **文档版本**：V1.0
|
||
> **生成日期**：2026-07-25
|
||
> **需求来源**：[音频板开发需求 20260725.xls](./音频板开发需求%2020260725.xls)
|
||
> **调试基准**：20260717 样机功能（以 Excel「版本1」跟踪表为准）
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
AC695x SDK 音频板定制固件，主要实现：
|
||
|
||
- SD 卡 / U 盘读取并播放 MP3、WAV、FLAC、APE
|
||
- 4 路光纤 + 3.5mm 立体声输出（经 CS8406）
|
||
- K1~K4 通道播放与切歌，K5/K6 音量调节
|
||
- U 盘 OTA 升级及提示音
|
||
- 多路 LED：系统灯、按键灯、灯条、音量灯
|
||
|
||
**核心代码路径**：
|
||
|
||
|
||
| 模块 | 文件 |
|
||
| -------- | -------------------------------------------------------------------- |
|
||
| 主逻辑 | `apps/kaotings/kt.c`、`apps/kaotings/kt.h` |
|
||
| 按键入口 | `apps/soundbox/task_manager/music/music.c` |
|
||
| 音量默认/不记忆 | `cpu/br23/audio_config.h`、`cpu/br23/audio_common/app_audio.c` |
|
||
| U 盘升级检测 | `apps/soundbox/include/app_config.h` |
|
||
| 升级提示 | `apps/common/update/update.c`、`apps/common/dev_manager/dev_update.c` |
|
||
|
||
|
||
---
|
||
|
||
## 2. 硬件引脚定义（当前 `kt.h`）
|
||
|
||
|
||
| 功能 | 引脚 | 宏定义 |
|
||
| -------------------------- | ------------------------- | ------------------------ |
|
||
| 系统指示灯 SYS_LED | PB03 | `SYS_LED_PIN` |
|
||
| 音频输出 CH1~CH4（CS8406 TX EN） | PB10 / PB09 / PB08 / PB07 | `AUDIO_OUT_CHANNEL1~4` |
|
||
| **按键灯** KEY_LED CH1~CH4 | PC02 / PC01 / PC00 / PA12 | `KEY_LED_OUT_CHANNEL1~4` |
|
||
| **灯条** LED_BAR CH1~CH4 | PA09 / PA10 / PB02 / PB11 | `LED_BAR_OUT_CHANNEL1~4` |
|
||
| 音量+ 灯 KUP_LED | PC03 | `KUP_LED_PIN` |
|
||
| 音量- 灯 KDOWN_LED | PB00 | `KDOWN_LED_PIN` |
|
||
| CS8406 复位 | PA06 | 代码中 `IO_PORTA_06` |
|
||
|
||
|
||
> **注意**：按键灯与灯条为两路独立输出，代码分别使用 `KEY_LED_`* 与 `LED_BAR_*`。两组引脚归属已经过实机校正。
|
||
|
||
---
|
||
|
||
## 3. 需求跟踪总表
|
||
|
||
调试基准为 Excel「版本1」表（20260718），状态说明：
|
||
|
||
- ✅ **通过**：已验证符合需求
|
||
- 🛠️ **待修改**：已实现但与需求不符，或功能缺失
|
||
- ⚠️ **待验证**：代码已有，尚未实测确认
|
||
|
||
|
||
| 需求 ID | 模块 | 需求摘要 | 验证状态 | 实现/差异说明 |
|
||
| ----------- | ------ | ----------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
|
||
| **AID-001** | 文件排序 | 按 `00/01/02…` 命名顺序播放；未命名文件也应能播放 | ⚠️ 待验证 | 空闲按键优先 `kt_play_file_idx(0)` 播 `00.`*；失败回退 `music_player_play_first_file()`，待实测非 `00` 文件及后续切歌顺序 |
|
||
| **AID-002** | 按键映射 | K1~~K4 对应 CH1~~CH4；K1↔K4、K2↔K3 需交换 | ✅ 通过 | 按键、音频通道和灯条映射已实测通过 |
|
||
| **AID-003** | 待机状态 | 上电待机，所有**按键灯**同步慢闪（约 1s 一次） | ✅ 通过 | 4 路 `KEY_LED` 同步慢闪，`LED_BAR` 待机全灭 |
|
||
| **AID-004** | 按键播放 | 待机按 Kx 播 `00`，对应通道出声；当前 KEY_LED + KUP/KDOWN 常亮，其它 KEY_LED 灭 | ⚠️ 待验证 | 通道播放、当前 `KEY_LED` 和 `LED_BAR` 状态正常；`KUP_LED/KDOWN_LED` 播放时常亮效果待复测 |
|
||
| **AID-005** | 播完恢复 | 单曲播完恢复待机，所有灯恢复 | ✅ 通过 | 播完关闭通道并恢复待机灯态，实测通过 |
|
||
| **AID-006** | 播放切通道 | 播放中按其它通道键，只切输出不换曲 | ✅ 通过 | `kt_switch_channel_only()` → `kt_channel_outputs_on()` |
|
||
| **AID-007** | 同通道下一曲 | 播放中再按当前通道键，播下一首（00→01→02…循环） | ✅ 通过 | 先 `kt_play_file_idx(idx+1)`，失败再 `music_player_play_next()` |
|
||
| **AID-008** | 音量 | 2~30 格，默认 23，±1，不记忆 | ✅ 通过 | 默认值、上下限、±1 步进及不记忆逻辑已实测通过 |
|
||
| **AID-009** | 灯条 | 仅当前通道灯条亮，待机全灭 | ✅ 通过 | `LED_BAR` 仅当前播放通道常亮，待机全灭，实测通过 |
|
||
| **AID-010** | 格式支持 | MP3 / WAV / FLAC / APE | ✅ 通过 | SDK 播放器原生支持 |
|
||
| **AID-011** | 系统指示灯 | 慢闪待机、快闪报错、常亮播放 | ✅ 通过 | `KT_LED_IDLE/FAIL/PLAY/UPDATE` 状态机 |
|
||
| — | VOL+ | 按一次 +1 格 | ✅ 通过 | `KEY_USER_KEY_5` → `KEY_VOL_UP` |
|
||
| — | VOL- | 按一次 -1 格 | ✅ 通过 | `KEY_USER_KEY_6` → `KEY_VOL_DOWN`（最小 2） |
|
||
|
||
|
||
---
|
||
|
||
## 4. 功能逻辑说明（20260717 调试版）
|
||
|
||
### 4.1 按键 K1~K4（通道键）
|
||
|
||
```
|
||
待机（active_ch == 0）
|
||
└─ 按 Kx → 播 00.*（sd1 优先，udisk0 次之）
|
||
→ 失败则播盘内第一首
|
||
→ 成功：开 CHx 音频 + 灯条，SYS_LED 常亮
|
||
|
||
播放中（active_ch != 0 且 decoding）
|
||
├─ 同通道再按 → idx+1 下一曲（失败则 player next）
|
||
└─ 异通道按 → 只切 AUDIO/灯条，不换曲
|
||
|
||
播完 / 拔卡 / 出错
|
||
└─ kt_music_play_end_handler()
|
||
→ 关通道、active_ch=0、music_player_stop(0)
|
||
→ 音量恢复 23、SYS_LED 慢闪
|
||
```
|
||
|
||
### 4.2 按键 K5 / K6（音量键）
|
||
|
||
- K5（VOL+）：`app_task_put_key_msg(KEY_VOL_UP)`
|
||
- K6（VOL-）：音量 > 2 时 `KEY_VOL_DOWN`
|
||
- 灯态：播放时与当前 KEY_LED 一起常亮；待机时与其它按键灯同步慢闪（无按后单独亮 3s）
|
||
|
||
### 4.3 LED 行为对照（需求 vs 当前）
|
||
|
||
|
||
| LED 类型 | 需求（20260717） | 当前实现 |
|
||
| ------------ | ----------------------- | -------------- |
|
||
| SYS_LED | 待机慢闪 / 播放常亮 / 报错快闪 | ✅ 已实现 |
|
||
| KEY_LED（按键灯） | 待机：4 路同步慢闪；播放：当前路常亮，其它灭 | ✅ 已实现并通过 |
|
||
| LED_BAR（灯条） | 播放：当前通道常亮；待机：全灭 | ✅ 已实现并通过 |
|
||
| KUP / KDOWN | 播放常亮；待机与 KEY_LED 同步慢闪 | ✅ 已实现 |
|
||
|
||
|
||
### 4.4 U 盘升级
|
||
|
||
|
||
| 阶段 | 行为 |
|
||
| ----- | -------------------------------------------------------------------------- |
|
||
| 检测 | `TCFG_DEV_UPDATE_IF_NOFILE_ENABLE = 0`，设备上线即 `dev_update_check` |
|
||
| 升级中 | `kt_update_led_start()`：SYS_LED 快闪；`kt_update_start_remind()` 播 `TONE_SUP` |
|
||
| 升级完成 | 成功播 `TONE_EUP`；`kt_update_led_finish()` 恢复 LED |
|
||
| 提示音通路 | CS8406 RST 释放 → 4 路 AUDIO 全开 → `app_audio_output_start` → 等 START/STOP |
|
||
|
||
|
||
**已知限制**：SDK `update_success_boot_check()` 在同一次开机内会拦截相同 UFW 重复升级。
|
||
|
||
---
|
||
|
||
## 5. 已修复问题记录
|
||
|
||
|
||
| 问题 | 原因 | 修复 |
|
||
| ------------------------- | -------------------------------------------- | -------------------------------------------- |
|
||
| U 盘不能升级 | `TCFG_DEV_UPDATE_IF_NOFILE_ENABLE=1` 仅无文件时检测 | 改为 `0` |
|
||
| 升级提示音偶发无声 | 异步 `tone_play` + 通道/CS8406 未就绪 | RST 时序 + 4 路全开 + 等 START/STOP |
|
||
| 播完再按键功能异常 | `active_ch=0` 但 `get_play_status()` 仍为 PLAY | 播完 `music_player_stop(0)`；判断加 `active_ch!=0` |
|
||
| `kt_voltage_all_off` 编译错误 | 函数定义顺序 | 调整函数顺序 |
|
||
| BT_LED 改名 | 需求统一为系统灯 | 全部改为 `SYS_LED` |
|
||
|
||
|
||
---
|
||
|
||
## 6. 待办事项（建议优先级）
|
||
|
||
### P0 — 待测试
|
||
|
||
1. **AID-001 文件排序**
|
||
- 验证无 `00.*` 时能否从待机播放普通命名文件，以及回退播放后的下一曲顺序
|
||
- 测试结果出来前暂不修改播放逻辑
|
||
2. **AID-004 播放灯态**
|
||
- 复测播放时当前 `KEY_LED`、`KUP_LED/KDOWN_LED` 是否持续常亮，其他 `KEY_LED` 是否熄灭
|
||
|
||
### P2 — 可选
|
||
|
||
1. 同开机重复升级测试：评估是否绕过 `update_success_boot_check`
|
||
2. 配置文件化按键/灯效（需求文档「备用功能」栏）
|
||
|
||
---
|
||
|
||
## 7. 测试检查清单
|
||
|
||
### 基本播放
|
||
|
||
- [x] 上电待机：4 路 KEY_LED 同步慢闪（约 1s），LED_BAR 全灭，SYS_LED 慢闪
|
||
- [ ] 待机按 K1：播 `00.*`，CH1 有声，K1 + KUP + KDOWN 常亮，其它 KEY_LED 灭，CH1 灯条亮
|
||
- [x] 待机按 K2/K3/K4：通道、按键灯和灯条对应正确
|
||
- [x] 单曲播完：恢复待机灯态，音量回到 23
|
||
- [x] 播放中按异通道：不换曲，灯条/按键灯跟随
|
||
- [x] 播放中按同通道：下一曲 00→01→02…
|
||
|
||
### 文件与通道
|
||
|
||
- [x] SD 卡 `00.mp3` 与 U 盘同时存在：优先 SD
|
||
- [x] 文件命名为 `AA.mp3`（非 00）：待机按键可播
|
||
- [x] K1/K4、K2/K3 物理位置与 CH 对应正确
|
||
|
||
### 音量
|
||
|
||
- [x] 默认音量 23
|
||
- [x] VOL+ 每次 +1，最大 30
|
||
- [x] VOL- 每次 -1，最小 2
|
||
- [x] 播完/待机后再播，音量恢复 23
|
||
|
||
### 升级
|
||
|
||
- [x] U 盘根目录放 `update.ufw`，上电可升级
|
||
- [x] 升级中 SYS_LED 快闪，播 `sup` 提示音
|
||
- [x] 升级成功播 `eup` 提示音，LED 恢复
|
||
|
||
### 异常
|
||
|
||
- [x] 无 `00.*` 且无音乐文件：对应通道快闪报错
|
||
- [ ] 拔卡/拔 U 盘：停止播放，恢复待机
|
||
|
||
---
|
||
|
||
## 8. 关键代码索引
|
||
|
||
### 按键分发（`music.c`）
|
||
|
||
```c
|
||
case KEY_USER_KEY_1 ~ KEY_USER_KEY_6:
|
||
err = kt_key_event_handler(key);
|
||
```
|
||
|
||
### 通道键核心（`kt.c`）
|
||
|
||
- `kt_channel_key_handler()` — 空闲播 00 / 同通道 next / 异通道切换
|
||
- `kt_play_success()` / `kt_play_fail()` — 成功/失败灯态
|
||
- `kt_music_play_end_handler()` — 播完收尾
|
||
|
||
### 音量
|
||
|
||
```c
|
||
// cpu/br23/audio_config.h
|
||
#define SYS_DEFAULT_VOL 23
|
||
|
||
// kt.c
|
||
static void kt_vol_reset_default(void);
|
||
```
|
||
|
||
### 升级开关
|
||
|
||
```c
|
||
// apps/soundbox/include/app_config.h
|
||
#define TCFG_DEV_UPDATE_IF_NOFILE_ENABLE 0
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 版本历史
|
||
|
||
|
||
| 版本 | 日期 | 说明 |
|
||
| ---- | ---------- | -------------------- |
|
||
| V1.0 | 2026-07-25 | 初版：需求对照、实现状态、待办与测试清单 |
|
||
|
||
|
||
---
|
||
|
||
*本文档由固件开发过程自动整理，如有需求变更请以最新 Excel 跟踪表为准。* |