STM32开发避坑指南：从编译下载到时钟串口外设的实战经验

做过几年STM32开发的人，谁手里没攒下一堆哭笑不得的debug经历。代码编译零错误，下载器却怎么都连不上芯片；程序跑得好好的，换了一块屏就白屏；定时器算好的1毫秒，实测成了3毫秒；串口助手收到的数据隔三差五丢一个字节。这些问题单独看都不算大，但在项目交付、毕业答辩、产品量产的时间节点上冒出来，能把人逼疯。

这篇内容把我自己踩过、也帮别人排查过的坑系统梳理了一遍，按“工程与编译—下载与调试—时钟与定时器—串口与通信—外设驱动—真实项目”这条线展开，每个坑都写了现象、排查链路、根因和最终解法。适合刚入门STM32的初学者、正在赶毕业设计的学生朋友，以及做产品开发被某个怪问题卡了好几天的工程师。看完不敢说百坑不侵，至少能帮你少熬几个夜。

1. 工程与编译的坑：从新建工程那一步就开始翻车

很多人以为踩坑是从烧录开始的，实际上最阴险的坑藏在工程模板和库的选择里。这类问题编译不报错，运行才暴露，一旦踩进去，排查起来特别费劲。

1.1 标准外设库、HAL库、LL库：选错库等于给自己挖坑

STM32的开发库大体分三类：标准外设库（Standard Peripheral Library）、HAL库和LL库。不少新手在新建工程时根本没有意识到三者差异，往往是在百度上看到哪个教程顺眼就抄哪个，结果抄到一半发现寄存器操作和库函数混在一起，或者把标准库的延时函数塞进HAL库工程里，编译没问题，运行直接进HardFault。

我的建议是：做产品或者长期维护的项目，统一用HAL库搭配CubeMX生成初始化代码，出问题容易排查；毕业设计如果参考的是老教程，那就整篇都用标准外设库，千万不要混。混用带来的典型问题是在HAL工程里调用了标准库的Delay()，而标准库的延时依赖SysTick的全局变量TimingDelay，HAL库的HAL_Init()已经占用了SysTick并把它配置成了HAL自己的时基，冲突发生后表现就是延时严重超时，甚至卡在中断里出不来。

1.2 Keil芯片包丢失与VS Code环境搭建的隐藏前提

Keil5装完打不开旧工程，提示找不到器件，这几乎是每个从Keil4转过来的人都会撞一次的坑。原因很简单：Keil5的器件支持不再内置，必须通过Pack Installer安装对应的芯片包。

我遇到过最尴尬的一次，是帮学弟弄STM32F103C8T6最小系统板，他点了Pack Installer界面的Check for Updates，然后断网安装失败，整个Pack列表变成空的。离线安装包的正确路径是去官网下载Keil.STM32F1xx_DFP.x.x.x.pack文件，然后在Pack Installer里那个方块图标（Install from Local）导入。不要在Check for Updates上反复折腾，服务器经常连不上，浪费时间。

再用VS Code做STM32开发时，坑点更隐蔽。VS Code本身只是个编辑器，编译和调试依赖插件。目前主流方案是EIDE插件或者PlatformIO，EIDE更轻量，PlatformIO配置更傻瓜化，但两者都依赖OpenOCD。我第一次用VS Code调试时卡在“OpenOCD找不到目标”上，折腾了半天发现是ST-LINK的驱动版本太旧，Windows设备管理器里显示的是感叹号，重新安装ST官方驱动后立刻正常。

1.3 “Load xxx.axf Error: Flash Download failed”的完整排查链路

这个报错是真高频，好几次有朋友把错误日志发给我，就是类似load "D:\STM32 Project\...\Objects\project.axf" error: Flash Download failed - "Cortex-M3"。报错发生在点击Download之后、程序还没进Flash的时候，背后原因通常有四类，按出现频率排序：

1. Flash算法缺失或选错。Keil中的Debug设置里，如果Flash Download一栏的Programming Algorithm列表为空或者选的是其他系列的算法，下载就会失败。
2. 芯片型号和算法不匹配。例如F103C8T6是128KB Flash，算法却选成了F103ZE的高密度版本，虽然芯片容量够，但地址映射有差异，照样失败。
3. 下载速度过快。SWD时钟频率太高，加上杜邦线过长，导致通信不稳。把Max Clock从10MHz降到1MHz或500kHz再试。
4. 芯片进入低功耗模式或复位脚被占用。芯片在Sleep/Stop模式下无法响应调试请求，按住复位键再点下载，有的板子能救回来。

