# flix_cpp

**Repository Path**: px4_dev/flix_cpp

## Basic Information

- **Project Name**: flix_cpp
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-05
- **Last Updated**: 2026-11-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<!-- markdownlint-disable MD041 -->

<p align="center">
  <img src="docs/img/flix.svg" width=180 alt="Flix logo"><br>
  <b>Flix</b> (<i>flight + X</i>) — 基于 ESP32 从零构建的开源微型四旋翼无人机飞控项目
</p>

> [!NOTE]
> 本仓库为 **Flix 飞控的现代 C++17 / ESP-IDF 原生工程移植版**。原工程采用 Arduino 编写，本项目将其完整重构为面向对象、零 Arduino 依赖、专为 ESP-IDF v5.x（支持经典 ESP32、ESP32-S3、ESP32-C3 及 Flix2 定制板）优化的确定性 1 kHz 工业级飞控。完整的移植背景、软件架构与工具链指引请参阅 [**移植与编译指南 (PORTING_GUIDE.md)**](doc/PORTING_GUIDE.md)。

---

<table>
  <tr>
    <td align=center><strong>版本 1.1</strong> (3D 打印一体机架)</td>
    <td align=center><strong>版本 0</strong> (手工简易机架)</td>
  </tr>
  <tr>
    <td><img src="docs/img/flix1.1.jpg" width=500 alt="Flix quadcopter v1.1"></td>
    <td><img src="docs/img/flix.jpg" width=500 alt="Flix quadcopter v0"></td>
  </tr>
</table>

## 项目特性

