3. GPIO驱动分层实战（一）：从HAL_GPIO_WritePin到业务层——抽象BSP层与驱动接口设计，实现LED/按键的跨平台封装。

好，我们直接进入正题。很多朋友学完HAL库的GPIO操作后，写出来的代码往往是这样的：HAL_GPIO_WritePin(LED_GPIO_Port, LED_Pin, GPIO_PIN_SET) 直接写在main函数里，或者散落在各个业务模块中。这样做，短期内跑个灯没问题，但一旦换板子、换MCU，或者要同时支持多个硬件版本，你就得满世界找这些API去改。

我个人习惯是，从一开始就把驱动层和业务层剥离开。说白了，就是让业务代码永远不知道它操作的是哪个GPIO端口、哪个引脚。今天这一讲，我们就来动手搭建这个分层架构。

3.1 为什么需要分层？——从一次惨痛经历说起

我记得几年前做一款工业控制器，项目中期突然要换主控型号，从STM32F103换到F407。硬件工程师改完原理图，我一看代码，好家伙，所有LED、按键、继电器控制全是裸调HAL_GPIO。那几天我几乎是在做“查找-替换”的体力活，还漏改了两个引脚，导致现场烧了一块板子。

从那以后，我给自己定了个规矩：硬件相关的代码，必须隔离在一个独立的BSP（Board Support Package）层里。业务层只调用BSP提供的接口，比如 BSP_LED_On()、BSP_Key_GetState()，绝不直接碰HAL。

3.2 分层架构总览

我们先画一张图，看看这三层到底怎么划分的。你想想看，一个嵌入式系统里，代码从最底层到最上层，应该像剥洋葱一样清晰。

这张图里，从上到下依次是：

• 业务层：只管逻辑，比如“开机后LED闪烁3次”、“按键按下时切换模式”。它不知道LED接在PA5还是PB0。
• BSP层：负责把硬件细节藏起来。它知道LED在哪个端口、按键是低电平有效还是高电平有效。
• HAL层：ST官方提供的库，直接操作寄存器。我们不动它。

3.3 BSP接口设计——LED驱动封装

我们先从最简单的LED开始。假设板子上有2个LED：一个红色（接PA5），一个绿色（接PB0）。

我的做法是，在BSP层定义一个枚举，把所有LED设备列出来：

/* bsp_led.h */
#ifndef __BSP_LED_H__
#define __BSP_LED_H__

#include <stdint.h>

typedef enum {
    BSP_LED_RED = 0,
    BSP_LED_GREEN,
    BSP_LED_COUNT   // 用于数组大小，不是有效LED
} BSP_LED_ID_t;

void BSP_LED_Init(void);
void BSP_LED_On(BSP_LED_ID_t led);
void BSP_LED_Off(BSP_LED_ID_t led);
void BSP_LED_Toggle(BSP_LED_ID_t led);

#endif /* __BSP_LED_H__ */

然后在 bsp_led.c 里，用一个结构体数组把硬件映射关系管理起来：

/* bsp_led.c */
#include "bsp_led.h"
#include "stm32f4xx_hal.h"

typedef struct {
    GPIO_TypeDef *port;
    uint16_t      pin;
    uint8_t       active_level;  // 1: 高电平点亮, 0: 低电平点亮
} LED_Map_t;

static const LED_Map_t led_map[BSP_LED_COUNT] = {
    [BSP_LED_RED]   = {GPIOA, GPIO_PIN_5,  1},
    [BSP_LED_GREEN] = {GPIOB, GPIO_PIN_0,  1},
};

void BSP_LED_Init(void)
{
    // 这里可以调用HAL_GPIO_Init配置引脚为推挽输出
    // 实际项目中，GPIO时钟使能和初始化通常在MX_GPIO_Init()中完成
    // 我们这里只做逻辑封装，假设HAL层已经初始化好了
}

void BSP_LED_On(BSP_LED_ID_t led)
{
    if (led >= BSP_LED_COUNT) return;

    if (led_map[led].active_level == 1) {
        HAL_GPIO_WritePin(led_map[led].port, led_map[led].pin, GPIO_PIN_SET);
    } else {
        HAL_GPIO_WritePin(led_map[led].port, led_map[led].pin, GPIO_PIN_RESET);
    }
}

void BSP_LED_Off(BSP_LED_ID_t led)
{
    if (led >= BSP_LED_COUNT) return;

    if (led_map[led].active_level == 1) {
        HAL_GPIO_WritePin(led_map[led].port, led_map[led].pin, GPIO_PIN_RESET);
    } else {
        HAL_GPIO_WritePin(led_map[led].port, led_map[led].pin, GPIO_PIN_SET);
    }
}

