嵌入式PWM音频驱动：无源蜂鸣器与扬声器精确发声方案

1. PwmSpeaker 库概述

PwmSpeaker 是一个轻量级、无依赖的嵌入式音频驱动库，专为资源受限的微控制器设计，其核心目标是仅通过硬件 PWM 外设驱动无源蜂鸣器或小型动圈扬声器，实现音调生成、简单旋律播放与基础音频控制。它不依赖 DAC、I²S 或音频编解码器，也不引入 RTOS、标准 C++ STL 或浮点运算库，完全基于裸机（Bare-metal）或 FreeRTOS 环境下的定时器/高级控制定时器（TIM）PWM 输出能力构建。

该库的设计哲学是“用最确定的硬件资源做最可控的声音输出”。在工业人机界面（HMI）、医疗设备提示音、IoT 节点状态反馈、教育开发板发声模块等场景中，开发者往往不需要高保真音频，而更关注：

• 音调频率精度（±0.5% 内可接受）
• 启停响应时间（< 100 µs）
• 占空比可调性（支持 10%–90% 线性调节以控制响度）
• 低 CPU 占用（PWM 由硬件自动翻转，CPU 仅配置寄存器）
• 可预测的时序行为（无动态内存分配、无中断嵌套风险）

PwmSpeaker 不提供音频文件解析（如 WAV/MP3）、混音、滤波或采样率转换功能。它本质上是一个频率-占空比-时长三元组的精确执行引擎，将抽象的“播放 Do 音持续 200ms”转化为对 TIMx->ARR、TIMx->CCRy 和 HAL_TIM_PWM_Start() 的原子级调用。

其典型部署形态如下：

• MCU：STM32F0/F1/F3/F4/H7、NXP Kinetis、RISC-V GD32VF103、ESP32（使用 LEDC 或 MCPWM）
• 外设：高级控制定时器（如 STM32 的 TIM1/TIM8）或通用定时器（TIM2–TIM5），支持互补通道与死区插入（可选）
• 驱动电路：NPN/PNP 推挽、MOSFET 半桥或专用音频驱动芯片（如 TPA2005D1），支持直流偏置消除
• 发声单元：8Ω/16Ω 无源扬声器（直径 ≤ 25mm）、压电蜂鸣器（需并联阻尼电阻）、或带内置振荡器的有源蜂鸣器（此时仅作开关使能，非本库主要目标）

⚠️ 注意：本库明确不支持有源蜂鸣器的“直接驱动”模式。有源蜂鸣器内部已集成振荡电路，仅需直流电压即可发声；而 PwmSpeaker 的设计前提——即通过外部 PWM 控制频率——对其无效。若误用于此类器件，将仅产生固定频率的单一音调（取决于其内置振荡器），且无法通过库 API 改变。

2. 硬件原理与信号链分析

2.1 PWM 驱动扬声器的物理基础

扬声器本质是电-力-声换能器。当电流流过音圈时，根据洛伦兹力定律 $ F = B \cdot I \cdot L $，音圈受力带动振膜振动，从而推动空气形成声波。对于无源扬声器，输入信号的基频决定音调（pitch），幅值决定响度（loudness），波形决定音色（timbre）。

PwmSpeaker 采用方波 PWM 作为激励源，其优势在于：

• 硬件实现极简：MCU 定时器原生支持，无需额外 DAC 或外设
• 功率效率高：MOSFET 工作于饱和/截止区，导通损耗低
• 频率控制精准：ARR（自动重装载值）与 CK_PSC（时钟预分频）共同决定 PWM 周期 $ T_{PWM} = (ARR + 1) \times (PSC + 1) / f_{CLK} $，误差仅来源于时钟晶振精度（通常 ±20 ppm）

但方波含丰富奇次谐波（$ f, 3f, 5f, \dots $），直接驱动扬声器会产生刺耳高频噪声。因此，PwmSpeaker 在设计中强制要求硬件低通滤波：

MCU PWM Pin → Series Resistor (R = 10–100 Ω) → Parallel RC Filter (Rf = 100 Ω, Cf = 100 nF) → Speaker

该 RC 滤波器截止频率 $ f_c = \frac{1}{2\pi R_f C_f} \approx 16,\text{kHz} $，可有效衰减 3f 及以上谐波（例如 1 kHz 音调的 3 kHz 分量被衰减约 -10 dB），同时保留基频能量。实测表明，未加滤波时 1 kHz 方波驱动 8Ω 扬声器产生明显“嘶嘶”声；加入上述滤波后，音色显著圆润，接近正弦波效果。

2.2 关键时序约束与定时器选型

PwmSpeaker 对定时器资源提出三项硬性要求：

