当前版本说明与边界

本手册依据 SwiftWing 仿真源码提交 87604283e73deccb2c55012b8489a0ce892b661d 整理，函数行号与行为说明以该版本为基准。以下内容用于帮助开发者正确理解现有实现，不代表所有上游版本或实机系统都具有相同行为。

源码更新后，可在 Wiki 仓库中运行：

python3 tools/generate_api_reference.py

该脚本会重新解析有效 Python 语法并生成 API 页面；控制公式、参数语义和运行流程仍需结合源码变更人工复核。

已提供能力

  • Ubuntu 20.04、ROS Noetic、PX4 v1.15.0、Gazebo Classic 组合；
  • 固定翼、垂起固定翼和多旋翼单机仿真；
  • 五类单机轨迹示例；
  • 6 机领航—跟随和分布式一致性编队；
  • 速度向量与姿态两类上层控制接口；
  • Docker 环境模板。

参数管理

轨迹点、巡航速度、飞行高度、GVF 增益、LQR 权重、编队间距和部分 PID 参数目前直接写在 Python 源码中。修改实验配置时，建议在实验记录中保存文件版本；如需批量实验，可进一步迁移为 ROS 参数或 YAML 配置。

依赖声明

运行时实际使用的 Python/ROS 依赖多于 package.xml 中当前列出的条目，例如 NumPy、SciPy、Matplotlib、Plotly、GeographicLib 与 PyGeodesy。环境安装应以本机环境配置和实际导入为准。

数值前提

部分控制与算法函数默认：

  • 速度模长非零；
  • 曲线梯度或切向量非零；
  • acos/asin 输入处于合法区间；
  • 路径相邻点不重合；
  • 图拉普拉斯矩阵尺寸、成员数和编号一致。

自定义算法应在调用前检查这些条件。API 页面中的“写入状态”和“主要调用”可帮助定位需要增加保护的位置。

命名与语义

源码保留了部分历史命名，例如 Eular、Quater、Jacobin。文档沿用函数原名以便搜索，但正文使用“欧拉角、四元数、雅可比”等标准术语。

个别注释中的坐标系缩写不完全一致。应以实际话题、消息字段、coordinate_frame 和现场单轴测试共同确认，而不是只依赖变量名。

仿真与实机

当前自动解锁、起飞和模式切换流程面向 SITL。仿真中的真值位姿、理想通信和计算资源与实机不同。实机迁移至少需要重新验证：

  • 估计器与坐标原点；
  • 空速、风场与传感器噪声；
  • 延迟、丢包与控制频率；
  • 模式切换和失控保护；
  • 执行机构、推力和姿态限幅；
  • 场地、空域和人工接管流程。

后续扩展方向

源码 README 中列出的方向包括混合机型编队、ROS 2 适配以及视觉/激光雷达传感器支持。它们属于扩展方向，不应视为当前版本已经提供的功能。