* **专为教学与科研设计**：结构清晰明了，算法无黑盒，是深入学习无人机动力学与飞行控制理论的理想载体。
* **通用低成本元器件**：无需昂贵专用的无人机零部件，普通空心杯电机、MOSFET 与标准传感器模块即可组装。
* **精炼优雅的源代码**：核心飞控纯代码量极小，已被本项目完整升级为符合现代 C++17 标准的模块化架构。
* **标准 MAVLink 协议**：支持通过 Wi-Fi（AP/STA 模式 UDP）或超低延迟 **ESP-NOW** 进行高速双向无线通信，完美兼容 QGroundControl。
* **丰富灵活的操控方式**：支持通过 USB 游戏手柄、常规遥控器（SBUS 协议）或智能手机进行控制。
* **无线交互式命令行与日志系统**：具备板载交互式 CLI 调试终端与 100 Hz 内存环形飞行黑匣子日志，可通过无线直接导出分析。
* **高保真 Gazebo 物理仿真**：支持使用 Gazebo 进行高精度空气动力学与传感器硬件级闭环仿真。
* **Python 脚本自动化飞行库**：配套提供 `pyflix` Python 库，便于编写自动化控制脚本与算法验证。
* **配套理论教材**：包含飞行控制理论与工程实践教程（[持续编写中](https://quadcopter.dev)）。
* **自主定点控制**：（*外环位置控制与视觉定位功能持续演进中*）。

---

## 飞行演示

* 完整试飞与功能演示视频：https://youtu.be/hT46CZ1CgC4
  <a href="https://youtu.be/hT46CZ1CgC4"><img width=500 src="https://i3.ytimg.com/vi/hT46CZ1CgC4/maxresdefault.jpg" alt="Flix Demo Video"></a>

* 版本 0 初代试飞视频：https://youtu.be/8GzzIQ3C6DQ
  <a href="https://youtu.be/8GzzIQ3C6DQ"><img width=500 src="https://i3.ytimg.com/vi/8GzzIQ3C6DQ/maxresdefault.jpg" alt="Flix v0 Demo"></a>

* 教育实训营应用展示 (RoboCamp 2025)：https://youtu.be/Wd3yaorjTx0
  <a href="https://youtu.be/Wd3yaorjTx0"><img width=500 src="https://i3.ytimg.com/vi/Wd3yaorjTx0/sddefault.jpg" alt="RoboCamp 2025"></a>

* 更多社区创作者机型展示请浏览 [用户制作机型画廊](docs/user.md)：  
  <a href="docs/user.md"><img src="docs/img/user/user.jpg" width=500 alt="User builds gallery"></a>

### Flix2 官方集成 PCB 板

官方集成硬件版 *(Flix2)* 正在持续推进中（基于 ESP32-S3、八线 Octal PSRAM 与 ICM-40609-D 高性能 IMU）。您可关注 [官方 Telegram 频道](https://t.me/opensourcequadcopter) 获取最新进展。

当前 Flix2 原型机的室外试飞演示：

<a href="https://youtu.be/KXlNmvUTi4g"><img width=300 src="https://quadcopter.dev/video/KXlNmvUTi4g.svg" alt="Flix2 Prototype Flight"></a>

### 位置与定点控制 (Position Control)

基于外部视觉定位的位置闭环控制正在开发中。RoboCamp 2026 顶部相机视觉定点悬停演示（[源码参考](https://github.com/xTimop/flix-poscontrol/compare/robolager2026...xTimop:flix-poscontrol:poscontrol)）：

<a href="https://youtu.be/369Xowm4HcU"><img width=300 src="https://quadcopter.dev/video/369Xowm4HcU.svg" alt="Position control demo"></a>

---

## 仿真物理系统 (Simulation)

模拟器基于 Gazebo 开发，可直接驱动真实的飞控核心算法与控制逻辑进行软硬件闭环验证：

<img src="docs/img/simulator1.png" width=500 alt="Flix simulator">

---

## 文档导航

### 核心指南

1. [硬件组装指南](docs/assembly.md) — 零起点的焊接与安装步骤
2. [使用说明：固件配置与飞行操作](docs/usage.md) — 参数配置、传感器标定与地面站连接
3. [Gazebo 仿真指南](gazebo/README.md) — 仿真环境配置与多机仿真
4. [Python 脚本开发库](tools/pyflix/README.md) — 通过 Python 控制飞行
5. [**C++17 / ESP-IDF 固件移植与编译手册**](doc/PORTING_GUIDE.md) — **本项目 C++ 原生构建与工具链教程**

### 进阶技术文档

* [用户制作机型展厅](docs/user.md)
* [固件系统架构解析](docs/firmware.md)
* [常见故障排查手册](docs/troubleshooting.md)
* [飞行黑匣子日志分析](docs/log.md)

---

## 硬件物料清单 (BOM)

| 类型 | 部件名称 | 实物参考 | 数量 | 说明 |
| - | - | :-: | :-: | - |
| **主控核心板** | ESP32 Mini<br>*(亦支持 ESP32-S3 / ESP32-C3 开发板)* | <img src="docs/img/esp32.jpg" width=100 alt="ESP32 Mini"> | 1 | 飞控计算与无线数传核心 |
| **IMU（含气压计¹）模块** | GY‑91 / MPU-9265<br>*(或其它 MPU‑9250 / MPU‑6500 板)*<br>ICM20948V2 (ICM‑20948)<br>GY-521 (MPU-6050) | <img src="docs/img/gy-91.jpg" width=90><br><img src="docs/img/icm-20948.jpg" width=100><br><img src="docs/img/gy-521.jpg" width=100> | 1 | 惯性测量单元，提供角速度与加速度输入 |
| *升压模块（可选）* | *5V 升降压输出模块* | <img src="docs/img/buck-boost.jpg" width=100 alt="Boost converter"> | 1 | *用于在大电流油门输出时提供更稳定的系统供电* |
| **空心杯电机** | 8520 3.7V 有刷空心杯电机 | <img src="docs/img/motor.jpeg" width=100 alt="8520 Motor"> | 4 | 需选购标称 **3.7V** 专用电机（勿选 3.7V~6V 宽压电机），且确保电机轴径与桨孔匹配 |
| **螺旋桨** | 55 mm 或 65 mm 正反桨 | <img src="docs/img/prop.jpg" width=100 alt="Propeller"> | 4 | 正桨 A × 2，反桨 B × 2 |
| **MOSFET (驱动场效应管)** | UMW 100N03A 或 [同类兼容型号](https://t.me/opensourcequadcopter/33) | <img src="docs/img/100n03a.jpg" width=100 alt="100N03A"> | 4 | **警告**：请勿使用 KIA 100N03A 或劣质厂商芯片，否则低导通电压可能无法驱动电机 |
| **电阻** | 10 kΩ 贴片/色环电阻 | <img src="docs/img/resistor10k.jpg" width=100 alt="10k Resistor"> | 6 | 4 个用作 MOSFET 栅极下拉电阻，2 个用作电池分压采样 |
| **动力锂电池** | 3.7V 1S Li-Po 电池 (LW 952540 或尺寸兼容型号) | <img src="docs/img/battery.jpg" width=100 alt="Battery"> | 1 | 必须具备足够的放电倍率与容量，**强烈建议 25C 以上倍率，容量 1000 mAh 或更高**！ |
| **电池连接线** | MX2.0 2P 母头端子线 | <img src="docs/img/mx.png" width=100 alt="MX2.0 connector"> | 1 | 电池电源接入端子 |
| **充电器** | 1S 锂电池专用充电器 | <img src="docs/img/charger.jpg" width=100 alt="Charger"> | 1 | 任意兼容 3.7V 单节锂电池的充电器 |
| **IMU 安装螺丝** | M3x5 沉头/圆头螺丝 | <img src="docs/img/screw-m3.jpg" width=100 alt="M3 screw"> | 2 | 固定 IMU 传感器板 |
| **机架装配螺丝** | M1.4x5 自攻螺丝 | <img src="docs/img/screw-m1.4.jpg" height=30 alt="M1.4 screw"> | 4 | 固定上下机架结构 |
| **机架主体结构** | 3D 打印件²：[`stl`](docs/assets/flix-frame-1.1.stl) / [`step`](docs/assets/flix-frame-1.1.step) | <img src="docs/img/frame1.jpg" width=100 alt="Frame main part"> | 1 | 推荐打印参数：层高 0.2 mm，线宽 0.4 mm，填充率 100% |
| **机架顶部盖板** | 3D 打印件：[`stl`](docs/assets/esp32-holder.stl) / [`step`](docs/assets/esp32-holder.step) | <img src="docs/img/esp32-holder.jpg" width=100 alt="ESP32 holder"> | 1 | 固定 ESP32 主控 |
| **IMU 减震垫圈** | 3D 打印件：[`stl`](docs/assets/washer-m3.stl) / [`step`](docs/assets/washer-m3.step) | <img src="docs/img/washer-m3.jpg" width=100 alt="M3 washer"> | 2 | 隔离电机高频振动传导 |
| **遥控设备（推荐）** | • CC2500 遥控器（如 BetaFPV LiteRadio CC2500，走硬件接收机或 Wi-Fi）<br>• 双摇杆 USB 游戏手柄（走 Wi-Fi，见 [QGC 推荐手柄列表](https://docs.qgroundcontrol.com/master/en/qgc-user-guide/setup_view/joystick.html#supported-joysticks)）<br>• 智能手机等 | <img src="docs/img/betafpv.jpg" width=100 alt="BetaFPV"><img src="docs/img/logitech.jpg" width=80 alt="Logitech Gamepad"> | 1 | 操控飞行器 |
| *独立遥控接收机（可选）* | *DF500 或其它 SBUS 接收机³* | <img src="docs/img/rx.jpg" width=100 alt="Receiver"> | 1 | *仅在使用传统硬件无线遥控时需要* |
| **配线** | 28 AWG 超软硅胶线 | <img src="docs/img/wire-28awg.jpg" width=100 alt="28 AWG wire"> | 适量 | 模块间信号与供电走线 |
| **辅助物料** | 绝缘胶带、高粘双面胶 | | 适量 | 固定电池与模块 |

*¹ — 气压计定高目前处于固件接口预留阶段。*  
*² — 该机架针对 GY-91 模块开孔优化；若选用其它 IMU 传感器板，请根据孔位微调螺丝定位点。*  
*³ — 支持任何具备 SBUS 标准反相协议的发射机-接收机套件。*

### 所需装配工具

* 3D 打印机（用于打印机架、固定座与垫圈）
* 电烙铁与焊锡丝（建议带松香助焊剂）
* 小型十字/一字螺丝刀套件
* 数字万用表（用于焊接后检查电源短路及分压比校验）

欢迎自由修改机械与电气设计，打造您专属的定制版本。您可以将您的改进成果与试飞体验分享至 [官方 Telegram 交流群](https://t.me/opensourcequadcopterchat)，或直接联系原项目作者（[E-mail](mailto:okalachev@gmail.com) / [Telegram](https://t.me/okalachev)）。

---

## 电气原理图与接线规范

### 简化接线拓扑图

<img src="docs/img/schematics1.svg" width=700 alt="Flix version 1 schematics">

*(虚线框内的元器件为可选扩展配置)。*

MOSFET 驱动与下拉电阻焊接示意：

<img src="docs/img/mosfet-connection.png" height=400 alt="MOSFET connection scheme">

社区开发者贡献的完整无人机电路连线参考详见 [Miro 在线原理图面板](https://miro.com/app/board/uXjVN-dTjoo=/?moveToWidget=3458764612338222067&cot=14)。

### 引脚接线要点

1. **系统电源**：
   * 将 3.7V 锂电池的正极 (+) 连接至 ESP32 Mini 的 VCC 引脚，负极 (-) 连接至 GND 引脚。
2. **IMU 传感器（以 SPI 方式为例）**：
   * 使用 VSPI 总线连接 ESP32 Mini 与 IMU 板，通过 3.3V 和 GND 引脚为传感器供电：

   | IMU 引脚 | ESP32 引脚 | 说明 |
   | - | - | - |
   | **GND** | **GND** | 接地 |
   | **3.3V / VCC** | **3.3V** | 传感器核心供电 |
   | **SCL (SCK)** | **GPIO18** | SPI 时钟线 (SCK) |
   | **SDA (MOSI)** | **GPIO23** | SPI 主出从入 (MOSI) |
   | **SAO (MISO)** | **GPIO19** | SPI 主入从出 (MISO) |
   | **NCS (CS)** | **GPIO5** | 片选信号 (CS) |

3. **MOSFET 电机驱动连接**：
   * 在每个 MOSFET 的栅极（Gate）与源极（Source/GND）之间并联焊接 10 kΩ 下拉电阻，防止开机瞬间悬空误触发。
   s* 按照下表将 4 路电机驱动连接至 ESP32 的 PWM 引脚：

   | 电机编号 | 机身物理方位 | 旋转方向 | 匹配桨叶 | 电机导线颜色 | ESP32 GPIO |
   | - | - | - | - | - | - |
   | **电机 0** | 左后方 (Rear Left) | 逆时针 (CCW) | **B 桨** | 黑白双绞线 | **GPIO12** *(TDI)* |
   | **电机 1** | 右后方 (Rear Right) | 顺时针 (CW) | **A 桨** | 蓝红双绞线 | **GPIO13** *(TCK)* |
   | **电机 2** | 右前方 (Front Right) | 逆时针 (CCW) | **B 桨** | 黑白双绞线 | **GPIO14** *(TMS)* |
   | **电机 3** | 左前方 (Front Left) | 顺时针 (CW) | **A 桨** | 蓝红双绞线 | **GPIO15** *(TD0)* |

   > **注意**：顺时针电机为蓝红引线，匹配 A 桨（桨叶表面印有标示）；逆时针电机为黑白引线，匹配 B 桨。

4. **SBUS 遥控接收机（可选配置）**：
   * 连接至 ESP32 的 UART1/UART2 接收引脚：

   | 接收机引脚 | ESP32 引脚 |
   | - | - |
   | **GND** | **GND** |
   | **VIN** | **VCC** (或 3.3V，根据接收机工作电压选择) |
   | **Signal (TX)** | **GPIO4** |

5. **电池电压分压采集（可选配置）**：
   * 连接至任意 ADC1 引脚（例如 ESP32 的 *GPIO32*、ESP32-S3 的 *GPIO3*）。
   * 由于 ESP32/ESP32-S3 的 ADC 输入量程限制，请按照电池 4.2V 满电电压合理选择两枚分压电阻的阻值比例。

---

## 社区与外部资源

* [Telegram 官方开发频道](https://t.me/opensourcequadcopter)（俄语 / 英语）
* [Telegram 官方交流群](https://t.me/opensourcequadcopterchat)
* [Habr.com 深度开发专访长文](https://habr.com/ru/articles/814127/)（详细记录从零制作无人机的工程思考）

---

## 免责声明 (Disclaimer)

本项目属于开源创客 DIY 实验性工程。尽管我们在算法稳定性与软件设计上做了大量测试与完善，但组装与调参仍存在一定技术门槛，项目源码与软硬件资料均按“现状”（AS-IS）提供，不包含任何明示或暗示的保证。

⚠️ **安全警告**：高速旋转的螺旋桨具有一定危险性。作者与贡献者对因使用本项目造成的任何直接或间接财产损坏、人身伤害概不承担责任。飞行前请务必在安全、空旷或带防护网的环境下进行测试，佩戴防护眼镜并注意用电与防火安全！