做嵌入式这些年，我见过太多人卡在"让蜂鸣器唱歌"这个看似入门的需求上。网上demo一搜一大把，可真照着抄，有人拿有源蜂鸣器捅了一下午也出不来半句调子，有人把PWM翻转频率算错一个数量级，还有人让蜂鸣器"唱"完一整首曲子期间连按键都扫不了。这篇文章我就把这个需求完整地拆一遍：从有源无源蜂鸣器的区别、压电片的发声原理，到定时器PWM的频率计算、旋律数据结构和代码实现，最后把我踩过的一些坑和排查思路一起捋清楚。不管你是刚学STM32的新手，还是被项目临时抓来加提示音的，跟着这个流程走，基本都能让蜂鸣器利利索索地哼出调子。
1. 先搞清楚：你要驱动的是哪种蜂鸣器
1.1 有源蜂鸣器和无源蜂鸣器，差的不只是一个字
"有源"和"无源"里的"源"指的是振荡源，不是电源。有源蜂鸣器内部自带了一套振荡电路，你只要给它通上直流电，它自己就会开始叫，频率基本固定，一般也就几百到几千赫兹，适合做报警提示。无源蜂鸣器内部没有振荡源，必须由外部提供一个方波信号才会发声，而且发声的频率完全由你给的方波决定——这才是播放旋律的前提条件。
很多新手买蜂鸣器时不看标签，拿了个有源的回来，调了半天频率发现音调纹丝不动，就是这个原因。有个简单的区分办法：有源蜂鸣器通上3.3V直流电就会响，无源的直流电只会"吧嗒"响一声就没了。我建议做旋律实验时直接买无源压电蜂鸣器，淘宝上几毛钱一个，多买几个备份，这东西在面包板上引脚很容易被掰断。
| 项目 | 有源蜂鸣器 | 无源蜂鸣器 |
|---|---|---|
| 内部振荡电路 | 有 | 无 |
| 通直流电是否持续发声 | 是 | 否（只有啪嗒一声） |
| 发声频率是否可调 | 否，固定 | 是，随输入方波频率变化 |
| 驱动信号 | 高低电平即可 | 需要PWM或方波 |
| 适合场景 | 按键提示音、报警 | 旋律播放、音乐效果 |
1.2 压电蜂鸣器发声原理：一个会跳舞的陶瓷片
压电蜂鸣器内部核心是一片压电陶瓷，通常是锆钛酸铅（PZT）材料。这种材料有压电效应：给它施加机械压力，两端会产生电压；反过来，在两端施加交变电压，它就会产生机械形变。我们把交变电压换成方波，陶瓷片就会跟着方波的频率来回弯曲振动，振动推动空气形成声波，这就是你听到的"嘀嘀"声。
这个原理解释了不少现象：为什么方波频率等于音高？因为陶瓷片的振动频率等于外加电压的变化频率，方波一次高低电平切换就是一次完整的振动周期。为什么占空比50%最好？因为对称方波让陶瓷片做对称的弯曲运动，振动幅度最大、声音最干净。为什么频率太高或太低都不行？因为人耳可听范围是20Hz到20kHz，低了只能听到"咔哒咔哒"的开关声，高了直接无声。
1.3 为什么播放旋律必须用PWM而不是GPIO翻转
理论上，用GPIO快速翻转电平也能产生方波。比如在循环里拉高、延时、拉低、延时，写个for循环翻转引脚，确实能响。但问题在于：微控制器的指令延时不可控，不同优化等级、不同编译器下延时会变，频率就不稳定；而且翻转过程中CPU被完全占住，啥事都干不了。
PWM的方案完全不同。定时器在后台自动计数，到点自动翻转引脚，CPU可以一点不操心。你只需要改一个寄存器——ARR——就能精确改变方波频率，分辨率可以做到1Hz以内。这就是为什么所有播放旋律的教程都让你用定时器PWM，而不是用delay自己翻转IO。虽然"GPIO+中断"也能做，但中断频繁触发同样消耗CPU，远不如PWM硬件输出来得干净。
2. 硬件连接：一个三极管解决的问题
2.1 物料清单
要复现这篇文章的实验，你最少需要这些东西：
- STM32开发板一块，我用的是STM32F103C8T6最小系统板，不过代码逻辑对其他系列完全通用
- 无源压电蜂鸣器一个，注意确认是无源的，买的时候跟商家说清楚
- NPN三极管，推荐2N2222或者S8050，几乎每个电子爱好者手里都有存货
- 电阻若干：1kΩ基极限流电阻一个、1kΩ下拉电阻一个
- 面包板、杜邦线若干
- 一个手机，装个免费的调音App，校音用，这个后面细说
2.2 驱动电路与接线
STM32的GPIO在推挽输出模式下，驱动能力大概在几毫安到二十毫安之间。蜂鸣器正常工作电流通常在10mA到30mA，直接用GPIO驱动不是不行，但声音会偏小，长期满负荷输出对引脚也不好。稳妥的做法是加一级三极管开关电路，电路结构很简单：
- 蜂鸣器一脚接3.3V（或者5V，看蜂鸣器规格）
- 蜂鸣器另一脚接三极管的集电极
- 三极管发射极直接接地
- 单片机的PWM输出引脚通过一个1kΩ电阻接到三极管基极
- 基极再接一个1kΩ电阻到地，防止单片机复位期间基极悬空导致蜂鸣器误响
注意：蜂鸣器模块如果自带驱动电路，那直接接IO就行；但如果你买的是一个裸的压电蜂鸣器片，就必须把这个三极管电路搭出来，否则声音会小到怀疑人生。
2.3 三极管开关电路的工作细节
这个电路里三极管工作在开关状态，不是放大状态。PWM高电平来时，基极电流通过1kΩ电阻流入，三极管饱和导通，集电极拉低，蜂鸣器两端获得接近电源电压的电压差；PWM低电平时三极管截止，蜂鸣器断电。于是蜂鸣器上得到的是一幅被"放大"的方波，峰峰值接近电源电压，驱动能力比GPIO直接推强得多。
基极电阻的取值有讲究。1kΩ对应基极电流大概是(3.3V - 0.7V) / 1kΩ ≈ 2.6mA，对2N2222来说足以进入深度饱和。如果你用了10kΩ电阻，基极电流只有0.26mA，三极管可能工作在放大区，导通不完全，蜂鸣器上的电压就达不到电源电压，声音明显偏小。这个坑我踩过，后来量了波形才发现三极管根本没饱和。
3. 定时器PWM：音符频率是怎么算出来的
3.1 STM32定时器产生方波的原理
STM32的定时器PWM输出原理可以一句话描述：计数器从0开始，每个时钟周期加1，数到ARR（自动重装载值）后归零重新计数，如此循环；CCR（捕获比较寄存器）里存了一个比较值，计数器计数小于CCR时输出高电平，大于等于CCR时输出低电平（具体极性取决于配置）。这样输出引脚上就出现了一个方波。
改变ARR，方波的周期就跟着变，也就是频率变了；改变CCR，高电平持续的时间就变了，也就是占空比变了。对我们播放旋律的场景来说，目标很明确：频率跟着音符走，占空比固定50%。所以每次切音符，只需要把ARR改成目标频率对应的值，同时把CCR设成ARR的二分之一。
3.2 ARR和PSC的换算公式
假设定时器时钟是f_tim，预分频系数是PSC，那么计数器实际计数频率是：
f_cnt = f_tim / (PSC + 1)
PWM输出频率则为：
f_pwm = f_cnt / (ARR + 1) = f_tim / ((PSC + 1) * (ARR + 1))
为了让程序里换算方便，我习惯先把PSC固定，让计数频率等于1MHz，也就是1微秒计一次数。这样ARR直接等于 1000000 / 目标频率 - 1。举个例子：A4标准音的频率是440Hz，那么ARR = 1000000 / 440 - 1 = 2272（取整）。C4中央C频率262Hz，ARR = 1000000 / 262 - 1 = 3816。
以STM32F103为例，系统时钟72MHz时，APB1定时器时钟也是72MHz，把PSC设成71，计数频率就是72MHz / (71+1) = 1MHz。这里要特别提醒：定时器时钟不一定等于系统主频。CubeMX里APB1分频系数一变，PCLK1和定时器时钟就变了。我见过不少人在F103上把APB1分频配成4，定时器时钟变成36MHz，结果音符频率全偏，还以为是音符表算错了。
3.3 音符频率对照表
十二平均律下，A4标准音是440Hz，每升高一个半音，频率乘以2的1/12次方（约1.05946）。C大调常用音符频率整理如下，做旋律实验用这张表就够：
| 音符 | 频率(Hz) | 音符 | 频率(Hz) |
|---|---|---|---|
| C4 | 262 | C5 | 523 |
| D4 | 294 | D5 | 587 |
| E4 | 330 | E5 | 659 |
| F4 | 349 | F5 | 698 |
| G4 | 392 | G5 | 784 |
| A4 | 440 | A5 | 880 |
| B4 | 494 | B5 | 988 |
工程上取整就行，人耳对几赫兹的偏差并不敏感。C4到C5是一个八度，频率正好翻倍，这个规律好记。我调音时习惯先把A4（440Hz）单独播放，用手机调音App对着听，只要A4准了，其他音基本不会偏。
4. 旋律数据结构和代码实现
4.1 把乐谱翻译成C语言数组
一首旋律本质上就是一串（音高，时值）的二元组。音高用一个频率值表示，休止符就用0表示；时值用一个毫秒数表示，代表这个音符持续多久。在C语言里定义成结构体数组，直观又好改：
typedef struct { uint16_t freq; // 音高对应的频率，单位Hz，0表示休止 uint16_t duration; // 持续时间，单位ms } Note;拿《小星星》第一段举例，简谱是 1 1 5 5 6 6 5- 4 4 3 3 2 2 1-，对应C调就是：
const Note twinkle[] = { {262, 400}, {262, 400}, {392, 400}, {392, 400}, {440, 400}, {440, 400}, {392, 800}, {349, 400}, {349, 400}, {330, 400}, {330, 400}, {294, 400}, {294, 400}, {262, 800}, };时值用400ms作为一个四分音符，800ms表示二分音符，听起来就是"一闪一闪亮晶晶"的节奏。这个数组可以无限扩展，想换歌就重新填数字，查表改频率就行。你甚至可以用宏定义把音符频率定义成好记的名字，比如#define NOTE_C4 262，代码可读性会好很多。
4.2 CubeMX配置步骤
如果你用STM32CubeMX生成工程，需要配置的其实只有一路PWM：
选择TIM2，把Channel1配置成PWM Generation CHx；Prescaler按前面的公式填，让计数频率为1MHz（比如PSC=71）；Counter Period（ARR）先随便填个999，程序运行时会动态改；Pulse（CCR）先填499，同样会被程序覆盖。生成代码后，记得检查一下定时器的时钟源是否选择了内部时钟Internal Clock，以及APB1分频是否影响了定时器时钟。
提示：CubeMX生成的代码里，PWM初始化完成后并没有立刻输出波形，需要手动调用HAL_TIM_PWM_Start才能启动。很多人的蜂鸣器没声音，不是初始化错了，而是忘了启动输出。
4.3 核心代码详解
核心逻辑就两个函数：设置频率和播放旋律。设置频率的函数需要处理休止符的情况，并动态修改ARR和CCR：
void Buzzer_SetFreq(uint16_t freq) { if (freq == 0) { // 休止符：停止PWM，引脚拉低，让蜂鸣器完全安静 HAL_TIM_PWM_Stop(&htim2, TIM_CHANNEL_1); return; } // 计数频率1MHz，ARR = 1000000 / freq - 1 uint32_t arr = 1000000UL / freq - 1; __HAL_TIM_SET_AUTORELOAD(&htim2, arr); __HAL_TIM_SET_COMPARE(&htim2, TIM_CHANNEL_1, arr / 2); HAL_TIM_PWM_Start(&htim2, TIM_CHANNEL_1); }播放函数就遍历数组，依次设置频率、延时、然后短暂停止：
void Buzzer_PlayMelody(const Note *melody, uint16_t len) { for (uint16_t i = 0; i < len; i++) { Buzzer_SetFreq(melody[i].freq); HAL_Delay(melody[i].duration); // 音符之间的短停顿，避免连音含糊 Buzzer_SetFreq(0); HAL_Delay(30); } Buzzer_SetFreq(0); }主函数里这样调用：
while (1) { Buzzer_PlayMelody(twinkle, sizeof(twinkle) / sizeof(twinkle[0])); HAL_Delay(1000); }这里有个细节值得说：为什么音频停止后要在音符间加30ms的停顿？因为如果两个音之间无缝切换，前一个音的余振会混进后一个音，听起来像滑音，不清脆。30ms足够在听觉上把两个音切开，又不会明显拖慢节奏。这个值可以根据曲子风格调整，慢歌可以加长到50ms，快节奏的儿歌可以缩到15ms。
4.4 阻塞与非阻塞播放：选哪种看你的项目
上面这个实现用的是HAL_Delay，代码最简单，但代价是播放旋律期间CPU完全被占住。如果项目的蜂鸣器只是系统里一个无关紧要的提示音，主循环里阻塞播放完全没问题；但如果你的系统还要同时响应按键、刷新OLED、跑串口通信，阻塞播放就会让其他任务全部卡顿，体验非常糟糕。
非阻塞方案的核心思路是"状态机+查询"。把每个音符的开始时间记下来，在主循环或者一个周期性的节拍函数里不断查询当前时间是否超过了音符应有的时长，到了就切下一个音：
static uint8_t playing = 0; static uint16_t note_idx = 0; static uint32_t note_start = 0; void Melody_Tick(void) { if (!playing) return; uint32_t elapsed = HAL_GetTick() - note_start; if (elapsed >= twinkle[note_idx].duration + 30) { note_start = HAL_GetTick(); note_idx++; if (note_idx >= MELODY_LEN) { playing = 0; Buzzer_SetFreq(0); return; } Buzzer_SetFreq(twinkle[note_idx].freq); } }然后在主循环里周期调用Melody_Tick()。1ms分辨率的HAL_GetTick对播放音乐来说足够了，误差最多一两毫秒，人耳完全听不出来。这种方案的好处是主循环空出来了，按键、显示、通信该干嘛干嘛，蜂鸣器在后台自己哼歌。如果对时序要求更严，也可以换成硬件定时器中断驱动切换，但那个逻辑更绕，新手先掌握查询法就够了。
5. 常见问题与排查实录
5.1 蜂鸣器只响一声或者干脆不响
这个问题的最高发原因，到现在依然是"有源蜂鸣器被当成无源用了"。有源蜂鸣器内部自带振荡电路，你给不给PWM它都只按自己那个固定频率响，有时候高频方波反而把它内部电路搞乱，直接不响。换成无源蜂鸣器，问题立刻消失。
第二个常见原因是PWM根本没启动，或者启动后又被别的代码停掉了。检查一下工程里有没有其他外设占用同一个定时器通道，或者某个中断服务函数里意外调用了HAL_TIM_PWM_Stop。还有一个小概率原因：引脚初始化成了复用功能以外的模式，PWM信号根本出不来。用示波器或者逻辑分析仪量一下引脚，没有波形就顺着初始化流程排查。
5.2 声音很小或者有杂音
先排除硬件。三极管C/E有没有接反？基极电阻是不是太大了？蜂鸣器正负极对不对？这些用万用表量一遍就能定位。如果是三极管没饱和，蜂鸣器上的电压摆幅不够，声音就会又轻又闷，把基极电阻降到1kΩ以下基本能解决。
软件方面，很多人会忽略PWM输出极性。CubeMX里Polarity如果选了LOW，PWM高电平时间变短，占空比就成了反的，声音听起来会怪。另外，有些引脚在初始化完成之前处于浮空状态，蜂鸣器会发出"滋滋"的底噪。解决办法是在初始化阶段先把PWM通道停掉，并把引脚配置成推挽输出低电平，等真正要播放时再启动。
5.3 音高不准、跑调怎么定位
音准问题的排查优先级我建议按这个顺序来：
- 确认定时器时钟。用调试器看RCC寄存器或者CubeMX的Clock Configuration页面，确认APB1分频后定时器时钟到底是多少。别想当然认为是主频。
- 确认PSC和ARR的公式。注意ARR算完之后要减1，减1这个操作丢了等于频率全部偏高约0.1%，虽然不大，但强迫症不能忍。
- 检查有没有其他代码在改这个定时器。比如某些照抄来的延时函数会重置TIM寄存器，或者FreeRTOS的时基用了同一个定时器。
经验：我习惯用A4标准音440Hz做自检。程序里单独播放一个440Hz的方波，拿手机上的调音App对着听。如果显示接近440Hz，说明软件逻辑没问题，再用示波器看波形占空比；如果偏差很大，十有八九是定时器时钟配置错了，改PSC重新听，多试几次就能锁定问题。
5.4 播放旋律卡住主程序
这个问题本质是HAL_Delay阻塞了CPU。表现就是"我按了按键没反应，要等蜂鸣器整段放完才行"。如果旋律很短（一两秒）可能还能忍，但如果你的《歌唱祖国》全长30秒，那整块板子就瘫了半分钟。
解决方法是换成4.4节说的非阻塞状态机。还有另一种情况：你的中断服务函数里调用了蜂鸣器播放函数，然后中断里又用了HAL_Delay，而SysTick中断优先级低于你这个外部中断，HAL_Delay就会永远等不到SysTick递增，直接卡死。这个是很多人在串口收发、按键消抖时踩过的经典坑，跟蜂鸣器本身无关，但如果你把播放逻辑放在中断里，就非常容易踩中。
5.5 从HAL库换到标准库或者寄存器操作
我上面的代码是基于HAL库的，但很多朋友还在用标准外设库，或者喜欢直接操作寄存器。核心逻辑完全一样，只是API不同：
// 标准库版本 TIM_SetAutoreload(TIM2, arr); TIM_SetCompare1(TIM2, arr / 2); TIM_Cmd(TIM2, ENABLE);// 寄存器版本 TIM2->ARR = arr; TIM2->CCR1 = arr / 2; TIM2->CCER |= TIM_CCER_CC1E; TIM2->CR1 |= TIM_CR1_CEN;只要理解了ARR控制频率、CCR控制占空比、CCER控制输出使能、CR1控制定时器使能，换成任何库都是顺手的事。我在VSCode+arm-none-eabi-gcc环境里也这么写过，代码换个平台照样跑，这就是原理吃透的好处。
写在最后的个人心得
玩了一圈下来，我的体会是蜂鸣器这个外设虽然不起眼，但它把STM32里几个最重要的概念——时钟树、定时器、PWM、状态机——全串起来了。你花一晚上把《小星星》调通，比对着教程背十遍寄存器定义都管用。别嫌它简单，先让声音按照你想要的节奏和音高出来，这个闭环本身就很有成就感。
最后再分享一个小技巧：做音乐提示音的时候，别只想着单音旋律。把两个定时器通道分别接两个蜂鸣器，一个放主旋律一个放伴奏，出来的效果能让整个项目的完成度上一个档次。还有，用PWM做"滴滴-哒哒"的Chirp提示音（频率线性变化）也很实用，比如设备低电量时的急促叫声，那个原理其实跟播放音符是一样的，只是把ARR改成动态变化而已。慢慢玩，你会发现蜂鸣器能玩出的花样远比你想象的多。
