如果你手头有一台e-puck，却把大量时间都花在调避障算法上，直到真正铺开实验场地才发现机器人在仿真里畅通无阻、放在实物场景却对着墙角反复横跳——那我觉得，欠的功课大概率不是算法本身，而是“场景搭建”这一环。e-puck就是这么一台有意思的小机器人：个头不大、传感器却相当齐全，但它的每一次感知本质上都是在对环境做“回应”，场景摆得对不对，直接影响实验结果的可信度和可复现性。这篇内容我打算把搭建经验完整整理一遍：从为什么场景值得单独设计，到Webots仿真场地怎么摆，再到实物场地怎么复刻，尽量覆盖避障、沿墙、编队这几类常见实验的配置方法，以及仿真转实物时最容易踩的坑。如果你正准备用e-puck做课程项目、毕业设计或者科研验证，这篇文章应该能帮你少走不少弯路。
1. e-puck是来头不小的实验平台，场景搭建却是最容易被低估的环节
1.1 e-puck这台机器人到底能做什么
e-puck最早是瑞士洛桑联邦理工学院（EPFL）为教学和科研设计的一款微型移动机器人，尺寸只有大概7厘米直径，两个轮子做差速驱动。它最大的特点是在这么小的体积里集成了红外测距传感器、摄像头、麦克风、加速度计、陀螺仪这些常用感知器件，而且硬件资料、固件源码全部开放。很多高校的实验课、机器人竞赛以及论文里的对比实验都用它，原因很简单：便宜、皮实、上手门槛低、上限也不低。
不过“皮实”对应的问题是硬件资源有限。e-puck一代的主控是dsPIC33系列，主频不高、内存也小，跑不了太复杂的视觉模型；e-puck2换成了STM32F4，算力有所提升，但也还是一台微型嵌入式平台。所以用e-puck做实验，通常不是比谁的神经网络更大，而是比谁的感知策略、行为规则、场景适配更聪明。换句话说，机器人的硬件天花板摆在那里，实验效果的区分度反而更多来自外部环境和任务设计。
1.2 为什么“场景”比算法本身更需要设计
很多人一提到机器人实验，第一反应是写代码，第二反应是调参，很少会专门考虑“把机器人放在什么样的环境里”。但实际做下来你会发现，场景决定了传感器能读到什么、控制器该响应什么、算法在什么边界条件下失效。同一个避障控制参数，放在两堵大白墙中间很稳定，放在黑色亚克力围成的迷宫里可能直接撞上去，因为红外传感器对深色表面的反射率极低。
我最早带e-puck做项目的时候，在Webots里随便拖了几个方块当障碍，跑通后没有校验物理参数，直接上实物场地，结果机器人一进真实迷宫就频繁误判。后来逐个排查才发现，仿真里默认的墙是浅灰色、地面摩擦系数偏大，而实物场地用的是黑色哑光地板、墙板表面还有轻微反光，传感器读数完全对不上。那次折腾之后，我把场景搭建当成实验流程的一等公民来对待：先明确场景的物理尺寸、材质、光照条件，再决定障碍物分布和感知目标，最后才是算法参数。这套习惯后来帮我省了不少时间。
2. 动手搭场景前，先把硬件、软件、固件这套底子补齐
2.1 硬件清单：e-puck本体、电池与必要外设
e-puck一代和e-puck2在场景搭建时需要注意的硬件差异不大，核心都是那一圈红外传感器和车头的摄像头。但有几个基础项必须提前确认：
- e-puck机身自带8个红外近距离传感器，编号从ps0到ps7，分布在车身周围，其中朝前和朝斜前的几个对避障最关键。
- 电池是锂离子充电电池，满电状态下跑一个小时左右基本没问题，但场地实验频繁启停会显著缩短续航，建议至少准备两块电池交替用。
- 如果要做多机器人编队，通常需要给每台e-puck配一个蓝牙或Zigbee通信模块，同时要在机身上方固定可识别的标记物。
- 摄像头是灰度或彩色VGA级别，近距离拍摄效果尚可，但光线变化会影响颜色识别，实验时最好保持固定光源。
实物场地搭建之前，建议先用纸箱或亚克力板做一个临时围挡，让e-puck在受限区域内跑通基本运动控制。这一步能提前暴露电池供电不稳、电机堵转、传感器接线松动等硬件问题，别把这些不确定性留到正式实验中。
2.2 仿真环境：Webots版本选择与安装
e-puck最常见的仿真平台是Webots，它自带e-puck的完整模型和示例控制器，包括传感器噪声、电机模型、碰撞响应，能够比较真实地模拟物理行为。Webots支持Linux、Windows和macOS，安装包可以直接从官网下载，也可以在用包管理器安装。
版本选择上，我个人建议用R2023b或更新的版本。新版本对e-puck2的支持更完整，也修复了不少旧版在物理引擎上的问题。如果你所在的项目组已经用老版本建了一批场景文件，可以先在旧版本里导出再导入新版本，但要注意兼容性提示，部分节点属性和材质参数可能需要手动调整。
安装完成后，先不要急着搭场景。打开Webots自带的“e-puck”示例世界，确认机器人能加载、控制器能编译运行，再开始做自己的场地。很多问题出在环境配置阶段，比如缺少交叉编译链、控制器依赖库没安装，这些问题在示例场景里最容易暴露。
2.3 固件烧录与通路验证
e-puck的固件负责解释控制器指令、采集传感器数据、控制电机。仿真环境里跑的是虚拟控制器，不涉及固件；但实物实验必须确保固件版本正确。e-puck2通常通过USB连接到电脑，按住机身底部的reset按钮进入固件升级模式，然后使用命令行工具烧录.hex文件。e-puck一代用的方式稍有不同，一般是串口烧录或者外接调试器。
烧录完成后，建议先用官方Demo做通路验证：机器人上电后，应该有基本的LED反馈，手动转动轮子时传感器数据会变化。如果这些都没有，先排除线材和供电问题，再查驱动和固件版本匹配情况。很多人跳过这一步，直接在仿真改完算法就上实物，最后发现机器人一动不动，还以为是代码问题，其实是固件根本没刷进去。
3. Webots仿真场景搭建：从空白场地到带障碍的迷宫
3.1 从模板创建世界文件，避免从零堆节点
Webots世界文件的后缀是.wbt，本质上是一个基于VRML语法扩展的文本文件，直接写当然可以，但不推荐从零开始，因为机器人模型、传感器参数、物理引擎配置非常冗长。更高效的方式是基于官方示例改写：复制一份自带e-puck的world文件，另存为“my_epuck_scene.wbt”，然后在WorldInfo、Viewpoint和机器人节点之间添加自己的场景元素。
这样做的好处是保留了正确的机器人模型路径和控制器挂载方式，你只需要关注场地元素。打开编辑器后，左边是场景树，右边是3D视图。场景树的层级关系要看清，每一个Solid节点代表一个具有物理属性的刚体，Shape节点只负责显示外观，真正的碰撞检测取决于boundingObject字段。很多新手在场景里画了一面墙，看起来漂亮，机器人却直接穿过去，就是因为忘了给墙体设置boundingObject。
3.2 墙体、障碍物与地标的设计规则
搭建场景时先用RectangleArena或Floor节点做地面，再在上面摆放墙壁和障碍物。地面尺寸需要和实物场地对应，建议先在纸上画出俯视图，标好墙体位置、开门方向、障碍物坐标，再在Webots里逐个添加。
墙体建议用Box形状的Solid节点。比如要搭一面长2米、高0.12米、厚0.05米的墙，就在Solid的Shape节点里定义Box的尺寸，然后在physics和boundingObject字段里也挂一个同尺寸的Box。这样既能看到墙的样式，也能让机器人真撞上去。障碍物可以设计成圆柱或方柱，关键参数是直径、位置和表面颜色。颜色会影响红外传感器的反射，仿真里也要尽量接近实物：黑墙和深色障碍物会让红外传感器读数偏低，白墙和浅色障碍物读数偏高。
地标用来做视觉定位或者Checkpoint，可以在场景中放置不同颜色的方块或者圆形标志物。颜色在仿真里可以用Material的diffuseColor属性设置，但要注意光照条件，默认的定向光在特定角度下会让颜色区分度下降。如果要复现实物实验中的视觉识别，最好在场景里加一盏位置固定的环境光，让标志物的颜色保持稳定。
一个典型的迷宫场景会包含至少三面以上的墙体，以及若干独立障碍。我会先把场景元素按功能分成三类：
- 连续导向墙：用于限制机器人活动空间，形成路径通道。
- 独立障碍物：用于触发避障行为，通常是圆柱体、方体或不规则体。
- 视觉地标区：用于定位或决策点，可以在墙面上贴色块，也可以在地面放置色板。
3.3 挂载控制器并用传感器数据验证场景
场景搭好以后，把控制器挂到e-puck节点上。Webots里可以在机器人节点的controller字段填你的C/Python/Matlab程序名称，也可以在运行时通过“Robot Window”手动加载。仿真运行时，建议把Webots自带的传感器可视化打开，查看红外测距传感器在机器人靠近墙壁时的读数变化。
用一段简单的避障代码做验证很合适。下面这个C程序读取前向红外传感器ps0和ps7，当检测到障碍时反向转向，否则直行：
#include <webots/robot.h> #include <webots/distance_sensor.h> #include <webots/motor.h> #define TIME_STEP 64 #define MAX_SPEED 6.28 int main(int argc, char **argv) { wb_robot_init(); WbDeviceTag ds_left = wb_robot_get_device("ps0"); WbDeviceTag ds_right = wb_robot_get_device("ps7"); wb_distance_sensor_enable(ds_left, TIME_STEP); wb_distance_sensor_enable(ds_right, TIME_STEP); WbDeviceTag motor_left = wb_robot_get_device("left wheel motor"); WbDeviceTag motor_right = wb_robot_get_device("right wheel motor"); wb_motor_set_position(motor_left, INFINITY); wb_motor_set_position(motor_right, INFINITY); while (wb_robot_step(TIME_STEP) != -1) { double left_distance = wb_distance_sensor_get_value(ds_left); double right_distance = wb_distance_sensor_get_value(ds_right); if (left_distance < 100.0 || right_distance < 100.0) { wb_motor_set_velocity(motor_left, -MAX_SPEED * 0.4); wb_motor_set_velocity(motor_right, MAX_SPEED * 0.4); } else { wb_motor_set_velocity(motor_left, MAX_SPEED * 0.4); wb_motor_set_velocity(motor_right, MAX_SPEED * 0.4); } } wb_robot_cleanup(); return 0; }这个控制器的阈值100并不是固定值，需要根据你场景里的墙壁颜色、传感器型号和距离读数范围调整。验证时重点看三个数据：机器人是否能在碰撞前完成转向、转向后的路径是否平滑、在长直道上的速度是否稳定。如果机器人在离墙很远的地方就转向，说明阈值偏大；如果快撞上了才反应，说明阈值偏小。这些都跟场景材质直接相关，所以在仿真阶段就要把材料、颜色定下来，不然后面很难复现。
4. 实物场景一比一复刻：材料、尺寸和坐标都对得上
4.1 选材和布局：哑光地面、可移动墙块
仿真里调通了，接下来就是实物场地。材料选择直接决定实验成败：地面尽量用哑光材质，比如哑光地板革或哑光喷漆木板，避免高光反射对红外传感器的干扰。墙壁可以用轻质木板、亚克力板或硬纸板，关键要求是表面平整、颜色统一、有一定强度。我的习惯是把墙板底部加一个小底座，方便移动和重新布局，避免每次实验都重新切割材料。
尺寸上，必须和仿真世界一一对应。先把Webots里的场景尺寸换算成真实长度，比如仿真里地面是5米×5米、墙高0.12米，实物场地也要保持这个比例。不要随手拿一个教室角落就开跑，场地大小变了，传感器探测范围和机器人转弯半径都会显得不同，实验结论没法比较。
4.2 关键尺寸：墙高、转弯半径与传感器视线
e-puck的红外传感器的安装位置离地面有一定高度，不是贴地扫描，而是斜向上朝前方探测。这意味着墙面高度至少要覆盖传感器的探测角度，否则机器人会从墙面上方“看”过去，导致测距失效。根据我的经验，墙面高度建议在8到12厘米之间，最低不要低于6厘米。太矮了机器人不识别，太高了搬运和存放不方便。
转弯半径也是常被忽略的一项。e-puck是差速机器人，转向时以两个轮子中心点为圆心画弧，最小转弯半径跟轮距和两侧轮速差有关。在设计迷宫通道宽度时，至少要留出两倍以上的车身直径加一个红外传感器的可靠探测距离。通道太窄，机器人在里面反复打转；通道太宽，避障行为不够明显。仿真里可以反复试，实物中要提前量好尺寸再切板材。
另外，地面平整度非常关键。e-puck的轮子直径小，对地面凸起非常敏感，一块地砖的落差就可能导致传感器抖动和轮速计漂移。实验前要清场，把可能干扰的红外信号源、反光物体、强光源都移开。
4.3 场地标定：画参考线、调转向、记轮速计漂移
实物搭建完毕后，需要做场地标定。第一步是画参考线：在地面标记起始点、转折点和目标点，用不同颜色胶带区分。第二步是验证机器人的基本转向精度，让e-puck原地转90度，对比实际转角和目标角度的误差，记录陀螺仪漂移量。第三步是轮速计标定，让机器人走一段固定距离，例如2米，对比传感器累计位移和实际距离的偏差，得到每米厘米级的漂移参考。
这个漂移数据在后续实验里非常重要，尤其是在编队或者路径规划任务中。如果发现漂移过大，优先检查两个电机的速度是否一致、轮子是否磨损、地面摩擦是否均匀。也可以通过修改固件里的轮径参数来微调。但更重要的是，你需要用这些标定数据反过来调整仿真里的物理参数，让仿真世界和实物世界的差距尽量小。比如实物地面偏滑，仿真里的coulombFriction就要相应降低；实物墙面颜色偏深，仿真里的漫反射系数也要调整。
5. 三类典型实验的场景配置思路：避障、沿墙、编队
5.1 避障场景：稀疏障碍与速度阈值的搭配
避障是e-puck入门实验，也是场景搭建最基础的需求。场景的核心是稀疏布置几个独立障碍物，让机器人从一个点出发，绕开所有障碍到达终点。障碍物之间要留出足够的间距，别让机器人卡在两个障碍之间反复试探。
速度阈值要和场景大小匹配。场地大、障碍稀疏时，可以把最大速度调高一些，提高实验效率；场地小、障碍密集时，速度要降下来，留给传感器响应的时间。e-puck在快速前进时制动距离并不短，如果阈值设得太激进，传感器读到障碍再转向就来不及了。通常我会先让对方把速度调成最大速度的40%跑通场景，再逐步提速度，观察控制器的反应极限。
5.2 沿墙行走场景：连续墙面与传感器朝向
沿墙行走是服务机器人领域的基础功能，e-puck实现起来主要是利用侧向的红外传感器保持固定距离跟随墙面。这个场景对墙面的连续性要求很高：墙体接缝要平滑，墙面不能有明显凹陷或凸起。否则传感器读到的是墙面的局部特征变化，而不是稳定的距离值，控制器会把这种变化误当成墙的方向改变。
场景布局上，可以用几块直板拼出L形或者U形走廊。重点是拐角处的处理，直角拐角对传感器朝向很敏感，如果机器人的侧向传感器没有完全对准墙面，拐弯时容易出现丢墙。建议在仿真里先测出侧向传感器在不同距离的读数曲线，再根据读数设定合适的“跟墙距离”和角速度。
5.3 编队实验场景：标识物与全局定位
多机器人编队是e-puck比较进阶的玩法，对场景的要求也更高。几台机器人要在同一块场地里协同运动，首先需要能区分彼此，一般做法是在机身上方固定不同颜色或不同图案的标识物，摄像头俯拍进行识别。
场地需要有全局定位能力，常见方案是在场地正上方架设一个俯视摄像头，通过识别标识物得到各机器人位置和朝向。这种情况下，地面颜色最好单一且与标识物颜色对比度高，避免把地面误检成机器人。灯光也要均匀，避免在场地局部产生阴影。
编队的场景中通常不需要太多障碍物，反而要留出相对开阔的运动空间。可以在场地周边设置软性围挡，防止机器人掉出边界。如果要做避障编队，再逐步加入障碍，但要确保每台机器人都能在编队和避障两个任务之间安全切换。
6. 仿真转实物最常见的坑，以及排查思路
6.1 地面摩擦和滑动摩擦参数导致的行为漂移
仿真和实物行为不一致，最典型的根源是物理参数设置。Webots里的地面和轮子默认接触参数是理想化的，摩擦系数偏高，表现为起步干脆、转向响应快。而实物地面可能偏滑，尤其是常见的环氧树脂地坪或瓷砖地面，机器人起步会轻微打滑，转向时转弯半径变大。
排查思路是：先记录机器人在实物上的一个标准动作，比如从静止加速到匀速、原地转90度、直线走2米，记录实际用时和终态位置；然后在仿真里跑相同的动作，调整WorldInfo里contactProperties节点下的coulombFriction和bounce参数，让仿真输出尽量接近实物。这个校准过程比较枯燥，但一次校准好之后，后续实验会省心很多。
6.2 红外距离传感器对不同颜色和材质的误判
e-puck的红外传感器靠反射红外光测距，深色表面吸收红外光的比例高，传感器读到的距离会比实际远；黑色表面的情况最极端，甚至可能认为前方无障碍。实验场景如果用了黑色或深色材料做墙壁、障碍物，避障算法的可靠性会大打折扣。
我遇到过最典型的情况是：仿真里用浅灰色墙面，避障算法完全正常，实物换成了黑色挡板之后，机器人在快要碰到墙时才开始转向，或者直接撞上。排查思路分两步。第一步确认材料，换用白色或浅色表面，或者在黑色墙板表面贴白色哑光贴纸。第二步是重新标定传感器，把真实距离和ADC读数拟合成一条曲线，根据曲线调整控制器阈值。千万不要拿着仿真里的阈值直接上实物。
另外，墙面如果过于光滑或者有镜面反光，红外信号会发生镜面反射，导致传感器读数出现尖峰抖动。这种情况下优先选择哑光表面，或者调整传感器朝向，让入射光不形成正反射。
6.3 场景文件的版本管理建议
最后说一个只有做得多了才会意识到的问题：场景文件要有版本管理。Webots的.wbt文件是文本格式，但改动很频繁，墙加了一面、颜色调了一点、摩擦系数改了一个，这些变化都会影响算法表现。如果不做记录，几天后你会发现“之前明明能跑通，怎么现在不行了”，然后陷入重复调参的泥潭。
我的做法是给每个场景文件单独建一个文件夹，里面放.wbt文件、对应的控制器代码、参数说明markdown文档、以及一张俯视布局截图。每次改场景，先复制一份旧版本，标注日期和改动内容。这样无论查问题还是写论文附录，都能清楚还原当时的实验条件。
在最终的项目总结里，我还会把仿真场景和实物场景的对照表一并整理出来，包括尺寸、材质、颜色、摩擦系数、传感器阈值这些关键项。这张表既是给合作者的交付物，也是后续扩展实验时的重要依据。毕竟e-puck的场景搭建不是一次性的体力活，它本质上是在为一个完整的实验闭环服务，把底子打扎实了，后续的算法调试才会有意义。
SQLPA：把 SQL 调优输入源改到 TaoToken)
