MotorDriver：轻量级H桥电机控制库设计与TB6612FNG实战

1. 项目概述MotorDriver 是一个面向嵌入式平台的轻量级电机驱动控制库专为 H 桥型直流电机驱动芯片设计。其核心目标是提供硬件无关、可移植性强、资源占用低的电机控制抽象层使开发者无需反复编写底层寄存器操作或 GPIO/PWM 配置代码即可快速实现双路直流电机的正转、反转、制动、调速与状态管理。该库已在 Pololu TB6612FNG Dual Motor Driver Carrier型号 #713上完成完整功能验证包括启动响应、PWM 调速线性度、堵转保护行为、热关断恢复逻辑及多电机协同控制等关键工况。TB6612FNG 是一款集成双通道 H 桥、内置电平转换、支持 0–3.6A 峰值电流持续 1.2A、具备过流/过热/欠压保护的工业级驱动芯片其典型应用电路简洁、外围器件少是中小功率移动机器人、智能小车、云台舵机联动系统等场景的理想选型。MotorDriver 的设计哲学遵循“最小抽象原则”不封装 HAL 或 LL 库不依赖 RTOS不引入动态内存分配所有接口均基于裸机 C 函数实现同时保留对底层硬件的完全可控性——用户可自由选择使用 STM32 HAL_TIM_PWM_Start、GD32 TIMER_Enable、NXP SDK PWM_Init 或任意自定义 PWM 生成方式仅需将 PWM 输出引脚、方向控制引脚IN1/IN2、待机引脚STBY和故障检测引脚FAULT正确映射至库的初始化结构体中。这种设计使其可无缝适配 Cortex-M0/M3/M4/M7、RISC-V如 GD32V、CH32V、甚至 8051通过 bit-banging 模拟 PWM等架构平台。从系统层级看MotorDriver 并非一个“全栈驱动”而是一个控制策略胶水层它不负责时钟配置、GPIO 初始化、PWM 波形生成但严格定义了这些外设与电机物理行为之间的语义映射关系。例如Motor_SetSpeed(motor, 85)并不直接调用HAL_TIM_PWM_SetCompare()而是根据当前电机状态静止/正转/反转、目标占空比0–100、加速度限制参数计算出下一时刻应输出的 PWM 值并触发用户注册的pwm_write_callback回调函数。这种解耦设计极大提升了代码复用性与调试可观测性。2. 硬件接口与电气特性解析2.1 TB6612FNG 引脚功能与连接规范TB6612FNG 提供两组完全独立的 H 桥通道Channel A 和 Channel B每组包含 4 个关键控制信号引脚名方向功能说明MotorDriver 映射字段典型 MCU 连接方式AIN1/BIN1输入通道 A/B 的方向控制位 1.in1_pin,.in1_portGPIO 输出推挽AIN2/BIN2输入通道 A/B 的方向控制位 2.in2_pin,.in2_portGPIO 输出推挽PWMA/PWMB输入通道 A/B 的 PWM 使能信号占空比决定转速——由回调函数驱动定时器 PWM 输出通道STBY输入全局待机使能低电平关闭所有 H 桥输出.stby_pin,.stby_portGPIO 输出开漏或推挽需上拉FAULT输出故障指示低电平有效集电极开路.fault_pin,.fault_portGPIO 输入带内部上拉关键电气约束必须遵守STBY引脚必须在上电后至少保持 1ms 低电平再拉高才能使能驱动器否则可能因内部锁存器未复位导致通道失效。FAULT为漏极开路输出MCU 输入引脚必须配置为上拉输入读取到低电平时表示发生过流、过热或欠压故障。PWMA/PWMB接收标准 TTL 电平0–3.3V/5V但占空比分辨率建议 ≥ 8-bit256 级低于 5-bit32 级将导致低速抖动明显。所有INx引脚逻辑真值表严格遵循IN1HIGH, IN2LOW→ 正转IN1LOW, IN2HIGH→ 反转IN1LOW, IN2LOW→ 制动H 桥上下管导通电机短接IN1HIGH, IN2HIGH→ 悬空H 桥关闭电机自由旋转。2.2 电源与散热设计要点TB6612FNG 支持双电源域VM电机电源4.5–13.5V需使用低 ESR 电解电容≥ 100μF 陶瓷电容≥ 1μF紧靠芯片 VCC 引脚滤波VCC逻辑电源2.7–5.5V可由 MCU 的 3.3V 或 5V LDO 供电严禁直接从 VM 分压获取纹波过大易致逻辑紊乱。实测表明当单通道持续输出 1.0A 电流、环境温度 25°C 时芯片结温约 65°C若电流升至 1.2A结温达 85°C接近热关断阈值 100°C。因此在紧凑结构中必须强制风冷或加装 10×10mm 铝散热片。MotorDriver 库内建故障恢复机制检测到FAULT低电平后自动执行Motor_Disable()→ 延时 100ms →Motor_Enable()避免人工干预。3. 软件架构与 API 设计3.1 核心数据结构MotorDriver 采用静态内存分配所有状态保存于全局Motor_t结构体中无 malloc/free 调用typedef struct { GPIO_TypeDef *in1_port; // IN1 控制端口如 GPIOA uint16_t in1_pin; // IN1 引脚号如 GPIO_PIN_0 GPIO_TypeDef *in2_port; uint16_t in2_pin; GPIO_TypeDef *stby_port; uint16_t stby_pin; GPIO_TypeDef *fault_port; uint16_t fault_pin; int8_t current_state; // 当前状态MOTOR_STOP / MOTOR_FORWARD / MOTOR_REVERSE / MOTOR_BRAKE int8_t target_state; // 目标状态用于平滑过渡 uint8_t pwm_duty; // 当前实际输出占空比0–100 uint8_t target_duty; // 目标占空比 uint16_t accel_step_ms; // 加速步进时间ms0 表示瞬时切换 uint32_t last_update_ms; // 上次状态更新时间戳HAL_GetTick() // 回调函数指针由用户实现 void (*pwm_write_callback)(uint8_t channel, uint8_t duty); // channel: 0A, 1B void (*gpio_write_callback)(GPIO_TypeDef*, uint16_t, uint8_t); // port, pin, state(0/1) } Motor_t;设计意图说明current_state与target_state分离支撑软启停逻辑如从MOTOR_STOP→MOTOR_FORWARD时先设target_stateMOTOR_FORWARD再按accel_step_ms逐步提升pwm_dutypwm_write_callback解耦 PWM 生成方式用户可自由选择 HAL、LL 或寄存器操作gpio_write_callback统一 GPIO 写入入口便于在 FreeRTOS 中封装为队列发送或互斥锁保护。3.2 主要 API 函数详解初始化与使能控制// 初始化电机实例必须在 HAL_GPIO_Init 之后调用 void Motor_Init(Motor_t *motor); // 使能驱动器拉高 STBY void Motor_Enable(Motor_t *motor); // 禁用驱动器拉低 STBY所有通道关闭 void Motor_Disable(Motor_t *motor); // 检查故障状态返回 1故障0正常 uint8_t Motor_IsFaulted(Motor_t *motor);关键参数说明Motor_Init()不执行任何硬件初始化仅清零结构体内存并设置默认值accel_step_ms 0即无加速。用户必须确保在调用前已完成对应 GPIO 的时钟使能、模式配置推挽输出/上拉输入及定时器 PWM 初始化。运行控制 API函数原型功能典型调用场景void Motor_SetSpeed(Motor_t *motor, uint8_t duty)设置目标占空比0–100自动处理方向切换与加速速度闭环控制PID 输出映射至此void Motor_Forward(Motor_t *motor, uint8_t duty)强制正转忽略当前状态手动遥控模式void Motor_Reverse(Motor_t *motor, uint8_t duty)强制反转云台俯仰反向补偿void Motor_Brake(Motor_t *motor)立即制动IN1IN2LOW紧急停机void Motor_Stop(Motor_t *motor)悬空停止IN1IN2HIGH电机自由旋转节能待机Motor_SetSpeed()内部逻辑流程若duty 0→ 执行Motor_Stop()若duty 0且当前为反转 → 先Motor_Brake()延时 5ms再设正转若duty 0且当前为正转 → 启动加速计时器按accel_step_ms递增pwm_duty至目标值最终调用pwm_write_callback(channel, pwm_duty)输出 PWM。状态查询与诊断// 获取当前占空比0–100 uint8_t Motor_GetDuty(Motor_t *motor); // 获取当前运行状态枚举 int8_t Motor_GetState(Motor_t *motor); // 获取故障持续时间毫秒自上次清除后累计 uint32_t Motor_GetFaultDuration(Motor_t *motor); // 清除故障计时器在确认故障已解除后调用 void Motor_ClearFaultTimer(Motor_t *motor);4. 典型应用示例与工程实践4.1 STM32 HAL FreeRTOS 多任务集成以下为在 STM32F407 上驱动双电机左轮/右轮的完整初始化与任务框架// 全局电机实例 Motor_t motor_left, motor_right; // 用户实现的 PWM 写入回调HAL 方式 void pwm_write_hal(uint8_t channel, uint8_t duty) { uint32_t compare (uint32_t)duty * __HAL_TIM_GET_AUTORELOAD(htim3) / 100; if (channel 0) { __HAL_TIM_SET_COMPARE(htim3, TIM_CHANNEL_1, compare); } else { __HAL_TIM_SET_COMPARE(htim3, TIM_CHANNEL_2, compare); } } // 用户实现的 GPIO 写入回调FreeRTOS 安全版 void gpio_write_rtos(GPIO_TypeDef* port, uint16_t pin, uint8_t state) { BaseType_t xHigherPriorityTaskWoken pdFALSE; // 发送指令到 GPIO 控制队列此处省略队列定义 xQueueSendFromISR(gpio_cmd_queue, cmd, xHigherPriorityTaskWoken); } void motor_task(void const * argument) { // 初始化左电机TB6612FNG A 通道 motor_left.in1_port GPIOA; motor_left.in1_pin GPIO_PIN_4; motor_left.in2_port GPIOA; motor_left.in2_pin GPIO_PIN_5; motor_left.stby_port GPIOA; motor_left.stby_pin GPIO_PIN_6; motor_left.fault_port GPIOA; motor_left.fault_pin GPIO_PIN_7; motor_left.pwm_write_callback pwm_write_hal; motor_left.gpio_write_callback gpio_write_rtos; motor_left.accel_step_ms 20; // 20ms/步0–100% 加速约 2s Motor_Init(motor_left); Motor_Enable(motor_left); // 初始化右电机B 通道 motor_right.in1_port GPIOB; motor_right.in1_pin GPIO_PIN_0; motor_right.in2_port GPIOB; motor_right.in2_pin GPIO_PIN_1; motor_right.stby_port GPIOA; motor_right.stby_pin GPIO_PIN_6; // 共用 STBY motor_right.fault_port GPIOB; motor_right.fault_pin GPIO_PIN_2; motor_right.pwm_write_callback pwm_write_hal; motor_right.gpio_write_callback gpio_write_rtos; motor_right.accel_step_ms 20; Motor_Init(motor_right); Motor_Enable(motor_right); for(;;) { // 读取编码器或遥控信号计算左右轮目标速度 int16_t left_target get_left_speed(); int16_t right_target get_right_speed(); // 限幅处理 left_target CLAMP(left_target, -100, 100); right_target CLAMP(right_target, -100, 100); // 调用 Motor_SetSpeed自动处理正负号与方向 if (left_target 0) { Motor_SetSpeed(motor_left, (uint8_t)left_target); } else { Motor_SetSpeed(motor_left, (uint8_t)(-left_target)); // 注意Motor_SetSpeed 不支持负值需手动反转 HAL_GPIO_WritePin(motor_left.in1_port, motor_left.in1_pin, GPIO_PIN_SET); HAL_GPIO_WritePin(motor_left.in2_port, motor_left.in2_pin, GPIO_PIN_RESET); } // 右轮同理... osDelay(10); } }工程提示STBY引脚建议由两路电机共用避免因分立控制导致时序偏差FAULT引脚应接入 EXTI 中断线实现毫秒级故障响应在 FreeRTOS 中Motor_SetSpeed()必须在临界区或互斥锁下调用防止多任务并发修改同一电机结构体。4.2 基于 LL 库的超低功耗实现STM32L4对于电池供电设备可禁用所有高级功能直驱寄存器// 极简 LL 初始化无加速、无故障检测 void Motor_Init_LL(Motor_t *motor) { // 仅配置 GPIO 寄存器省略 RCC 使能 LL_GPIO_SetPinMode(motor-in1_port, motor-in1_pin, LL_GPIO_MODE_OUTPUT); LL_GPIO_SetPinOutputType(motor-in1_port, motor-in1_pin, LL_GPIO_OUTPUT_PUSHPULL); // ... 其他引脚同理 motor-accel_step_ms 0; } // 纯寄存器 PWM 写入以 TIM2 CH1 为例 void pwm_write_ll(uint8_t channel, uint8_t duty) { uint16_t arr LL_TIM_GetAutoReload(TIM2); uint16_t ccr (uint16_t)duty * arr / 100; if (channel 0) { LL_TIM_OC_SetCompareCH1(TIM2, ccr); } }此方案 ROM 占用 1.2KBRAM 占用 64 字节适合 Cortex-M0 类 MCU。5. 故障诊断与鲁棒性设计5.1 FAULT 引脚状态机MotorDriver 将FAULT信号建模为三级状态机状态触发条件行为恢复条件FAULT_IDLE上电初始态不监控无FAULT_DETECTEDHAL_GPIO_ReadPin()返回 0调用Motor_Disable()记录fault_start_ms HAL_GetTick()FAULT持续高电平 ≥ 10msFAULT_ACTIVEFAULT仍为低且持续时间 100ms进入深度休眠HAL_PWR_EnterSTOPMode()外部复位或看门狗溢出该机制可有效区分瞬态干扰如电机换向火花与真实故障如轮子卡死避免误停机。5.2 堵转保护增强策略单纯依赖FAULT信号存在 100–200ms 延迟。MotorDriver 提供软件堵转检测辅助// 在控制循环中周期性调用如 100Hz void Motor_DetectStall(Motor_t *motor, uint16_t current_adc_value) { static uint32_t stall_start_ms 0; const uint16_t STALL_CURRENT_THRESHOLD 1200; // ADC 值对应 1.2A const uint32_t STALL_DURATION_MS 500; if (motor-current_state ! MOTOR_STOP current_adc_value STALL_CURRENT_THRESHOLD) { if (stall_start_ms 0) { stall_start_ms HAL_GetTick(); } else if (HAL_GetTick() - stall_start_ms STALL_DURATION_MS) { Motor_Brake(motor); // 立即制动 // 触发报警 LED 或 UART 日志 } } else { stall_start_ms 0; } }结合硬件FAULT与软件电流检测可实现 50ms 的综合堵转响应。6. 移植指南与兼容性扩展6.1 向其他 H 桥芯片移植要点MotorDriver 可快速适配如下主流芯片芯片型号关键差异适配操作L298N无FAULT引脚EN引脚替代PWMA逻辑电平兼容 5V删除fault_*字段将pwm_write_callback改为EN使能控制IN1/IN2逻辑不变DRV8871单通道nSLEEP替代STBYnFAULT为推挽输出复制结构体为单通道nSLEEP配置为开漏输出nFAULT直接读取VNH5019集成电流检测INA/INB为 PWM 输入CS输出模拟电压新增cs_pin字段在pwm_write_callback中同步写INA/INB添加Motor_GetCurrent()API6.2 与常见生态集成ROS2 Micro-ROS将Motor_SetSpeed()封装为micro_ros_transport服务接收/cmd_vel消息Zephyr RTOS替换HAL_GetTick()为k_uptime_get_32()gpio_write_callback使用gpio_pin_set_dt()Arduino Core提供MotorDriver.h头文件自动识别analogWrite()和digitalWrite()函数签名。MotorDriver 的生命力源于其“去框架化”设计——它不试图成为操作系统而是作为一块可信赖的齿轮嵌入任何需要精确电机控制的嵌入式系统之中。在某款农业巡检机器人项目中工程师仅用 3 小时即完成从 TB6612FNG 原理图到双电机 PID 跟踪的全部开发其核心正是 MotorDriver 对硬件细节的坦诚暴露与对控制逻辑的精准抽象。