Kaotings/KT25-1015_AC695x_SDK310
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
b499020541
KT25-1015_AC695x_SDK310/Doc/音频板开发需求对照与实现状态.md

243 lines
12 KiB
Markdown
Raw Normal View History

根据需求excel表格修改,修改完成,等待测试
2026-07-25 12:48:18 +00:00
# 音频板开发需求对照与实现状态
> **文档版本**：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)`，KUP_LED 常亮 3s 后慢闪
- K6（VOL-）：音量 > 2 时 `KEY_VOL_DOWN`，KDOWN_LED 常亮 3s 后慢闪
### 4.3 LED 行为对照（需求 vs 当前）
| LED 类型 | 需求（20260717） | 当前实现 |
| ------------ | ----------------------- | -------------- |
| SYS_LED | 待机慢闪 / 播放常亮 / 报错快闪 | ✅ 已实现 |
| KEY_LED（按键灯） | 待机：4 路同步慢闪；播放：当前路常亮，其它灭 | ✅ 已实现并通过 |
| LED_BAR（灯条） | 播放：当前通道常亮；待机：全灭 | ✅ 已实现并通过 |
| KUP / KDOWN | 播放时常亮 | 🛠️ 播放时仍慢闪，待修改 |
### 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 跟踪表为准。*
Reference in New Issue Copy Permalink