排查顺序我建议这样走：先点Options for Target -> Debug -> Settings，看能否识别到SW Device。识别到了，再去Flash Download列表里删掉错误的算法，添加对应型号算法，勾选Reset and Run。如果此时下载仍然失败，把Settings里的Connect模式从Normal换成Under Reset，这个选项对于程序里刚开始就禁用调试端口的情况非常有用。

还有一种“下载成功但跑不起来”的隐性坑：芯片如果之前被烧录过读保护选项字节，Flash内容会被锁定，下载后程序停在启动文件中。遇到这种情况需要先用ST-LINK Utility或STM32CubeProgrammer解除读保护，再做全片擦除。

2. 下载与调试的坑：连不上才是噩梦的开始

工程能编译、能下载，不代表调试就一帆风顺。很多时候坑发生在连接阶段：电脑不识别下载器、SWD协议连不上、程序跑飞后无法重新烧录。这部分问题一眼看上去像是硬件坏了，但是里面有大量软性原因。

2.1 ST-LINK连接失败：驱动、接线和固件三板斧

ST-LINK连不上芯片时，最常见三个层面的问题。

第一，电脑压根不识别ST-LINK。插上ST-LINK后，设备管理器如果直接显示未知设备，基本是驱动没装。Win10及以上的系统有时能自动装上驱动，但自动装的驱动版本老，与新版Keil配合不稳定。直接去ST官网下载最新的ST-LINK驱动，或者安装STM32CubeProgrammer时会附带驱动，一并解决。

第二，设备管理器识别正常，但Keil里SW Device列表是空的。这时候优先怀疑接线。SWD只需要四根线：3.3V、SWDIO、SWCLK、GND，很多人忘记接GND，只接了信号线和电源线，结果就是时好时坏。另外SWDIO和SWCLK两根线不能太长，最好控制在10厘米以内，杜邦线长了信号完整性会变差，下载到一半报错。

第三，SWD接口连接正常，但提示“No Target connected”。可能是目标板没有供电。ST-LINK虽然能输出3.3V，但电流很小，带不动带屏或者带电机驱动的板子；也可能是目标芯片的BOOT0被拉高进入了系统Bootloader，部分系统Bootloader不响应SWD调试请求，把BOOT0拉回低电平再看。

还有一类无法连接的情况是芯片本身太新，ST-LINK固件需要升级。我之前给一块G071板子连接调试器就遇到过，Keil里识别不到，后来用STM32CubeProgrammer的Firmware update把ST-LINK固件升了一级才解决。

2.2 禁用JTAG把自己锁死：最经典的自闭现场

“stm32禁用jtag”在热搜词里排得很靠前，说明踩过这个坑的人非常多。STM32的PB3、PB4、PA15默认复用为JTAG信号，很多开发者为了多几个普通IO口，会在初始化里把复用功能改为GPIO，比如调用GPIO_PinRemapConfig(GPIO_Remap_SWJ_Disable, ENABLE)。

这个操作本身合法，但有个致命的副作用：它会把SWD的调试引脚一并释放。释放之后，如果再想从SWD口连接芯片烧录程序，调试器自然找不到目标设备，因为引脚已经变成普通IO，不再响应调试协议了。程序里可能还有其他外设初始化，一旦写错一次，整块板子就成了所谓的“砖头”。

解决办法最常用的是三种：

1. 使用ST-LINK Utility或STM32CubeProgrammer，连接选项选择Connect under reset。原理是让芯片上电时先处于复位状态，趁调试口还没被程序改掉之前建立连接，然后立刻全片擦除。
2. 硬件上把BOOT0拉高到3.3V，断电重启，芯片进入系统Bootloader。这种情况下CPU不执行Flash内程序，SWD调试口恢复可用，连接后擦除Flash，再把BOOT0拉回低电平。
3. 如果没有ST-LINK，只有USB转串口，也可以利用BOOT0=1，通过USART1的ISP协议烧录一个恢复程序，先把调试引脚配置改正过来。

