单片机与物联网 / 系统课时
驱动模块设计
驱动模块设计
驱动模块设计的目标不是简单地把 HAL 调用搬进单独文件,而是建立稳定边界:应用层只表达“打开、关闭、读取、写入”等业务意图,驱动层负责引脚、时序、寄存器和错误处理。本课用 LED 驱动完成一个可复用的最小结构。
学习目标
- 划分应用层、驱动层与 HAL 层的职责
- 使用头文件、源文件和配置结构封装硬件细节
- 设计清晰、可扩展且便于测试的驱动接口
分层边界
应用层决定何时执行功能,驱动层决定如何操作具体器件,HAL 层提供 GPIO、SPI、I2C 等芯片级接口。应用代码不应直接散落端口号、寄存器地址和有效电平,否则更换开发板或器件时会产生大量联动修改。
一个驱动模块通常由公开头文件、私有实现文件和实例配置组成。头文件声明外部可用的类型与函数,源文件保存实现细节,配置结构描述端口、地址、超时或工作模式。这样既能复用同一份实现,也能创建多个独立实例。

设计最小公开接口
公开接口应围绕设备能力命名,而不是暴露底层实现。例如 LED 驱动提供初始化、设置状态和翻转状态即可,不需要让应用层知道 GPIO 是高电平点亮还是低电平点亮。
下面三个文件组成一个最小示例,依赖 STM32CubeMX 生成的 GPIO 初始化代码。LedDriverConfig 保存不会频繁变化的硬件参数,LedDriver 表示一个可独立使用的驱动实例。
/* led_driver.h */
#ifndef LED_DRIVER_H
#define LED_DRIVER_H
#include "stm32f1xx_hal.h"
#include <stdbool.h>
/* 配置结构保存实例差异,不向应用层暴露电平判断。 */
typedef struct {
GPIO_TypeDef *port;
uint16_t pin;
GPIO_PinState active_level;
} LedDriverConfig;
/* 每个对象持有自己的配置,可同时创建多个 LED 实例。 */
typedef struct {
LedDriverConfig config;
} LedDriver;
void LedDriver_Init(LedDriver *driver, const LedDriverConfig *config);
void LedDriver_Set(LedDriver *driver, bool on);
void LedDriver_Toggle(LedDriver *driver);
#endif/* led_driver.c */
#include "led_driver.h"
static GPIO_PinState LedDriver_GetLevel(const LedDriver *driver, bool on)
{
/* 有效电平由配置决定,应用层无需判断 LED 是高电平还是低电平点亮。 */
if (on) {
return driver->config.active_level;
}
/* 关闭状态必须返回与有效电平相反的电平。 */
return driver->config.active_level == GPIO_PIN_SET
? GPIO_PIN_RESET
: GPIO_PIN_SET;
}
void LedDriver_Init(LedDriver *driver, const LedDriverConfig *config)
{
driver->config = *config;
/* 初始化完成后先关闭 LED,建立确定的硬件状态。 */
LedDriver_Set(driver, false);
}
void LedDriver_Set(LedDriver *driver, bool on)
{
HAL_GPIO_WritePin(
driver->config.port,
driver->config.pin,
LedDriver_GetLevel(driver, on)
);
}
void LedDriver_Toggle(LedDriver *driver)
{
HAL_GPIO_TogglePin(driver->config.port, driver->config.pin);
}/* main.c:用户代码区片段 */
#include "main.h"
#include "gpio.h"
#include "led_driver.h"
int main(void)
{
LedDriver status_led;
/* 本例按 STM32F103 常见 PC13 低电平有效 LED 配置。 */
const LedDriverConfig status_led_config = {
.port = GPIOC,
.pin = GPIO_PIN_13,
.active_level = GPIO_PIN_RESET
};
HAL_Init();
SystemClock_Config();
MX_GPIO_Init();
LedDriver_Init(&status_led, &status_led_config);
while (1) {
LedDriver_Toggle(&status_led);
HAL_Delay(500);
}
}预期结果
PC13 连接的低电平有效 LED 每 500 ms 翻转一次状态。
若开发板的 LED 引脚或有效电平不同,只修改 status_led_config。配置、状态与私有实现
配置描述实例的固定差异,例如 GPIO 端口、I2C 地址和 SPI 片选引脚;状态描述运行期间会变化的数据,例如初始化标志、缓存值和错误计数。简单 LED 不需要额外状态,但传感器、显示屏和通信模块通常需要在驱动实例中保存这些信息。
只供模块内部使用的辅助函数应声明为 static,避免污染全局符号。寄存器地址、私有命令和内部缓冲区也应放在源文件中,不要全部暴露到头文件。公开接口越稳定,应用层对底层变化越不敏感。
扩展驱动而不污染应用层
当驱动从 GPIO 扩展到 SPI 或 I2C 设备时,可以继续保留同样的结构:配置中增加总线句柄、设备地址和超时,公开接口增加与设备能力对应的读写函数,源文件内部负责命令帧、重试和数据转换。
错误处理应通过返回值表达,例如返回 HAL_StatusTypeDef 或项目统一错误码,而不是在驱动内部静默失败。需要异步操作时,可增加完成回调或状态查询接口,但不要让应用层直接操作 DMA 标志位和中断寄存器。
验收与常见错误
验收时先确认应用层没有直接调用该设备对应的 HAL 接口,再检查更换引脚是否只需修改配置。最后创建第二个驱动实例,验证两个实例不会共享错误状态或覆盖彼此配置。
常见问题包括在头文件中定义可变全局变量、把板级引脚写死在源文件、公开过多内部函数,以及初始化函数没有建立确定的初始状态。这些问题都会削弱模块复用性,并增加后续测试和迁移成本。