算法与场景演示

本页说明如何在 AISWARMLAB 地面站中选择环境和算法，如何从选择结果定位并修改对应源码与 YAML 配置，以及如何配置虚拟设备、真实设备和虚实混合算法演示。

修改前先停止算法

修改真机参数前必须停止正在运行的算法节点，避免旧进程继续向无人机发送位置或速度指令。

宿主机路径因电脑而异

原始操作电脑上的项目根目录为 /home/frank12/aiswarmlab/aiswarmlab，其中 frank12 是该电脑的用户名，其他电脑不能直接照抄。

本文使用 <AISWARMLAB_ROOT> 表示当前电脑中 AISWARMLAB 项目的实际根目录。请先在项目根目录执行 pwd 查看真实路径，再替换文中的该占位符。Docker 容器内以 /home/linuxbrew/... 开头的路径不受宿主机用户名影响。

1. 算法与环境目录

项目源码通过 Docker Volume 挂载到容器中。在宿主机修改 source/swarmlab_simulator_ws 下的文件后，容器中的对应源码会同步变化。

1.1 宿主机与容器路径对照

内容	宿主机路径	Docker 容器路径
无人车算法源码	`<AISWARMLAB_ROOT>/source/swarmlab_simulator_ws/src/swarm_brain/swarm_brain/wheelswarm_algos`	`/home/linuxbrew/swarmlab_simulator_ws/src/swarm_brain/swarm_brain/wheelswarm_algos`
无人车算法参数	`<AISWARMLAB_ROOT>/source/swarmlab_simulator_ws/src/swarm_brain/config/wheelswarm_algos`	`/home/linuxbrew/swarmlab_simulator_ws/src/swarm_brain/config/wheelswarm_algos`
无人车环境配置	`<AISWARMLAB_ROOT>/source/swarmlab_simulator_ws/src/swarm_env/config/wheelswarm_env_config`	`/home/linuxbrew/swarmlab_simulator_ws/src/swarm_env/config/wheelswarm_env_config`
无人机算法源码	`<AISWARMLAB_ROOT>/source/swarmlab_simulator_ws/src/swarm_brain/swarm_brain/crazyswarm_algos`	`/home/linuxbrew/swarmlab_simulator_ws/src/swarm_brain/swarm_brain/crazyswarm_algos`
无人机算法参数	`<AISWARMLAB_ROOT>/source/swarmlab_simulator_ws/src/swarm_brain/config/crazyswarm_algos`	`/home/linuxbrew/swarmlab_simulator_ws/src/swarm_brain/config/crazyswarm_algos`
无人机环境配置	`<AISWARMLAB_ROOT>/source/swarmlab_simulator_ws/src/swarm_env/config/crazyswarm_env_config`	`/home/linuxbrew/swarmlab_simulator_ws/src/swarm_env/config/crazyswarm_env_config`

1.2 各类文件的用途

