简介合肥工业大学机器人足球球队源代码是一套面向机器人足球竞赛的完整软件工程资源适合学习机器人控制、多智能体协作与AI策略规划的开发者参考。代码覆盖硬件驱动、运动控制、策略规划、传感器处理与通信协议等关键环节底层采用C/C实现核心逻辑包含球员决策、世界模型、阵型配置等模块并配有启动脚本与配置文件能够帮助理解机器人从环境感知到执行动作的完整链路。压缩包共6个文件大小约4.19MB以C源文件.cpp/.h为主辅以conf配置与sh脚本结构紧凑清晰。该资源源自真实校级机器人足球赛并获二等奖不仅包含最终版本还留有开发期间的修改记录便于对照学习排错思路和模块迭代过程其中状态机、PID控制等算法均有直观体现。目前已有2226人学习下载对于希望深入机器人足球系统设计或参与相关竞赛的学习者是一份很有价值的实践参考。1. 球队代码的第一次重构从6000行单文件到分层架构大多数人听到机器人足球这四个字第一反应是给机器人装一套踢球程序。实际上真正上场过的球队都知道这套代码远不是踢球两个字能概括的——你要同时处理视觉或者仿真环境提供的场上数据、决策、运动控制、通信、裁判盒交互、日志回放……每一个环节都会单独占掉你几百行代码。我刚加入实验室球队那会儿仓库里躺着一份传了三四届的源码主力文件超过6000行从main()一路写到运动控制中间还有无数的全局变量在互相传递状态。仿真环境下还勉强能跑一放到实机上就各种灵异现象机器人突然原地转圈、明明看到球却不出脚、按键响应慢半拍。后来我花了一个赛季做重构最大的收获不是代码写得多漂亮而是想清楚了一件事——机器人足球的源码本质上是感知-决策-执行三个层次之间不断交换数据和指令的系统任何一层的逻辑混进另一层后期一定出问题。1.1 拆出三层骨架Perception / Decision / Execution第一次重构我先画了一张非常简单的数据流图没有用任何花哨的架构模式就是最原始的输入-处理-输出场上数据球的位置、机器人的位置、对手机器人的位置 ↓ Perception层滤波、坐标变换、预测 ↓ Decision层状态判断、角色分配、行为选择 ↓ Execution层速度指令、踢球动作、转向参数代码结构也按这个来分目录src/ perception/ # 视觉/传感器数据解析、滤波、坐标变换 decision/ # 状态机、角色分配、行为决策 execution/ # 运动控制、踢球机构、底层通信 comm/ # 与仿真平台或实机车载板的数据收发 utils/ # 日志、参数配置、数学工具 hal/ # 硬件抽象层实机和仿真共用同一套决策代码的前提这样一个结构至少有三个直观的好处第一Debug的时候能很快定位是看错了、想错了还是跑错了第二比赛前的参数微调只改配置文件不用在源代码里大海捞针第三仿真平台和实机平台复用同一套决策层代码只需要替换Perception和Execution的底层实现。1.2 全局变量是最隐蔽的定时炸弹旧代码里有一堆全局变量比如ball_x、ball_y、our_goal_x……看起来方便实际上谁在什么时候写了它、谁在什么时候读了它完全不可控。最典型的一个bug感知线程20ms更新一次ball_x决策线程看的时候正好撞上更新窗口读到了半个周期的脏数据结果就是机器人对着空气踢了一脚。我的做法是把感知层的输出封装成一份不可变快照Snapshot结构体每帧生成一次统一发布。决策层只读当前帧快照不直接访问任何裸全局变量。这么做最直接的效果是决策层拿到的一定是完整的一帧数据而不是拼凑出来的半帧。你不需要上并发锁因为数据是批次性更新的——只需要保证快照在发布前不被改写就行。2. 决策层设计有限状态机为主、队形匹配为辅决策层是整个球队代码里最能体现是不是自己上场踢过球的部分。仿真组和实机组在这里的差别不大核心都是三个问题我现在该干什么我的队友该干什么我们作为一个整体应该怎么配合2.1 状态机不是简单的switch-case堆叠很多新手球队的代码里状态机就是一个函数加一堆if判断if (ball_distance 20) state KICK;。这种做法在demo里没问题但一到比赛就会显得特别愣——机器人永远在被动响应而不是主动判断局面。我在代码里用的是一种带优先级的状态机框架。每种状态都实现四个接口class State { public: virtual bool onEnter(PlayerContext ctx) { return true; } virtual void onUpdate(PlayerContext ctx) 0; // 状态内执行逻辑 virtual bool onExit(PlayerContext ctx) { return true; } virtual int getPriority() const { return 0; } // 优先级越高越优先抢占 };状态切换不是当前状态自己决定要不要走而是由一个独立的决策入口每帧扫描所有状态的进入条件按优先级排序选出最高优先级且条件满足的状态作为当前状态。这样做的好处是新加战术动作比如边路传中、回传倒脚时不需要去改别的状态的代码只需要新加一个状态类并设置好触发条件即可真正做到了开闭原则。状态划分上我参考了RoboCup仿真组的常见做法待命Idle没有明确任务时的默认状态向队形站位点运动。追球Chase朝球的预测落点移动注意不是实时追球位置而是预测位置。带球Dribble球在可控范围内往进攻方向推进。传球Pass找到队友传球队列表计算传球线路安全度。射门Shoot评估射门角度与守门员位置。防守Defend回到防守队形位置保持阵型。守门Goalie仅守门员使用沿球门线平移。2.2 角色分配别让两个机器人抢一个球比状态机更容易被新手忽略的是角色分配Role Assignment。没有角色分配的比赛画面就是三个机器人追着球跑球门前面空荡荡。我最早调试的时候录了一段回放四个机器人叠在同一个坐标点场面非常滑稽。角色分配我在代码里用了一个贪心算法效果足够且性能开销几乎为零每个机器人先根据当前位置和场上形势计算自己执行每种角色的代价比如距离球的远近、朝向角偏差、是否被对手卡住。把代价矩阵用一个匈牙利算法做全局最优指派得到每个机器人对应的角色。这里有一个很关键的小细节分配必须有滞后阈值。如果每帧都重新算最优分配会出现角色抖动——两个机器人来回换角色导致整体队形来回摇摆。我的做法是新分配方案与当前分配方案的代价差异超过某个阈值比如20%才切换角色否则沿用上一帧的分配结果。代码实现大概长这样# 伪代码角色分配核心逻辑 # cost_matrix[i][j] 机器人i执行角色j的代价 row_ind, col_ind linear_sum_assignment(cost_matrix) for robot_idx, role_idx in zip(row_ind, col_ind): if cost_matrix[robot_idx][role_idx] current_cost[robot_idx] * 0.8: assign_role(robot_idx, role_idx)2.3 参数必须做到比赛现场可调这一条是实打实的血泪教训。第一次出去打交流赛对面球队的机器人防守收缩得特别靠前我们的射门状态里写死了距离球门2米以内才射门——结果全场几乎没有一次有效射门。当时改源代码、重新交叉编译、再烧录折腾了快二十分钟。后来我把所有阈值、系数、权重全部抽到了一个team_config.yaml文件里上位机直接通过通信链路热更新参数。比赛暂停期间改一个参数、下发一条指令五秒钟就生效。3. 运动控制层决策定方向运动定成败决策层想清楚了要干什么剩下的问题就是怎么过去。这部分我在写代码时踩过的坑最多也最值得拿出来单独说。3.1 速度分解与坐标系对齐以我们实验室用的麦克纳姆轮小车为例运动控制输入通常是三个量x方向速度、y方向速度、旋转角速度。如果决策层已经给出了目标点坐标那么速度解算其实就是一个坐标系变换的问题。一定要先把球场坐标系全局坐标转换成机器人坐标系局部坐标再做分解。很多新手直接拿全局坐标差去算PID结果机器人怎么走都偏——因为它的前方向在全局坐标里是实时变化的。局部坐标转换的核心就一句把目标点的全局坐标减去机器人当前坐标然后做一个旋转矩阵变换旋转角取机器人的当前朝向角。// 全局坐标 → 机器人坐标 double dx target.x - robot.x; double dy target.y - robot.y; double local_x dx * cos(-robot.theta) - dy * sin(-robot.theta); double local_y dx * sin(-robot.theta) dy * cos(-robot.theta);得到局部坐标之后以距离误差和角度误差作为PID控制器的输入计算出x速度、y速度和旋转速度。注意这里PID的三个环位置环、方向环目标值和反馈值必须用局部坐标系内的量不然一旋转就崩。3.2 避障路径规划不能只看目标点刚开始写运动控制的时候我以为只要朝目标点走遇到障碍绕开就够了。实际上足球场上最难的避障不是静态障碍物而是动态的、带有意图的对手球员。代码层面我最终采用的是**势场法Potential Field**的改进版本在原有引力朝目标和斥力远离障碍的基础上增加了一个敌方球门方向的偏置力让机器人在避障的同时还能保持进攻姿态。不过势场法有一个非常著名的bug——局部极小值陷阱也就是说机器人在某个位置受力平衡原地打转出不去。我的规避手段很朴素加上一个随机扰动也叫逃离力如果检测到机器人连续一段时间比如2秒位置变化小于某个阈值就激活随机绕行逻辑。这个方法不够fancy但胜在稳定。3.3 为什么仿真里能进球、实机一跑就崩在仿真里写代码逻辑和实机调试完全是两种体验。仿真环境里控制周期是精确的、传感器是理想化的、机器人之间的碰撞往往是简化的。我第一次把仿真代码挪到实机上的时候小车要么冲过头要么原地抖动。原因集中在三处控制周期不稳定实机的底层线程调度受系统负载影响导致PID输出时滞。里程计/视觉定位的噪声比仿真大一个量级滤波参数没有针对性调整。车轮打滑。麦克纳姆轮在木地板上的打滑系数是仿真环境根本模拟不出来的。一个比较实用的方案是为实机单独维护一份控制参数表与仿真参数表分开。两套参数跑同一份决策和运动控制代码只是PID系数、最大速度上限、加速度限制不同。我给运动控制层加了一组安全钳位// 限制加速度变化率避免急起急停导致打滑 double clamped_accel std::clamp(desired_v - current_v, -max_accel, max_accel); double final_v current_v clamped_accel;这行代码的价值在实机上比在仿真里大得多。没加之前小车每次启动都像弹射起步加了之后带球稳定性肉眼可见地提升。4. 通信与调试记录源码之外最容易被低估的部分说到机器人足球源代码很多人只盯着策略怎么写却忽略了比赛现场代码能不能稳定跑起来很大程度上取决于通信和调试工具链是否完备。这也是我认为我们球队源码里另一个值得写进文档的部分。4.1 把通信细节藏进抽象层无论是仿真平台还是实机上位机球队代码都要与外部环境交换数据从仿真服务器接收场上信息、下发控制指令到实机车载板。我做过一次很关键的抽象——把通信协议单独隔离成一个comm层上层决策、执行只依赖三个接口class CommInterface { public: virtual bool sendCommand(const RobotCommand cmd) 0; virtual std::optionalWorldFrame receiveFrame(int timeout_ms) 0; virtual bool isConnected() 0; };这样做最大的便利是换仿真平台、换实机通信模块都只需要实现新的CommInterface决策代码一行不动。我在重构时还专门跑了回归测试用同一套决策代码分别连仿真环境和实机验证行为一致性这比什么都说明问题。4.2 可复现的日志与回放是Debug第一生产力机器人足球比赛现场节奏非常快你不可能在对方进攻的时候盯着屏幕看变量。所以日志系统必须做到赛场上出了问题赛后能完整回放。我的日志设计分两层一层是实时状态流记录每一帧的关键信息机器人的坐标、速度、状态名、目标点、决策输出值。一层是事件流记录状态切换、角色分配、异常触发等离散事件。所有日志带统一时间戳回放工具可以把日志叠加到一张空的球场图上逐帧播放。有一次对手投诉我们防守机器人越位虽然规则里没有越位但对方就是觉得我们违规我直接用日志回放证明了机器人的坐标始终在合法区域内。这个工具在比赛后的复盘和技术交流中价值远超你的想象。4.3 比赛中最值得盯的三个数据调试状态下实机上位机屏幕上我通常只开三个数字当前状态名、目标点坐标、控制输出的速度向量。状态名让你知道决策层在想什么目标点让你知道决策层想去哪速度向量让你知道执行层实际在干什么。三个数字对齐了一切正常对不齐问题当场暴露——大概率是某层的数据传输延迟或者坐标变换出错。5. 从接手到出成绩给新球队的几个代码层面的建议最后这部分写给准备组建球队、或者刚接手球队代码仓库的同学。我在这个项目上熬了好几个通宵最大的感受是机器人足球的源代码难度不在某一行的算法而在于把十几个子系统捏合成一个整体系统。给出几个具体的建议希望能帮你们少走一些弯路。5.1 建立代码规范之前先建立回滚机制球队代码一般都会在赛前经历集中修改很容易出现比赛前一天改崩了的情况。我的习惯是把git tag打在每一个稳定可跑的版本上——注意不是功能完成才打tag而是当前能通过自测场景我们定义了一组基础测试开球、追球、射门、防守回位的版本都打一个tag。比赛前如果时间紧任何有风险的改动都不直接上而是先基于最新稳定tag开分支测试。5.2 把仿真通过当作起点而不是终点很多球队过度依赖仿真平台验证逻辑等到真正比赛才发现一堆隐性问题。我后来培养了一个习惯仿真通过之后强制在实机或者至少带噪声的数据回放上做一遍同样的场景测试。因为仿真环境再真实也无法完全模拟出实机的延迟、丢包、轮子打滑、传感器毛刺。源码的运行环境差异才是新手球队差距最大的地方。5.3 让下一个人看得懂你的代码比让机器跑得更快更重要球队代码是代代相传的你毕业了源码会交给下一届。所以我在重构过程中做了一个决定任何超过10行的函数必须配注释说明输入是什么、输出是什么、和在仿真/实机上的差异是否有坑。听起来很基础但真的能做到的球队不多。代码里每个魔法数字magic number都必须有对应的参数名和默认值说明否则下一任队长拿到手第一件事一定是花一个月时间反编译你的意图。说到底源代码的价值不止于能跑还在于能活下去。它是一个团队智慧的沉淀是每一场比赛复盘之后凝聚下来的经验结晶。你在代码里积累的每一个封装、每一条注释、每一个合理的默认参数都是在为下一届队员铺路。这也正是我始终认为机器人足球球队的代码库值得像工程项目一样认真对待的原因。本文还有配套的精品资源点击获取