1. 分辨率足够：需覆盖人耳可听范围 20 Hz – 20 kHz。以 20 kHz 为例，若系统主频 $ f_{CLK} = 72,\text{MHz} $，则最大 ARR 值需满足 $ (ARR+1) \geq f_{CLK}/f_{min} = 72,\text{MHz}/20,\text{Hz} = 3.6 \times 10^6 $。16 位定时器（ARR 最大 65535）无法直接满足，必须启用预分频（PSC）。合理配置为PSC = 0x00FF（255），则有效计数频率为 $ 72,\text{MHz}/256 \approx 281.25,\text{kHz} $，此时 20 Hz 对应 ARR = 14062，完全可行。
2. 更新事件可控：频率切换必须在 PWM 周期边界发生，避免相位跳变导致“咔嗒”声（pop noise）。因此必须使用定时器的影子寄存器（shadow register）机制，即修改 ARR/CCR 后，等待 UEV（Update Event）触发才生效。HAL 库中通过__HAL_TIM_SET_AUTORELOAD()+__HAL_TIM_SET_COMPARE()配合HAL_TIM_GenerateEvent()实现。
3. 通道独立性：单音播放仅需 1 路 PWM；双音和声（如和弦）需至少 2 路独立可调频率的 PWM 通道，并确保它们的时钟源同步（共用同一 TIMx，而非 TIM1+TIM2）。STM32 高级控制定时器（TIM1/TIM8）支持 4 路互补通道，是理想选择。

下表列出常见 MCU 平台的推荐定时器配置：

2.3 电气安全与驱动能力匹配

MCU GPIO 直接驱动扬声器存在严重风险：

• STM32 GPIO 最大灌电流约 25 mA，而 8Ω 扬声器在 3.3 V 下理论电流达 412 mA（$ I = V/R $），远超限值
• 瞬态反电动势（back-EMF）可达 ±20 V，易击穿 IO 口

因此，PwmSpeaker强制要求外部功率级。典型方案包括：

方案 A：NPN+PNP 推挽（低成本，适合 ≤ 100 mW）

MCU PWM → 1kΩ → Q1(NPN, e.g. 2N2222) Base ↓ Collector → Speaker Top Q2(PNP, e.g. 2N2907) Base ← 1kΩ ← MCU PWM ↑ Emitter → Speaker Bottom Speaker Bottom → GND

优点：元件少、成本低；缺点：存在交越失真，低频响应差。

方案 B：N-MOSFET 半桥（推荐，高效可靠）

MCU PWM → Gate Driver (e.g. TC4420) → N-MOS (e.g. IRLZ44N) Gate MOS Drain → Speaker Top Speaker Bottom → GND MOS Source → GND

需注意：MOSFET 必须选用逻辑电平驱动型（$ V_{GS(th)} < 2.5,\text{V} $），并添加 10kΩ 下拉电阻确保关断。

方案 C：专用音频功放（高保真，如 TPA2005D1）

• 输入兼容 3.3 V TTL 电平
• 内置滤波与过热保护
• 支持 1.4 W @ 8Ω，THD+N < 1%
• 仅需连接 PWM 引脚至 IN+，IN- 接地，VDD 接 5 V

无论何种方案，必须在 PWM 输出引脚与驱动电路间串联 10–100 Ω 限流电阻，防止高频振铃损坏 MCU。

3. 核心 API 设计与实现逻辑

PwmSpeaker 提供一组精简但完备的 C 函数接口，全部声明于pwmspeaker.h，实现位于pwmspeaker.c。所有函数均以pwmspeaker_为前缀，避免命名冲突。关键 API 按功能分组如下：

3.1 初始化与硬件绑定

