Flix：ESP32 四旋翼从零制作、调试与源码学习教程

Flix（flight + X）是一套“从通用元件开始做一台能飞的四旋翼”的开源方案。仓库同时包含飞控固件、硬件/装配文档、Gazebo 仿真、Python 控制库和日志分析工具。

2.1 仓库主结构

2.2 1000 Hz 主循环

flix/flix.ino 的主循环非常直白，几乎就是整套飞控的数据流图：

void loop() {
    readIMU();
    step();
    readRC();
    estimate();
    control();
    sendMotors();
    handleConsole();
    processMavlink();
    readVoltage();
    logData();
    syncParameters();
}

这也是推荐的源码阅读顺序：先看数据从哪里来，再看它如何被估计、控制和输出。

2.3 姿态估计

• estimate.ino 先对 gyro 做低通滤波，默认注释约 40 Hz。
• 每个周期用角速度 × dt 形成旋转向量，再更新四元数姿态。
• 无人机静止/落地时，用加速度计重力方向修正姿态漂移。
• 飞行中不直接信任加速度计作为重力方向，而是用很弱的 level correction 抑制长期漂移。

2.4 级联控制与电机混控

control.ino 默认模式为 STAB。姿态控制先把姿态误差变成角速度目标，再由角速度 PID 产生三轴 torque target，最后与总推力一起混到四个电机。

FL = thrust + roll - pitch + yaw
FR = thrust - roll - pitch - yaw
RL = thrust + roll + pitch - yaw
RR = thrust - roll + pitch + yaw

源码默认参数可作为阅读起点，而不是直接当作“任何机架都通用”的最终调参：roll/pitch rate PID 约 P=.05 I=.2 D=.001，yaw rate P 约 .3；姿态 P 则 roll/pitch 约 6、yaw 约 3。

2.5 其他关键模块

路线 A：预编译固件，最快让板子跑起来

1. 按 ESP32 / ESP32-S3 / ESP32-C3 / Flix2 板型下载仓库文档提供的 merged binary。
2. 打开 ESP32 Web Flasher，连接板子的串口。
3. 选择下载的固件。
4. Flash address 设置为 0。
5. Program，完成后重启。

适合“先验证硬件/网络/地面站”的第一轮。

路线 B：源码构建，适合学习与二次开发

Arduino IDE

1. Arduino IDE 2.x。
2. 安装 ESP32 core 3.3.10。
3. Library Manager 安装 FlixPeriph 最新版。
4. 安装 MAVLink 2.0.33。
5. 打开 flix/flix.ino。
6. ESP32 Mini 选择 WEMOS D1 MINI ESP32；S3 常用 ESP32S3 Dev Module。
7. Tools → Core Debug Level → Error。
8. Build & Upload。

命令行

git clone https://github.com/okalachev/flix.git
cd flix
make
make upload
make upload monitor

Makefile 会安装指定 ESP32 core 和 Arduino 库。S3/C3 可以通过 BOARD 覆盖 FQBN：

make BOARD=esp32:esp32:esp32s3 upload

7.1 三种人工控制方式

• 手机：QGroundControl Virtual Joystick 或 Mavlink Joystick，经 Wi‑Fi。
• SBUS 遥控：设置 RC_RX_PIN，用 rc 检查接收，再执行 cr 校准。
• USB 双摇杆：电脑运行 QGroundControl，经 Wi‑Fi 连接无人机，在 Vehicle Setup → Joystick 中校准。

7.2 默认摇杆与解锁

默认左摇杆：Throttle + Yaw；右摇杆：Pitch + Roll。

7.3 第一趟真实飞行建议

1. 满电电池，检查 4 个桨均无裂纹。
2. 先在地面解锁，观察四电机是否平稳、无强振动。
3. 轻推油门，只做短暂“减重/离地”。
4. 如果机体明显向固定方向翻，立刻收油，回到电机旋向、桨型、IMU 朝向检查。
5. 能够稳定离地后，再尝试 0.5–1 m 悬停。
6. 先保持默认 STAB，不要第一飞就切 ACRO/AUTO。

Flix 的模拟器使用 Gazebo 11，并把飞控 Arduino 逻辑放进虚拟物理环境。项目文档推荐 Ubuntu 20.04；近期 macOS 上 Gazebo 11 兼容性不理想。

