ZMotor3Library：面向Motor3控制板的嵌入式电机驱动信号抽象库

1. ZMotor3Library 项目概述ZMotor3Library 是专为 Motor3 控制板设计的嵌入式底层驱动库面向基于 ARM Cortex-M 系列微控制器典型如 STM32F4/F7/H7的电机控制硬件平台。该库并非通用电机驱动框架而是深度耦合 Motor3 板级硬件拓扑的固件抽象层其核心价值在于将物理信号链路——包括三相逆变桥驱动、电流采样、编码器/霍尔反馈、使能与故障信号——映射为可编程、可验证、可复用的软件接口。Motor3 板采用双 MCU 架构主控 MCU如 STM32H743负责运动控制算法、通信协议与系统调度协处理器如 STM32F072专责实时 PWM 生成、硬件死区插入、过流快速关断与模拟前端同步采样。ZMotor3Library 主要运行于主控 MCU通过高速 SPI 或共享内存与协处理器通信实现纳秒级响应的保护机制与微秒级精度的电流环闭环。本库的设计哲学是“信号即接口”Signal-as-Interface。所有功能模块均围绕三类基础信号展开输入信号Input来自外部的指令与反馈包括 CAN 命令帧、UART 配置指令、编码器 ABZ 相脉冲、霍尔 U/V/W 电平、模拟电流采样值±10V 范围、母线电压、温度传感器 ADC 值输出信号Output驱动执行机构的控制量包括六路互补 PWM含可编程死区、数字使能EN、刹车BRAKE、方向DIR、LED 状态指示、CAN 状态上报帧状态信号Signal反映系统健康度的内部信号包括过压/欠压标志、过流锁存、IGBT 驱动故障、编码器丢失、看门狗超时、协处理器通信 CRC 错误。这种信号中心化建模方式使库具备强可测试性所有输入可通过 GPIO 模拟注入所有输出可被逻辑分析仪捕获验证所有状态信号可被单元测试断言覆盖。2. 硬件架构与信号映射关系2.1 Motor3 板关键硬件资源模块器件型号接口类型关键参数ZMotor3Library 映射主控 MCUSTM32H743VIK6—480MHz, 2MB Flash, 1MB RAMZM3_Handle_t实例载体运行 HAL FreeRTOS协处理器STM32F072CBT6SPI2 (主) / SPI3 (从)48MHz, 硬件 PWM 定时器ZM3_CoProc子系统通过ZM3_SpiTransfer()通信三相逆变桥6x STGIPQ5C60T-H6路 PWM 输入600V/15A, 集成驱动与保护ZM3_PWM_SetDutyCycle(),ZM3_PWM_Enable()电流采样2x AD8418A (相电流), 1x INA240 (母线)差分模拟输入 → ADC1_IN12/13/14±10V 输入, 20V/V 增益ZM3_ADC_GetPhaseCurrents(),ZM3_ADC_GetBusVoltage()编码器接口AM26LS32ACN (RS422 接收器)A/B/Z 差分输入100kHz 最大频率, 4x 细分支持ZM3_Encoder_GetPosition(),ZM3_Encoder_GetSpeedRPM()故障信号光耦 TLP290-44路隔离输入过流(OCP)、过温(OTP)、欠压(UVLO)、驱动故障(FAULT)ZM3_Signal_GetFaultFlags()2.2 信号物理层到软件对象的映射ZMotor3Library 将每个物理信号抽象为ZM3_Signal_t结构体统一管理其采样、滤波、阈值判断与事件触发typedef struct { uint8_t id; // 信号唯一IDZM3_SIGNAL_ID_OCP, ZM3_SIGNAL_ID_UVLO等 uint16_t raw_value; // ADC 值或 GPIO 电平0/1 uint16_t filtered_value; // IIR 滤波后值仅模拟信号 uint8_t state; // 当前逻辑状态ZM3_SIGNAL_STATE_HIGH / LOW uint8_t last_state; // 上次状态用于边沿检测 uint32_t timestamp_us; // 最近一次有效采样时间戳DWT_CYCCNT uint32_t debounce_ms; // 消抖时间默认 2ms uint8_t is_debounced; // 是否已消抖 } ZM3_Signal_t;该结构体被封装进ZM3_Handle_t主句柄中构成信号池Signal Pool由ZM3_Signal_UpdateAll()函数在 100μs 定时中断中统一刷新// 在 TIM6 中断服务函数中调用10kHz void TIM6_IRQHandler(void) { HAL_TIM_IRQHandler(htim6); ZM3_Signal_UpdateAll(hzm3); // 同步读取所有GPIO/ADC信号 ZM3_PWM_UpdateDeadTime(hzm3); // 动态调整死区基于温度/母线电压 }此设计确保所有信号状态在确定性时间窗口内完成采集与同步避免因轮询顺序导致的状态不一致问题为安全关键操作如故障急停提供时间可预测性保障。3. 核心 API 接口详解3.1 初始化与配置接口ZM3_Init()是库的入口函数完成硬件外设初始化、信号池注册及默认参数加载/** * brief 初始化 ZMotor3 库 * param hzm3: ZMotor3 句柄指针 * param init_config: 初始化配置结构体 * retval HAL_StatusTypeDef: HAL_OK / HAL_ERROR / HAL_BUSY / HAL_TIMEOUT */ HAL_StatusTypeDef ZM3_Init(ZM3_Handle_t *hzm3, const ZM3_InitConfig_t *init_config); // 典型初始化配置示例FreeRTOS 环境下 ZM3_InitConfig_t init_cfg { .pwm_freq_hz 20000, // PWM 开关频率20kHz .adc_sample_rate_hz 10000, // 电流采样率10kHz双缓冲DMA .encoder_ppr 2500, // 编码器线数2500 PPR四倍频后10000 CPR .fault_response ZM3_FAULT_RESPONSE_SHUTDOWN, // 故障时立即关断PWM .uart_handle huart3, // 用于调试命令行的 UART 外设句柄 };关键配置项说明.pwm_freq_hz直接影响电机噪声与控制带宽。20kHz 是折中选择——高于人耳听觉上限20kHz同时避免开关损耗剧增。若使用 SiC MOSFET可提升至 50–100kHz。.adc_sample_rate_hz必须 ≥ 电流环控制周期的 2 倍奈奎斯特准则。10kHz 对应 100μs 控制周期满足 FOC 算法对电流环通常 50–200μs的实时性要求。.encoder_ppr决定位置分辨率。2500 PPR 编码器在 4x 细分后提供 0.036° 机械角分辨率适用于中高精度伺服场景。3.2 PWM 输出控制接口ZMotor3Library 提供两级 PWM 控制应用层占空比设置与底层硬件寄存器直写。应用层接口推荐/** * brief 设置三相桥臂占空比归一化 0.0 ~ 1.0 * param hzm3: 句柄 * param u_duty: U 相占空比0.0 0%, 1.0 100% * param v_duty: V 相占空比 * param w_duty: W 相占空比 * retval HAL_StatusTypeDef */ HAL_StatusTypeDef ZM3_PWM_SetDutyCycle(ZM3_Handle_t *hzm3, float u_duty, float v_duty, float w_duty); // 使用示例SVPWM 空间矢量调制输出 float sv_pwm[3]; SVPWM_Compute(alfa_beta, sv_pwm[0], sv_pwm[1], sv_pwm[2]); ZM3_PWM_SetDutyCycle(hzm3, sv_pwm[0], sv_pwm[1], sv_pwm[2]);该函数内部执行将浮点占空比映射至定时器自动重装载值ARR与比较寄存器CCR插入硬件死区由协处理器 SPI 命令动态配置执行互补通道同步更新避免上下桥臂直通。底层寄存器接口高级调试用/** * brief 直接写入定时器 CCR 寄存器绕过死区与校验 * param hzm3: 句柄 * param channel: PWM 通道ZM3_PWM_CHANNEL_UH/UH/VH/VH/WH/WH * param ccr_val: CCR 寄存器值0 ~ TIMx-ARR */ void ZM3_PWM_WriteCCR(ZM3_Handle_t *hzm3, ZM3_PWM_Channel_t channel, uint32_t ccr_val);此接口用于死区补偿算法验证硬件故障注入测试强制某相 PWM 锁死协处理器固件升级过程中的 PWM 保持。3.3 信号采集与处理接口模拟信号电流/电压/** * brief 获取三相电流与母线电压经滤波与标定 * param hzm3: 句柄 * param currents: 输出数组 [Iu, Iv, Iw]单位A有符号 * param bus_voltage: 输出母线电压单位V * retval HAL_StatusTypeDef */ HAL_StatusTypeDef ZM3_ADC_GetPhaseCurrents(ZM3_Handle_t *hzm3, float currents[3], float *bus_voltage); // 内部标定流程在 ZM3_Init() 中完成 // 1. 读取零点偏移无电流时 ADC 值 // 2. 读取满量程增益10A 时 ADC 值 // 3. 计算转换系数current_A (raw - offset) * gain_A_per_LSB数字信号编码器/霍尔/** * brief 获取编码器绝对位置与转速 * param hzm3: 句柄 * param position: 输出位置单位脉冲计数非角度 * param rpm: 输出转速单位RPM有符号 * retval HAL_StatusTypeDef */ HAL_StatusTypeDef ZM3_Encoder_GetPositionAndSpeed(ZM3_Handle_t *hzm3, int32_t *position, int16_t *rpm); // 位置计算基于 TIM2 编码器模式计数器32位 // 转速计算采用 M 法测频rpm (cnt_diff * 60 * f_timer) / (ppr * period_us) // 其中 period_us 为两次调用间隔由 FreeRTOS xTaskGetTickCount() 提供3.4 故障管理与安全接口ZMotor3Library 实现三级故障响应机制级别触发条件响应动作可恢复性Level 1警告温度 85°C、母线电压波动 ±5%降低 PWM 占空比降额运行自动恢复Level 2故障过流120%额定、UVLO、OTP立即关断 PWM置位故障标志需软件清除Level 3致命协处理器通信失败、看门狗超时硬件强制拉低 EN 引脚GPIO 复位需上电复位核心 API/** * brief 查询当前故障状态 * param hzm3: 句柄 * param flags: 输出故障标志位掩码ZM3_FAULT_FLAG_OCP | UVLO | ... * retval uint8_t: 故障级别0无故障, 1警告, 2故障, 3致命 */ uint8_t ZM3_Fault_GetStatus(ZM3_Handle_t *hzm3, uint32_t *flags); /** * brief 清除可恢复故障标志仅 Level 1/2 * param hzm3: 句柄 * param flags_to_clear: 待清除的标志位掩码 * retval HAL_StatusTypeDef */ HAL_StatusTypeDef ZM3_Fault_Clear(ZM3_Handle_t *hzm3, uint32_t flags_to_clear); // 典型故障处理任务FreeRTOS Task void FaultHandlerTask(void *argument) { uint32_t fault_flags; uint8_t level; for(;;) { level ZM3_Fault_GetStatus(hzm3, fault_flags); if (level 2) { // Level 2 故障记录日志、点亮红色LED、发送CAN告警帧 ZM3_LED_SetColor(ZM3_LED_RED, ZM3_LED_BLINK_FAST); CAN_SendAlertFrame(fault_flags); // 若持续 3 秒未恢复则进入安全停机 if (xSemaphoreTake(xFaultSem, pdMS_TO_TICKS(3000)) pdTRUE) { ZM3_Safety_Shutdown(hzm3); // 硬件级关断 } } vTaskDelay(pdMS_TO_TICKS(100)); } }4. FreeRTOS 集成实践ZMotor3Library 原生支持 FreeRTOS所有阻塞型 API如 UART 命令解析、CAN 通信均基于队列与信号量实现。4.1 任务划分建议任务名称优先级周期主要职责关键资源ControlTask5100μsFOC 算法执行、PWM 更新hzm3.pwm_mutex,hzm3.adc_queueCommTask31msCAN/UART 命令解析、状态上报hzm3.can_rx_queue,hzm3.uart_tx_semFaultTask610ms故障监控、安全逻辑hzm3.fault_mutexLogTask2100ms温度/电流历史记录SPI Flashhzm3.flash_mutex4.2 关键同步机制PWM 更新互斥hzm3.pwm_mutex为二值信号量确保ZM3_PWM_SetDutyCycle()与ZM3_PWM_WriteCCR()不被并发调用ADC 数据队列hzm3.adc_queue为长度 10 的QueueHandle_tZM3_ADC_GetPhaseCurrents()从队列中取最新有效样本避免阻塞控制环CAN 接收中断到任务通知使用xQueueSendFromISR()将 CAN RX FIFO 数据推入hzm3.can_rx_queueCommTask以非阻塞方式xQueueReceive()处理。// CAN RX 中断服务函数 void CAN_RX0_IRQHandler(void) { HAL_CAN_IRQHandler(hcan1); CAN_RxHeaderTypeDef rx_header; uint8_t rx_data[8]; if (HAL_CAN_GetRxMessage(hcan1, CAN_RX_FIFO0, rx_header, rx_data) HAL_OK) { // 将完整帧打包为结构体 CanFrame_t frame {.header rx_header, .data {0}}; memcpy(frame.data, rx_data, 8); // 发送至队列中断安全 xQueueSendFromISR(hzm3.can_rx_queue, frame, NULL); } }5. 典型工程应用场景5.1 无感 FOC 启动流程利用 ZMotor3Library 的信号同步能力实现可靠的高频注入启动// 步骤1开环高频注入2kHz 正弦波叠加在 D 轴 ZM3_PWM_SetDutyCycle(hzm3, 0.5f 0.1f * sinf(theta_inj), 0.5f 0.1f * sinf(theta_inj - 2.094f), 0.5f 0.1f * sinf(theta_inj 2.094f)); // 步骤2同步采样高频响应电流 ZM3_ADC_GetPhaseCurrents(hzm3, i_alpha_beta, v_bus); // 解调 i_alpha_beta 中的 2kHz 分量 → 估算转子初始位置 // 步骤3切换至闭环观测器PLL if (estimator_lock) { ZM3_FOC_SetMode(hzm3, ZM3_FOC_MODE_OBSERVER); }5.2 多板级联 CAN 同步通过 ZMotor3Library 的 CAN 时间戳功能实现多 Motor3 板 PWM 相位同步误差 100ns// 主板广播同步帧含 64-bit 时间戳 CanSyncFrame_t sync_frame { .timestamp DWT-CYCCNT, // 使用 DWT 计数器作为高精度时基 .sync_id 0x12345678 }; CAN_TransmitSyncFrame(sync_frame); // 从板接收后计算本地时钟偏移并校准 TIMx void CAN_SyncHandler(CanSyncFrame_t *frame) { uint32_t local_ts DWT-CYCCNT; int32_t offset (int32_t)(frame-timestamp - local_ts); __HAL_TIM_SET_COUNTER(htim1, __HAL_TIM_GET_COUNTER(htim1) offset); }5.3 硬件在环HIL测试接口ZMotor3Library 提供ZM3_TestMode_Enter()接口将所有输出信号切换为 GPIO 模拟模式便于连接 HIL 仿真器// 进入测试模式后 // - PWM 输出引脚变为 GPIO 输出可由仿真器驱动 // - 电流采样 ADC 输入切换至仿真器 DAC 输出 // - 编码器信号由仿真器 ABZ 发生器注入 ZM3_TestMode_Enter(hzm3, ZM3_TEST_MODE_GPIO_OVERRIDE); // 此时可运行自动化测试脚本 Test_RunCurrentLoopStepResponse(hzm3); Test_RunPositionTracking(hzm3);6. 调试与诊断工具链ZMotor3Library 内置轻量级调试子系统无需额外 JTAG 探针即可完成现场诊断UART 命令行接口通过ATZM3指令集实时查询/配置参数ATZM3?→ 返回当前 PWM 占空比、电流、温度、故障码ATZM3OCP,0→ 清除过流故障LED 状态编码红/绿/蓝三色 LED 组合显示运行状态RED ON GREEN BLINK Level 2 故障待清除BLUE FAST BLINK 协处理器通信异常故障日志环形缓冲区存储最近 32 次故障的精确时间戳、信号快照与堆栈回溯使用__builtin_return_address(0)性能统计ZM3_Perf_GetStats()返回控制环抖动Jitter、最差执行时间Worst-case latency、ADC 丢包率等关键指标用于评估实时性裕量。7. 安全合规性设计要点ZMotor3Library 的实现严格遵循 IEC 61800-5-2可调速电力驱动系统安全标准双独立故障检测路径过流既通过 ADC 采样软件判断也通过比较器硬件电路LM393直接触发 EXTI二者结果进行 AND 门仲裁看门狗分层监护独立窗口看门狗IWDG监控主控 MCU独立独立看门狗independent watchdog in co-processor监控协处理器任一失效均触发 EN 引脚硬拉低安全状态确认所有安全关断操作ZM3_Safety_Shutdown()后必须通过ZM3_Safety_ConfirmShutdown()读取 EN 引脚电平为低才认为关断成功参数防错校验所有通过 UART/CAN 设置的参数如 PID 增益、限幅值均进行范围检查与 CRC32 校验非法值自动拒绝并上报错误码。这些设计使 ZMotor3Library 不仅满足功能需求更可作为 SIL2Safety Integrity Level 2认证的基础软件组件为工业伺服、机器人关节、电动车辆电控等安全关键应用提供可信支撑。