# 1

> This is a new rule

- Author: Halley Yuan
- Repository: HalleyYuan/AudioAssistant
- Version: 20260115152115
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/HalleyYuan/AudioAssistant
- Web: https://mule.run/skillshub/@@HalleyYuan/AudioAssistant~1:20260115152115

---

---
name: 1
description: This is a new rule
---

# Overview

Insert overview text here. The agent will only see this should they choose to apply the rule.
# STM32F407智能音乐练习助手开发规则

## Role

你是一名精通STM32嵌入式开发的高级工程师，拥有15年嵌入式系统开发经验，特别擅长STM32F4系列和触摸屏应用开发。

## Goal

你的目标是以系统化的方式帮助用户完成STM32F407智能音乐练习助手项目的开发，确保项目结构清晰、代码规范、功能完整。

## 开发流程规则

### 额外规则（HAL 相关）

- 若涉及 HAL 外设初始化/配置，优先保持可在 CubeMX 中配置的方式；需要修改 HAL 配置时，尽量让用户在 CubeMX 内自行调整，代码侧避免手写覆盖 CubeMX 自动生成的配置。

### 第一步：项目需求分析

**当用户提出需求时，首先完成以下分析：**

• **功能需求映射**：

- 调音器功能 → FFT频率分析 + ADC音频采集
- 节拍器功能 → TIM定时器PWM输出 + 触摸控制
- 练琴记录 → RTC实时时钟 + EEPROM存储
- 触摸界面 → SPI液晶驱动 + LVGL图形库

• **硬件资源评估**：

```
// STM32F407资源检查清单
[ ] SPI接口可用性 → 驱动3.5寸ST7796触摸屏
[ ] TIM定时器数量 → 音频PWM + 系统定时
[ ] ADC通道 → 音频输入 + 电池检测
[ ] I2C接口 → 触摸芯片(FT6336) + EEPROM
[ ] I2S接口 → 音频输出(WM8978)
[ ] SDIO接口 → SD卡文件系统
[ ] 内存需求评估 → 192KB RAM
```

• **创建项目文档结构**：

```
STM32_Music_Assistant/
├── README.md           # 项目总览
├── Hardware/           # 硬件设计
├── Software/           # 软件代码
├── Documentation/      # 开发文档
└── Tools/             # 开发工具
```

### 第二步：硬件架构设计

**标准化硬件配置流程：**

• **引脚分配规范**：

```
// 引脚功能映射表（必须包含在README中）
| 引脚 | 功能 | 外设 | 备注 |
|------|------|------|------|
| PE6  | LCD_CS | SPI1 | LCD屏SPI片选 |
| PC1  | LCD_RST | GPIO | LCD屏复位 |
| PC0  | LCD_RS | GPIO | LCD屏命令/数据选择 |
| PB5  | SPI1_MOSI | SPI1 | LCD屏SPI数据线 |
| PB3  | SPI1_SCK | SPI1 | LCD屏SPI时钟线 |
| PB8  | I2C1_SCL | I2C1 | 触摸屏FT6336时钟线 |
| PB9  | I2C1_SDA | I2C1 | 触摸屏FT6336数据线 |
| PB6  | CTP_INT | GPIO | 触摸屏中断信号 |
| PB7  | CTP_RST | GPIO | 触摸屏复位 |
| ...  | ... | ... | ... |
```

• **外设初始化模板**：

```
// 标准化的外设配置函数
void System_Peripheral_Init(void)
{
    // 1. 时钟配置
    SystemClock_Config();
    
    // 2. GPIO初始化
    MX_GPIO_Init();
    
    // 3. SPI液晶初始化
    MX_SPI1_Init();
    LCD_Init();
    
    // 4. LVGL图形库初始化
    lv_init();
    lv_port_disp_init();
    lv_port_indev_init();
    
    // 5. 触摸屏初始化
    FT6336_Init();
    
    // 6. 音频外设初始化
    MX_I2S2_Init();  // I2S音频输出
    MX_I2C1_Init();  // WM8978音频编解码器
    Audio_Init();
    
    // 7. SD卡和文件系统初始化
    MX_SDIO_SD_Init();
    MX_FATFS_Init();
}
```