swarm_brain/swarm_brain/*_algos/*.py：算法实现源码，例如路径规划、编队控制和速度计算逻辑；
swarm_brain/config/*_algos/*_algo_config.yaml：算法参数，例如速度上限、安全半径、控制增益、目标点和飞行高度；
swarm_env/config/*_env_config/*_env_config.yaml：运行模式、虚拟/真实设备编号、场地边界、障碍物或威胁区域；
algorithm_registry.yaml：地面站或 Brain 可选算法名称与 Python 类、参数文件之间的注册关系；
env_registry.yaml：环境名称与环境类、环境配置文件之间的注册关系；
wheelswarm_env_config.yaml 或 crazyswarm_env_config.yaml：当前选择的环境名称；
wheelswarm_brain_config.yaml 或 crazyswarm_brain_config.yaml：当前选择的算法名称。

修改文件时可按以下原则判断：

调整设备数量、设备编号、场地边界或虚实模式：修改环境 YAML；
调整速度、控制增益、航点、飞行高度或避碰参数：修改算法参数 YAML；
改变算法的计算逻辑：修改对应的 .py 源码；

2. 在 UI 中选择平台、环境和算法

在地面站顶部或平台选择区域切换目标平台：无人车选择 Wheelswarm，无人机选择 Crazyswarm/UAV；
打开环境或场景配置区域，选择本次演示环境，并点击“设为当前”；
打开算法配置区域，选择与环境匹配的算法，并点击“设为当前”；
确认 UI 中显示的机器人数量和编号与实际配置一致；
真机演示时，先完成 YAML 配置和 ROS 2 话题检查，再启动算法。

2.1 无人机环境与算法配对

无人机环境与算法的正式对应关系存放在项目根目录：

text

<AISWARMLAB_ROOT>/01-室内版无人机集群算法真机验证进度表.docx

当前进度表中记录的主要配对如下：

测试内容	UI 环境名称	UI 算法名称
双机避碰	`fanci_square`	`FanciSquare_Algorithm`
盘旋	`circle`	`Circle_Algorithm`
航点导航	`waypoints`	`Waypoints_Algorithm`
区域搜索	`area_search`	`AreaSearch_Algorithm`
区域巡逻	`area_patrol`	`AreaPatrol_Algorithm`
区域突防	`area_penetration`	`AreaPenetration_Algorithm`
编队集结	`assembly_flight`	`AssemblyFlight_Algorithm`
编队飞行	`formation_fly`	`FormationFly_Algorithm`
编队变换	`formation_change`	`FormationChange_Algorithm`
协同搜索	`collaborative_search`	`CollaborativeSearch_Algorithm`
多机协同路径规划	`cbs_astar`	`CBS_AStar_Algorithm`

如果进度表、UI 当前选项和代码注册表不一致，应以经过现场确认的最新进度表和注册表为准，不要仅根据文件名自行组合环境与算法。

3. 从 UI 名称定位对应文件

以无人机区域突防为例，UI 中选择：

text

环境：area_penetration
算法：AreaPenetration_Algorithm

3.1 查询环境注册表

在容器中执行：

bash

cd /home/linuxbrew/swarmlab_simulator_ws
rg -n -A 5 '^  area_penetration:' src/swarm_env/config/crazyswarm_env_config/env_registry.yaml

环境注册表中的 area_penetration 条目会指向 area_penetration_env_config.yaml。

3.2 查询算法注册表

bash

rg -n -A 5 '^  AreaPenetration_Algorithm:' src/swarm_brain/config/crazyswarm_algos/algorithm_registry.yaml

算法注册表中的 AreaPenetration_Algorithm 条目会指向算法源码、Python 类名和 area_penetration_algo_config.yaml。

如果容器中没有 rg，可改用：

bash

grep -n -A 5 '^  area_penetration:' src/swarm_env/config/crazyswarm_env_config/env_registry.yaml
grep -n -A 5 '^  AreaPenetration_Algorithm:' src/swarm_brain/config/crazyswarm_algos/algorithm_registry.yaml

3.3 检查当前选择文件

无人机当前环境和算法的主选择文件分别是：

text

src/swarm_env/config/crazyswarm_env_config/crazyswarm_env_config.yaml
src/swarm_brain/config/crazyswarm_algos/crazyswarm_brain_config.yaml

区域突防示例中，对应内容应为：

yaml

# crazyswarm_env_config.yaml
env_name: area_penetration

yaml

# crazyswarm_brain_config.yaml
alg_name: AreaPenetration_Algorithm

通常由地面站 UI 完成选择。排查配置时，可以直接查看这两个文件，确认 UI 是否写入预期名称。

无人车的查找方式相同，但使用以下文件：

text

src/swarm_env/config/wheelswarm_env_config/env_registry.yaml
src/swarm_env/config/wheelswarm_env_config/wheelswarm_env_config.yaml
src/swarm_brain/config/wheelswarm_algos/algorithm_registry.yaml
src/swarm_brain/config/wheelswarm_algos/wheelswarm_brain_config.yaml

4. 修改环境配置

虚实接口字段的详细说明位于：

text

<AISWARMLAB_ROOT>/虚实接口设置.md

4.1 无人机常用字段

无人机环境配置常用字段如下：

字段	作用
`sim2real`	`sim` 为纯仿真，`real` 为纯真机，`hybrid` 为虚实混合
`sim_drone_indexing`	虚拟无人机编号方式，取值为 `auto` 或 `manual`
`sim_drone_num`	自动编号时的虚拟无人机数量
`sim_drone_init_id`	自动编号时的虚拟无人机起始 ID
`sim_drone_ids`	手动编号时的虚拟无人机 ID 列表
`real_drone_indexing`	真实无人机编号方式，取值为 `auto` 或 `manual`
`real_drone_num`	自动编号时的真实无人机数量
`real_drone_init_id`	自动编号时的真实无人机起始 ID
`real_drone_ids`	手动编号时的真实无人机 ID 列表
`inner_boundaries`	主要任务区域边界
`outer_boundaries`	外部安全或显示边界
`ax_boundaries`	绘图坐标范围

4.2 自动编号示例

自动生成虚拟无人机 ID 21、22：

yaml

sim_drone_indexing: auto
sim_drone_num: 2
sim_drone_init_id: 21
sim_drone_ids: []

4.3 手动编号示例

手动指定虚拟无人机 ID 21、25：

yaml

sim_drone_indexing: manual
sim_drone_num: 2
sim_drone_init_id: 21
sim_drone_ids: [21, 25]

选择 manual 时，程序以 *_ids 列表为准，并根据列表长度计算设备数量。仍建议让 *_num 与列表长度保持一致，减少旧代码或其他工具读取配置时产生歧义。

4.4 无人车对应字段

无人车使用相同规则，但字段名称改为：

text

sim_robot_indexing、sim_robot_num、sim_robot_init_id、sim_robot_ids
real_robot_indexing、real_robot_num、real_robot_init_id、real_robot_ids

4.5 设备编号约束

配置 ID 时必须满足：

虚拟设备与真实设备的 ID 不重复；
真实无人机 ID 与动捕话题一致，例如 ID 1 对应 /uav_1/pose；
真实无人车 ID 与 ROS 2 命名空间一致，例如 ID 1 对应 /robot_1/...；
算法参数文件中按设备 ID 配置的任务项覆盖所有参与设备；
场地边界、目标点和障碍物使用同一个坐标系和单位。

5. area_penetration 虚实混合示例

5.1 演示目标

运行区域突防算法，使用两架虚拟无人机 21、22 和一架真实无人机 1。

先在地面站 UI 中选择：

text

平台：无人机 / Crazyswarm
环境：area_penetration
算法：AreaPenetration_Algorithm

5.2 环境配置文件位置

宿主机路径：

text

<AISWARMLAB_ROOT>/source/swarmlab_simulator_ws/src/swarm_env/config/crazyswarm_env_config/area_penetration_env_config.yaml

容器内对应路径：

text

/home/linuxbrew/swarmlab_simulator_ws/src/swarm_env/config/crazyswarm_env_config/area_penetration_env_config.yaml

这两个路径通过 Docker Volume 指向同一份源码文件，选择其中一种位置修改即可。

5.3 自动编号配置

将设备部分配置为：

yaml

# 虚实混合模式
sim2real: hybrid

# 两架虚拟无人机，自动生成 ID 21、22
sim_drone_indexing: auto
sim_drone_num: 2
sim_drone_init_id: 21
sim_drone_ids: []

# 一架真实无人机，自动生成 ID 1
real_drone_indexing: auto
real_drone_num: 1
real_drone_init_id: 1
real_drone_ids: []

5.4 手动编号配置

yaml

sim2real: hybrid

sim_drone_indexing: manual
sim_drone_num: 2
sim_drone_init_id: 21
sim_drone_ids: [21, 22]

real_drone_indexing: manual
real_drone_num: 1
real_drone_init_id: 1
real_drone_ids: [1]

5.5 现场相关环境参数

area_penetration_env_config.yaml 还包含：

min_height、max_height：允许的飞行高度范围；
inner_boundaries、outer_boundaries、ax_boundaries：任务边界、安全边界和显示范围；
threat_zones：威胁区域的中心坐标、半径和威胁等级。

不要直接使用示例边界

以上参数必须根据动捕场地的实际尺寸、坐标原点和安全区域调整，不要直接把示例边界用于真实飞行。

5.6 算法参数文件位置

宿主机路径：

text

<AISWARMLAB_ROOT>/source/swarmlab_simulator_ws/src/swarm_brain/config/crazyswarm_algos/area_penetration_algo_config.yaml

容器内路径：

text

/home/linuxbrew/swarmlab_simulator_ws/src/swarm_brain/config/crazyswarm_algos/area_penetration_algo_config.yaml

该文件包含：

grid_resolution、safety_margin：路径规划网格与威胁区安全边距；
velocity_limit、position_gain、altitude_gain：运动控制参数；
barrier_gain、safety_radius、enable_collision_avoidance：避碰参数；
drones：每架无人机的 drone_id、起点、终点和飞行高度。

本示例参与设备 ID 为 1、21、22，因此 drones 列表中必须存在这三个 ID 的任务配置。起点、终点、高度和安全半径必须经过现场复核后再运行。

完整字段规则以 虚实接口设置.md 为准，环境与算法配对以 01-室内版无人机集群算法真机验证进度表.docx 为准。

6. 让修改后的配置生效

源码目录虽然挂载到容器中，但 ROS 2 节点通过 get_package_share_directory() 读取 install 安装空间中的 YAML。因此，修改源码配置后应重新构建对应功能包。

6.1 只修改了环境配置

在容器中执行：

bash

cd /home/linuxbrew/swarmlab_simulator_ws
source /opt/ros/humble/setup.bash
colcon build --packages-select swarm_env --symlink-install
source install/setup.bash

6.2 修改了算法源码、算法注册表或算法参数

在容器中执行：

bash

cd /home/linuxbrew/swarmlab_simulator_ws
source /opt/ros/humble/setup.bash
colcon build --packages-select swarm_brain --symlink-install
source install/setup.bash

6.3 环境和算法都发生了修改

在容器中执行：

bash

cd /home/linuxbrew/swarmlab_simulator_ws
source /opt/ros/humble/setup.bash
colcon build --packages-select swarm_env swarm_brain --symlink-install
source install/setup.bash

构建完成后：

停止旧的环境、仿真器和 Brain 节点；
在启动节点的终端重新执行 source install/setup.bash；
必要时重新启动地面站，使 UI 重新加载算法和环境列表；
重新选择环境与算法，并检查终端输出的配置文件路径。

可检查安装空间中的环境配置是否已经更新：

bash

grep -n -E 'sim2real|sim_drone_num|real_drone_num' \
  /home/linuxbrew/swarmlab_simulator_ws/install/swarm_env/share/swarm_env/crazyswarm_env_config/area_penetration_env_config.yaml

7. 启动算法前检查

以 area_penetration 虚实混合模式为例，启动前逐项确认：

UI 环境是 area_penetration；
UI 算法是 AreaPenetration_Algorithm；
sim2real 是 hybrid；
虚拟 ID 与真实 ID 不冲突；
/uav_1/pose 持续更新；
仿真无人机 21、22 的状态话题正常；
算法参数中的 drones 包含 1、21、22；
所有起点、目标点、威胁区域和边界都在实际可用场地内；
速度、高度和安全半径适合首次低速演示；
RViz 的降落功能和现场急停手段可用。

8. 启动算法

完成以上检查后：

点击右侧工具栏中的编译入口，进入“编译工作空间”；
核对当前环境、当前算法、运行模式、设备数量、设备 ID 和场景边界；
点击“开始编译”，观察编译输出并确认没有错误；
编译完成后点击地面站左上角的“启动”；
同时观察地面站、RViz 和相关终端输出。

编译当前环境和算法并启动地面站运行

9. 演示过程监控与停止

演示过程中至少在已加载 ROS 2 环境的容器终端中监控：

bash

ros2 node list
ros2 topic hz /uav_1/pose
ros2 topic echo /uav_1/battery

同时观察地面站中的无人机位置、轨迹、节点状态和终端错误信息。

出现以下任一情况时，应立即停止算法，并执行现场规定的降落或急停流程：

位姿停止更新或冻结；
坐标发生明显跳变；
无人机偏离实际可用场地；
算法持续输出异常控制指令；
地面站、VRPN、FCU 或无人机通信中断。

发生异常时不要先关闭动捕或 Docker 容器，应先停止算法并安全降落或急停无人机。

算法与场景演示 ​

1. 算法与环境目录 ​

1.1 宿主机与容器路径对照 ​

1.2 各类文件的用途 ​

2. 在 UI 中选择平台、环境和算法 ​

2.1 无人机环境与算法配对 ​

3. 从 UI 名称定位对应文件 ​

3.1 查询环境注册表 ​

3.2 查询算法注册表 ​

3.3 检查当前选择文件 ​

4. 修改环境配置 ​

4.1 无人机常用字段 ​

4.2 自动编号示例 ​

4.3 手动编号示例 ​

4.4 无人车对应字段 ​

4.5 设备编号约束 ​

5. area_penetration 虚实混合示例 ​

5.1 演示目标 ​

5.2 环境配置文件位置 ​

5.3 自动编号配置 ​

5.4 手动编号配置 ​

5.5 现场相关环境参数 ​

5.6 算法参数文件位置 ​

6. 让修改后的配置生效 ​

6.1 只修改了环境配置 ​

6.2 修改了算法源码、算法注册表或算法参数 ​

6.3 环境和算法都发生了修改 ​

7. 启动算法前检查 ​

8. 启动算法 ​

9. 演示过程监控与停止 ​

算法与场景演示

1. 算法与环境目录

1.1 宿主机与容器路径对照

1.2 各类文件的用途

2. 在 UI 中选择平台、环境和算法

2.1 无人机环境与算法配对

3. 从 UI 名称定位对应文件

3.1 查询环境注册表

3.2 查询算法注册表

3.3 检查当前选择文件

4. 修改环境配置

4.1 无人机常用字段

4.2 自动编号示例

4.3 手动编号示例

4.4 无人车对应字段

4.5 设备编号约束

5. area_penetration 虚实混合示例

5.1 演示目标

5.2 环境配置文件位置

5.3 自动编号配置

5.4 手动编号配置

5.5 现场相关环境参数

5.6 算法参数文件位置

6. 让修改后的配置生效

6.1 只修改了环境配置

6.2 修改了算法源码、算法注册表或算法参数

6.3 环境和算法都发生了修改

7. 启动算法前检查

8. 启动算法

9. 演示过程监控与停止