1. 项目概述mrm-node是面向 MRMSModular Robotic Motion System架构设计的专用 CAN 总线节点固件库专为基于 STM32 系列微控制器的嵌入式运动控制板卡开发。其核心定位并非通用 CAN 协议栈而是构建一个可配置、可扩展、面向机电执行器与传感器的本地化 CAN 设备节点——即在单块硬件上完成伺服驱动、电机控制、传感器采集等本地实时任务并通过标准化 CAN 报文接口向上位机如主控 MCU、ROS 节点或 PLC暴露统一的功能服务。该库不依赖外部操作系统可直接运行于裸机Bare-Metal环境亦可无缝集成 FreeRTOS 实时操作系统底层通信基于 STM32 标准外设库HAL或更轻量的 LLLow-Layer驱动确保对不同型号 STM32如 STM32F0/F3/F4/G0/G4/H7 系列的广泛兼容性。所有功能模块均围绕“本地执行 远程访问”双模态设计本地任务如 PID 闭环、PWM 输出、ADC 采样由 MCU 独立完成无需总线交互而参数配置、状态查询、指令下发等操作则通过预定义的 CAN 报文 ID 和数据格式实现形成一套轻量级、确定性高的设备级通信协议。从工程角度看mrm-node的本质是一个固件框架Firmware Framework而非单纯驱动库。它定义了统一的设备抽象模型Device Abstraction Model可插拔的外设驱动注册机制Servo/Motor/Sensor Driver Registration基于 CAN ID 的命令-响应式服务接口Command-Response Service Interface本地资源调度与状态管理引擎Local Resource Scheduler State Manager这种设计显著降低了多节点机器人系统的集成复杂度开发者无需为每类执行器重复编写 CAN 解析逻辑只需按规范实现对应驱动并注册进框架即可获得标准化的远程控制能力。2. 系统架构与核心组件2.1 整体分层架构mrm-node采用清晰的四层架构自底向上分别为层级名称关键职责典型实现方式L1硬件抽象层HAL/LL初始化 CAN 外设、GPIO、TIM、ADC、PWM 等基础外设提供寄存器级或 HAL 封装的底层操作接口HAL_CAN_Init()、HAL_TIM_PWM_Start()、LL_ADC_Enable()L2设备驱动层Device Drivers面向具体物理设备的驱动封装如mrm_servo_driver_t、mrm_motor_driver_t、mrm_sensor_driver_t负责将抽象命令映射为硬件操作PWM 占空比计算、PID 运算、I²C/SPI 数据读取L3节点服务层Node Service Layer核心调度中枢解析 CAN 报文 → 分发至对应设备驱动 → 执行本地任务 → 构造响应报文维护全局设备状态表、心跳计时器、错误日志缓冲区mrm_node_process_can_rx()、mrm_node_update_state()L4应用接口层Application Interface向用户代码暴露的 C API 集合用于注册设备、配置参数、触发诊断等屏蔽底层协议细节mrm_node_register_servo()、mrm_node_set_control_mode()该分层结构严格遵循“关注点分离”原则L1 保证硬件可移植性L2 实现设备行为可替换性L3 提供协议一致性保障L4 降低应用开发门槛。2.2 CAN 协议设计面向设备服务的精简指令集mrm-node未采用 CANopen 或 J1939 等重型协议而是定义了一套极简但高扩展性的二进制指令集全部基于标准帧11-bit ID共划分三类报文2.2.1 控制指令报文Command Frame, ID: 0x100–0x1FF用于下发动作指令或配置参数数据域格式固定为[CMD_ID][TARGET_ID][PAYLOAD...]CMD_ID1 byte命令类型如0x01设置目标位置、0x02启动闭环、0x03写入 PID 参数TARGET_ID1 byte目标设备逻辑 ID0x00 表示广播0x01–0xFE 为单个设备0xFF 保留PAYLOAD0–6 bytes命令参数按小端序编码如 4-byte float 或 2-byte int工程考量限定 8 字节数据长度是为兼顾实时性与带宽效率。CAN 总线在 500 kbps 下单帧传输耗时约 180 μs远低于典型伺服响应时间1–10 ms避免因长报文导致的总线拥塞。2.2.2 状态响应报文Response Frame, ID: 0x200–0x2FF设备执行指令后主动回传ID 0x200 TARGET_ID数据域格式[STATUS_CODE][PAYLOAD...]STATUS_CODE1 byte0x00成功0x01设备未注册0x02参数越界0x03硬件故障如过流、过温PAYLOAD0–6 bytes返回值如当前位置、当前速度、温度值等2.2.3 心跳与诊断报文Heartbeat/Diag Frame, ID: 0x300周期性广播默认 100 msID 固定为0x300数据域[NODE_ID][MODE][VOLTAGE][TEMP][ERROR_FLAGS]NODE_ID1 byte本节点唯一标识出厂烧录MODE1 byte当前运行模式0x00待机0x01位置模式0x02速度模式VOLTAGE2 bytesADC 采样母线电压mV小端TEMP2 bytesMCU 内部温度传感器读数0.1°C小端ERROR_FLAGS2 bytes位图bit0过流bit1过温bit2CAN 错误被动bit3看门狗复位关键设计心跳报文集成关键诊断信息使上位机无需轮询即可掌握节点健康状态极大降低总线负载。3. 主要 API 接口详解3.1 设备注册 API所有外设必须通过注册函数接入框架注册过程完成资源绑定、状态初始化及服务映射// 注册舵机驱动支持 PWM反馈 typedef struct { uint8_t id; // 逻辑 ID (1–126) TIM_HandleTypeDef *htim; // PWM 定时器句柄 uint32_t channel; // PWM 通道 (TIM_CHANNEL_1/2/3/4) ADC_HandleTypeDef *hadc; // 反馈 ADC 句柄可选 uint32_t adc_channel; // ADC 通道可选 float min_pulse_us; // 最小脉冲宽度 (μs)对应 0° float max_pulse_us; // 最大脉冲宽度 (μs)对应 180° float gear_ratio; // 减速比用于角度-位置换算 } mrm_servo_config_t; // 注册函数原型 mrm_status_t mrm_node_register_servo(const mrm_servo_config_t *config);参数说明id设备逻辑地址决定其响应的 CAN ID如 ID0x05则响应0x105指令、发送0x205响应htim/channel指定 PWM 输出引脚框架自动调用HAL_TIM_PWM_Start()hadc/adc_channel若提供则启用闭环控制框架周期性调用HAL_ADC_Start()HAL_ADC_PollForConversion()min/max_pulse_us标定参数框架内部线性映射angle → pulse_width避免应用层重复计算返回值MRM_OK成功、MRM_ERR_INVALID_PARAMID 冲突或指针为空、MRM_ERR_RESOURCE_BUSY定时器/ADC 已被占用3.2 控制模式配置 API支持动态切换设备工作模式直接影响本地任务执行逻辑// 设置舵机控制模式 mrm_status_t mrm_node_set_servo_mode(uint8_t servo_id, mrm_servo_mode_t mode); // 模式枚举 typedef enum { MRM_SERVO_MODE_POSITION 0x01, // 位置模式接收目标角度内部 PID 调节 MRM_SERVO_MODE_VELOCITY 0x02, // 速度模式接收目标角速度开环 PWM 输出 MRM_SERVO_MODE_TORQUE 0x03, // 力矩模式接收目标 PWM 占空比0–100% MRM_SERVO_MODE_PWM_RAW 0x04 // 原始 PWM 模式直接输出占空比0–65535 } mrm_servo_mode_t;工程意义同一硬件可适配不同上层控制策略。例如ROS 的joint_state_controller发送位置指令而自定义轨迹规划器可能直接下发速度指令框架自动适配底层执行逻辑。3.3 CAN 报文处理核心 API所有 CAN 收发由框架统一托管用户仅需实现回调// 用户需实现的 CAN 接收回调由 HAL_CAN_RxCpltCallback() 触发 void mrm_node_can_rx_callback(CAN_HandleTypeDef *hcan, uint32_t rxHeader, uint8_t *rxData); // 框架内部调用此函数解析并分发 void mrm_node_process_can_rx(uint32_t can_id, uint8_t *data, uint8_t len); // 用户需实现的 CAN 发送函数框架调用 mrm_status_t mrm_node_can_transmit(uint32_t can_id, uint8_t *data, uint8_t len);典型实现HAL FreeRTOS// 使用 FreeRTOS 队列解耦 CAN 中断与业务处理 QueueHandle_t can_rx_queue; void HAL_CAN_RxCpltCallback(CAN_HandleTypeDef *hcan) { CAN_RxHeaderTypeDef rxHeader; uint8_t rxData[8]; HAL_CAN_GetRxMessage(hcan, CAN_RX_FIFO0, rxHeader, rxData); xQueueSendFromISR(can_rx_queue, rxHeader, NULL); // 入队 xQueueSendFromISR(can_rx_queue, rxData, NULL); } void can_task(void *pvParameters) { CAN_RxHeaderTypeDef header; uint8_t data[8]; while(1) { if(xQueueReceive(can_rx_queue, header, portMAX_DELAY) pdTRUE) { xQueueReceive(can_rx_queue, data, portMAX_DELAY); mrm_node_process_can_rx(header.StdId, data, header.DLC); } } }3.4 本地状态查询 API提供非中断安全的同步状态读取接口适用于调试或低频监控// 获取舵机当前状态位置、速度、温度等 mrm_status_t mrm_node_get_servo_state(uint8_t servo_id, mrm_servo_state_t *state); typedef struct { float position_deg; // 当前角度° float velocity_dps; // 当前角速度°/s float torque_nm; // 估算力矩N·m基于电流采样 uint16_t temperature_c; // 温度0.1°C uint16_t voltage_mv; // 供电电压mV uint8_t error_flags; // 当前错误标志 } mrm_servo_state_t;注意该函数在裸机环境下直接读取全局状态变量在 FreeRTOS 下加临界区保护确保多任务安全。4. 典型应用场景与代码示例4.1 场景一双舵机协同云台控制需求上位机通过 CAN 指令控制俯仰Pitch与偏航Yaw两个舵机实现 ROSsensor_msgs/JointState消息到硬件的映射。硬件配置Pitch 舵机ID0x01接 TIM2_CH1ADC1_IN5电位器反馈Yaw 舵机ID0x02接 TIM3_CH2无反馈开环初始化代码// 1. 初始化 CAN500 kbps CAN_FilterTypeDef sFilterConfig; hcan1.Instance CAN1; hcan1.Init.Prescaler 6; // APB136MHz → 500kbps hcan1.Init.Mode CAN_MODE_NORMAL; HAL_CAN_Init(hcan1); sFilterConfig.FilterBank 0; sFilterConfig.FilterMode CAN_FILTERMODE_IDMASK; sFilterConfig.FilterScale CAN_FILTERSCALE_32BIT; sFilterConfig.FilterIdHigh 0x100 5; // 匹配 0x100–0x1FF sFilterConfig.FilterMaskIdHigh 0x1F0 5; HAL_CAN_ConfigFilter(hcan1, sFilterConfig); HAL_CAN_Start(hcan1); HAL_CAN_ActivateNotification(hcan1, CAN_IT_RX_FIFO0_MSG_PENDING); // 2. 注册舵机 mrm_servo_config_t pitch_cfg { .id 0x01, .htim htim2, .channel TIM_CHANNEL_1, .hadc hadc1, .adc_channel ADC_CHANNEL_5, .min_pulse_us 500.0f, .max_pulse_us 2500.0f, .gear_ratio 1.0f }; mrm_node_register_servo(pitch_cfg); mrm_servo_config_t yaw_cfg { .id 0x02, .htim htim3, .channel TIM_CHANNEL_2, .min_pulse_us 500.0f, .max_pulse_us 2500.0f, .gear_ratio 1.0f }; mrm_node_register_servo(yaw_cfg); // 3. 设置为位置模式 mrm_node_set_servo_mode(0x01, MRM_SERVO_MODE_POSITION); mrm_node_set_servo_mode(0x02, MRM_SERVO_MODE_POSITION);上位机指令CANalyzer 截图发送ID0x101, Data[0x01][0x01][0x00 0x00 0x00 0x42]→ 设置 Pitch 目标位置 65.0°0x42000000 65.0f发送ID0x102, Data[0x01][0x02][0x00 0x00 0x80 0x42]→ 设置 Yaw 目标位置 66.0°框架响应ID0x201, Data[0x00][0x00 0x00 0x00 0x42]Pitch 当前位置 65.0°ID0x202, Data[0x00][0x00 0x00 0x00 0x42]Yaw 当前位置 66.0°4.2 场景二电机驱动器集成BLDC 方案需求将mrm-node作为 BLDC 电机的 CAN 网关接收上位机std_msgs/Float32速度指令经 PID 调节后输出 SVPWM 波形。关键扩展需实现mrm_motor_driver_t驱动利用 STM32 的高级定时器如 TIM1生成互补 PWM并读取霍尔传感器GPIO 中断或编码器TIM 编码器模式。核心逻辑片段// 在 mrm_node_update_state() 中周期执行1 kHz void mrm_motor_update_control(mrm_motor_t *motor) { // 1. 读取编码器位置 int32_t pos __HAL_TIM_GET_COUNTER(htim1); // 2. 计算速度单位RPM static int32_t last_pos 0; int32_t delta pos - last_pos; last_pos pos; float rpm (delta * 1000.0f) / (65536.0f * 60.0f); // 假设 16-bit 计数器 // 3. PID 运算位置式 motor-error motor-target_rpm - rpm; motor-integral motor-error * 0.001f; // Ts1ms motor-output motor-kp * motor-error motor-ki * motor-integral motor-kd * (motor-error - motor-last_error); motor-last_error motor-error; // 4. 限幅并输出 PWM motor-output CLAMP(motor-output, -100.0f, 100.0f); HAL_TIMEx_PWMN_Start(htim1, TIM_CHANNEL_1); // 启动互补通道 __HAL_TIM_SET_COMPARE(htim1, TIM_CHANNEL_1, (uint32_t)(motor-output * 327.67f)); // 映射到 0–65535 }5. 配置选项与编译定制mrm-node通过mrm_config.h头文件提供编译期配置所有选项均为#define无运行时开销// mrm_config.h 片段 #define MRM_NODE_ID 0x0A // 本节点 ID0x00–0xFE #define MRM_CAN_BAUDRATE CAN_BAUDRATE_500K // CAN 波特率宏 #define MRM_MAX_SERVOS 8 // 最大舵机数量影响 RAM 占用 #define MRM_MAX_SENSORS 4 // 最大传感器数量 #define MRM_USE_FREERTOS 1 // 1启用 FreeRTOS0裸机 #define MRM_ENABLE_DIAG_LOG 1 // 1启用错误日志环形缓冲区 #define MRM_ADC_VREF_MV 3300 // ADC 参考电压mV #define MRM_PWM_PERIOD_US 20000 // PWM 周期20ms舵机标准关键配置说明MRM_MAX_SERVOS直接决定mrm_node_state_t结构体中servos[]数组大小编译时静态分配避免动态内存管理MRM_USE_FREERTOS若为 1则启用xQueue、xTaskCreate等且mrm_node_process_can_rx()不再在中断中执行转为任务函数MRM_ENABLE_DIAG_LOG启用后框架自动记录CAN_ERROR_PASSIVE、OVERCURRENT等事件到 128-entry 环形缓冲区可通过mrm_node_get_diag_log()读取6. 故障诊断与调试支持mrm-node内置三级诊断机制覆盖从硬件到协议的全链路6.1 硬件级诊断CAN 错误中断捕获HAL_CAN_ErrorCallback()中检测HAL_CAN_ERROR_BUSOFF自动执行总线恢复HAL_CAN_Stop()→HAL_CAN_Start()电源监控ADC 定期采样 VDDA低于阈值如 2.7V置位ERROR_FLAGS_VOLTAGE_LOW温度保护MCU 内部温度传感器读数 85°C 时强制进入MOTOR_MODE_STOP并上报错误6.2 协议级诊断ID 校验收到0x1XX指令时检查XX是否在已注册设备 ID 范围内否则返回0x01设备未注册长度校验指令报文DLC必须匹配CMD_ID要求如0x01需 4 字节 payload否则返回0x02参数越界心跳超时上位机若连续 500 ms 未收到0x300报文判定节点离线6.3 调试接口提供 SWOSerial Wire Outputprintf 支持通过 ST-Link V2-1 的虚拟串口输出// 在 mrm_debug.c 中 void mrm_debug_printf(const char *format, ...) { va_list args; va_start(args, format); #ifdef MRM_DEBUG_SWO ITM_SendChar(0x03); // SWO 同步字节 vsnprintf((char*)debug_buf, sizeof(debug_buf), format, args); for(int i0; debug_buf[i]; i) ITM_SendChar(debug_buf[i]); #endif va_end(args); } // 使用示例 mrm_debug_printf(SERVO[%02X] POS:%.1f DEG, ERR:%d\n, servo_id, state.position_deg, state.error_flags);7. 与主流生态的集成路径7.1 ROS 2Micro-ROS集成通过 Micro-ROS 的rclc客户端将mrm-node封装为 ROS 2 Node创建mrm_node_publisher发布/mrm/joint_statessensor_msgs/msg/JointState创建mrm_node_subscriber订阅/mrm/joint_commands自定义消息含id,position,velocity在回调中调用mrm_node_set_servo_position()等 API7.2 Arduino 生态兼容提供Arduino.h兼容头文件mrm_arduino_wrapper.h将核心 API 映射为 Arduino 风格class MRMNode { public: void begin(uint8_t node_id); void registerServo(uint8_t id, uint8_t pwm_pin, uint8_t adc_pin 255); void setServoPosition(uint8_t id, float degrees); float getServoPosition(uint8_t id); };7.3 STM32CubeMX 一键配置提供.ioc配置模板预设CAN1500 kbps过滤器匹配0x100–0x3FFTIM2/TIM3PWM 模式预分频器0周期1999920msADC1单次转换通道 5/6/7电位器/温度/电压GPIO所有 PWM 引脚设为Alternate Function Push-Pull开发者导入后仅需点击 Generate Code 即可获得完整初始化代码mrm-node库以中间件形式集成。8. 性能边界与实测数据在 STM32F407VGT6168 MHz平台上实测关键指标指标数值测试条件CAN 指令处理延迟≤ 85 μs从HAL_CAN_RxCpltCallback到mrm_node_can_transmit()返回舵机闭环周期1.0 ms启用 ADC 反馈PID 运算 PWM 更新最大设备容量8 舵机 4 传感器RAM 占用 12.4 KB含 FreeRTOS 内核总线吞吐能力1200 帧/秒指令响应心跳混合流量500 kbps 总线利用率 65%功耗待机18 mA 12V仅 CAN 收发器使能MCU 进入 Stop Mode关键优化点零拷贝报文处理CAN RX Buffer 直接传入mrm_node_process_can_rx()避免内存复制查表式 PID对常用 PID 参数预计算系数表替代浮点乘除提升 3.2× 速度DMA ADC 采样启用 ADC DMA 循环模式CPU 无需干预采样过程这些数据表明mrm-node在资源受限的 STM32 平台上仍能提供工业级的实时响应能力完全满足多自由度机器人关节控制的严苛要求。