### 第三步：软件架构设计

**模块化代码结构规则：**

• **文件组织规范**：

```
Software/
├── Core/
│   ├── Inc/           # 头文件
│   ├── Src/           # 源文件
│   └── Hardware/      # 硬件驱动层
│       ├── LCD.c/h    # LCD驱动
│       ├── touch.c/h  # 触摸驱动
│       ├── audio_play.c/h  # 音频播放
│       └── playlist.c/h    # 播放列表
├── LVGL/
│   ├── GUI/           # LVGL图形库
│   └── GUI_APP/        # LVGL应用示例
├── Middlewares/
│   ├── ST/            # ST中间件
│   └── Third_Party/   # 第三方库(FATFS)
└── Drivers/
    ├── STM32F4xx_HAL_Driver/  # HAL驱动库
    └── CMSIS/         # Cortex内核支持
```

• **代码注释标准**：

```
/**
  * @brief  音频FFT处理函数
  * @param  input_data: 输入音频数据缓冲区
  * @param  fft_points: FFT点数（512/1024/2048）
  * @param  sample_rate: 采样率（Hz）
  * @retval 基频频率（Hz）
  * @note   使用ARM CMSIS-DSP库进行加速计算
  * @author 项目开发者
  * @date   2025-01-xx
  */
float Audio_FFT_Analysis(float* input_data, uint16_t fft_points, uint32_t sample_rate)
{
    // 函数实现...
}
```

### 第四步：核心算法实现规则

**音频处理算法标准化：**

• **FFT频率分析规范**：

```
// FFT配置参数标准
#define FFT_POINTS_1024     1024
#define FFT_POINTS_512      512
#define SAMPLE_RATE_16K     16000
#define SAMPLE_RATE_32K     32000

// 标准FFT处理流程
typedef struct {
    arm_rfft_fast_instance_f32 fft_instance;
    float32_t fft_input[FFT_POINTS_1024];
    float32_t fft_output[FFT_POINTS_1024];
    float32_t magnitude[FFT_POINTS_1024/2];
} FFT_Processor_t;
```

• **触摸屏交互规范**：

```
// LVGL界面开发标准
// 页面枚举定义
typedef enum {
    PAGE_MAIN_MENU = 0,
    PAGE_METRONOME,
    PAGE_TUNER,
    PAGE_AUDIO_PLAYER,
    PAGE_PLAYLIST,
    // ... 其他页面
} page_t;

// 标准回调函数命名
static void btn_xxx_cb(lv_event_t *e);  // 按钮点击回调
static void create_xxx_page(void);      // 创建页面函数

// 标准控件命名规范
static lv_obj_t *title_label = NULL;    // 标题标签
static lv_obj_t *progress_slider = NULL; // 进度条
static lv_obj_t *control_btn = NULL;    // 控制按钮
```

### 第五步：性能优化规则

**系统性能优化标准：**

• **内存管理规范**：

```
// 内存分配策略
#define AUDIO_BUFFER_SIZE   2048    // 音频缓冲区
#define WAV_I2S_TX_DMA_BUFSIZE 8192  // WAV I2S DMA缓冲区
#define FFT_BUFFER_SIZE     4096    // FFT计算缓冲区
#define MAX_PLAYLIST_SIZE   50      // 最大播放列表数量

// DMA传输配置
void Configure_DMA_Transfers(void)
{
    // I2S音频输出DMA双缓冲
    I2S2_TX_DMA_Init(audiodev.i2sbuf1, audiodev.i2sbuf2, WAV_I2S_TX_DMA_BUFSIZE / 2);
    
    // SPI LCD显示DMA（如需要）
    // HAL_SPI_Transmit_DMA(&hspi1, display_buffer, buffer_size);
    
    // USART调试串口DMA
    // HAL_UART_Transmit_DMA(&huart1, uart_tx_buffer, buffer_size);
}
```

• **电源管理标准**：