我之前有块自制板就是第一种方式救回来的。当时的经验是：Connect under reset模式下，Keil的Settings里SW Device依然可能显示空，但直接用STM32CubeProgrammer操作，成功率高很多，按住板子复位键，软件界面点Connect的瞬间松手，要反复试几次，有点碰运气成分，但最终都能救。

2.3 调试进阶：printf重定向和断点失效背后的问题

串口printf是嵌入式开发最常见的调试手段，但很多新手在Keil里直接调用printf，发现程序死机或者完全没有输出，问题出在C库与微控制器的适配上。标准C库的printf默认通过半主机模式（Semihosting）与调试器通信，MCU工程里没有实现底层终端接口，程序执行到printf时就会卡死。

Keil环境下的标准解法是：勾选Options for Target -> Target -> Code Generation -> Use MicroLIB，从而使用微库，避免半主机模式。同时在串口初始化后，重定义fputc函数：

int fputc(int ch, FILE *f) { while (!(USART1->SR & USART_SR_TXE)); USART1->DR = (uint8_t)ch; return ch; }

如果用的是HAL库，对应写成：

int fputc(int ch, FILE *f) { HAL_UART_Transmit(&huart1, (uint8_t *)&ch, 1, 0xFFFF); return ch; }

重定向完成后，串口输出的乱码又是另一个坑。排除波特率错误的情况，最常见原因是时钟配置偏离了预期频率。比如外部晶振实际是8MHz，而代码里按12MHz配置了PLL，系统时钟偏了50%，所有通信时序全部偏移。

断点调试时不生效也值得留意。Keil里把优化等级设为-O0通常能让断点正常工作，但如果调成-O2或更高，变量可能被优化掉，断点也可能被编译器移动位置，甚至Watch窗口里看到的变量显示<optimized out>。遇到这种情况，可以暂时把优化等级调低，或者用volatile修饰关键调试变量。

3. 时钟、定时器与延时函数的坑：板子不跑的第一个元凶

很多“程序烧录成功但运行异常”的问题，追根溯源都出在时钟树和定时器配置上。这类问题在STM32开发者中的共性非常强，热门搜索“stm32时钟树”“stm32延时函数delay卡死”就说明了这一点。

3.1 时钟树配置错误：你的72MHz可能根本不是72MHz

STM32F103的时钟树对新手来说信息量巨大，有HSI、HSE、PLL等多个时钟源，还有AHB、APB1、APB2三级分频总线。最常见的配置是外部8MHz晶振，PLL倍频9倍，得到72MHz系统时钟。

我见过大量因时钟树配置错误引发的怪异问题：比如串口波特率设置9600，实际输出却是10560；定时器按1ms配置，实测却是2.7ms；USB设备反复枚举失败。这些症状的共同来源都是系统时钟不是预期值。

排查这类问题要养成一个习惯：上电后第一件事，用MCO引脚输出时钟频率，用示波器或逻辑分析仪实测。F103的PA8可以复用为MCO，配置RCC_MCOConfig(RCC_MCO_PLLCLK_DIV2, ...)后，这个引脚输出系统时钟二分频。如果实测频率是36MHz，说明PLL配置正确，72MHz成立；如果实测明显偏差，检查晶振负载电容和PLL倍频系数。

还有个容易忽略的点是APB1和APB2总线频率差异。STM32F103中APB1最高36MHz，APB2最高72MHz，挂在两条总线上的外设时钟基准不同。串口1、2、3挂APB2，定时器2~7挂APB1，配置定时器时使用不同的总线频率算初值，搞混了算出来的定时时间必定不对。

3.2 delay函数卡死：SysTick被占用和中断优先级翻转

“stm32延时函数delay卡死”这个搜索词背后有一大堆案例。裸机编程中，延时无非是软件循环、SysTick延时、定时器延时三种。软件循环延时的死法很简单：编译器开优化后把空循环直接优化掉了，延时变成零。SysTick延时的卡死则复杂得多。

标准外设库的经典延时方案是：

static __IO uint32_t TimingDelay; void Delay_ms(uint32_t nTime) { TimingDelay = nTime; while (TimingDelay != 0); } void SysTick_Handler(void) { if (TimingDelay != 0) TimingDelay--; }

这个方案成立的前提是：SysTick中断正常触发，并且中断里只做了TimingDelay递减。如果工程里某个优先级更高的中断服务函数执行时间过长，SysTick中断一直被抢占，TimingDelay长时间无法递减，外部看起来就是延时卡死。

