2. STM32CubeMX I2C配置：时钟、GPIO与速率模式

好，咱们正式开始动手配置。上一章我们聊了WM8960的I2C协议基础，现在要落地到STM32的硬件上。我个人习惯是先用CubeMX把外设骨架搭好，再往里面填业务逻辑。这样不容易漏配置，也方便后期维护。

说白了，I2C配置就三件事：时钟树怎么走、引脚怎么连、速率选多快。这三件事在CubeMX里都有对应的配置页面，我们一个一个来。

2.1 时钟树配置：给I2C外设喂对时钟

I2C模块的时钟源来自APB1总线（对于STM32F4/F7/H7系列而言）。你想想看，如果APB1时钟配错了，I2C的波特率计算就会全盘跑偏。我在项目中遇到过一位同事，折腾了两天I2C通信不稳定，最后发现是时钟树里APB1分频器设成了/4，导致SCL实际频率只有目标值的一半。

在CubeMX的Clock Configuration页面，你需要关注这几个点：

• HSE/LSE选择：如果板上有8MHz晶振，选HSE作为PLL源；如果对功耗敏感，可以用HSI内部振荡器，但精度会差一些。
• PLL倍频系数：根据目标主频（比如168MHz）反推，确保PLL输出在芯片规格范围内。
• APB1分频器：APB1最高频率通常限制在42MHz（F4系列）或45MHz（F7系列），分频后要≤这个上限。
• APB1 Timer Clock：如果APB1分频系数≠1，定时器时钟会翻倍，这个不影响I2C，但要注意。

嗯，这里要注意：CubeMX的时钟树页面是动态计算的，你改一个参数，所有相关时钟都会联动变化。我建议先把HCLK（主频）设为目标值，再回头检查APB1是否超标。

2.2 GPIO引脚配置：选对引脚，省一半调试时间

I2C的SCL和SDA引脚必须是开漏输出（Open-Drain），并且要外接上拉电阻。CubeMX里配置GPIO时，有几点容易踩坑：

• 引脚功能选择：在Pinout视图里，点击目标引脚，选择I2Cx_SCL或I2Cx_SDA。不要选成GPIO_Output，否则I2C硬件模块无法控制引脚电平。
• 上拉电阻：CubeMX默认会给I2C引脚配置内部上拉。但说实话，内部上拉电阻约40kΩ，对于400kHz快速模式来说太弱了。我建议外部加4.7kΩ上拉，CubeMX里把GPIO上拉设为No Pull，避免内外上拉并联导致阻抗不匹配。
• 输出速度：选High或Very High。选Low的话，上升沿会变缓，高速通信时容易出时序错误。
• Alternate Function：确认AF编号与芯片型号匹配。比如STM32F407的PB6/PB7对应I2C1的AF4，而STM32H743可能不同。

参数	推荐配置	原因
GPIO Mode	Alternate Function Open-Drain	I2C总线需要开漏输出实现线与逻辑
Pull-up	No Pull（外部上拉）	避免内外上拉并联，保证上升沿时间
Speed	High / Very High	保证SCL/SDA信号边沿陡峭
Alternate Function	根据芯片手册选择对应AF	错误AF会导致引脚无输出

2.3 速率模式选择：100kHz还是400kHz？

WM8960的I2C接口支持最高400kHz的快速模式。但选多快，不只看从机上限，还要考虑总线长度和寄生电容。

CubeMX的I2C配置页面里，Timing Settings选项卡下有个I2C Speed Mode下拉框：

• Standard Mode (100kHz)：最稳，兼容性最好。如果WM8960离STM32比较远（超过10cm），或者线上挂了多个设备，我建议先用这个模式调通。
• Fast Mode (400kHz)：WM8960寄存器读写就那么几个字节，400kHz完全够用。但要注意，总线上拉电阻要按400kHz重新计算（通常4.7kΩ配100pF负载没问题）。
• Fast Mode Plus (1MHz)：WM8960不支持，别选。

选好模式后，CubeMX会自动计算SCL Rise Time和SCL Fall Time。这两个参数影响内部时序滤波器的配置。如果你用的板子走线比较长，可以把Rise Time稍微设大一点（比如从默认的100ns改成300ns），让I2C模块的滤波器更宽容。

2.4 生成HAL初始化代码

所有配置完成后，点击Project → Generate Code。CubeMX会生成以下关键文件：

• i2c.c / i2c.h：I2C外设的HAL初始化函数MX_I2C1_Init()，以及引脚配置函数HAL_I2C_MspInit()。
• gpio.c / gpio.h：如果I2C引脚有额外的GPIO配置（比如复位引脚），会在这里生成。
• main.c：在main()函数里调用MX_I2C1_Init()。

生成的初始化代码大致长这样：

// i2c.c 中的初始化函数
void MX_I2C1_Init(void)
{
  hi2c1.Instance = I2C1;
  hi2c1.Init.ClockSpeed = 400000;          // 400kHz
  hi2c1.Init.DutyCycle = I2C_DUTYCYCLE_2;  // 标准占空比
  hi2c1.Init.OwnAddress1 = 0;              // 主模式不需要自身地址
  hi2c1.Init.AddressingMode = I2C_ADDRESSINGMODE_7BIT;
  hi2c1.Init.DualAddressMode = I2C_DUALADDRESS_DISABLE;
  hi2c1.Init.OwnAddress2 = 0;
  hi2c1.Init.GeneralCallMode = I2C_GENERALCALL_DISABLE;
  hi2c1.Init.NoStretchMode = I2C_NOSTRETCH_DISABLE;
  if (HAL_I2C_Init(&hi2c1) != HAL_OK)
  {
    Error_Handler();
  }
}

// i2c.c 中的MSP初始化函数
void HAL_I2C_MspInit(I2C_HandleTypeDef* hi2c)
{
  GPIO_InitTypeDef GPIO_InitStruct = {0};
  if(hi2c->Instance == I2C1)
  {
    __HAL_RCC_GPIOB_CLK_ENABLE();   // 使能GPIOB时钟
    __HAL_RCC_I2C1_CLK_ENABLE();    // 使能I2C1时钟

    // PB6: SCL, PB7: SDA
    GPIO_InitStruct.Pin = GPIO_PIN_6|GPIO_PIN_7;
    GPIO_InitStruct.Mode = GPIO_MODE_AF_OD;
    GPIO_InitStruct.Pull = GPIO_NOPULL;
    GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_VERY_HIGH;
    GPIO_InitStruct.Alternate = GPIO_AF4_I2C1;
    HAL_GPIO_Init(GPIOB, &GPIO_InitStruct);
  }
}

嗯，这里有个细节：HAL_I2C_MspInit()是HAL库的弱函数，CubeMX自动生成的代码会覆盖它。如果你手动修改了这个函数，下次重新生成代码时会被覆盖。我个人的做法是：把自定义的I2C相关配置（比如DMA、中断优先级）放在HAL_I2C_MspInit()的USER CODE BEGIN和USER CODE END之间，这样重新生成时不会被擦掉。

2.5 本章核心流程SVG

下面这张图总结了从CubeMX配置到生成代码的完整流程，你可以对照着操作：

配置完成后，下一步就是写代码去读写WM8960的寄存器了。不过在那之前，我建议你先用逻辑分析仪抓一下SCL和SDA的波形，确认时钟频率和引脚电平都正常。嗯，这个习惯帮我省了不少调试时间。