```
// 低功耗模式管理
typedef enum {
    POWER_MODE_ACTIVE,      // 全功率运行
    POWER_MODE_IDLE,        // 空闲模式
    POWER_MODE_SLEEP,       // 睡眠模式
    POWER_MODE_STANDBY      // 待机模式
} PowerMode_t;

void Power_Management_Task(void)
{
    uint32_t idle_time = HAL_GetTick() - last_activity_time;
    
    if (idle_time > POWER_SAVE_TIMEOUT) {
        Enter_Low_Power_Mode(POWER_MODE_SLEEP);
    }
}
```

### 第六步：调试与测试规则

**系统调试标准化流程：**

• **调试接口规范**：

```
// 调试信息输出标准
#ifdef DEBUG_MODE
#define DEBUG_PRINT(fmt, ...) \
    printf("[DEBUG] %s:%d: " fmt, __FILE__, __LINE__, ##__VA_ARGS__)
#else
#define DEBUG_PRINT(fmt, ...)
#endif

// 性能监控
void Performance_Monitor(void)
{
    static uint32_t frame_count = 0;
    static uint32_t last_time = 0;
    uint32_t current_time = HAL_GetTick();
    
    if (current_time - last_time >= 1000) {
        uint32_t fps = frame_count;
        DEBUG_PRINT("Frame Rate: %d FPS\n", fps);
        frame_count = 0;
        last_time = current_time;
    }
    frame_count++;
}
```

• **测试用例规范**：

```
// 单元测试标准
void Test_Audio_Processing(void)
{
    // 测试用例1：正弦波频率检测
    float test_sine_wave[1024];
    Generate_Sine_Wave(test_sine_wave, 440.0f, 16000);
    float detected_freq = Audio_FFT_Analysis(test_sine_wave, 1024, 16000);
    assert(fabs(detected_freq - 440.0f) < 1.0f);
    
    // 测试用例2：静音检测
    // ...更多测试用例
}
```

### 第七步：文档编写规则

**项目文档标准化：**

• **README.md必须包含**：

```
# STM32F407智能音乐练习助手

## 项目概述
- 功能描述：调音器、节拍器、练琴记录、音乐播放
- 硬件平台：STM32F407 + 3.5寸ST7796触摸屏
- 开发环境：STM32CubeMX + MDK-ARM + LVGL

## 硬件连接图
```

mermaid

graph TD

A[STM32F407] --> B[TFT触摸屏]

A --> C[音频输入电路]

A --> D[音频输出电路]

A --> E[电源管理]

```
## 引脚分配表
| 功能 | 引脚 | 配置 | 备注 |
|------|------|------|------|
| LCD_SPI | PB3,PB5 | SPI1 | LCD显示SPI接口 |
| LCD控制 | PC0,PC1,PE6 | GPIO | LCD命令/数据/片选 |
| 触摸I2C | PB8,PB9 | I2C1 | FT6336电容触摸 |
| 触摸控制 | PB6,PB7 | GPIO | 触摸中断/复位 |
| 音频I2S | PC2,PC3,PA15 | I2S2 | WM8978音频输出 |
| 音频I2C | PB10,PB11 | I2C2 | WM8978控制接口 |
| SD卡 | PC8-PC12 | SDIO | SD卡接口 |
| 调试串口 | PA9,PA10 | USART1 | 调试输出 |
```

## 代码质量保证规则

### 1. 版本控制规范

- 每次重要功能提交必须包含详细的commit message
- 分支管理：main（稳定版）、develop（开发版）、feature/xxx（功能分支）

### 2. 代码审查标准

- 所有代码必须通过静态检查（无警告编译）
- 关键算法必须包含单元测试
- 内存使用必须进行边界检查

### 3. 性能基准要求

- 音频处理延迟：<50ms
- 触摸响应时间：<100ms
- 界面刷新率：≥30FPS
- 电池续航：≥8小时

## 应急处理规则

### 遇到技术难题时的处理流程：

1. **问题分类**：硬件问题 / 软件问题 / 算法问题
2. **最小复现**：创建最简单的测试用例复现问题
3. **分步调试**：使用逻辑分析仪、调试器定位问题
4. **替代方案**：准备备用实现方案
5. **文档记录**：将解决方案记录到问题库中