HAL库的HAL_Delay()卡死的原因更典型。HAL_Delay()依赖HAL_GetTick()，后者靠SysTick中断维护的uwTick变量。假如工程里初始化了其他外设中断，且这些中断的优先级被配置成高于SysTick，同时这个高优先级中断服务函数里又调用了HAL_Delay()，系统会直接死锁：高优先级中断等待uwTick变化，而SysTick因优先级低被阻塞。

解决这类问题的思路有三个方向：一是中断服务函数里杜绝阻塞式延时，凡是超过几十微秒的延时都不要在中断里做；二是把SysTick中断优先级调到最高；三是改用不依赖中断的延时，比如循环读取DWT计数器。

void DWT_Delay_us(uint32_t us) { DWT->CYCCNT = 0; while (DWT->CYCCNT < us * (SystemCoreClock / 1000000)); }

DWT延时在实际项目中非常稳，不占用SysTick，也不依赖中断，我在处理时序要求严格的传感器驱动时优先用这个。

3.3 定时器与编码器模式的几个隐蔽要点

定时器是STM32里功能最丰富的外设，但配置时最容易出问题的有三个地方：时基计算的边界、PWM的极性和预装特性、编码器模式下的计数器竞争。

先看时基计算。F103中定时器挂在APB1上，如果APB1分频系数为2，那么定时器实际时钟是APB1的两倍，也就是72MHz。定时1ms时，预分频器PSC设为71（即72分频），自动重载值ARR设为999，则定时周期为(71+1)*(999+1)/72MHz = 1ms。很多新手把PSC和ARR的关系当成寄存器直接赋值，不记得加1，算出来的时间误差不大但很顽固，很难一眼看出来。

PWM配置里最容易误导人的是POLARITY（极性）。配置为高电平有效时，占空比寄存器值越大，输出高电平时间越长；配置为低电平有效时刚好反过来。用示波器观察波形时，如果发现占空比和预期相反，首先要检查的不是代码逻辑，而是极性设置。

编码器模式也一样有坑。STM32定时器编码器模式支持1倍频、2倍频、4倍频计数，大多数工程选择4倍频。在读取计数器前要注意更新事件带来的数据竞争：一次更新中断会把CNT清零，如果程序在清零之后、读走数据之前触发了更新事件，读到的计数就丢了。我的习惯是读取CNT前先失能更新中断，读完之后再恢复。

4. 串口、printf与通信协议的坑：数据永远是验证真相的唯一标准

串口是STM32项目中最常用的通信手段，也是问题最多的地方。乱码、丢字节、连不上设备、收不到预期数据，几乎每个做嵌入式的人都被这些折磨过。这部分的坑大多不是原理性问题，而是细节上的疏忽。

4.1 串口乱码、丢字节和USB虚拟串口的兼容性问题

串口乱码的排查有一个固定套路：先确认物理连接方向和电平匹配，再确认波特率两端一致，最后确认时钟配置。很多人第一步就栽了——TTL串口模块和STM32之间的TX/RX要交叉连接，如果误接了同向线，收不到数据是小事，严重时可能烧坏引脚。

还有一种隐蔽的乱码原因：USB转串口模块用的CH340芯片工作在5V电平，STM32的USART引脚是3.3V。如果直接连接，虽然大部分时候能用，但长时间工作后可能出现电平干扰导致的丢字符。稳妥做法是加电平转换芯片，或者确认串口模块支持3.3V电平。

丢字节的典型案例是连续发送多个字节时，最后一个字节丢失。原因在于使用了发送数据寄存器空（TXE）作为发送完成标志。TXE置位只代表数据从寄存器移到了移位寄存器，移位寄存器没发完不算完成。正确做法是判断USART_FLAG_TC（发送完成）：

void USART_SendString(uint8_t *buf, uint16_t len) { for (uint16_t i = 0; i < len; i++) { USART1->DR = buf[i]; while (!(USART1->SR & USART_FLAG_TC)); } }

USB虚拟串口（CDC）是另一个高频话题。STM32的USB CDC类设备在CubeMX里配置出来后，上电后电脑如果有新设备但始终提示“设备描述符请求失败”，大概率是以下原因：USB的D+引脚外部上拉电阻缺失，或者上拉时机不正确。标准USB规范要求设备上电后D+线保持一段时间的低电平，再拉高让主机检测连接。STM32内部有上拉电阻但默认未使能，CubeMX里要勾选USB_DEVICE -> CDC并用正确的GPIO初始化方式做上拉控制。USB的48MHz时钟也必须在配置时钟树时单独检查，PLLQ输出不对，USB永远枚举失败。