安装与启动

git clone https://github.com/okalachev/flix.git
cd flix

# 安装 Arduino CLI 后，安装 Gazebo 11 / libgazebo11-dev / SDL2 等依赖
make simulator

模拟器三层结构

仿真启动后，可以像真机一样用 QGroundControl 手机虚拟摇杆或 USB 摇杆控制。这样可以在没有螺旋桨风险的情况下熟悉 arm/disarm、参数、控制模式和 pyflix。

9.1 安装与连接

pip install pyflix

from pyflix import Flix

flix = Flix()   # 等待网络中的 Flix
print(flix.connected)
print(flix.attitude_euler)
print(flix.rates)
print(flix.voltage)

真机要先连接 flix Wi‑Fi；模拟器则让脚本与运行 Gazebo 的主机处于同一网络。

9.2 参数、CLI 与事件

pitch_p = flix.get_param('CTL_ATT_P_P')
flix.set_param('CTL_ATT_P_P', 5)

print(flix.cli('imu'))
print(flix.cli('time'))

flix.on('connected', lambda: print('Connected'))
att = flix.wait('attitude_euler', timeout=3)

9.3 AUTO 模式

pyflix 当前可发姿态目标、角速度目标，也可以直接设置 raw motor outputs。教程建议先只使用“姿态/角速度目标”，不要从 raw motor outputs 开始。

flix.set_mode('AUTO')

# 姿态目标：roll / pitch / yaw + thrust
flix.set_attitude([0.0, 0.0, 0.0], 0.25)

# 停止推力：AUTO 下会自动 disarm
flix.set_attitude([0.0, 0.0, 0.0], 0.0)

当前文档明确标注 set_position 和 set_velocity 仍在开发、暂不可用。

9.4 与 QGroundControl 同时使用

flix-proxy

然后在 QGroundControl → Comm Links 新建 UDP link，端口 14560，即可让 pyflix 脚本和 QGC 同时工作。

10.1 日志

固件默认把飞行日志暂存在 RAM，文档默认容量约 10 秒、100 Hz。Wi‑Fi 连上无人机后：

make log
# CSV 保存在 tools/log/*.csv

make plot
# 用 PlotJuggler 打开最近一次日志

make log plot

也可以把 CSV 转成 ULog 给 FlightPlot，或转 MCAP 给 Foxglove Studio。

10.2 常见故障矩阵

11.1 增加一个新子系统

官方架构文档给出的推荐方式：

1. 新建一个 *.ino。
2. 定义 setupXxx() 与 loopXxx()。
3. 需要降频时使用 Rate，不要在飞行主线程里做阻塞延时。
4. 在 flix.ino 的 setup() / loop() 注册调用。

Rate mySubsystemRate(100);  // 100 Hz

void loopMySubsystem() {
    if (!mySubsystemRate) return;
    // do something lightweight
}

11.2 增加参数

参数系统基于 ESP32 Preferences 存到非易失存储。一般流程：定义全局变量 → 加入 parameters 表 → 需要时绑定参数变化回调。这样 QGroundControl、Console 和 pyflix 都能继续复用统一参数入口。

11.3 不要在飞行主线程 delay()

官方文档明确警告：这是经典 Arduino 单线程设计，飞行时命令里使用阻塞 delay() 可能直接让飞控失去实时性。地面命令需要暂停时使用项目自己的 pause()，以保持 MAVLink 连接处理。

11.4 值得做的二次开发方向

• 扩展 IMU 或磁力计/气压计支持，并评估更强的姿态/高度估计。
• 把 AUTO 从姿态/角速度目标推进到位置/速度闭环。
• 给 pyflix 增加实验脚本、轨迹生成与安全状态机。
• 为日志增加更多控制误差字段，并自动生成调参图表。
• 用 Gazebo 建立参数扫描/回归测试，减少真机试错。

• GitHub：okalachev/flix
• Assembly guide
• Usage：build, setup and flight
• Firmware architectural overview
• Gazebo simulation
• pyflix Python library
• Troubleshooting
• Log analysis
• 主循环 flix.ino
• 级联控制 control.ino
• 姿态估计 estimate.ino
• 电机输出 motors.ino