嵌入式入门：STM32 HAL 库 API 的理解与实战（附代码示例）

关键词：嵌入式，stm32，HAL库，API，CubeMX

前言：在学习STM32 HAL库时，我们提到使用HAL库，一般来讲就是调用HAL库中的API。HAL 库（硬件抽象层）是 ST 官方主推的库函数框架，其 API（应用程序接口）封装了底层寄存器操作。作为嵌入式开发的入门者，理解 API 是快速上手STM32开发与外设控制的关键。本文结合实战代码，从基础到应用带你吃透 HAL 库 API。

一、什么是API？

API（Application Programming Interface，应用程序接口） 可以理解为 “别人封装好的功能模块”，你不需要知道它内部如何实现，只需按照规定的“使用方法”调用，就能直接获得结果。

在STM32开发中，API通常是芯片厂商（如ST公司）封装好的 库函数，STM32 的库函数分为标准库（StdPeriph）和 HAL 库：标准库是早期版本，外设驱动与芯片型号绑定；HAL 库是 ST 后期推出的跨系列通用库，API 接口统一，配合 STM32CubeMX 工具可自动生成代码，目前是主流开发方式。

API可用于操作芯片的硬件资源（如GPIO、串口、定时器等）。你无需直接操作复杂的寄存器，只需调用这些函数即可完成功能。

类比生活场景：

比如你用手机“打电话”：

你不需要知道手机内部电路如何工作、信号如何传输（底层实现），只需输入号码、点击“拨打”按钮（调用API的参数和方法），就能接通电话（获得结果）。

二、HAL库API的原理：封装与抽象

1. 为什么需要API？

• STM32的底层操作复杂：直接操作寄存器需要熟悉芯片手册中每个寄存器的地址、位功能（如配置GPIO的模式、速度、上下拉等），开发效率低且容易出错。

• API的作用：将寄存器操作封装成简单的函数，隐藏底层细节，让开发者专注于业务逻辑。

  简单说，就是你不需要去了解为什么能打通电话，只需要会拨电话号就好了。

2. 以STM32的GPIO为例看API原理

假设我们要控制STM32的一个引脚输出高电平：

• 寄存器操作（底层）：

  // 示例：将PA5引脚设置为输出模式（伪代码，实际需查寄存器地址）
  RCC_APB2ENR |= (1 << 2);       // 使能GPIOA时钟
  GPIOA_CRL &= ~(0xF << 20);      // 清除PA5引脚模式位
  GPIOA_CRL |= (0x1 << 20);       // 设置PA5为推挽输出模式
  GPIOA_ODR |= (1 << 5);          // 输出高电平
  

• API操作（HAL库）：

  // 使用STM32 HAL库的API（实际代码）
  GPIO_InitTypeDef GPIO_InitStruct = {0};
  
  __HAL_RCC_GPIOA_CLK_ENABLE();    // 使能GPIOA时钟（API封装）
  GPIO_InitStruct.Pin = GPIO_PIN_5; // 指定PA5引脚
  GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP; // 推挽输出模式
  GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_HIGH;
  HAL_GPIO_Init(GPIOA, &GPIO_InitStruct); // 初始化GPIO（API封装）
  
  HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, GPIO_PIN_SET); // 输出高电平（API封装）
  

• 对比总结：

  • HAL库的HAL_GPIO_Init()、HAL_GPIO_WritePin()等函数，本质是对寄存器操作的封装。
  • 你只需关注函数的参数（如引脚、模式、电平），无需记忆寄存器地址和位操作细节。
  • 尽管看起来代码更繁杂了，但大部分是软件自动生成的。我们通过STM32CubeMX图形化软件，设置好引脚功能后，代码会自动编辑。后续修改可通过CubeMX覆盖旧设置。也可以自行修改原代码。我们只需要认识并会使用这些函数与参数的命名即可。可以通过HAL库自带的库文件进行查询。

三、HAL库API的优缺点

• 优点：
  • 开发效率高：无需深入底层，快速实现功能。
  • 移植性强：不同型号的STM32芯片，HAL库API接口基本一致，代码可复用。
• 缺点：
  • 代码体积大：库函数会增加程序占用的Flash和RAM。
  • 执行效率略低：部分场景下（如高频控制），直接操作寄存器比调用API更快。

四、HAL库API实战场景

STM32的API主要用于操作各类硬件外设，常见场景包括：

以下代码仅供认识了解，不易移植使用。具体编写建议使用CubeMX直接生成。

1. GPIO控制（输入/输出）

以下代码需先通过 STM32CubeMX 配置 GPIOA 时钟、PA5 引脚为推挽输出，生成工程后在main.c中补充逻辑。

功能：控制引脚电平（输出）或读取引脚状态（输入）。
示例：LED闪烁（输出）

#include "stm32f1xx_hal.h" // HAL库头文件

GPIO_InitTypeDef GPIO_InitStruct;