4.2 I2C、RS485、ESP8266：协议调试的实战经验

I2C总线的问题集中在线上状态和时序上。最常见的故障是SDA线被拉死为低电平，主机一直收到ACK失败。这通常是总线某处发生了总线冲突，或者从机故障。排查方法是：分别测量SDA和SCL空闲时电平，正常应为高，如果SDA为低，就是有设备把总线拉住了，需要逐个断开从机排查。

I2C上拉电阻也是必查项。STM32的I2C引脚是开漏输出，必须外接上拉电阻才能输出高电平。如果板子上没有画上拉电阻，使用软件模拟I2C没问题，但是硬件I2C可能会工作异常。所以我现在做I2C传感器（比如BH1750、OLED）时，优先用GPIO模拟I2C，虽然代码多，但排查方便，不依赖芯片硬件外设的微小差异。

RS485通信的核心坑是方向切换时序。RS485是半双工，发送时要把DE引脚拉高，发送完毕后拉低切回接收。很多人忽略了一个细节：HAL_UART_Transmit()返回时，最后一个字节可能还在移位寄存器中，立刻把DE拉低会截断最后一帧。正确做法是发送后等待TC标志再切方向。

伺服电机通过RS485控制时，用Modbus RTU协议是常见做法。这个场景下的坑是空闲时刻总线上的偏置电阻。RS485总线空闲时A、B之间的电压差要在200mV以上，否则接收端会收到乱码。很多只做了收发电路、没有加偏置电阻的板子，在电机不响应指令时，用示波器看波形全是乱跳的毛刺，就是偏置不足。

ESP8266模块的坑集中在AT指令上。发AT指令时没有加回车换行，模块不响应；波特率不匹配，模块上电打印乱码；模块默认波特率是115200/9600等，不同固件不同版本不一样。ESP8266的电压域是3.3V，但很多开发板上的USB转串口是5V供电，直接给模块5V供电会烧模块。我调试ESP8266时通常独立供电，然后只接TX/RX和GND，避免模块从串口反灌电流。

4.3 K210与STM32通信、OTA升级的进阶坑

K210和STM32联调时，最常见的错误是TX/RX没有交叉连接。很多人会把两根线对齐接上，结果通信无反应，查半天才发现问题。还有一个容易被忽视的点是两边的电平参考地必须共地。有些模块用USB供电，有些用开关电源供电，如果两个板子的地没有连起来，串口信号的电压参考就不统一，表现为随机收到错误数据。

OTA升级是个更大的话题。把固件分成Bootloader区和App区后，Bootloader跳转到App之前，需要正确设置向量表偏移。STM32F103中要修改SCB->VTOR，并在编译链接时把App起始地址设定为0x08008000之类的位置。如果不设置向量表偏移，App里的中断来了之后，CPU跳转到0x08000000处的Bootloader中断向量表，整个程序逻辑会彻底错乱。

我做OTA还踩过升级失败后变砖的坑：升级过程掉电，App区写入一半，Bootloader启动后校验失败又没有回滚机制，于是系统永远卡在Bootloader里。后来的设计思路是保留两个App区，升级时先把新固件写入备份区，校验成功后再切换标志位，下次启动时Bootloader优先启动备份区，发现无效才回退到旧App。这套机制让升级失败不再变砖。

5. 外设驱动的坑：ADC、按键、编码器与传感器的实战细节

外设驱动这块的坑，写在数据手册里的很少，全是实际调试中逼出来的经验。ADC采样时间、按键消抖电路、超声波时序，单看都简单，组合到同一块板子上就经常打架。

5.1 ADC采样时间的真相：转换结果跳变的根源

STM32F103的ADC最大时钟频率是14MHz，超出后转换结果线性度显著变差。很多人把ADC预分频器设成6分频，等于12MHz，看起来没问题，但如果APB2时钟已经超频，ADC实际时钟也可能超。设置ADC时钟的一个关键原则是：不要追求最高的转换速度，而是保证采样时间足够长。

