简介面向TonyPi人形机器人竞赛场景的代码仓库项目整合障碍跑比赛所需的运动控制、传感器数据处理、路径规划、实时避障与比赛规则适配等核心模块适合机器人竞赛参赛者、嵌入式开发者及人形机器人方向研究人员参考。资源包共7个文件以Python脚本2个py、说明文档docx、md、txt为主另附LICENSE与.gitignore压缩包整体仅47KB轻量但目录结构清晰。目前已有186人浏览学习。这份资料的价值在于提供了一套可直接运行的赛题代码骨架从关节协调控制、步态生成到基于图像与距离数据的障碍识别再到路径规划和动态避障逻辑均有对应实现同时说明文档和附赠的docx资源整理了比赛规则适配与嵌入式底层驱动、外设配置要点方便读者快速上手TonyPi平台并针对具体赛题二次开发。 做机器人比赛的项目最怕的不是代码写不出来而是写出来的代码只能在自家地板上跑一到赛场就各种翻车。TonyPi这台小机器人我在不少比赛里见过也算老朋友了它体型不大、舵机响应够快非常适合障碍跑这类需要灵活机动性的赛项。这套障碍跑比赛代码仓库算是把我这几年的经验都沉淀进去了今天拆开来讲讲从运动控制到避障逻辑再到比赛规则适配每一块是怎么设计、怎么实现的以及我在实际调车过程中踩过的那些坑。1. 项目整体架构与模块化设计思路1.1 为什么采用分层模块化结构拿到“障碍跑比赛”这个需求时第一反应不是急着写代码而是先想清楚一件事这场比赛到底考的是什么。障碍跑不同于单纯的竞速它要求机器人在有限场地内完成多段不同难度的路线期间要绕过或跨过障碍物还要在规定时间内完赛。这意味着代码必须具备三方面能力稳定的运动控制、灵敏的感知响应、以及临场的路径决策能力。所以代码仓库一开始就按功能拆成了四个独立模块运动控制模块负责底层舵机驱动和步态切换传感器数据处理模块负责摄像头和超声波的信号解析路径规划与实时避障模块负责路线选择与动态避让比赛规则适配模块则负责把前面三者统一到比赛场景下。这样拆分的好处很明显。其一各模块可以独立调试运动控制有问题不用去翻视觉代码视野清晰。其二比赛现场往往要临时调整策略参数模块化之后只改对应的配置文件即可不需要动主体逻辑。其三代码复用性高赛后把规则适配模块换掉这套底层代码还能延伸到其他赛项。1.2 模块间协作流程与数据流设计四个模块之间不是孤立的协作关系也经过了仔细设计。传感器数据处理模块处于最上游它负责把摄像头采集到的图像数据和超声波返回的距离数据转换成统一格式的结构体。比如识别到前方1.2米处有红色障碍物就会生成一个ObstacleInfo数据对象包含障碍物类型、相对角度、距离三个字段。这个数据对象会交给路径规划模块路径规划模块根据当前机器人位姿、目标点位置和障碍物分布输出一条局部路径。这条路径不是全局规划出来的大路线而是下一段两三米内的短期路线因为障碍跑场地里的障碍位置虽然固定但机器人自身累积的位姿误差会导致实际位置偏移全局路径在这种情况下意义不大。运动控制模块最后接收路径指令把它转换成具体的步态和舵机角度序列。整个过程数据流是单向的回传数据只用于状态监控不参与主决策这样降低了耦合度排错时责任边界非常清楚。我在设计这套数据流时有个体会模块间通信越简单越好优先使用结构体直传而不是全局变量。2. 运动控制与传感器数据处理的实现细节2.1 TonyPi步态控制的核心逻辑TonyPi采用的舵机驱动方案底层依赖PWM信号控制每一个关节角度。实现步态控制时我没有直接去逐帧操控所有舵机而是把步态抽象成阶段序列。一个完整的行走周期被拆解成四个阶段支撑相、摆动相、过渡相和重心转移相。每个阶段都有对应的关节角度目标值代码中通过插值方式生成平滑过渡轨迹让舵机不会因角度突变产生抖动。不同步态的切换是运动控制模块的核心难点。障碍跑中常见的动作有直线前进、左右转弯、跨越障碍、原地旋转。每种动作对应一组预定义的关节轨迹但直接切换会导致重心不稳。我的处理方法是在动作切换时插入一个重心调整阶段先让躯干回到中立位置再进入下一个动作。举个例子从直线前进切换到左转时先暂停前进躯干回正然后执行转弯步态。实测下来加了这个过渡阶段后摔倒概率至少降低一半。2.2 舵机角度计算与PWM信号校准TonyPi每个舵机的PWM信号范围需要在程序里预先标定。新拿到手的机器人舵机中值往往不在理论值上如果不校准机器人站都站不稳。我写了一个校准工具函数通过串口逐个控制舵机转动到极限位置记录对应的PWM值然后建立映射表。这个映射表是运动控制模块的基础配置后续所有步态参数都基于它计算。比如小腿舵机理论中值是500但实测发现495才是腿部竖直的位置差5个PWM单位反映到脚底可能就是1到2厘米的偏移行走时就会往一侧偏。校准这一步偷懒不得。我建议在比赛前至少完整校准两遍因为舵机在使用过程中会因磨损产生微小漂移。2.3 传感器选型与数据融合策略障碍跑中TonyPi主要依赖两类传感器摄像头和超声波模块。摄像头负责远距离的障碍物识别与颜色分类超声波负责近距离的精确测距两者配合才能实现可靠的避障。摄像头数据处理这一块我用的是OpenCV的颜色阈值分割法。因为赛场上障碍物颜色通常是纯色检测红色障碍物就是用cv2.inRange在HSV空间提取红色区域然后通过轮廓检测求出中心点坐标和面积大小。面积大小可以换算成距离轮廓中心点的x坐标偏移量就是障碍物的方位角。超声波数据处理相对简单读取时序为发送10微秒高电平触发脉冲然后等待回响信号高电平持续时间通过时间乘以声速除以2得到距离值。实际使用中要注意超声波模块的波束角大概在15度左右太近的物体小于3厘米会盲区测不准所以近距离避障时我习惯用超声波数据做最后一道防线视觉作为主导。传感器数据融合方面我采用了一个朴素但有效的策略以摄像头识别为主超声波为修正。当两者数据冲突时取超声波测距值作为精确值摄像头数据作为区域分类依据。设计上没有做过重的滤波算法因为比赛场地环境相对干净过度滤波反而会增加延迟。3. 路径规划算法与实时避障逻辑3.1 局部路径规划中的DWA算法应用障碍跑比赛场地通常是几十平方米的矩形区域障碍物数量一般不超过十个且位置相对固定。全局路径规划在这种场景下的收益有限我更看重局部规划的实时性。最终选用的是DWADynamic Window Approach动态窗口法。DWA的原理说起来其实不复杂机器人在每个时间步首先根据当前速度生成一个速度采样窗口这个窗口内的每个速度组合都代表一种可能的运动轨迹。然后通过评价函数对所有轨迹打分选得分最高的轨迹执行。评价函数综合考虑三个因素朝向目标的程度、离最近障碍物的距离、当前速度与最大速度的差距。我在实现时把评价函数权重设成了0.50.40.1优先保证朝向正确其次保证安全避障最后才是速度效率。实测下来这个权重分配比较均衡既不会因为太激进撞到障碍物也不会因为太保守导致比赛超时。如果场地难度较大我会把障碍物权重适当提高到0.5让安全性优先于效率。3.2 路径平滑与曲率约束处理DWA输出的轨迹虽然是连续的但直接作为舵机指令还不够平滑。我在运动控制模块中加了三次样条插值处理对轨迹上的关键点进行平滑。这样做的原因很实际舵机如果收到突变的角速度指令不仅会产生晃动还会让机器人重心偏移在快速转弯时容易侧翻。平滑处理的实现方式不复杂我取了轨迹上相邻三个关键点用三次多项式拟合中间点的位置和速度确保相邻段的连接处速度连续。实际效果是转弯动作更加柔和没有了明显的顿挫感。3.3 实时避障的状态机设计避障逻辑我写成了有限状态机状态包括直行、左转避障、右转避障、暂停检测、跨越障碍。状态机的好处是逻辑清晰每种状态下执行相应的运动指令状态之间通过传感器数据触发切换。状态机转移条件是避障逻辑的关键。我设定多个参数min_safe_distance表示最小安全距离默认30厘米turn_angle表示转弯角度默认45度detect_delay表示检测间隔默认0.2秒。当超声波检测到前方距离小于min_safe_distance时机器人进入暂停检测状态摄像头重新扫描前方区域确认障碍物宽度然后决定向左还是向右绕行。绕行决策我还设计了一个偏向规则默认向右绕行但如果右侧同时有障碍物右侧距离小于40厘米则改为向左绕行。这个规则避免了机器人左右摇摆的困境。3.4 避障优先级与安全兜底策略避障逻辑不可能百分之百完美所以我加了安全兜底。当机器人在某个状态内超过5秒无法突破比如连续检测到障碍物但绕不过去状态机强制切换到原地旋转动作旋转90度后重新开始路径规划。这个策略能有效防止机器人卡死在角落虽然会浪费几秒时间但总比超时强。另外在避障优先级上也做了明确划分超声波数据优先级最高摄像头数据次之预置地图数据优先级最低。这意味着即使摄像头识别出错超声波仍能阻止碰撞反过来超声波误报时摄像头能提供修正依据。这个优先级链设计是调车过程中救了我很多次的保障。4. 比赛规则适配模块与赛场实战要点4.1 规则适配模块的程序化实现比赛规则适配模块听起来高大上本质就是一套可配置的比赛参数模板。不同的比赛场次障碍物摆放位置会变完赛时间限制会变甚至起跑区域的形状也会变。如果每次赛前都改主程序代码不仅容易出现低级错误还会消耗大量宝贵的调试时间。我的做法是写了一个rules_config.json配置文件把场地尺寸、障碍物坐标、时间限制、允许碰撞次数上限等参数全部放进去。比赛前只需要在配置文件中更新场地信息主程序启动时读取配置然后动态生成全局路径的起点与终点。这个模块虽然代码量不大但在实际参赛中帮了大忙省去了每场赛前改代码的心智负担。4.2 赛场环境变化的动态适配比赛当天的环境光线、场地表面摩擦系数和家里训练时完全不同。摄像头颜色阈值在室内荧光灯下正常到了赛场自然光环境可能就识别不到红色障碍物。我在适配模块里加了一个一键自校准功能启动时自动扫描当前环境提取场景中背景色和障碍物颜色的实际HSV值动态更新阈值参数。场地表面摩擦系数变化主要影响步态参数。光滑地板上步幅太大容易打滑粗糙地毯上步幅太小又浪费时间。我在配置文件中提供了三组步态参数预设硬质地面模式、短毛地毯模式、光滑地砖模式。赛前观察场地后直接切换模式不用重新调试。4.3 赛前检查清单与调参顺序每次比赛前我基本都会按固定顺序检查一遍检查所有舵机供电电压确保在额定范围内。运行舵机校准程序确认PWM映射表未发生漂移。在场地边启动视觉自校准确认颜色阈值适配当前光线。空跑一遍直线行走确认步态参数与地面材质匹配。在场地内模拟一次完整障碍跑记录实际用时作为策略调整依据。调参顺序上我的经验是先调步态稳定性再调节奏速度最后调避障策略。步态不稳时追求速度是空中楼阁避障策略调得再好机器人走两步摔一跤也白搭。这个顺序是我踩过几次坑后总结出来的之前试过硬地场地直接切到了快速步态结果第一个弯道就侧翻后来才意识到要先确认地面是否支持这个步幅。5. 常见问题与实战排错实录5.1 机器人行走路线偏移问题排查这个问题出现频率最高。明明程序里写的是直线前进但实际走起来总是往左偏。排查顺序麻烦但不复杂先确认所有舵机PWM映射表是否准确再检查是否为左右腿机械结构不对称导致这把尺子量一下即可最后检查步态参数中的步幅是否一致。大概率是校准没做细致重新校准一遍就能解决。5.2 避障反应迟缓导致碰撞避障逻辑明明写了但机器人还是撞上去原因通常是两个传感器数据刷新频率不够或者避障状态机的触发距离参数设置得太小。超声波模块我建议把更新频率提到20Hz以上比默认值高一倍。避障触发距离也不要设得太极限30厘米触发算是比较安全的底线再小的距离留给舵机响应的时间就不够了。5.3 视觉识别误判的处理误判常见于颜色相近的情况比如红色障碍物旁边有橙色锥桶HSV阈值如果不加限制会把两个都识别为同类。我的处理方法是加一个尺寸过滤条件只有轮廓面积在合理范围内比如50到5000像素才认定为有效障碍物。另外在颜色分类时把HSV的H通道范围收紧减少误判可能。5.4 舵机过热导致动作迟缓连跑几轮之后舵机温度升高动态响应变慢动作看起来软绵绵的。解决办法是在两次试跑之间让机器人完全断电休息三到五分钟让舵机散热。程序层面也可以加入温度保护逻辑当检测到连续运行时间超过90秒时主动降低步速防止过热。我把这套代码仓库反复测试过很多次在标准障碍跑场地上稳定完赛率已经达到八成以上。比赛中真正拉开差距的其实不是算法多高级而是细节控得好不好。舵机螺丝有没有拧紧、电池电压有没有掉到阈值以下、超声波模块有没有被线缆挡住这些不起眼的小事往往是决定成败的关键。如果你也打算用TonyPi跑障碍跑比赛记住一个原则代码是基础调试才是王道。把基础模块磨扎实再把现场调试的流程跑顺成绩自然不会差。本文还有配套的精品资源点击获取