1. 从标准库到HAL库：平衡车代码移植的完整思路拆解
平衡车这个项目在STM32圈子里算是经典中的经典，B站铁头山羊那套标准库教程带出来的人不在少数。但这两年明显能感觉到一个趋势：新入坑的兄弟直接上HAL库，老玩家手里的标准库代码想往CubeMX生态迁移，还有一部分人是因为公司项目要求统一用HAL库开发。不管你是哪种情况，把一套跑通的标准库平衡车代码完整移植到HAL库，这件事本身就值得认真做一遍。
我手里这套代码最早就是跟着铁头山羊的视频敲出来的，标准库版本，Keil MDK环境，主控STM32F103C8T6，MPU6050读姿态，编码器测速，TB6612或者DRV8833驱动有刷电机，OLED显示状态，PID串级控制。代码在标准库下跑得很稳，但后来想加一些新功能，比如USB虚拟串口调参、FreeRTOS多任务、或者换F4系列主控，标准库的维护成本就上来了。HAL库配合CubeMX，外设初始化代码自动生成，底层驱动统一，跨系列移植方便，这些优势在项目变复杂之后会越来越明显。
移植这件事，核心不是把标准库的GPIO_Init()换成HAL_GPIO_Init()就完事了。真正的难点在于三个层面：时钟配置的差异、中断处理逻辑的重构、外设句柄管理方式的转变。标准库是直接操作寄存器结构体，HAL库是面向句柄的抽象层，思维方式不一样。我见过不少人移植到一半卡住，基本都是因为没理解HAL库的HAL_Init()到底干了什么，或者中断服务函数里忘了调HAL_GPIO_EXTI_IRQHandler()导致回调进不去。
这篇文章我会把整个移植过程拆开讲，从工程搭建、外设配置、中断重构、PID控制逻辑迁移，到实际调试中遇到的坑，全部过一遍。适合两类人看：一类是手里有标准库平衡车代码想转HAL库的，另一类是刚开始学STM32想直接走HAL库路线的。代码基于STM32F103C8T6，但思路对F4、G4、H7系列同样适用。
2. 工程环境搭建与CubeMX基础配置
2.1 工具链选择与工程创建
先说工具。标准库时代大家基本是Keil MDK + 手动建工程，HAL库时代我强烈建议用STM32CubeMX做初始化代码生成，然后配合Keil或者STM32CubeIDE开发。CubeMX的好处是引脚分配、时钟树、外设参数全部图形化，生成的代码结构统一，后面换芯片型号重新生成一遍就行，不用手动改寄存器。
具体操作：打开CubeMX，新建工程，搜索STM32F103C8，选中对应封装。第一步先配RCC，把HSE设为Crystal/Ceramic Resonator，也就是外部晶振。这一步很关键，标准库代码里通常直接写RCC_PLLConfig()，但CubeMX里你要在Clock Configuration标签页把PLL倍频系数设好，让系统时钟跑到72MHz。F103的典型配置是HSE 8MHz，PLLMUL设为9，得到72MHz的SYSCLK，AHB不分频，APB1二分频36MHz，APB2不分频72MHz。
注意：CubeMX里如果HSE没起振，时钟树会标红，生成的代码会默认用HSI。一定要确认晶振电路上的负载电容匹配，通常22pF，具体看晶振规格书。
SYS标签页里，Debug要选Serial Wire，不然下载一次程序后SWD引脚可能被禁用，下次就连不上了。这个坑我在标准库时代踩过，HAL库下同样要注意。Timebase Source保持默认的SysTick就行，如果后面要上FreeRTOS，建议改成TIM1或者其他定时器，把SysTick让给RTOS。
2.2 外设引脚分配与参数设置
平衡车用到的外设不算多，但每个都要配对。我把标准库代码里的引脚定义列出来，然后在CubeMX里一一对应。
电机驱动部分，标准库通常用TIM3的CH1和CH2输出PWM，对应PA6和PA7。CubeMX里把PA6、PA7设为TIM3_CH1和TIM3_CH2，模式选PWM Generation CH1/CH2。PWM频率标准库代码一般设10kHz左右，CubeMX里看Prescaler和Counter Period。72MHz主频，Prescaler设0，Counter Period设7199，得到72M/7200=10kHz。占空比通过__HAL_TIM_SET_COMPARE()调节，范围0到7199。
编码器接口用TIM2或者TIM4，标准库下配置为Encoder Mode。CubeMX里把TIM2的Combined Channels设为Encoder Mode，CH1和CH2对应PA0和PA1。这里有个细节：编码器模式下的计数方向、极性、滤波参数都要根据实际编码器类型调。我用的霍尔编码器，PPR是13线，四倍频后每转52个计数。CubeMX里Encoder Mode默认TI1和TI2都触发，对应四倍频。
MPU6050走I2C，标准库代码里通常是软件模拟I2C，因为硬件I2C在F103上有已知的锁死问题。但HAL库的硬件I2C已经稳定很多，我建议直接用硬件I2C1，PB6和PB7。CubeMX里I2C1模式选I2C，Speed Mode选Fast Mode，400kHz。如果坚持用软件I2C，就把两个引脚设为GPIO_Output和GPIO_Input，手动翻转电平，但那样HAL库的优势就没了。
OLED如果也是I2C接口，可以挂在同一个I2C总线上，地址不冲突就行。MPU6050地址0x68，OLED通常0x3C或0x78。如果OLED是SPI接口，就另外配SPI外设。
串口用于调参和调试，USART1，PA9和PA10，波特率115200。CubeMX里USART1模式选Asynchronous，其他默认。中断优先级后面统一配。
2.3 时钟树配置与代码生成注意事项
时钟树是CubeMX里最容易出错的地方。F103的时钟路径是：HSE→PLL→SYSCLK→AHB Prescaler→APB1/APB2 Prescaler。标准库代码里这些是手动算的，CubeMX里直接填数字，但你要知道每个数字的含义。
我一般这样配：HSE 8MHz，PLL Source选HSE，PLLMUL选9倍频，SYSCLK 72MHz，AHB Prescaler 1分频，APB1 Prescaler 2分频得到36MHz，APB2 Prescaler 1分频得到72MHz。定时器时钟要注意，APB1上的定时器如果APB1分频系数不为1，定时器时钟会倍频。比如APB1是36MHz，但TIM2的时钟实际是72MHz。这个细节在计算PWM频率和编码器计数时很重要。
生成代码前，Project Manager里Toolchain/IDE选MDK-ARM V5，Code Generator里勾选"Generate peripheral initialization as a pair of .c/.h files per peripheral"，这样每个外设的初始化代码分开，工程结构清晰。最后点GENERATE CODE，CubeMX会生成完整的HAL库工程。
提示：生成的代码里
main.c的while(1)循环是空的，你的应用逻辑要写在/* USER CODE BEGIN WHILE */和/* USER CODE END WHILE */之间，这样重新生成代码时不会被覆盖。
3. 核心外设驱动移植与中断逻辑重构
3.1 GPIO与电机PWM控制的HAL库实现
标准库下电机控制代码大概长这样：TIM_SetCompare1(TIM3, duty);，HAL库下变成__HAL_TIM_SET_COMPARE(&htim3, TIM_CHANNEL_1, duty);。看起来只是函数名变了，但背后有个关键区别：HAL库的定时器句柄htim3包含了定时器的所有状态信息，而标准库是直接操作寄存器。
电机方向控制引脚，标准库用GPIO_SetBits(GPIOB, GPIO_Pin_0)，HAL库用HAL_GPIO_WritePin(GPIOB, GPIO_PIN_0, GPIO_PIN_SET)。这些是机械替换，没什么难度。但要注意HAL库的GPIO初始化结构体里，Speed和Pull参数要配对。电机方向引脚设成GPIO_MODE_OUTPUT_PP，Speed选High，Pull选NOPULL。
PWM启动有个容易漏的地方：HAL库下必须调用HAL_TIM_PWM_Start(&htim3, TIM_CHANNEL_1)和HAL_TIM_PWM_Start(&htim3, TIM_CHANNEL_2)，否则PWM不会输出。标准库下TIM_Cmd(TIM3, ENABLE)就够了，HAL库把通道启动单独拆开了。我移植的时候就在这里卡了半小时，示波器量PA6没波形，后来发现是忘了启动通道。
3.2 编码器接口与速度采集的差异处理
编码器接口在HAL库下的配置和标准库差别不大，但读取计数值的方式变了。标准库用TIM_GetCounter(TIM2)，HAL库用__HAL_TIM_GET_COUNTER(&htim2)。清零用__HAL_TIM_SET_COUNTER(&htim2, 0)。
真正需要注意的是编码器的计数溢出处理。标准库代码里通常用int16_t读计数器，因为TIM2是16位定时器，计数范围0到65535，正反转时溢出会回绕。HAL库下同样用(int16_t)__HAL_TIM_GET_COUNTER(&htim2)来读，利用有符号数的回绕特性得到正负速度值。
速度计算周期我设的是10ms，用SysTick或者定时器中断触发。标准库下可能用TIM_ITConfig(TIM2, TIM_IT_Update, ENABLE)开更新中断，HAL库下用HAL_TIM_Base_Start_IT(&htim2)启动定时器中断，然后在HAL_TIM_PeriodElapsedCallback()回调里处理。这个回调函数是HAL库的弱定义函数，你在main.c里重写它就行。
void HAL_TIM_PeriodElapsedCallback(TIM_HandleTypeDef *htim) { if (htim->Instance == TIM2) { int16_t cnt = (int16_t)__HAL_TIM_GET_COUNTER(&htim2); __HAL_TIM_SET_COUNTER(&htim2, 0); encoder_left = cnt; // 速度计算... } }注意：回调函数里不要做耗时操作，速度计算和PID尽量放到主循环或者RTOS任务里，中断里只做数据采集和标志位置位。
3.3 MPU6050数据读取与I2C通信稳定性
MPU6050的驱动移植是重头戏。标准库代码里如果是软件I2C，移植到HAL库硬件I2C需要重写读写函数。HAL库的I2C接口是HAL_I2C_Mem_Read()和HAL_I2C_Mem_Write()，参数包括设备地址、寄存器地址、数据长度、超时时间。
HAL_I2C_Mem_Read(&hi2c1, MPU6050_ADDR, MPU6050_ACCEL_XOUT_H, I2C_MEMADD_SIZE_8BIT, buffer, 14, 100);这一行读14个字节，包含加速度、温度、陀螺仪数据。标准库下可能是分开读的，HAL库下可以一次读完，效率更高。
但硬件I2C有个坑：如果从设备没应答，HAL_I2C_Mem_Read()会返回HAL_ERROR或者HAL_TIMEOUT，程序可能卡在超时等待里。我的处理方式是加错误重试机制，连续读失败3次就重新初始化I2C外设。
uint8_t retry = 0; while (HAL_I2C_Mem_Read(&hi2c1, MPU6050_ADDR, reg, I2C_MEMADD_SIZE_8BIT, buf, len, 10) != HAL_OK) { if (++retry > 3) { HAL_I2C_DeInit(&hi2c1); HAL_I2C_Init(&hi2c1); retry = 0; } }MPU6050的DMP库在HAL库下也能用，但DMP库本身是标准库风格的，移植时需要把I2C读写函数替换成HAL库版本。如果不想折腾DMP，直接用原始数据做互补滤波或者卡尔曼滤波也够用。我用的互补滤波，计算量小，F103跑起来没压力。
3.4 中断优先级配置与EXTI回调
标准库下中断优先级用NVIC_Init()配置，HAL库下在CubeMX里图形化配置，或者用HAL_NVIC_SetPriority()和HAL_NVIC_EnableIRQ()。平衡车项目里中断不多，主要是定时器中断、I2C中断（如果用DMA）、串口接收中断。
优先级分组用HAL_NVIC_SetPriorityGrouping(NVIC_PRIORITYGROUP_4)，4位抢占优先级，0位子优先级。定时器中断优先级设1，串口设2，I2C设3。抢占优先级高的能打断低的，平衡车控制周期10ms，定时器中断优先级要高于串口，保证控制周期稳定。
EXTI外部中断，比如按键或者MPU6050的INT引脚，HAL库下的处理流程是：HAL_GPIO_EXTI_IRQHandler()在中断服务函数里被调用，然后触发HAL_GPIO_EXTI_Callback()回调。标准库下是直接在EXTIx_IRQHandler()里写逻辑，HAL库下要重写回调函数。
void HAL_GPIO_EXTI_Callback(uint16_t GPIO_Pin) { if (GPIO_Pin == MPU6050_INT_Pin) { // 读取MPU6050数据 } }提示：CubeMX生成的
stm32f1xx_it.c里已经写好了EXTIx_IRQHandler()，里面调用了HAL_GPIO_EXTI_IRQHandler()，你只需要重写回调函数，不要动it.c里的代码。
4. 控制算法迁移与PID参数整定实操
4.1 串级PID结构在HAL库下的实现
平衡车的控制核心是串级PID：外环角度环，内环速度环，输出叠加到电机PWM。标准库代码里PID计算通常是纯C函数，和硬件无关，这部分移植最简单，直接复制过来就行。但要注意数据类型的统一，标准库代码里可能用float，HAL库下同样用float，F103没有FPU，浮点运算靠软件模拟，10ms周期内算完没问题。
角度环PID：
typedef struct { float Kp, Ki, Kd; float integral; float prev_error; float output; float integral_limit; float output_limit; } PID_TypeDef; float PID_Calc(PID_TypeDef *pid, float target, float actual) { float error = target - actual; pid->integral += error; if (pid->integral > pid->integral_limit) pid->integral = pid->integral_limit; if (pid->integral < -pid->integral_limit) pid->integral = -pid->integral_limit; float derivative = error - pid->prev_error; pid->prev_error = error; pid->output = pid->Kp * error + pid->Ki * pid->integral + pid->Kd * derivative; if (pid->output > pid->output_limit) pid->output = pid->output_limit; if (pid->output < -pid->output_limit) pid->output = -pid->output_limit; return pid->output; }速度环的输出作为角度环的目标值，角度环的输出作为PWM占空比。这个结构在标准库和HAL库下完全一样，移植时不用改。
4.2 角度环与速度环参数整定步骤
PID参数整定是平衡车调试最耗时间的环节。我的步骤是：先调角度环，再调速度环，最后联调。
角度环整定：把速度环输出固定为0，只调角度环。Kp从0开始加，加到车身能直立但有小幅振荡，然后加Kd抑制振荡。Ki先不加，等Kp和Kd稳定后再加一点点消除静差。我最终的角度环参数是Kp=180，Kd=1.2，Ki=0.5，输出限幅5000（对应PWM的0到7199）。
速度环整定：角度环调好后，加速度环。速度环的Kp决定车身受到扰动后恢复的速度，Ki消除速度静差。速度环输出限幅要小，一般不超过角度环目标值的10%，否则会干扰角度环。我的速度环参数是Kp=80，Ki=0.3，输出限幅5度。
注意：整定过程中一定要用串口把角度、速度、PWM输出实时打印出来，用上位机画波形。光靠眼睛看车身姿态，很多振荡是看不出来的。
4.3 互补滤波与姿态解算的代码迁移
MPU6050原始数据有噪声，直接算角度会抖得厉害。互补滤波是平衡车最常用的姿态解算方法，计算量小，效果好。标准库代码里的互补滤波公式：
angle = 0.98 * (angle + gyro_y * dt) + 0.02 * accel_angle;gyro_y是陀螺仪Y轴角速度，accel_angle是加速度计算出的角度，dt是采样周期。这个公式在HAL库下完全一样，移植时不用改。但要注意dt的准确性，最好用定时器实际测量的周期，而不是理论值。
加速度计角度计算：
accel_angle = atan2(accel_x, accel_z) * 180 / 3.1415926;陀螺仪零偏校准：上电时静止采集1000次陀螺仪数据，取平均值作为零偏，后续读数减去零偏。这个步骤在标准库和HAL库下都一样，但HAL库下要注意I2C读取速度，1000次读取大概需要几百毫秒，上电初始化时做一次就行。
4.4 电机死区补偿与方向控制逻辑
有刷电机有死区，PWM占空比低于一定值电机不转。标准库代码里通常加一个死区补偿，HAL库下同样处理。我的电机死区在PWM值800左右，所以输出PWM时如果绝对值小于800，就补到800，方向不变。
if (pwm_output > 0 && pwm_output < 800) pwm_output = 800; if (pwm_output < 0 && pwm_output > -800) pwm_output = -800;方向控制：正PWM时一个方向引脚高另一个低，负PWM时反过来。HAL库下用HAL_GPIO_WritePin()设置方向引脚，然后__HAL_TIM_SET_COMPARE()设置占空比。
提示：电机正反转切换时，最好加一个短暂的死区时间，避免H桥上下管直通。TB6612内部有死区，但DRV8833需要外部处理。我一般在方向切换后延时1ms再输出PWM。
5. 调试过程中遇到的典型问题与排查实录
5.1 HAL库I2C通信失败与总线锁死
移植后第一个大坑就是I2C。标准库软件I2C跑得好好的，换成HAL库硬件I2C后，MPU6050读不出数据，HAL_I2C_Mem_Read()返回HAL_ERROR。用逻辑分析仪抓波形，发现SCL被拉低后一直不释放，总线锁死了。
原因：F103的硬件I2C在从设备异常时可能进入死锁状态，SCL被从设备拉低，主机无法产生时钟。解决方法有两种：一是加I2C总线恢复函数，手动翻转SCL引脚9次，让从设备释放总线；二是直接用软件I2C，放弃硬件I2C。
我最终选了软件I2C，因为平衡车对I2C速度要求不高，软件I2C更稳定。软件I2C的引脚用PB6和PB7，配成GPIO_MODE_OUTPUT_OD开漏输出，手动控制SCL和SDA。HAL库下用HAL_GPIO_WritePin()和HAL_GPIO_ReadPin()实现I2C时序。
void I2C_Start(void) { SDA_HIGH(); SCL_HIGH(); delay_us(2); SDA_LOW(); delay_us(2); SCL_LOW(); delay_us(2); }5.2 定时器中断不触发与回调函数未执行
第二个坑是定时器中断。CubeMX里配了TIM2更新中断，HAL_TIM_Base_Start_IT(&htim2)也调了，但HAL_TIM_PeriodElapsedCallback()就是不进。查了半天发现是CubeMX里NVIC标签页没使能TIM2全局中断。标准库下NVIC_Init()里使能了，CubeMX里要在NVIC Settings里勾选TIM2 global interrupt。
注意：CubeMX里每个外设的中断都要单独使能，生成代码后检查
stm32f1xx_it.c里有没有对应的IRQHandler，以及main.c里有没有HAL_NVIC_EnableIRQ()。
5.3 编码器计数方向错误与速度符号反相
编码器读出来的速度符号和电机转向相反，导致速度环正反馈，车身一启动就飞车。标准库下编码器方向可以通过TIM_EncoderInterfaceConfig()的极性参数调整，HAL库下在CubeMX里配Encoder Mode的极性，或者软件里取反。
我直接在速度计算时取反：encoder_left = -encoder_left;。但要注意，两个电机的编码器可能都需要取反，也可能只需要一个，具体看安装方向。调试时先用手转动轮子，看串口打印的速度符号和转向是否一致。
5.4 程序卡在HAL_Delay或超时等待
HAL库的HAL_Delay()依赖SysTick中断，如果SysTick优先级设得太低，或者在其他中断里调用了HAL_Delay()，程序会卡死。标准库的delay_ms()通常是空循环，不依赖中断，所以没这个问题。
我的处理：HAL_Delay()只在初始化和非中断上下文用，中断里用自定义的delay_us()空循环。另外，SysTick优先级设为最高（0），保证HAL_Delay()和HAL_GetTick()正常。
5.5 常见问题速查表
| 问题现象 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| I2C读MPU6050失败 | 硬件I2C死锁 | 逻辑分析仪看SCL/SDA | 改用软件I2C或加总线恢复 |
| 定时器中断不进 | NVIC未使能 | 检查it.c和NVIC配置 | CubeMX里勾选中断使能 |
| 编码器速度符号反 | 极性配置错误 | 手动转轮看串口输出 | 软件取反或改极性 |
| 程序卡在HAL_Delay | SysTick优先级低 | 检查NVIC优先级 | SysTick设最高优先级 |
| PWM无输出 | 通道未启动 | 示波器量引脚 | 调HAL_TIM_PWM_Start |
| 电机不转 | 死区未补偿 | 串口打印PWM值 | 加死区补偿 |
| 车身振荡 | PID参数不当 | 上位机看波形 | 重新整定PID |
| 串口乱码 | 波特率不匹配 | 检查时钟配置 | 确认USART时钟源 |
6. 移植后的优化方向与扩展思路
6.1 用FreeRTOS重构任务调度
HAL库配合FreeRTOS是自然选择。标准库时代用裸机前后台架构，主循环里轮询，实时性靠中断保证。HAL库下可以上FreeRTOS，把姿态解算、PID控制、串口通信、OLED显示分成独立任务，优先级从高到低排列。
控制任务优先级最高，周期10ms，用vTaskDelayUntil()保证周期稳定。姿态解算任务优先级次之，5ms周期。串口和显示任务优先级最低，空闲时跑。任务间通信用队列或者全局变量加互斥锁。
CubeMX里可以直接勾选FreeRTOS，生成任务框架代码。注意SysTick要被FreeRTOS占用，HAL库的Timebase Source要改成其他定时器，比如TIM1。
6.2 加入USB虚拟串口方便调参
F103C8T6没有原生USB，但可以用USB转串口芯片，或者换F103CBT6（有USB）。HAL库的USB Device库配合CDC类，可以虚拟出一个串口，上位机直接连，不用额外转换芯片。CubeMX里配USB Device，选CDC类，生成代码后调用CDC_Transmit_FS()发送数据。
USB虚拟串口的好处是波特率随便设，传输稳定，适合大量数据实时上传。但USB中断优先级要配好，不能干扰控制任务。
6.3 换F4系列主控的性能提升
F103跑平衡车够用，但如果要加摄像头、激光雷达、或者更复杂的控制算法，F4系列更合适。HAL库的优势在这里体现明显：CubeMX里换芯片型号，重新生成代码，外设初始化代码自动适配，应用层代码基本不用改。
F407主频168MHz，有FPU，浮点运算快很多，PID计算和姿态解算可以跑更高频率。F4的定时器更多，编码器接口、PWM通道都更充裕。移植时注意F4的HAL库和F1的HAL库API基本一致，但时钟树配置不同，外设寄存器有差异，CubeMX会处理好。
6.4 无刷电机FOC控制的扩展
有刷平衡车玩透了，下一步可以上无刷电机FOC。HAL库有专门的MCU SDK，配合STM32的定时器互补输出和ADC注入通道，可以实现电流环、速度环、位置环三环控制。FOC代码比有刷复杂得多，但HAL库的抽象层让底层驱动统一，你可以把精力放在算法上。
无刷平衡车的轮毂电机KV值要选对，KV太低转速不够，KV太高扭矩不足。我试过KV=30的轮毂电机，配合FOC控制，低速扭矩很足，平衡效果比有刷好很多。
6.5 代码版本管理与团队协作
最后说个容易被忽视的点：代码版本管理。标准库时代很多人用Keil的工程文件直接备份，HAL库时代建议用Git。CubeMX生成的代码和用户代码要分开管理，.ioc文件纳入版本控制，Drivers目录可以忽略，重新生成即可。
团队协作时，每个人用自己的CubeMX版本生成代码，.ioc文件冲突了手动合并。用户代码写在/* USER CODE */区间内，重新生成不会丢失。这个习惯在项目变大后能省很多事。
我在实际移植过程中最大的体会是：HAL库不是标准库的简单替换，而是开发方式的转变。标准库让你贴近寄存器，HAL库让你关注应用逻辑。平衡车这个项目作为练手，正好能把两种方式的差异体会清楚。移植完成后，代码的可维护性和扩展性确实上了一个台阶，后面加功能、换平台都轻松很多。如果你也在做类似的移植，建议先把I2C和定时器中断这两个坑趟平，后面的路就顺了。