ADC转换过程包含采样阶段和转换阶段，采样时间由ADC_SMPR寄存器控制。更快的外部信号源需要更短的采样时间，高阻抗信号源则需要更长的采样时间。我实际调一个光敏电阻分压电路时，ADC读数跳动幅度达到几十个数，后来加长采样周期后读数稳定下来。原因是光敏电阻阻值高，外部等效阻抗大，ADC内部采样电容充电时间不足，电压还没充到位就开始转换了。

多通道扫描的坑更常见。ADC开启扫描模式后，各通道的数据在全部转换完成后统一更新DMA缓冲区。如果在转换过程中读取某个通道的数据寄存器，可能读到的是上一次的值。调试时用DMA循环采集多通道，需要注意DMA缓冲区索引和通道顺序的对应关系。

5.2 按键电路设计：为什么按键总是“自己触发”

按键模块的电路设计在入门项目中非常基础，但翻车率很高。用STM32的GPIO直接读取按键，如果引脚配置成浮空输入，按键悬空时引脚电平不稳定，会随机触发。正确做法是配置内部上拉或下拉输入，并配合外部滤波。

也有很多人把按键电路设计成“按下为高”，直接在引脚到地之间接按键，靠内部上拉电阻把空闲状态拉到高电平。这种电路的问题是内部上拉电阻阻值大（约40kΩ），在电磁环境稍差的场合容易误触发。更可靠的做法是在按键两端并联一个0.1μF电容做硬件消抖，软件里再做一次延时消抖。

软件消抖的逻辑顺序也容易踩坑：检测到按键电平变化后立即触发，然后在延时后再次读取。正确顺序是：检测到电平变化，延时10~20ms，再读取电平，若状态仍为按下才确认有效。跳过第一次读取直接延时的做法，会漏掉快速抖动期间的完整按键事件。

5.3 超声波测距的时序：Echo引脚高电平宽度才是关键

超声波测距模块HC-SR04的工作原理是：给Trig引脚一个10μs以上的高电平脉冲，模块发出40kHz超声并拉高Echo引脚，收到回波后Echo拉低。Echo高电平持续时间和距离成正比：距离（厘米）= Echo高电平时间（微秒）/ 58。

这个模块最大的坑是Echo引脚输出5V电平，而STM32的GPIO耐压和逻辑阈值是按3.3V设计的，直接连接有一定风险。稳妥方案是加电阻分压，把5V降低到3.3V再给MCU读取。

时序上更隐蔽的问题是：如果用阻塞式延时读取Echo，等待回波期间CPU被占死，程序无法处理其他任务。更好的方案是用定时器输入捕获功能，把Echo接到定时器某个输入捕获通道上，通过捕获上升沿和下降沿的时间差计算回波时间。这样CPU可以同时在主循环里处理显示、按键等任务。我看到不少人在做基于STM32的超声波测距项目时用while等待Echo引脚变化，距离一远，程序整个卡住，就是这个原因。

6. 动手做项目才会遇到的坑：从智能台灯到两轮小车

如果说前面那些坑是点状的，那么做完整项目时遇到的坑就是面状的。毕业设计、智能台灯、两轮差速小车、鱼缸监控，看起来项目不大，但设计时的引脚分配、电源管理、系统结构都会引发连锁问题。

6.1 从毕业设计里总结的通用教训

基于STM32的毕业设计翻车案例中，最痛的不是代码BUG，而是方案设计阶段没有留好调试余量。有个学弟做智能台灯，功能有PWM调光、环境光检测、按键控制、OLED显示，听起来很常规，结果硬件画板时发现PB3、PB4、PA15三个引脚被用作按键的IO口，又恰好这三个引脚是JTAG复用引脚，烧录器连不上。

这类问题就属于典型的引脚功能冲突。F103中PB3、PB4、PA15默认是JTAG引脚，如果当作普通IO使用，必须在初始化时禁用JTAG，但禁用后SWD又不能用了。之前的方案是保留SWD要用到的PA13、PA14，只禁用JTAG功能：

GPIO_PinRemapConfig(GPIO_Remap_SWJ_JTAGDisable, ENABLE);

这样PB3、PB4、PA15释放出来，同时SWD还能正常连接。但很多人在库函数版本里误用了GPIO_Remap_SWJ_Disable，把SWD也一起禁了，才导致板子变砖。