int main(void) {
  HAL_Init(); // 初始化HAL库
  __HAL_RCC_GPIOA_CLK_ENABLE(); // 使能GPIOA时钟

  // 配置PA5为推挽输出（LED通常接在PA5）
  GPIO_InitStruct.Pin = GPIO_PIN_5;
  GPIO_InitStruct.Mode = GPIO_MODE_OUTPUT_PP;
  GPIO_InitStruct.Speed = GPIO_SPEED_FREQ_LOW;
  HAL_GPIO_Init(GPIOA, &GPIO_InitStruct);

  while (1) {
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, GPIO_PIN_SET); // 高电平，LED亮
    HAL_Delay(500); // 延时500ms（API封装的延时函数）
    HAL_GPIO_WritePin(GPIOA, GPIO_PIN_5, GPIO_PIN_RESET); // 低电平，LED灭
    HAL_Delay(500);
  }
}

2. 串口通信（USART）

需在 CubeMX 中配置 USART1（如引脚 PA9/PA10）、使能对应 GPIO 和 USART1 时钟，波特率 115200。

功能：通过串口发送/接收数据（如与电脑通信）。
示例：串口发送字符串

#include "stm32f1xx_hal.h"
UART_HandleTypeDef huart1; // 定义USART1句柄

void UART_Init(void) {
  __HAL_RCC_USART1_CLK_ENABLE(); // 使能USART1时钟
  __HAL_RCC_GPIOA_CLK_ENABLE();  // 使能GPIOA时钟（假设串口引脚接GPIOA）
  huart1.Instance = USART1;
  huart1.Init.BaudRate = 115200; // 波特率
  huart1.Init.WordLength = UART_WORDLENGTH_8B; // 8位数据位
  huart1.Init.StopBits = UART_STOPBITS_1; // 1位停止位
  huart1.Init.Parity = UART_PARITY_NONE; // 无校验位
  HAL_UART_Init(&huart1); // 初始化串口
}

// 发送字符串的API（封装HAL库函数）
void UART_SendString(char *str) {
  HAL_UART_Transmit(&huart1, (uint8_t*)str, strlen(str), 1000); // 发送数据
}

int main(void) {
  HAL_Init();
  UART_Init(); // 初始化串口

  while (1) {
    UART_SendString("Hello, STM32!\r\n"); // 调用API发送字符串
    HAL_Delay(1000);
  }
}

代码中，句柄（Handle）是 HAL 库中用于管理外设状态的结构体，包含外设实例（如 USART1）、初始化参数（如波特率）、状态标志等，后续操作该外设的 API（如HAL_UART_Transmit）都需要传入句柄作为参数。

3. 定时器（TIM）

功能：实现精准延时、周期性中断等。
示例：定时器中断（每1秒触发一次）

#include "stm32f1xx_hal.h"
TIM_HandleTypeDef htim2; // 定义TIM2句柄

void TIM_Init(void) {
  htim2.Instance = TIM2;
  htim2.Init.Prescaler = 7199; // 预分频器（72MHz时钟，分频后10kHz）
  htim2.Init.Period = 9999; // 自动重装载值（10kHz × 10000 = 1秒）
  HAL_TIM_Base_Init(&htim2);
  HAL_TIM_Base_Start_IT(&htim2); // 启动定时器并使能中断
}

// 定时器中断回调函数（API会自动调用）
void HAL_TIM_PeriodElapsedCallback(TIM_HandleTypeDef *htim) {
  if (htim == &htim2) {
    // 在这里写定时触发的逻辑（如翻转LED电平）
    HAL_GPIO_TogglePin(GPIOA, GPIO_PIN_5); // 翻转LED电平
  }
}

int main(void) {
  HAL_Init();
  TIM_Init(); // 初始化定时器
  while (1) {} // 主循环等待中断
}

五、如何高效学习HAL库API？

以HAL库为例，其中的API很多很多，不要求记住，只需要在一次次使用中熟悉，会用即可。

1. 查看官方文档：

   • 《STM32 HAL库参考手册》：详细介绍每个API的参数、返回值和使用步骤。
   • 《STM32芯片参考手册》：若需深入理解API底层原理，可对照查看寄存器描述。

2. 参考例程：

   • ST官网提供HAL库例程（如STM32CubeF1中的Projects文件夹），直接查看GPIO、USART等外设的API使用方法。

3. 动手实践：

   • 从简单功能开始（如LED、按键），逐步尝试串口、定时器、ADC等复杂外设，通过调试理解API的执行流程。

4. API 调用常见错误？：

   • 调用外设 API 前必须先使能时钟（如__HAL_RCC_GPIOA_CLK_ENABLE），否则函数无效；中断回调函数（如HAL_TIM_PeriodElapsedCallback）需确保参数判断正确（如if(htim == &htim2)），避免多个中断冲突。

六、总结

HAL 库 API 的核心价值是隐藏底层细节，是STM32开发的“桥梁”，它让开发者从繁琐的寄存器操作中解放出来，专注于项目逻辑。对于入门者，建议先熟练使用HAL库的API，快速完成项目原型。

掌握 HAL 库 API 后，可进一步学习 SPI、I2C、ADC 等外设的 API 使用，结合传感器（如温湿度、陀螺仪）实现复杂功能。后续会更新具体外设的实战教程，欢迎关注～