tynyDC：面向MX1919的超轻量电机驱动库

1. 项目概述tynyDC是一个面向嵌入式系统的轻量级驱动库专为 MX1919 双路直流电机驱动芯片设计。该库并非通用型电机控制框架而是聚焦于资源受限场景下的最小可行驱动实现——适用于 Cortex-M0/M0/M3 等低功耗 MCU如 STM32G0、STM32F0、nRF52832、RISC-V 架构 MCU如 GD32VF103以及裸机Bare-metal或 FreeRTOS 环境下的实时控制任务。MX1919 是一款国产高集成度双 H 桥驱动 IC采用 SOP-16 封装支持宽电压输入4.5V–36V单通道持续输出电流达 3.5A峰值 5A内置过流保护OCP、过温关断TSD、欠压锁定UVLO及死区时间控制逻辑。其控制接口极为简洁仅需两对独立的 PWMDIR 信号IN1/IN2 与 IN3/IN4即可完成双路电机的正反转与调速无需 SPI/I²C 配置寄存器亦不依赖外部电流采样电路。这一硬件特性决定了tynyDC的核心设计哲学——零配置、零依赖、零抽象开销。tynyDCv0.0.1 作为首个测试版本已通过 STM32F072RBCortex-M0平台在 24V/12W 直流有刷电机上完成基础功能验证双路独立 PWM 调速、方向切换、急停Brake与自由停止Coast模式切换。该版本未引入 HAL 库封装层所有 GPIO 与定时器操作均基于 LLLow LayerAPI 或直接寄存器访问确保代码体积小于 800 字节ARM Thumb-2 编译中断响应延迟稳定控制在 1.2μs 以内以 TIM1 UPD 中断为例。2. MX1919 硬件接口与电气特性解析理解tynyDC的工程实现逻辑必须首先厘清 MX1919 的引脚定义与关键时序约束。下表列出其核心控制引脚与推荐工作条件引脚名类型功能说明电平要求工程注意事项VCC电源逻辑供电3.3V 或 5V3.0–5.5V必须与 MCU I/O 电压域匹配建议并联 100nF 10μF 陶瓷电解电容滤波VM电源电机驱动供电4.5–36V需独立大电流走线靠近芯片放置 100μF 以上电解电容GND地逻辑与功率地共接点—必须单点连接避免地弹干扰 ADC 或通信外设IN1/IN2输入通道 A 控制信号TTL/CMOS 兼容IN1H/IN2L → 正转IN1L/IN2H → 反转IN1IN2L → 刹车IN1IN2H → 悬空CoastIN3/IN4输入通道 B 控制信号TTL/CMOS 兼容同上完全独立于通道 AOUT1/OUT2输出通道 A 驱动输出开漏推挽接电机两端布线需等长、加粗≥20milOUT3/OUT4输出通道 B 驱动输出开漏推挽同上FAULT输出故障状态指示开漏低有效外接 10kΩ 上拉至 VCCMCU 需配置为带滤波的外部中断输入关键时序参数直接影响tynyDC的底层驱动策略最小脉冲宽度INx 输入高/低电平持续时间 ≥ 500ns典型值这意味着即使在 48MHz 系统时钟下LL_GPIO_SetPin() 与 LL_GPIO_ResetPin() 的组合也能满足要求方向切换建立时间从“正转”IN1H,IN2L切换至“反转”IN1L,IN2H时必须确保 IN1 与 IN2 同时为 L 的死区时间 ≥ 1.5μs否则可能引发直通短路。tynyDC在tinydc_set_direction()函数中强制插入 2μs NOP 延迟对应 96 个周期 48MHz此值经实测可覆盖全温度范围PWM 频率范围推荐 1kHz–20kHz。低于 1kHz 易产生可闻噪声高于 20kHz 则开关损耗显著上升。tynyDC默认初始化 TIMx 为 10kHz100μs 周期占空比分辨率 8-bit0–255。工程提示MX1919 的FAULT引脚在发生过流、过热或 UVLO 时会立即拉低并锁存至故障清除。tynyDC不提供自动故障恢复机制因实际应用中需由上层逻辑判断故障类型如堵转 vs 散热不良并执行差异化处理重启电机 vs 降低负载。用户需在FAULT中断服务程序中调用tinydc_clear_fault()并检查tinydc_get_fault_status()返回值。3.tynyDCAPI 接口规范与实现逻辑tynyDC提供 7 个核心 API全部为静态内联函数static inline编译时直接展开消除函数调用开销。所有函数均以tinydc_为前缀严格遵循 C99 标准无全局变量依赖线程安全FreeRTOS 下需确保同一电机通道不被多任务并发调用。3.1 初始化与硬件绑定// 绑定 GPIO 引脚与定时器通道完成硬件资源配置 // 参数说明 // ch: 电机通道枚举值TINYDC_CH_A 或 TINYDC_CH_B // pwm_port/pwm_pin: PWM 输出引脚如 GPIOA, LL_GPIO_PIN_8 // dir1_port/dir1_pin: 方向引脚 1IN1 或 IN3 // dir2_port/dir2_pin: 方向引脚 2IN2 或 IN4 // tim: 定时器实例LL_TIM_INSTANCE_t如 TIM1 // tim_ch: 定时器通道LL_TIM_CHANNEL_CH1 等 // 返回值0成功非0错误码目前仅返回 -1 表示 TIM 通道不支持 PWM int tinydc_init( tinydc_channel_t ch, LL_GPIO_TypeDef* pwm_port, uint32_t pwm_pin, LL_GPIO_TypeDef* dir1_port, uint32_t dir1_pin, LL_GPIO_TypeDef* dir2_port, uint32_t dir2_pin, LL_TIM_TypeDef* tim, uint32_t tim_ch );实现要点自动配置 PWM 引脚为复用推挽输出LL_GPIO_MODE_ALTERNATE方向引脚为推挽输出LL_GPIO_MODE_OUTPUT对tim执行基本初始化时基时钟分频 SystemCoreClock / (10000 * 65536)确保 10kHz 基频计数模式为向上计数将tim_ch配置为 PWM 模式 1LL_TIM_OCMODE_PWM1预装载使能LL_TIM_CCUPDATESOURCE_GLOBAL关键设计不启用定时器主输出使能LL_TIM_MOE_DISABLE由用户在tinydc_start()中显式开启避免初始化瞬间产生意外 PWM 输出。3.2 电机控制核心函数// 启动指定通道的 PWM 输出使能定时器主输出 void tinydc_start(tinydc_channel_t ch); // 停止 PWM 输出关闭定时器主输出保持当前方向引脚状态 void tinydc_stop(tinydc_channel_t ch); // 设置 PWM 占空比0–25500%255100% void tinydc_set_duty(tinydc_channel_t ch, uint8_t duty); // 设置电机方向与运行模式 // mode: TINYDC_DIR_FORWARD / TINYDC_DIR_REVERSE / TINYDC_DIR_BRAKE / TINYDC_DIR_COAST void tinydc_set_direction(tinydc_channel_t ch, tinydc_dir_mode_t mode); // 紧急停止同时拉低 IN1/IN2通道 A或 IN3/IN4通道 B强制刹车 void tinydc_emergency_brake(tinydc_channel_t ch);tinydc_set_direction()内部逻辑详解以通道 A 为例static inline void tinydc_set_direction_a(tinydc_dir_mode_t mode) { switch(mode) { case TINYDC_DIR_FORWARD: LL_GPIO_SetPin(dir1_port_a, dir1_pin_a); // IN1 H LL_GPIO_ResetPin(dir2_port_a, dir2_pin_a); // IN2 L break; case TINYDC_DIR_REVERSE: LL_GPIO_ResetPin(dir1_port_a, dir1_pin_a); // IN1 L LL_GPIO_SetPin(dir2_port_a, dir2_pin_a); // IN2 H break; case TINYDC_DIR_BRAKE: LL_GPIO_ResetPin(dir1_port_a, dir1_pin_a); // IN1 L LL_GPIO_ResetPin(dir2_port_a, dir2_pin_a); // IN2 L break; case TINYDC_DIR_COAST: LL_GPIO_SetPin(dir1_port_a, dir1_pin_a); // IN1 H LL_GPIO_SetPin(dir2_port_a, dir2_pin_a); // IN2 H break; } // 强制插入 2μs 死区延迟96 cycles 48MHz for(volatile uint32_t i 0; i 96; i); }此实现确保任何方向切换均经过IN1IN2L的安全中间态彻底规避直通风险。3.3 故障管理接口// 清除 FAULT 锁存状态需先拉高 FAULT 引脚 10μs void tinydc_clear_fault(void); // 读取当前 FAULT 引脚电平0故障1正常 // 注意此函数不带去抖需由用户在中断或轮询中自行添加软件滤波 uint8_t tinydc_get_fault_status(void);tinydc_clear_fault()实现原理 MX1919 的故障锁存需通过将FAULT引脚短暂拉高10μs来复位。tynyDC采用 GPIO 模拟开漏输出方式// 将 FAULT 引脚配置为推挽输出拉高 LL_GPIO_SetPinMode(FAULT_PORT, FAULT_PIN, LL_GPIO_MODE_OUTPUT); LL_GPIO_SetPinOutputType(FAULT_PORT, FAULT_PIN, LL_GPIO_OUTPUT_PUSHPULL); LL_GPIO_SetPin(FAULT_PORT, FAULT_PIN); LL_mDelay(1); // 10μs 延迟 // 恢复为浮空输入内部上拉生效 LL_GPIO_SetPinMode(FAULT_PORT, FAULT_PIN, LL_GPIO_MODE_INPUT); LL_GPIO_SetPinPull(FAULT_PORT, FAULT_PIN, LL_GPIO_PULL_NO);4. 典型应用示例双电机差速转向小车以下代码展示如何在 STM32F072RB 上驱动两个 MX1919实现小车的前进、后退、原地转向与紧急制动。该示例采用 FreeRTOS创建两个独立任务分别控制左右轮体现tynyDC的多通道并发能力。4.1 硬件连接映射MCU 引脚功能MX1919 引脚PA8TIM1_CH1 PWMIN1 (CH_A)PA9TIM1_CH2 PWMIN3 (CH_B)PB0GPIOIN2 (CH_A)PB1GPIOIN4 (CH_B)PC13GPIO (FAULT)FAULT4.2 FreeRTOS 任务实现#include tinydc.h #include FreeRTOS.h #include task.h // 电机参数左轮CH_A右轮CH_B #define LEFT_WHEEL TINYDC_CH_A #define RIGHT_WHEEL TINYDC_CH_B // 任务堆栈大小 #define MOTOR_TASK_STACK_SIZE 128 // 全局控制结构体避免多任务竞争 typedef struct { int8_t left_speed; // -100 ~ 100 int8_t right_speed; // -100 ~ 100 uint8_t emergency; // 1触发急停 } robot_cmd_t; static robot_cmd_t g_robot_cmd {0}; // 左轮控制任务 void vLeftMotorTask(void *pvParameters) { // 初始化PA8(TIM1_CH1), PB0(IN2), TIM1, CH1 tinydc_init(LEFT_WHEEL, GPIOA, LL_GPIO_PIN_8, GPIOB, LL_GPIO_PIN_0, GPIOB, LL_GPIO_PIN_0, TIM1, LL_TIM_CHANNEL_CH1); while(1) { if (g_robot_cmd.emergency) { tinydc_emergency_brake(LEFT_WHEEL); g_robot_cmd.emergency 0; } else { // 将 -100~100 映射到 0~255 占空比并设置方向 uint8_t duty (g_robot_cmd.left_speed 0) ? (g_robot_cmd.left_speed * 255 / 100) : (-g_robot_cmd.left_speed * 255 / 100); if (g_robot_cmd.left_speed 0) { tinydc_set_direction(LEFT_WHEEL, TINYDC_DIR_FORWARD); } else if (g_robot_cmd.left_speed 0) { tinydc_set_direction(LEFT_WHEEL, TINYDC_DIR_REVERSE); } else { tinydc_set_direction(LEFT_WHEEL, TINYDC_DIR_BRAKE); } tinydc_set_duty(LEFT_WHEEL, duty); } vTaskDelay(10); // 10ms 更新周期 } } // 右轮控制任务同理使用 PA9/TIM1_CH2/PB1 void vRightMotorTask(void *pvParameters) { tinydc_init(RIGHT_WHEEL, GPIOA, LL_GPIO_PIN_9, GPIOB, LL_GPIO_PIN_1, GPIOB, LL_GPIO_PIN_1, TIM1, LL_TIM_CHANNEL_CH2); while(1) { if (g_robot_cmd.emergency) { tinydc_emergency_brake(RIGHT_WHEEL); g_robot_cmd.emergency 0; } else { uint8_t duty (g_robot_cmd.right_speed 0) ? (g_robot_cmd.right_speed * 255 / 100) : (-g_robot_cmd.right_speed * 255 / 100); if (g_robot_cmd.right_speed 0) { tinydc_set_direction(RIGHT_WHEEL, TINYDC_DIR_FORWARD); } else if (g_robot_cmd.right_speed 0) { tinydc_set_direction(RIGHT_WHEEL, TINYDC_DIR_REVERSE); } else { tinydc_set_direction(RIGHT_WHEEL, TINYDC_DIR_BRAKE); } tinydc_set_duty(RIGHT_WHEEL, duty); } vTaskDelay(10); } } // 主函数启动 FreeRTOS int main(void) { LL_APB2_GRP1_EnableClock(LL_APB2_GRP1_PERIPH_SYSCFG); LL_APB1_GRP1_EnableClock(LL_APB1_GRP1_PERIPH_PWR); // 初始化系统时钟48MHz SystemClock_Config(); // 创建电机控制任务 xTaskCreate(vLeftMotorTask, LeftMotor, MOTOR_TASK_STACK_SIZE, NULL, 2, NULL); xTaskCreate(vRightMotorTask, RightMotor, MOTOR_TASK_STACK_SIZE, NULL, 2, NULL); // 启动调度器 vTaskStartScheduler(); for(;;); }4.3 运动控制逻辑封装上层应用可通过修改g_robot_cmd结构体实现高级运动前进g_robot_cmd.left_speed g_robot_cmd.right_speed 80;后退g_robot_cmd.left_speed g_robot_cmd.right_speed -80;左转原地g_robot_cmd.left_speed -60; g_robot_cmd.right_speed 60;右转原地g_robot_cmd.left_speed 60; g_robot_cmd.right_speed -60;紧急制动g_robot_cmd.emergency 1;5. 调试与故障排查指南tynyDC的极简设计降低了调试复杂度但需关注以下关键点5.1 常见问题与解决方案现象可能原因排查步骤解决方案电机完全不转1.tinydc_start()未调用2. VM 电源未接入或过低3.FAULT引脚持续低电平1. 用逻辑分析仪抓pwm_port/pin是否有波形2. 万用表测 VM 电压3. 测FAULT电平若为低则读tinydc_get_fault_status()1. 确保tinydc_start()在tinydc_init()后调用2. 检查 VM 供电路径与电容3. 执行tinydc_clear_fault()并检查散热电机抖动/异响1. PWM 频率过低1kHz2. 方向切换无死区延迟3. 电源纹波过大1. 用示波器测 PWM 波形频率2. 检查tinydc_set_direction()是否含 NOP 延迟3. 用示波器测 VM 对地纹波1. 修改tinydc_init()中 TIM 时基参数提升频率2. 确认 v0.0.1 源码中for()循环存在3. 增加 VM 电解电容容量至 470μF单通道失效1. GPIO 引脚配置错误如复用功能未使能2. 定时器通道与引脚映射不匹配1. 查阅 MCU datasheet 确认 PA8 是否支持 TIM1_CH12. 检查LL_GPIO_SetAFPin_XX()调用1. 在tinydc_init()中添加LL_GPIO_SetAFPin_XX(GPIOA, LL_GPIO_PIN_8, LL_GPIO_AF_2)以 STM32F0 为例5.2 关键信号观测点PWM 信号质量使用示波器探头接地弹簧针紧贴 PWM 引脚焊盘观察上升/下降沿是否陡峭100ns、占空比是否随tinydc_set_duty()线性变化方向引脚时序同时观测 IN1 与 IN2确认方向切换时存在明确的IN1IN2L重叠期宽度 ≥2μsFAULT 引脚行为在电机堵转时FAULT应立即拉低并保持执行tinydc_clear_fault()后应恢复高电平。6. 与主流嵌入式生态的集成路径tynyDC的设计天然适配多种开发环境无需修改源码即可集成6.1 STM32CubeMX HAL 库兼容方案尽管tynyDC基于 LL但可无缝嵌入 HAL 工程在 CubeMX 中配置 TIMx 为 PWM GenerationGPIO 为 GPIO_Output生成代码后在main.c中包含tinydc.h将tinydc_init()的tim参数替换为htimx.Instancetim_ch替换为LL_TIM_CHANNEL_CHx如LL_TIM_CHANNEL_CH1注意禁用 HAL_TIM_PWM_Start()改用tinydc_start()启动 PWM。6.2 Zephyr RTOS 集成Zephyr 用户可利用其设备树Device Tree机制motor_a { compatible mx,1919; pwms pwm1 1 10000000 0; // channel 1, 10kHz direction-gpios gpioa 0 GPIO_ACTIVE_HIGH, gpioa 1 GPIO_ACTIVE_HIGH; };在驱动中解析 device tree 节点将pwms属性传给tinydc_init()的tim/tim_ch参数direction-gpios传给dir1_port/dir1_pin等。6.3 与传感器融合的扩展思路tynyDC的低耦合设计便于与编码器、IMU 等构成闭环系统速度闭环将霍尔编码器 A/B 相接入 MCU 的 TIMx 编码器接口HAL_TIM_Encoder_Start()获取 RPM通过 PID 计算tinydc_set_duty()的目标值姿态稳定MPU6050 输出俯仰角当角度超限时tinydc_set_duty()动态调整左右轮差速实现自平衡。7. 性能边界与优化空间tynyDCv0.0.1 的实测性能边界如下最小可控占空比1/255 ≈ 0.39%对应电机最低维持转速约 30RPM 24V最大 PWM 频率受限于 TIMx 时钟STM32F0 下可达 48MHz/64 750kHz此时占空比分辨率降至 4-bit多通道同步性双通道 PWM 相位误差 5ns由同一 TIMx 计数器驱动内存占用ROM 800BRAM 0B无静态变量。未来优化方向v0.1.0 规划增加tinydc_set_ramp_rate()接口实现加减速斜坡控制消除启停冲击支持硬件死区插入通过 TIMx BDTR 寄存器替代软件 NOP 延迟提供 CMSIS-DSP 加速的 PID 控制器模板与tinydc_set_duty()直接对接。tynyDC的价值不在于功能繁复而在于以最精炼的代码在最严苛的资源约束下可靠地释放 MX1919 的全部硬件能力。一个合格的嵌入式工程师应当能读懂这 800 行代码背后的每一个晶体管开关时序并在自己的 PCB 上复现它。