PWM调光的坑也很典型。很多人直接把LED接到定时器PWM输出引脚，调光时发现LED亮度非线性地跳变，这是因为人眼对亮度的感知是对数的，PWM占空比从0到100线性变化时，人眼感觉是前10%非常亮，后90%几乎没变化。处理方法是做Gamma校正，把PWM占空比按非线性映射调整。

智能台灯如果涉及220V调压，千万要注意强弱电隔离和继电器续流二极管。继电器线圈在断开瞬间会产生高压反电动势，不加续流二极管会把MCU的IO口打坏。这个在示波器上能看到很明显的电压尖刺，板子偶尔复位，就是这个原因。

6.2 两轮差速小车：电机控制是个系统工程

两轮差速小车的控制，核心在一个式子：左轮速度 = 基础速度 - 转向偏移，右轮速度 = 基础速度 + 转向偏移。算明白这个公式，小车的直行和转弯逻辑就通了。但实际项目中真正难的不是公式，而是电机驱动电路。

电机驱动芯片（比如L298N、TB6612）的输入端是TTL电平，但驱动输出的是大电流。如果MCU和驱动板共用一个电源，电机启动瞬间的大电流会导致电压跌落，MCU直接复位。我见过一个小车每次启动加速就重启，最后发现电池电压在电机启动瞬间跌到3V以下。解决办法是MCU单独供电（用稳压芯片），电机直接接电池，两个电源之间单点共地。

编码器反馈也有坑。两轮小车的电机编码器通常输出A、B两相信号，接入STM32的定时器编码器模式。要注意编码器的供电电压：很多小型电机编码器是5V供电，输出高电平也是5V，如果直接接3.3V的STM32引脚，引脚可能损坏。用分压电阻或电平转换电路是必须的。

PID调参的体会是：不要一上来就调PID参数，先把PWM死区搞清楚。电机在低占空比下可能不转，比如PWM占空比小于10%时电机纹丝不动，进入死区。不处理死区，PID积分项会一直累计，小车要么不动要么猛冲。实测中我的做法是上下限限幅，输出占空比低于死区值时直接输出0，高于某个值时再线性映射。

6.3 鱼缸监控项目的结构设计：裸机状态机胜过大而全的框架

“stm32鱼缸”这个热词确实有点出人意料，但也能代表不少人做家居项目的思路。鱼缸监控无非是水温、水位、灯光、自动换水几个功能，硬件上涉及DS18B20温度传感器、继电器控制加热棒和循环泵、LED灯带。

这类项目最大的坑是继电器控制周期和传感器读取周期的耦合。写裸机程序时，最常见的写法是主循环里按顺序依次执行所有任务，结果温度传感器读取等待750ms期间，水位检测和灯光控制全被卡住。一旦水位异常需要紧急关泵，就可能因为等待温度转换而延迟响应。

解决这个问题的思路是状态机或时间片轮询：每个任务分配固定的时间片，到时间才执行，不互相阻塞。比如主循环每隔10ms扫描一次按键，每隔100ms读一次水位，每隔500ms启动一次温度转换并读取结果，继电器状态由事件驱动而不是顺序驱动。这种结构在鱼缸这种多传感器多执行机构的场景里非常实用，改造成本低。

还有一个电气上的注意点：鱼缸环境湿度大，继电器和电源走线要做好防潮处理，否则铜箔氧化会导致接触不良，前期很难察觉，用一段时间后随机性故障频发。我曾见过一块板子因为雾气冷凝导致继电器误动作，加热棒持续工作，水温冲到36度。这类安全事故在项目调试里必须提前设防。

写在最后的一点实在话

踩过这么多坑之后，我最想分享的一个习惯是：遇到疑难问题，不要反复猜，直接上工具。逻辑分析仪、示波器、串口打印，能用的都用上。大部分“灵异现象”在波形面前都变得非常平庸，无非是电平时序不对、时钟频率错了、ACK没等到。

另外就是调试日志要写下来。很多人觉得项目小，记日志没必要，但同样的坑隔几个月就会再踩一次，到时候回忆“上次好像也是这里出了问题”却怎么也想不起来细节，才是最亏的。我自己的做法是每次项目都开一个调试记录文档，按日期记录问题现象、排查过程、最终根因、解决动作，多说一句，每次排查先从最近的改动入手，大部分问题都是自己改出来的，不是芯片坏了。