简介面向STM32单片机开发者与麦克纳姆轮小车爱好者的完整工程源代码包基于C语言实现代码结构完整、可直接编译下载。内容涵盖麦克纳姆轮运动控制核心算法、操纵杆信号解析与无线通信协议、电机驱动控制并附带原理图、PCB及工程配置文件适合智能车竞赛、轮式机器人项目或入门STM32G4系列开发的学生与工程师深入参考。整个压缩包共951个文件以C源文件和头文件为主体另含启动汇编文件、链接脚本、库文件、多种IDE工程文件及硬件图纸整体体积仅26.38MB便于快速下载与本地查阅。已有582人学习浏览下载后可直接获得整套可运行源码与配套硬件资料能显著缩短运动底盘和操纵杆控制系统的联调周期也可作为模块化改造与二次开发的稳定起点。1. 麦克纳姆轮小车项目为什么必然牵扯到 STM32 和舵杆控制代码麦克纳姆轮小车在机器人毕设、电子竞赛和移动底盘项目里出现的频率越来越高原因是四个带 45° 滚子的轮子让底盘获得了三个平移自由度和一个偏航自由度整车不再受“只能前后走”的约束。但自由度的提升是有代价的底盘期望速度需要分解成四个轮子各自的线速度而这个分解在每个控制周期都要重新算一遍。多数开源代码采用 STM32 平台来做这件事核心原因不是主频高而是定时器和编码器接口非常贴合四路电机闭环的需求。如果你的目标是下载这份 C 语言工程后快速二次开发第一步不是打开 main.c 从头读而是先分清代码里的三层结构最底层是 STM32 定时器生成的 PWM 和编码器计数读取中间层是麦克纳姆轮逆运动学解算和 PID 速度环最上层是操纵杆数据的接收和映射。搞清楚这三层如何衔接换底盘、换遥控器、换主控芯片时才不会到处打补丁。这篇文章按“运动学模型 → 底层定时器/PWM → 操纵杆协议 → 联调验证”的顺序把代码里最关键的模块逐段拆开。文中代码以 STM32F103 系列常见写法为例但涉及的思路对其他型号同样适用。2. 麦克纳姆轮逆运动学解算C 语言实现四轮速度分配2.1 先定参考系再说公式麦克纳姆轮的运动学公式本身很简单麻烦的是坐标系和符号约定。不同博主、不同仓库里的源码公式形态看起来几乎一样但轮子转向的定义不同最终代码行为就可能完全相反。统一采用下面的约定以小车底盘几何中心为原点x 轴指向车头前方y 轴指向车身左侧ω 为正时表示从车尾向车头看过去的逆时针旋转。四个轮子分别记作 FL、FR、RL、RR每个轮子的正向定义为电机正转时让小车沿该轮安装方向前进的方向也就是朝车头方向滚动。设小车前后轮轴距一半为 L左右轮距一半为 W轮子半径为 R。期望底盘速度为 (vx, vy, ω)单位统一为 m/s 和 rad/s。则四个轮子的目标线速度可以写成FL 轮V vx - vy - (L W) * ωFR 轮V vx vy (L W) * ωRL 轮V vx - vy (L W) * ωRR 轮V vx vy - (L W) * ω将结果除以轮半径 R就得到每个轮子的角速度。实际代码里通常不直接操控电机角速度而是先经过 PID 速度环再把目标速度换算成 PWM 占空比。2.2 把运动学写成一个独立模块工程里最忌讳把运动学公式散落在中断或者主循环里。常见做法是单独建一个 kinematics.c 文件结构体保存底盘参数函数负责求解四轮速度。typedef struct { float half_wheelbase; // 前后轮距的一半 L float half_track; // 左右轮距的一半 W float wheel_radius; // 轮子半径 R } ChassisParam_t; typedef struct { float fl; float fr; float rl; float rr; } WheelSpeed_t; WheelSpeed_t Kinematics_Solve(const ChassisParam_t *p, float vx, float vy, float omega) { WheelSpeed_t out; float r p-half_wheelbase p-half_track; out.fl ( vx - vy - r * omega) / p-wheel_radius; out.fr ( vx vy r * omega) / p-wheel_radius; out.rl ( vx - vy r * omega) / p-wheel_radius; out.rr ( vx vy - r * omega) / p-wheel_radius; return out; }代码逻辑不复杂但有几个点容易写错。第一L 和 W 用的是“一半”而不是整车长宽很多工程出问题就是因为这里传入了整车尺寸。第二速度量纲必须自洽vx、vy 用 m/somega 用 rad/swheel_radius 用 m推导出来的 WheelSpeed_t 单位是 rad/s。如果后续 PID 环输入的设定值是 RPM那还要再乘一个系数做单位转换。2.3 轮距和轮径参数要单独标定运动学解算的精度直接取决于 L、W、R 这三个参数。实际小车底盘上这四个参数经常不是整数值比如 150mm 轮距的底盘轮半径是 39mm。项目代码里应该把这三个值集中放在一个配置头文件里#define CHASSIS_HALF_WHEELBASE 0.150f // 单位m #define CHASSIS_HALF_TRACK 0.145f #define WHEEL_RADIUS 0.039f提示测量轮距时以四个轮子的接地点构成的矩形为准而不是以底盘安装孔位为准。麦克纳姆轮滚子有一定宽度安装孔位和实际接地点往往不严格重合。差值虽然只有几毫米但会造成斜向行走时出现肉眼可见的偏移。参数测量建议误差影响轮距一半 L测量前后轮接地点距离后除 2误差主要影响旋转分量轮距一半 W测量左右轮接地点距离后除 2误差主要影响旋转分量轮半径 R测量轮子外径后除 2误差影响所有方向的速度3. STM32 的电机控制代码定时器 PWM、方向引脚与编码器接口3.1 四路电机的引脚资源分配麦克纳姆轮小车有四个电机每个电机需要一路 PWM 控制速度一路 GPIO 控制方向。如果用带死区功能的 H 桥驱动则需要两路互补 PWM。主流微型小车方案基本分成两类一类用 TB6612、DRV8833 这种小电流驱动设置 STBY、AIN1/AIN2、PWMA 的形式每个电机占用 3 个 GPIO另一类用 BTS7960 或分立 MOS 管搭的 H 桥要求两路具有死区特性的互补 PWM。STM32 的定时器资源有限规划引脚时一般这样分配TIM1 或 TIM8 的高级定时器输出 4 路互补 PWM 给 H 桥驱动或者用 TIM3、TIM4 这类通用定时器输出 4 路普通 PWM再搭配普通 GPIO 控制方向。下面这张表是典型的 F103C8T6 的分配方式电机PWM定时器通道方向引脚编码器接口FL 电机TIM3_CH1 (PA6)PB0TIM2_CH1/CH2FR 电机TIM3_CH2 (PA7)PB1TIM4_CH1/CH2RL 电机TIM3_CH3 (PB0)PB10TIM2_CH3/CH4RR 电机TIM3_CH4 (PB1)PB11TIM4_CH3/CH4TIM3 的四个通道输出 PWM 给四个电机方向交给 GPIO编码器接到 TIM2 和 TIM4。这样一个定时器专门做 PWM两个定时器专门做编码器采集互不干扰。3.2 PWM 初始化和占空比限制基于 HAL 库的工程里初始化通常由 CubeMX 生成。关键参数是 PWM 频率一般选 10kHz 到 20kHz。低于 5kHz电机会有明显的电流噪声高于 30kHzMOS 管开关损耗变大。STM32F103 主频 72MHz定时器时钟 72MHz设置预分频 Prescaler 和自动重装值 Counter Period 就能得到目标频率// 20kHz PWM: 72MHz / (72 * 50) 20kHz htim3.Init.Prescaler 72 - 1; htim3.Init.CounterMode TIM_COUNTERMODE_CENTERALIGNED1; htim3.Init.Period 50 - 1; HAL_TIM_PWM_Start(htim3, TIM_CHANNEL_1);占空比通过比较寄存器 CCR 控制。比如 Period 为 49CCR 值为 25占空比就是 50%。代码里通常会加一个安全限幅防止占空比达到 100% 时电流过大#define PWM_MAX_DUTY 49 // 对应 100% #define PWM_MIN_DUTY 0 uint16_t pwm_duty_from_speed(float speed_ratio) { if (speed_ratio 1.0f) speed_ratio 1.0f; if (speed_ratio -1.0f) speed_ratio -1.0f; return (uint16_t)(speed_ratio * PWM_MAX_DUTY); }speed_ratio 是一个归一化目标速度范围 -1 到 1。负值代表反转实际输出 PWM 时结合方向引脚实现而不是直接给负占空比。3.3 编码器速度闭环用定时器编码器模式替代 GPIO 外部中断麦克纳姆轮底盘只做开环控制往往很难用四轮负载不一致加上地面摩擦差异同样占空比下车速并不相同。更好的做法是每路电机加编码器STM32 定时器切换到编码器模式硬件自动根据 A、B 相相位差计数。初始化编码器模式时最关键的是配置 SlaveMode 为编码器模式并让两个通道都生效TIM_Encoder_InitTypeDef enc {0}; enc.EncoderMode TIM_ENCODERMODE_TI12; // TI1 和 TI2 都计数 enc.IC1Polarity TIM_ICPOLARITY_RISING; enc.IC2Polarity TIM_ICPOLARITY_RISING; HAL_TIM_Encoder_Init(htim2, enc); HAL_TIM_Encoder_Start(htim2, TIM_CHANNEL_ALL);编码器计数方向会自动跟随电机转动方向无需 GPIO 读方向。读取速度时在定时器中断里周期性采样计数值两次采样之差除以时间就是转速。// 每 10ms 采样一次将编码器 Ticks 转换成 RPM int16_t ticks __HAL_TIM_GET_COUNTER(htim2); __HAL_TIM_SET_COUNTER(htim2, 0); float rpm (float)ticks * 100.0f / ENC_TICKS_PER_REV;这里 ENC_TICKS_PER_REV 要匹配电机减速比和编码器线数。比如电机减速比 1:30编码器每圈输出 13 个脉冲STM32 编码器模式 4 倍频那么 ENC_TICKS_PER_REV 30 × 13 × 4 1560。用这个值才能得到真实转速。3.4 PID 速度环代码骨架底盘四轮各自独立闭环PID 参数可以四个轮子共用一个如果追求更好的效果每个轮子单独标定一组参数。控制周期固定PID 才能踏实调参。常见实现如下typedef struct { float kp, ki, kd; float integral; float last_err; float out_limit; } Pid_t; float Pid_Update(Pid_t *pid, float target, float measure) { float err target - measure; pid-integral err; if (pid-integral pid-out_limit) pid-integral pid-out_limit; if (pid-integral -pid-out_limit) pid-integral -pid-out_limit; float out pid-kp * err pid-ki * pid-integral pid-kd * (err - pid-last_err); pid-last_err err; return out; }这个函数的输出是归一化的速度指令再通过 pwm_duty_from_speed 转成占空比。需要特别注意的是PID 目标值和反馈值单位必须一致。如果运动学解算输出的是 rad/s而编码器测量得到的是 RPM两者直接相减会造成巨大的比例误差。4. 操纵杆控制协议串口中断接收、帧解析与速度映射4.1 遥控链路PS2 手柄和自定义 2.4G 摇杆麦克纳姆轮小车项目中操纵杆类遥控器最主流的选择有两种。一种是 PS2 无线手柄它的接收器使用 SPI 协议与 STM32 通信PS2 手柄库能直接读取左右摇杆的模拟量另外一种是航模遥控器或 2.4G 数传模块加摇杆扩展板通过串口输出数据帧。自定义串口方案更常见于源码中因为协议可以自己定调试也相对好做。4.2 帧格式定义和校验自定义摇杆协议的帧格式一般类似下面这样帧头帧头数据长度数据区校验0xAA0x550x06左右摇杆 X/Y 共四个 int16累加和数据区内每个物理量用两个字节传输高字节在前。帧头越多误判概率越低一般连续两个固定字节就能满足小车短距离场景。4.3 串口中断接收和状态机解析在 STM32 上做串口接收最简单可靠的方式是单字节中断加状态机避免阻塞主循环。代码如下typedef enum { FRAME_WAIT_H1, FRAME_WAIT_H2, FRAME_WAIT_LEN, FRAME_WAIT_DATA, FRAME_WAIT_CRC } FrameState_t; static FrameState_t frame_state FRAME_WAIT_H1; static uint8_t frame_buf[64]; static uint8_t frame_len; static uint8_t frame_crc; void UART_OnByte(uint8_t byte) { switch (frame_state) { case FRAME_WAIT_H1: if (byte 0xAA) frame_state FRAME_WAIT_H2; break; case FRAME_WAIT_H2: if (byte 0x55) frame_state FRAME_WAIT_LEN; else frame_state FRAME_WAIT_H1; break; case FRAME_WAIT_LEN: frame_len byte; frame_crc byte; if (frame_len 64) frame_state FRAME_WAIT_H1; else frame_state FRAME_WAIT_DATA; break; case FRAME_WAIT_DATA: frame_buf[frame_idx] byte; frame_crc byte; if (frame_idx frame_len) frame_state FRAME_WAIT_CRC; break; case FRAME_WAIT_CRC: if (byte frame_crc) { Joystick_HandleFrame(frame_buf, frame_len); } frame_state FRAME_WAIT_H1; frame_idx 0; break; } }状态机的核心是让每一个字节的处理都保持常数时间不出现循环等待。中断里只做状态迁移和字节拷贝真正解析数据放到主循环或者专门的函数里做避免中断执行时间过长。解析摇杆数据时把四个 int16 的高低位合并然后判断通道对应的物理意义void Joystick_HandleFrame(uint8_t *buf, uint8_t len) { if (len 8) return; joystick_data.left_x (int16_t)((buf[0] 8) | buf[1]); joystick_data.left_y (int16_t)((buf[2] 8) | buf[3]); joystick_data.right_x (int16_t)((buf[4] 8) | buf[5]); joystick_data.right_y (int16_t)((buf[6] 8) | buf[7]); }4.4 摇杆原始量到目标速度的映射摇杆返回的模拟量通常是 0 到 1023 或 0 到 4095中心点大概在中值附近。把原始值减掉中心值再除以最大偏移量就得到 -1 到 1 的归一化输入。这里有一个容易忽略的问题摇杆物理阻尼不同中心点附近会有死区直接不做死区会导致小车在摇杆回中时缓慢漂移。float Joystick_Normalize(int16_t raw, int16_t center, int16_t max) { float deadzone 20.0f; float value ((float)raw - center) / (float)max; if (value deadzone / max) value 0.0f; if (value -deadzone / max) value 0.0f; return value; } float left_x Joystick_Normalize(joystick_data.left_x, 512, 512); float left_y Joystick_Normalize(joystick_data.left_y, 512, 512); float right_x Joystick_Normalize(joystick_data.right_x, 512, 512);映射关系通常按照下面约定左摇杆上下控制 vx左右控制 vy右摇杆左右控制 ω。这样符合直觉新手拿到遥控器不会因为映射方向搞混。摇杆通道对应底盘速度说明左摇杆 Yvx前后平移左摇杆 Xvy左右横移右摇杆 Xω原地旋转右摇杆 Y未使用可以映射为附加功能死区设置不能太大否则细微操控变得迟钝太小又无法消除漂移。推荐先调到摇杆总行程的 3% 到 5%具体在联调时按手感微调。4.5 目标速度限幅和加速度限制即使摇杆推到最大底盘速度也不应该瞬间打满。尤其麦克纳姆轮侧移时四个轮子受力方向复杂瞬间冲击容易打齿或造成电流过载。代码里加一个简单的斜坡限制float Limiter_Update(float target, float current, float step) { if (target current) { current step; if (current target) current target; } else if (target current) { current - step; if (current target) current target; } return current; }step 的选择依赖控制周期。如果主循环固定 100Hzstep 取 0.05理论上需要 20 个控制周期才能从 0 加速到最大速度即 200ms。这个爬升速率对普通小车来说比较温和既保证了起步不突兀又不会让转向响应变得明显滞后。5. 联调技巧方向正向性检查、PID 整定与轮系差异修正5.1 方向正向性检查脚本真正上电组装之前不要急着推摇杆。先用一段极简的诊断代码逐一验证每个轮子的方向。具体方法在代码里写一组固定速度输出分别测试“全轮前进”“全轮后退”“左侧轮对转”“右侧轮对转”观察车身实际运动方向与预期方向是否一致。测试指令预期运动常见错误(0.3, 0, 0)小车直线前进某轮反转导致斜向移动(0, 0.3, 0)小车向左横移前后轮方向接反变成对角线走(0, 0, 0.5)小车原地逆时针旋转同侧轮方向一致变成侧移如果发现某个轮子方向不对优先检查该轮方向引脚的电平定义而不是去改运动学公式。运动学公式一旦统一修改其他正常方向的车也会跟着乱。5.2 编码器速度环的验证PID 整定前先用开环测试确认编码器读数正确。让一个电机以固定占空比运转串口打印 RPM 值。如果 RPM 方向与电机实际转向不一致需要交换编码器 A、B 相或者在代码里对计数取反。PID 参数可以从纯比例开始kp 从很小值逐渐增大观察速度阶跃响应。当出现持续振荡时减少 kp 或增加 kd。积分项不要一开始就加大它主要补偿静差和负载扰动但对于小车这种低速负载积分作用太强会导致响应迟缓的钱而转向过冲。四个轮子 PID 参数差别如果超过 20%优先检查机械阻力差异而不是盲目调大 ki 去硬拉转速否则会出现转弯时某个轮子“顶牛”现象。5.3 最终抗抖滤波处理验收测试时把小车放在平整地面上推右侧摇杆让它横向移动再快速回中观察车身是否出现抖动。抖动来源通常是编码器采样频率太低或 P 项增益过大。可以在速度反馈上加一阶低通滤波也可以把控制周期从毫秒级固定到更稳定的数值——1kHz 的控制频率配合 10ms 的 PID 计算周期高速小车明显比低频控制稳定。最后还有一个小技巧在源码里加一条独立的调试串口输出周期性打印运动学输入 vx、vy、ω 和四路编码器转速。上位机记录这两组数据对比就能判断整车运动是算法偏差还是执行机构偏差。有了这条链路后面换电机、换轮距直径都不用再从头猜问题出在哪。本文还有配套的精品资源点击获取