typedef struct { TIM_HandleTypeDef *htim; // 指向 HAL TIM 句柄（必需） uint32_t channel; // PWM 通道：TIM_CHANNEL_1/2/3/4（必需） uint32_t pwm_gpio_pin; // GPIO 引脚号（如 GPIO_PIN_6，必需） GPIO_TypeDef *pwm_gpio_port; // GPIO 端口（如 GPIOA，必需） uint8_t volume_level; // 初始占空比（0–100，对应 0%–100%，默认 50） } PwmSpeakerConfig_t; /** * @brief 初始化 PwmSpeaker 实例 * @param hspk: PwmSpeaker 句柄指针（用户定义的 static PwmSpeakerHandle_t 变量） * @param config: 硬件配置结构体 * @retval HAL_StatusTypeDef: HAL_OK 表示成功，HAL_ERROR 表示参数非法或硬件错误 */ HAL_StatusTypeDef pwmspeaker_init(PwmSpeakerHandle_t *hspk, const PwmSpeakerConfig_t *config);

pwmspeaker_init()执行以下关键操作：

1. 校验htim是否已由MX_TIMx_Init()初始化（检查htim->Instance != NULL）
2. 配置 GPIO 引脚为复用推挽输出（GPIO_MODE_AF_PP），设置速度为高速（GPIO_SPEED_FREQ_HIGH）
3. 将指定通道配置为 PWM 模式（TIM_OCMODE_PWM1），启用预装载（TIM_OC_PRELOAD_ENABLE）
4. 设置初始占空比：__HAL_TIM_SET_COMPARE(htim, config->channel, (config->volume_level * (htim->Init.Period + 1)) / 100)
5. 启动 PWM 输出：HAL_TIM_PWM_Start(htim, config->channel)

📌 注：htim->Init.Period即 ARR 值。库不修改定时器周期，仅调整 CCR（比较寄存器），因此频率由用户初始化定时器时设定，PwmSpeaker 仅负责音调切换。

3.2 音调控制 API

/** * @brief 设置当前播放频率（Hz），立即生效 * @param hspk: PwmSpeaker 句柄 * @param freq_hz: 目标频率，范围 20–20000 Hz * @retval HAL_StatusTypeDef */ HAL_StatusTypeDef pwmspeaker_set_frequency(PwmSpeakerHandle_t *hspk, uint32_t freq_hz); /** * @brief 播放指定频率持续指定毫秒数（阻塞式） * @param hspk: PwmSpeaker 句柄 * @param freq_hz: 频率（Hz） * @param duration_ms: 持续时间（毫秒），0 表示无限长（需手动停止） * @retval HAL_StatusTypeDef */ HAL_StatusTypeDef pwmspeaker_play_tone(PwmSpeakerHandle_t *hspk, uint32_t freq_hz, uint32_t duration_ms); /** * @brief 停止当前播放（关闭 PWM 输出） * @param hspk: PwmSpeaker 句柄 * @retval HAL_StatusTypeDef */ HAL_StatusTypeDef pwmspeaker_stop(PwmSpeakerHandle_t *hspk);

pwmspeaker_set_frequency()是核心函数，其实现逻辑严格遵循定时器更新事件规范：

HAL_StatusTypeDef pwmspeaker_set_frequency(PwmSpeakerHandle_t *hspk, uint32_t freq_hz) { if (freq_hz < 20 || freq_hz > 20000) return HAL_ERROR; // 1. 计算新 ARR 值（假设时钟已知，此处以 84 MHz 为例） uint32_t new_arr = (84000000U / freq_hz) - 1U; if (new_arr > 0xFFFFU) new_arr = 0xFFFFU; // 限幅 // 2. 禁用更新事件中断（若已启用） __HAL_TIM_DISABLE_IT(hspk->htim, TIM_IT_UPDATE); // 3. 写入影子寄存器 __HAL_TIM_SET_AUTORELOAD(hspk->htim, new_arr); __HAL_TIM_SET_COMPARE(hspk->htim, hspk->channel, (hspk->volume_level * (new_arr + 1U)) / 100U); // 4. 生成更新事件，使新值生效 HAL_TIM_GenerateEvent(hspk->htim, TIM_EVENTSOURCE_UPDATE); // 5. 重新使能更新中断（保持原有状态） __HAL_TIM_ENABLE_IT(hspk->htim, TIM_IT_UPDATE); return HAL_OK; }

pwmspeaker_play_tone()在裸机环境下使用HAL_Delay()实现阻塞；在 FreeRTOS 下则创建临时任务或使用vTaskDelay()，避免阻塞调度器。其伪代码为：

// FreeRTOS 版本 void play_task(void *pvParameters) { PwmSpeakerHandle_t *hspk = (PwmSpeakerHandle_t*)pvParameters; uint32_t freq = *(uint32_t*)pvParameters; uint32_t ms = *(uint32_t*)((uint8_t*)pvParameters + sizeof(uint32_t)); pwmspeaker_set_frequency(hspk, freq); vTaskDelay(pdMS_TO_TICKS(ms)); pwmspeaker_stop(hspk); vTaskDelete(NULL); } HAL_StatusTypeDef pwmspeaker_play_tone(...) { xTaskCreate(play_task, "SPK_PLAY", 128, &params, 1, NULL); return HAL_OK; }

3.3 高级功能：音阶映射与旋律播放

为简化音乐编程，库内置国际标准音高（A4 = 440 Hz）十二平均律计算：

// 音符枚举（C4 = 261.63 Hz） typedef enum { NOTE_C4 = 0, NOTE_CS4 = 1, NOTE_D4 = 2, NOTE_DS4 = 3, NOTE_E4 = 4, NOTE_F4 = 5, NOTE_FS4 = 6, NOTE_G4 = 7, NOTE_GS4 = 8, NOTE_A4 = 9, NOTE_AS4 = 10, NOTE_B4 = 11, // ... 可扩展至 C8 } Note_t; /** * @brief 根据音符编号和八度计算频率 * @param note: 音符（NOTE_C4 等） * @param octave: 八度（4 表示中央 C 所在八度） * @retval uint32_t: 计算出的频率（Hz，四舍五入取整） */ uint32_t pwmspeaker_note_to_freq(Note_t note, uint8_t octave);

计算公式为：
$$ f = 440 \times 2^{\frac{(note - 9) + 12 \times (octave - 4)}{12}} $$
其中note - 9是相对于 A4 的半音数（A4 编号为 9）。

用户可构建旋律数组：

typedef struct { uint32_t frequency; // Hz uint16_t duration_ms; // 毫秒 } Tone_t; const Tone_t melody[] = { {pwmspeaker_note_to_freq(NOTE_C4, 4), 500}, {pwmspeaker_note_to_freq(NOTE_E4, 4), 500}, {pwmspeaker_note_to_freq(NOTE_G4, 4), 500}, {pwmspeaker_note_to_freq(NOTE_C5, 5), 1000}, }; // 播放旋律（FreeRTOS 环境） void play_melody_task(void *pvParameters) { for (int i = 0; i < sizeof(melody)/sizeof(Tone_t); i++) { pwmspeaker_play_tone(&hspk, melody[i].frequency, melody[i].duration_ms); vTaskDelay(pdMS_TO_TICKS(100)); // 音符间隔 } vTaskDelete(NULL); }

4. 典型应用工程实践

4.1 STM32CubeMX 配置指南

以 STM32F407VG 为例，使用 CubeMX 生成初始化代码：

1. RCC：HSE = 8 MHz，PLL 配置为 168 MHz（APB1 = 42 MHz，APB2 = 84 MHz）
2. TIM1：
   • Clock Source → Internal Clock
   • Counter Settings → Prescaler = 0, Counter Period = 8399（对应 10 kHz 基准，便于计算）
   • Channel 1 → PWM Generation CH1，Polarity = High
   • Master Configuration → Update Event Request → Enable
3. GPIOA Pin 8：
   • GPIO Mode → Alternate Function Push-Pull
   • GPIO Pull-up/Pull-down → No Pull-up and No Pull-down
   • Maximum Output Speed → High
   • Channel 1 Remap → Full Remap（若使用 PA8）
4. 生成代码，在main.c中添加：

#include "pwmspeaker.h" PwmSpeakerHandle_t hspk; PwmSpeakerConfig_t spk_config = { .htim = &htim1, .channel = TIM_CHANNEL_1, .pwm_gpio_pin = GPIO_PIN_8, .pwm_gpio_port = GPIOA, .volume_level = 60 // 60% 占空比 }; int main(void) { HAL_Init(); SystemClock_Config(); MX_GPIO_Init(); MX_TIM1_Init(); // 此函数由 CubeMX 生成 if (pwmspeaker_init(&hspk, &spk_config) != HAL_OK) { Error_Handler(); // 初始化失败处理 } // 播放中央 C 音（262 Hz）持续 1 秒 pwmspeaker_play_tone(&hspk, 262, 1000); while (1) { // 主循环可处理其他任务 } }

4.2 FreeRTOS 集成与多任务协同

在 FreeRTOS 环境中，需确保 PWM 控制不干扰高优先级任务。推荐做法：

• 将pwmspeaker_play_tone()封装为独立低优先级任务（如tskIDLE_PRIORITY + 1）
• 若需在中断中触发声音（如按键按下），使用xQueueSendFromISR()将音调指令发往播放任务队列
• 为避免多个任务同时调用pwmspeaker_set_frequency()导致竞争，可在pwmspeaker.c中添加互斥锁：

static SemaphoreHandle_t xSemaphore = NULL; HAL_StatusTypeDef pwmspeaker_init(...) { // ... 原有初始化代码 xSemaphore = xSemaphoreCreateMutex(); return HAL_OK; } HAL_StatusTypeDef pwmspeaker_set_frequency(...) { if (xSemaphore == NULL) return HAL_ERROR; if (xSemaphoreTake(xSemaphore, portMAX_DELAY) == pdTRUE) { // 执行频率设置... xSemaphoreGive(xSemaphore); return HAL_OK; } return HAL_ERROR; }

4.3 故障排查与性能优化

性能关键点：

• pwmspeaker_set_frequency()执行时间 < 1.5 µs（Cortex-M4 @ 168 MHz），对实时性无影响
• 内存占用：静态分配句柄仅 24 字节，无堆内存申请
• 最大支持并发音调数 = 硬件 PWM 通道数（如 TIM1 支持 4 通道，即可同时播放 4 个不同频率）

5. 与其他音频方案的对比评估

结论：当项目需求聚焦于“低成本、低功耗、快速响应、确定性时序”的提示音场景时，PwmSpeaker 是不可替代的最优解。它用最朴素的硬件资源，实现了嵌入式音频中最本质的功能——让机器发出可识别、可控制的声音。