void BSP_LED_Toggle(BSP_LED_ID_t led)
{
    if (led >= BSP_LED_COUNT) return;
    HAL_GPIO_TogglePin(led_map[led].port, led_map[led].pin);
}

3.4 BSP接口设计——按键驱动封装

按键比LED稍微复杂一点，因为涉及到消抖和电平反转。我们同样先定义接口：

/* bsp_key.h */
#ifndef __BSP_KEY_H__
#define __BSP_KEY_H__

#include <stdint.h>

typedef enum {
    BSP_KEY_USER1 = 0,
    BSP_KEY_USER2,
    BSP_KEY_COUNT
} BSP_KEY_ID_t;

typedef enum {
    BSP_KEY_RELEASED = 0,
    BSP_KEY_PRESSED
} BSP_KEY_State_t;

void BSP_KEY_Init(void);
BSP_KEY_State_t BSP_KEY_GetState(BSP_KEY_ID_t key);

#endif /* __BSP_KEY_H__ */

实现文件里，同样用映射表管理：

/* bsp_key.c */
#include "bsp_key.h"
#include "stm32f4xx_hal.h"

typedef struct {
    GPIO_TypeDef *port;
    uint16_t      pin;
    uint8_t       press_level;  // 1: 按下为高电平, 0: 按下为低电平
} KEY_Map_t;

static const KEY_Map_t key_map[BSP_KEY_COUNT] = {
    [BSP_KEY_USER1] = {GPIOC, GPIO_PIN_13, 0},  // 常见开发板按键按下为低
    [BSP_KEY_USER2] = {GPIOA, GPIO_PIN_0,  1},
};

void BSP_KEY_Init(void)
{
    // 引脚初始化由HAL层完成
}

BSP_KEY_State_t BSP_KEY_GetState(BSP_KEY_ID_t key)
{
    uint8_t raw_level;

    if (key >= BSP_KEY_COUNT) return BSP_KEY_RELEASED;

    raw_level = HAL_GPIO_ReadPin(key_map[key].port, key_map[key].pin);

    if (key_map[key].press_level == 1) {
        return (raw_level == GPIO_PIN_SET) ? BSP_KEY_PRESSED : BSP_KEY_RELEASED;
    } else {
        return (raw_level == GPIO_PIN_RESET) ? BSP_KEY_PRESSED : BSP_KEY_RELEASED;
    }
}

3.5 跨平台封装的关键——映射表模式

你发现没有，上面LED和按键的代码，核心都是一个常量映射表。这个模式是我最常用的跨平台手段。它的好处是：

我曾经在一个项目里，用这个模式同时支持了3块不同的硬件版本。每块板子的LED引脚、按键极性都不一样，但业务层代码完全复用。测试的时候，只需要编译时选择不同的BSP源文件即可。

3.6 业务层怎么用？——一个简单的例子

假设我们有一个任务，要求按键按下时LED翻转。业务层的代码会写成这样：

/* app_task.c */
#include "bsp_led.h"
#include "bsp_key.h"

void App_Task_KeyControl(void)
{
    if (BSP_KEY_GetState(BSP_KEY_USER1) == BSP_KEY_PRESSED) {
        BSP_LED_Toggle(BSP_LED_RED);
        // 这里可以加一个简单的延时防抖，或者用状态机
    }
}

你看，这段代码里没有任何GPIO端口、引脚号、电平高低的信息。它只关心“哪个按键”、“哪个LED”、“做什么操作”。这就是分层的目的——让业务代码只描述“做什么”，而不关心“怎么做”。

3.7 避坑指南与个人经验

最后，分享几个我踩过的坑：

• 不要把所有外设的BSP写在一个文件里。我曾经图省事，把LED、按键、蜂鸣器全塞进一个bsp.c，结果项目后期文件膨胀到2000行，找东西非常痛苦。建议每个外设一个文件：bsp_led.c、bsp_key.c、bsp_buzzer.c。
• 映射表一定要用const。放在Flash里，不要占用RAM。我见过有人用全局变量做映射表，RAM吃紧不说，还有被意外修改的风险。
• 初始化函数要幂等。也就是说，调用多次和调用一次效果一样。这样在系统启动时，不管谁先初始化，都不会出问题。
• 接口参数用枚举，不要用int。枚举有类型检查，能避免传错参数。比如 BSP_LED_On(0) 和 BSP_LED_On(BSP_LED_RED)，后者一眼就能看出意图。