🚁 Flix 飞控 · 耀坤整理版

从零实现的 ESP32 开源四轴飞控 —— 固件不足 2000 行 Arduino 代码，专为教学与研究而生

简体中文 · English

📌 本仓库是 okalachev/flix 的中文整理版 + 双板硬件适配版。
master 分支保持上游原样（仅调整目录位置，未改一行代码逻辑）。
yaokun-organized 分支在整理版基础上新增了硬件适配与中文界面：同一份源码支持两块 PCB —— 耀坤 S3 无人机（默认板型）与 微辣火龙果 2.0「ESP32 迷你无人机」（编译期 -DFLIX_BOARD=2 切换）。
上游项目与作者：Oleg Kalachev · 项目官网 quadcopter.dev

📌 这是什么

Flix 是一款专为教育和科研设计的开源四轴飞行器固件，运行在 ESP32 系列芯片上。

它的最大特色是极简：固件全部用 Arduino C/C++ 写成，不足 2000 行，
没有 RTOS、没有闭源库、没有黑盒算法 —— 传感器驱动、姿态解算、PID 控制、电机混控、
MAVLink 通信全部摊开在你面前，读完就能真正理解飞控是怎么工作的。

✨ 核心特性

特性	说明
极简源码	Arduino 编写，固件 < 2000 行，全部逻辑可读可改
通用元件	全部采用市面常见元件，无需定制打样即可组装
MAVLink 通信	通过 Wi-Fi 或 ESP-NOW 使用 MAVLink 协议，可用 QGroundControl 等地面站
多种操控方式	USB 手柄 / RC 遥控器 / 手机，Wi-Fi 与 ESP-NOW 双链路
无线命令行	无需连接电脑，直接用手机/电脑连上 Wi-Fi 就能下发命令、查看状态
Gazebo 仿真	仿真器跑的是同一份 Arduino 源码，改固件不用等烧板子
Python 库	提供 `pyflix` 库，可用脚本编排自动飞行
配套教材	飞控理论与实践的系统教材（持续编写中）
多芯片支持	ESP32 / ESP32-S3 / ESP32-C3 一份代码通吃，换板子只改 `BOARD`

🚁 真的能飞

实机演示视频：https://youtu.be/hT46CZ1CgC4

Version 0 演示视频：https://youtu.be/8GzzIQ3C6DQ

教育应用（RoboCamp 2025）：https://youtu.be/Wd3yaorjTx0

社区作品展：Docs/user.md

📁 目录结构（本整理版重新整理）

🔧 为什么要重整：上游仓库把固件、文档、工具脚本平铺在根目录，
目录里同时存在 .ino 源码、Python 脚本、mdBook 教材和 Gazebo 模型，容易看花。
本整理版按"用途"重新分层，固件相关的一律收进 Firmware/。
重要的是：Firmware/ 内部是一个完整可独立构建的工程，
所以在根目录执行 make 依然能直接编译，不需要改任何构建参数。

flix/                          # ← 仓库根：说明文档 + 转发用 Makefile
├── README.md                  # 本文件（中文）
├── README_EN.md               # 英文版说明
├── Makefile                   # 转发器：把根目录的 make 转发给 Firmware/Makefile
├── Firmware/                  # ★ 固件工程（可独立构建）
│   ├── Makefile               #   真正的构建脚本（编译 / 烧录 / 仿真）
│   ├── flix/                  #   Arduino sketch —— 飞控全部源码
│   │   ├── flix.ino           #     主入口：setup / loop
│   │   ├── config.h           #     引脚定义与飞行参数
│   │   ├── i18n.h             #     ★ 界面文案表（中英双语，169 条，唯一数据源）
│   │   ├── imu.ino            #     IMU 驱动、自动识别与校准
│   │   ├── estimate.ino       #     姿态解算
│   │   ├── control.ino        #     PID 控制与电机混控
│   │   ├── motors.ino         #     电机 / MOSFET 驱动
│   │   ├── rc.ino             #     遥控器输入
│   │   ├── mavlink.ino        #     MAVLink 协议
│   │   ├── wifi.ino           #     Wi-Fi 与 ESP-NOW 通信
│   │   ├── console.ino        #     无线命令行
│   │   ├── led.ino / power.ino / log.ino / safety.ino / time.ino / parameters.ino
│   │   └── pid.h / filter.h / quaternion.h / vector.h / util.h
│   ├── tools/                 #   ★ 发布打包脚本
│   │   ├── pack_flix_release.py   # 耀坤S3：合并四段 + 脱敏 + 重算校验字节与 SHA-256 + 生成中英说明
│   │   ├── gen_hlg_note.py        # 火龙果：只读整片 bin，现场生成中英说明（哈希/大小/编译时间现测）
│   │   ├── check_i18n.py          # 中英文案配对自检（含板型横幅块的双语分支）
│   │   └── md2html.py             # 台架清单 md → 自包含图文版 html（改完 md 重跑一次）
│   ├── release固件v1.1/        #   ★ 发布产物（双板整片 bin + 中英指纹与烧录说明 + 发布说明）
│   └── gazebo/                #   Gazebo 仿真器（跑同一份 .ino 源码）
│       ├── flix.world         #     仿真世界
│       ├── simulator.cpp      #     仿真主程序
│       └── models/            #     机架 / 场景模型
├── Docs/                      # ★ 文档与教材
│   ├── 耀坤S3适配说明.md       #   ★ 改动清单 / 根因分析 / 验证记录
│   ├── YaoKunS3_Adaptation_Notes_EN.md  #   同上，英文版（供海外复刻用户）
│   ├── flix技术说明书.html     #   ★ 图文版技术说明书（浏览器打开，排版精美）
│   ├── flix技术说明书.md       #   ★ 同内容 Markdown 版（GitHub 上可直接在线阅读）
│   ├── Flix_Technical_Manual_EN.html    #   同上，英文版（图文）
│   ├── Flix_Technical_Manual_EN.md      #   同上，英文版（Markdown）
│   ├── 耀坤S3版台架实测清单_v1.1.md  #   ★ S3 板接板后照着做（全程拆桨）
│   ├── 耀坤S3版台架实测清单_v1.1.html   #   同上图文版（浏览器直接打开 / 可打印）
│   ├── 火龙果版台架实测清单V1.1.md   #   ★ 微辣火龙果 2.0 板对应清单（烧录地址 / 引脚与 S3 不同，不能混用）
│   ├── 火龙果版台架实测清单V1.1.html    #   同上图文版
│   ├── Bench_Test_Checklist_EN.md       #   S3 清单英文版（另有同名 .html 图文版）
│   ├── MildlySpicyDragon_Bench_Test_Checklist_EN.md   # 火龙果清单英文版（另有同名 .html）
│   ├── assembly.md            #   组装说明
│   ├── usage.md               #   编译 / 调试 / 飞行
│   ├── firmware.md            #   固件架构总览（强烈推荐先读）
│   ├── troubleshooting.md     #   故障排查
│   ├── log.md                 #   日志分析
│   ├── user.md                #   社区作品展
│   └── book/                  #   mdBook 飞控教材
├── Tools/                     # ★ 工具脚本
│   ├── pyflix/                #   Python 飞控库
│   ├── espnow-proxy/          #   ESP-NOW 代理固件
│   ├── csv_to_ulog/           #   CSV → ULog 转换
│   └── log.py / fft.py / test.py ...
└── .github/workflows/         # CI：编译验证 + 文档构建 + 工具测试

整理前后对照：

原始路径	整理后路径	理由
`flix/`	`Firmware/flix/`	Arduino 固件源码
`gazebo/`	`Firmware/gazebo/`	仿真器跑同一份固件，属固件工程一部分
`Makefile`	`Firmware/Makefile`（+ 根目录转发器）	构建脚本跟固件走；根目录留转发器保兼容
`docs/`	`Docs/`	文档
`tools/`	`Tools/`	工具脚本

🛩️ 耀坤 S3 / 微辣火龙果 2.0 双板适配（`yaokun-organized` 分支）

⚠️ 只在 yaokun-organized 分支上生效。 master 始终跟随上游，不包含以下改动。

这一分支把 Flix 跑到了耀坤 S3 无人机上，并解决了"换用自研 ESP-NOW 遥控后飞机毫无反应"的问题；
自 v1.1 起，又通过编译期板型宏（Firmware/flix/board.h，一个板型 = 一组 PIN_* 宏）把同一套源码跑到了微辣火龙果 2.0「ESP32 迷你无人机」上 —— 一个代码库，两块 PCB，编出来是两份固件。
改动清单、根因分析与逐条验证记录见 Docs/耀坤S3适配说明.md。

🔴 为什么不自动认板：电机引脚在硬件上没有身份标识，运行时"猜"板型一旦猜错，上电瞬间四个电机就会按错误顺序起转。所以板型只由编译期宏决定，绝不运行时探测。

📘 技术说明书：中文 Markdown 版（GitHub 可直接阅读）· 中文图文版（浏览器打开，带封面与配色）· English Markdown · English illustrated

🌐 English docs (for overseas builders): YaoKunS3_Adaptation_Notes_EN.md · Flix_Technical_Manual_EN.md · Bench_Test_Checklist_EN.md

关键改动一览

编号	改动	为什么必须改
R1	时间基准改 64 位微秒累加器	上游 `t = micros()/1e6`，而 `micros()` 是 32 位 → 每 71.6 分钟回绕，`t` 倒退会让全工程 `t - last >= 周期` 的判据集体失效，表现为"上电 71.6 分钟后遥测全停、终端还在回显、reboot 就恢复"
R2	`COMMAND_LONG` 统一回 ACK	解锁被拒/模式非法时若不回 ACK，QGC 会一直卡在"正在执行"直到超时
R4	ESP-NOW 接收改用原生 `esp_now_register_recv_cb` + 字节队列	上游走 `ESPNOWSerial::read()` 的会话机制，只交出已登记 peer 的数据；而登记 peer 靠 4 字节 `flix` 发现包，上游还把它门控在 `isEncrypted()` 里 → 不加密就永远建不了会话，遥控器显示已连接但飞机不动。这是本次改造的核心
R5	电机引脚 15 / 5 / 6 / 16，PWM 20 kHz	耀坤 S3 实物布线；20 kHz 超出人耳范围，电机不尖叫
R6	电压检测 GPIO 2，分压系数 2	对应耀坤 S3 分压电阻实测值
R7	IMU 上电自动识别（I2C 的 MPU6050 / SPI 的 MPU-6500），朝向按总线分档	两块板子用的 IMU 不同，型号选错 `IMU::create()` 返回 `nullptr` → 上游会空指针崩溃。本版加了 `imuOK` 判据，IMU 不可用时禁止解锁并红灯长鸣告警
R8	三色灯（GPIO 41/7/14）+ 蜂鸣器（GPIO 39）灯语系统	现场不看串口也知道状态；连接判定改用 `controlTime` 而非 `mavlinkTime` —— 后者任何 MAVLink 帧都会刷新，会"没接遥控也显示已连接"
R9	全中文界面（`i18n.h` 集中管理，170 条文案）	help 菜单、IMU 校准、初始化提示、错误信息全中文
R10	参数表新增 `IMU_AUTO_DETECT` / `IMU_ROT_LOCK` / `LED_` / `BUZ_`	换 IMU、换板不必重编固件
R11	默认 ESP-NOW + 热点共存（`wifi both`）；热点名后缀改读 eFuse STA MAC	原版三种模式互斥，ESP-NOW 分支不开 UDP → 地面站连上热点也没应答；复刻用户开箱还得先跑命令。共存后遥控与 QGC 同时在线，`wifi both` 也成为可显式切换的模式
R12	热点密码三层校验：读取端清洗 NVS 脏值 + 写入端拒绝非法参数 + 出厂密码改码表构造	脏值事故：占位符 `<密码>` 的 UTF-8 恰 8 字节混过 `strlen>=8` 校验进了 NVS → 出厂密码被覆盖，怎么输都连不上。三层防线后此类脏值自动清除/拒绝

中文 / 英文双版本

界面文字全部集中在 Firmware/flix/i18n.h，默认中文：

// 编英文版：在 flix.ino 最顶部（第一条 #include 之前）加这一行
#define FLIX_LANG_EN

或者编译时传宏，不改任何文件：

arduino-cli compile --build-property "compiler.cpp.extra_flags=-DFLIX_LANG_EN" ...

两种版本的中英文案条数严格一致（170 : 170），有脚本可校验，不会出现"改了中文忘了英文"。

编译与烧录（耀坤 S3，默认板型）

cd Firmware
arduino-cli compile \
  --fqbn "esp32:esp32:esp32s3:FlashSize=8M,PartitionScheme=default_8MB" \
  --export-binaries flix

USB 走原生口（HWCDC）：另需 USBMode=hwcdc,CDCOnBoot=cdc；串口监视器打开时 DTR=1、RTS=0。 🔴 必须带 --export-binaries，否则 build/ 目录不会更新，打包脚本会拿旧固件拼出一个"看起来正常但内容错误"的 bin。

编译与烧录（微辣火龙果 2.0，编译期选板）

cd Firmware
arduino-cli compile \
  --fqbn "esp32:esp32:esp32:FlashSize=4M,PartitionScheme=default" \
  --build-property "compiler.cpp.extra_flags=-DFLIX_BOARD=2" \
  --export-binaries flix

🔴 -DFLIX_BOARD=2 不能省：省了就按耀坤 S3 的引脚编，烧到火龙果上电机顺序全错。芯片是 ESP32 经典片（不是 S3），Flash 4MB，default 分区表。

火龙果 2.0 引脚（21 脚，board.h 的 BOARD_HLG_V2 分支）

外设	引脚
电机 M1 右前 / M2 右后 / M3 左后 / M4 左前	GPIO 33 / 27 / 26 / 32
IMU（SPI，MPU6500）	SCK 18 / MOSI 23 / MISO 19 / CS 5
I2C 总线（MPU6050、MS5611 等）	SDA 21 / SCL 22
电池电压 ADC	GPIO 35（分压 100K+100K 或 10K+10K）
蜂鸣器 / 板载 LED	GPIO 25 / GPIO 2（单灯，状态用闪烁频率表达）
SBus 接收机	GPIO 4
光流（预留，PMW3901）	MOS 13 / CLK 14 / MIS 12 / CS 15
激光测距（预留，VL53L1X，I2C1）	SCL 16 / SDA 17

⚠️ MPU6500 与 MPU6050 不会同时插在排母上，固件按总线自动识别。 ⚠️ 单独烧 bootloader 时地址是 0x1000（ESP32 经典片规则），不是 S3 的 0x0；整片烧 0x0 即可。

打包发布件

# 耀坤 S3（合并四段 + 脱敏 + 重算校验字节与 SHA-256 + 生成中英说明）
python Firmware/tools/pack_flix_release.py --version 1.1 --date-tag 20261106

# 火龙果 2.0（只读整片 bin，现场生成中英说明）
python Firmware/tools/gen_hlg_note.py --bin "release固件v1.1/xxx_整片4MB.bin" --version 1.1 --date-tag 20261106

产物在 release固件v1.1/：*_merged.bin / *_整片*.bin（烧 0x0）+ 中英双语《指纹与烧录说明》。
🔴 打包前务必确认 build/ 就是本次编译产物 —— 拿旧构建目录打包会生成"版本号对、内容却是旧固件"的错件（v1.1 发布时就踩过）。

控制台命令（中文版实际显示）

连上串口（115200，原生 USB 口）敲 help：

可用命令：

help - 显示本帮助
p - 显示全部参数
p <前缀> - 显示以该前缀开头的参数
p <参数名> <数值> - 修改参数（自动存盘）
preset - 恢复出厂参数（会重启）
time - 显示时间与主循环频率
imu - 显示惯性测量单元数据
ca - 校准加速度计（六面校准）
st - 显示姿态估计结果
arm / disarm - 解锁 / 上锁
raw/stab/acro/auto - 切换飞行模式
rc - 显示遥控（ESP-NOW）数据
cr - 校准遥控行程
pw - 显示电源与电压
wifi - 显示无线连接信息
wifi ap/sta/espnow/both/off - 设置无线模式
ap <热点名> <密码> - 设置飞机热点（⚠️ 尖括号只是占位符，要换成真实值，别照抄）
sta <路由名> <密码> - 连接家里的路由器（同上）
espnow <遥控器MAC> [<密钥>] - 设置 ESP-NOW 对端
ch [<信道>] - 查看或设置 ESP-NOW 信道
mot - 显示四路电机输出
log [dump] - 打印日志表头 [以及数据]
mfr/mfl/mrr/mrl [<油门>] - 单独测试电机（务必拆桨！）
sys - 显示系统信息
reset - 复位姿态估计
reboot - 重启飞机

📌 如果只看到品牌横幅、看不到上面这份命令表：那是旧版（v1.0 早期）构建的截断问题（HWCDC 发送缓冲默认仅 256 B，1.7 KB 的菜单一次写出会被静默丢弃）。已修复：setupConsole() 把 TX 缓冲扩到 4 KB + 命令收尾补推一次。请按《指纹与烧录说明》核对固件 SHA-256 后重新烧录。

无线模式：默认 ESP-NOW + 热点共存

出厂默认就是 遥控（ESP-NOW）与手机/地面站（Wi-Fi 热点 + UDP）同时在线，开箱即用，不需要先跑任何串口命令。

命令	热点	ESP-NOW 遥控	UDP 地面站	典型用途
`wifi both`（默认）	✅	✅	✅ 14550	正常飞行：遥控 + QGC / 手机同时在线
`wifi espnow`	✅（不启 UDP）	✅	❌	排查空口干扰，二分定位是哪条链路的问题
`wifi ap`	✅	❌	✅ 14550	只调参、不飞
`wifi sta`	❌（改连路由器）	❌	✅	接家里的路由器
`wifi off`	❌	❌	❌	完全关闭射频

为什么能共存：ESP-NOW 本来就挂在 Wi-Fi 的 AP 接口上跑，两者共用同一个射频 —— WiFi.mode(WIFI_AP) 一调用，热点其实早就在广播了。差别只在"UDP 有没有监听、遥测发不发得出去"。

两个必须知道的约束：

热点信道 = ESP-NOW 信道（默认 1，ch 命令查看）。两者共用射频，信道不一致就是物理层直接失联，且没有任何报错。

千万别在 QGC 里开虚拟摇杆。MANUAL_CONTROL 不校验来源，QGC 的虚拟摇杆会和实体遥控抢控制权，表现为"遥控打杆没反应"或"杆量乱跳"。

从 v1.0 升级的提示：老板子 NVS 里存着旧值 WIFI_MODE=3（纯 ESP-NOW），只改固件默认值是无效的。本版内置一次性迁移，首次开机会自动升到共存并打印一行 无线模式已升级为 ESP-NOW + 热点（共存）；此后你手动切到 espnow 不会被改回来（迁移只做一次）。

ESP-NOW 遥控的四个必查项

飞机端和遥控器端必须满足以下四点，否则现象一律是"遥控器显示已连接、飞机毫无反应"：

信道一致 —— 飞机端 ch 命令查看，默认 1。耀坤中文版遥控（ESP32-DJI-Dev-Yaokun20260815）不调用 esp_wifi_set_channel，走 Wi-Fi 默认信道 1，所以飞机端也取 1。

⚠️ 早期版本按英文版遥控的 esp_wifi_set_channel(6) 把默认值定成 6，结果飞机听 6、遥控发 1，物理层彻底错开。这个故障极具迷惑性：遥控器"对端发现"页仍能列出飞机（扫描是跨信道的），"能看到"≠"能通"。
飞机已登记遥控器为 ESP-NOW peer —— ESP-NOW 的接收回调只对已登记在 peer 表里的 MAC 触发，未登记的包在驱动层就被丢弃。中文版遥控 connect(mac) 后走单播，所以必须登记。本版已实现：开机预登记广播地址 + onReceive 记录来源 MAC + 主循环 learnPeerIfNeeded() 自动学习（回调里不能直接 esp_now_add_peer，会取 Wi-Fi 锁死锁）。
遥控器已使能 —— 中文版遥控的 enabled 默认是 false，此时 MANUAL_CONTROL 照发不误，但四轴数值全是中位（≈0.01）。使能方法 = 按遥控器的「左按钮（辅助按钮）」，界面上没有这个开关，是纯物理按键。

⚠️ 飞机每次重启，都要重新走一遍：对端发现 → 点选飞机 → 按左按钮使能。
接收链路已注册 —— 开机日志出现 ESP-NOW 原生接收已启用；wifi 命令里 接收丢包 与 队列字节 两项可判断是"发不出去"还是"收不过来"。

用 wifi 命令按这个顺序排查：

现象	结论
`接收包数` = 0	物理层不通 → 查信道（第 1 项）
包数涨，`已解析 MAVLink 帧数` = 0	协议不匹配
帧数涨，`最近一帧消息 ID` ≠ 69	遥控没发 `MANUAL_CONTROL`
msgid = 69，但 `rc` 四轴全 0.01	遥控器未使能 → 按左按钮（第 3 项）
全对，四轴跟摇杆动	✅ 链路正常

⚠️ 家庭路由器与飞机热点同信道时会互相干扰，表现为手机连上就掉、界面假死。
用 ch <1-13> 改飞机端，但遥控器端必须同步改，否则物理层直接收不到。

飞行能力边界（务必先读）

本固件是纯姿态自稳 + 手动油门，没有任何位置/速度传感器（无 GPS / 气压计 / 测距 / 光流）：

松杆不会悬停 —— 姿态会稳平，但会保持水平速度继续飘。
松油门就掉高度 —— 没有定高环。
四源全静默会被判失联 —— 遥控、地面站全断 1 秒后自动降油门，10 秒归零并上锁。

首次试飞请在空旷场地、低空、装保护圈的前提下进行。

🚀 快速开始

1. 编译固件

需要先安装 arduino-cli。

git clone https://github.com/YaoKunS/flix.git
cd flix
git checkout yaokun-organized   # ★ 切到耀坤整理版分支（默认 master 是上游原版结构）

# 首次运行会自动下载 ESP32 core 3.3.10 与依赖库（FlixPeriph / MAVLink）
make                                    # 默认编译 ESP32
make BOARD=esp32:esp32:esp32s3          # 编译 ESP32-S3
make BOARD=esp32:esp32:esp32c3          # 编译 ESP32-C3

💡 make 在根目录可用 —— 根目录的 Makefile 会自动转发到 Firmware/。
也可以 cd Firmware && make，效果完全一样。

🔴 本整理版有两块目标板，编译参数不同：耀坤 S3 用 esp32:esp32:esp32s3:FlashSize=8M,PartitionScheme=default_8MB；微辣火龙果 2.0 用 esp32:esp32:esp32:FlashSize=4M,PartitionScheme=default 并必须加 -DFLIX_BOARD=2 （详见上文《编译与烧录（微辣火龙果 2.0，编译期选板）》，用错板型电机顺序会全错）。

2. 烧录与调试

make upload                 # 编译并烧录
make monitor                # 打开串口监视器（115200）
make erase                  # 擦除 bootloader

3. 运行 Gazebo 仿真

不想买硬件也能先玩起来（需要 Gazebo 11）：

make build_simulator
make simulator

4. 无线遥控

编译烧录 ESP-NOW 代理固件：

make upload_proxy

连上飞机的 Wi-Fi（AP 名称见串口日志），即可用浏览器或地面站操控。

飞机热点名规则（耀坤版）

项	规则
前缀	`YaoKun_`（品牌统一，注意大小写：`Y`、`K` 大写）
后缀	芯片出厂 STA MAC 末两字节（4 位十六进制，大写），每块板子自动不同
默认密码	`1-2-3-4-5-6-7-8` 连字符只是分隔符，输入时不要带，实际就是 8 个字符：逐位读作一、二、三、四、五、六、七、八 ⚠️ 文档只写这种带连字符的形式 —— 连续数字串在传输/渲染通道会被改写（本工程实测多次，v1.0 文档曾因此写错密码）。源码以 ASCII 码表 `{49,50,51,52,53,54,55,56,0}` 构造
实际值怎么看	开机日志里有一行 `当前热点名：YaoKun_xxxx`，以它为准
想改名	`ap 新热点名出厂密码` 然后 `reboot`；尖括号是占位符，不要照抄；改名后前缀不再自动生成
误填占位符	名字含 `<` `>` 或超过 32 字符 → 判为脏值，自动清除并恢复 `YaoKun_xxxx` 自动命名
密码写脏了	密码不在 8~63 位可打印 ASCII 内（含中文、尖括号、过短过长）→ 判为脏值，自动清除并回退出厂默认，开机日志会打印一行提示
密码校验	`ap` / `sta` 写入前先校验，非法直接拒绝并说明原因，不会再让脏值进 NVS

✅ 热点名后缀 = wifi 命令里那串 MAC 的末两字节，两者必然一致，可以直接对照： 1 号机 MAC 80:65:99:DF:F2:24 → 热点名 YaoKun_F224； 2 号机 MAC 3C:84:27:C7:DE:38 → YaoKun_DE38。

🔑 出厂密码逐位对照（照着下表逐位按键即可；每位单独成格，中英文读者都能拼出，文档里不会出现整串）：

位次第 1 位第 2 位第 3 位第 4 位第 5 位第 6 位第 7 位第 8 位

该位字符 1 2 3 4 5 6 7 8

手机/电脑输入时按这张表一位一位敲，共 8 位，中间不要加空格或符号。

📌 实现细节（v1.1 修正）：旧版用 WiFi.macAddress()，在 AP / ESP-NOW 上下文里返回的是 AP 接口 MAC（1 号机末两字节 = 62:02，于是热点名成了 YaoKun_6202），与 wifi 命令显示的对不上。现改为 esp_read_mac(ESP_MAC_WIFI_STA) 直接读芯片 eFuse，任何 Wi-Fi 模式下都返回同一个出厂值。代码里没有任何硬编码后缀，同一份固件通吃所有板子。

📌 ESP-NOW 模式下也会广播这个热点（ESP-NOW 只能跑在 AP/STA 接口上， WiFi.mode(WIFI_AP) 一起就会起热点）。旧版这里用的是 core 默认名 ESP_xxxxxx，现场分不清是谁家的机器，现已统一成 YaoKun_ 前缀。

🔴 2026-11-05 事故复盘：热点密码被占位符覆盖，用户怎么输都连不上

现象：手机连飞机热点，输出厂密码始终提示"密码错误"；而固件里的默认密码明明是对的，代码怎么看都没问题。

根因：早年有人照本文档照抄了 ap <热点名> <密码>。<密码> 这四个字符的 UTF-8 是 60,229,175,134,231,160,129,62 —— 恰好 8 字节，刚好通过当时唯一的 strlen(second) >= 8 校验，于是被当成真密码写进 NVS（并被驱动写进 net80211 的 ap.passwd）。此后每次开机，NVS 里的这个值都会覆盖编译期的出厂默认值 —— 改代码、重烧固件都不会好（整片写清 NVS 才行）。NVS 原始字节实证： 0x024E8 处 ap.passwd = [60,229,175,134,231,160,129,62]。

修法（三层）：

读取端：setupWiFi() 用 isUsableWifiPass() 校验 NVS 密码，不可用就删掉该项并回退出厂默认，同时打印一行"已恢复出厂默认"，现场从开机日志就能看出问题被清洗过；

写入端：ap / sta 命令写入前同样校验，非法直接拒绝并说明原因；

源码层：出厂密码改为 ASCII 码表构造（{49,50,…,56,0}），源码里不出现那串数字，避免文本链路改动，也方便逐字节核对。

自查口诀：p WIFI 看不到密码（故意不回显）；判断密码是否正常，看开机日志有没有 "NVS 里的热点密码不可用…已恢复出厂默认"这一行。

🔌 硬件清单

Type	Part	Image	Quantity
主控板	ESP32 Mini 也支持 ESP32-S3 / ESP32-C3		1
主控板（微辣火龙果 2.0）	ESP32 DevKit V1（30 针）微辣火龙果 2.0 PCB，立创开源硬件	—	1
IMU¹	GY-91、MPU-9265（或其它 MPU-9250 / MPU-6500） ICM20948V2 GY-521（MPU-6050）		1
升压模块（可选，供电更稳）	5V 输出		1
电机	8520 3.7V 有刷电机必须是标称 3.7V，不能是工作电压区间（3.7V–6V）确认电机轴径与桨孔径匹配！		4
桨叶	55 mm 或 65 mm		4
MOSFET	UMW 100N03A 或类似型号 ⚠️ 不要用 KIA 100N03A 等杂牌，可能不工作！		4
下拉电阻电压采样电阻	10 kΩ		6
3.7V 锂电池	LW 952540（或同尺寸兼容型号）建议 25C 1000 mAh 以上！		1
电池线	MX2.0 2P 母座		1
锂电池充电器	任意		1
IMU 板固定螺钉	M3x5		2
机架装配螺钉	M1.4x5		4
机架主体	3D 打印²：`stl` `step` 推荐参数：层高 0.2 mm，线宽 0.4 mm，填充 100%。		1
机架上盖	3D 打印：`stl` `step`		1
IMU 板垫片	3D 打印：`stl` `step`		2
遥控器（推荐）	CC2500 发射器，如 BetaFPV LiteRadio CC2500（RC 接收 + Wi-Fi）双摇杆手柄（仅 Wi-Fi）——见推荐手柄列表其它⁵		1
RC 接收机（可选）	DF500 或其它³		1
导线	推荐 28 AWG
胶带、双面胶

¹ — 目前气压计未使用。

² — 此机架为 GY-91 板优化，换其它板需修改固定孔位。

³ — 也可用任何 SBUS 接口的发射机 / 接收机组合。

组装所需工具：3D 打印机、烙铁、助焊焊锡、螺丝刀、万用表。

欢迎自由修改设计与代码，做出你自己的改进版本。
成果可发到官方 Telegram 群，
或直接联系作者（E-mail · Telegram）。

🔧 接线图

简化连接图

（虚线框内为可选元件。）

电机连接方案：

社区贡献的完整电路图变体。

接线要点

用锂电池的 VCC（+）与 GND（−）给 ESP32 Mini 供电。
IMU 板通过 VSPI 接入 ESP32 Mini，供电用 3.3V 与 GND：

IMU 引脚 ESP32 引脚

GND GND

3.3V 3.3V

SCL (SCK) SVP (GPIO18)

SDA (MOSI) GPIO23

SAO (MISO) GPIO19

NCS GPIO5
MOSFET 必须焊接下拉电阻。

电机经 MOSFET 接 ESP32 Mini：

电机	位置	转向	桨型	电机线	GPIO
Motor 0	左后	逆时针	B	黑 & 白	GPIO12 (TDI)
Motor 1	右后	顺时针	A	蓝 & 红	GPIO13 (TCK)
Motor 2	右前	逆时针	B	黑 & 白	GPIO14 (TMS)
Motor 3	左前	顺时针	A	蓝 & 红	GPIO15 (TD0)
顺时针电机配蓝红线，对应 A 型桨（桨上有标记）；逆时针电机配黑白线，对应 B 型桨。

RC 接收机可选接入 ESP32 的 UART2：

接收机引脚 ESP32 引脚

GND GND

VIN VCC（按接收机而定，也可用 3.3V）

Signal (TX) GPIO4
电池电压分压采样可选接入任意 ADC1 引脚（如 ESP32 的 GPIO32、ESP32-S3 的 GPIO3）。

ESP32 与 ESP32-S3 最多可测 3.1 V，
ESP32-S3 / ESP32-C3 最多 2.5 V，请据此选择分压电阻。

📚 推荐阅读顺序

刚接触飞控的话，按这个顺序读，半天就能搞懂原理：

固件架构总览 —— 数据怎么流动、控制怎么闭环
组装说明 —— 把机器装起来
使用手册 —— 编译、调试、飞行
飞控教材 —— 姿态解算、坐标系、陀螺仪原理
故障排查 —— 起飞异常时先看这里
日志分析 —— 用 PlotJuggler 分析飞行数据

更多：

🔌 社区资源

开发频道（俄语）：https://t.me/opensourcequadcopter
官方 Telegram 群（英/俄）：https://t.me/opensourcequadcopterchat
开发历程长文（俄语）：https://habr.com/ru/articles/814127/
飞控教材网站：https://quadcopter.dev

📜 开源协议与致谢

本整理版：仅做中文文档与目录整理，未修改固件逻辑，固件版权归原作者所有。
本仓库整理：耀坤智联 YaoKunSmart · https://github.com/YaoKunS
B 站：https://space.bilibili.com/3707011699050767

⚠️ 关于许可证的重要说明：

上游 okalachev/flix 仓库目前未附带任何 LICENSE 文件，
也未在 README 中声明具体开源许可证名称。这意味着严格来说，
版权默认保留给原作者（著作权法默认「未授权」）。
因此本整理版不擅自添加 LICENSE 文件，也不会替作者选择许可协议 ——
这属于原作者的决定。
本仓库仅作学习研究与技术交流用途；如需商业使用或再分发，
请先联系原作者取得明确授权，并遵守所在地法律法规。

⚠️ 使用、修改、分发本项目时，请保留上游作者署名与项目出处。

⚠️ 免责声明

这是一个 DIY（自己动手）项目，希望你觉得它有趣且有用。
但它并不容易组装和调试，且按"现状"提供，不附带任何担保 ——
不保证它能完美工作，甚至不保证它能工作。

⚠️ 作者不对使用本项目造成的任何损坏、伤害或损失负责。风险自负！
飞行时请务必在空旷场地试飞，并遵守当地无人机法规。

🚁 Flix · 由 Oleg Kalachev 倾力打造
· 本中文整理版由耀坤智联维护

Name		Name	Last commit message	Last commit date
.vscode		.vscode
Docs		Docs
Firmware		Firmware
Tools		Tools
release固件v1.0		release固件v1.0
release固件v1.1		release固件v1.1
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
Makefile		Makefile
README.md		README.md
README_EN.md		README_EN.md

Navigation Menu

Repository navigation

About

Repository files navigation

🚁 Flix 飞控 · 耀坤整理版

📌 这是什么

✨ 核心特性

🚁 真的能飞

📁 目录结构（本整理版重新整理）

🛩️ 耀坤 S3 / 微辣火龙果 2.0 双板适配（`yaokun-organized` 分支）

关键改动一览

中文 / 英文双版本

编译与烧录（耀坤 S3，默认板型）

编译与烧录（微辣火龙果 2.0，编译期选板）

打包发布件

控制台命令（中文版实际显示）

无线模式：默认 ESP-NOW + 热点共存

ESP-NOW 遥控的四个必查项

飞行能力边界（务必先读）

🚀 快速开始

1. 编译固件

2. 烧录与调试

3. 运行 Gazebo 仿真

4. 无线遥控

飞机热点名规则（耀坤版）

🔌 硬件清单

🔧 接线图

简化连接图

接线要点

📚 推荐阅读顺序

🔌 社区资源

📜 开源协议与致谢

⚠️ 免责声明

About

Releases

Packages

Contributors

Languages

IMU 引脚	ESP32 引脚
GND	GND
3.3V	3.3V
SCL (SCK)	SVP (GPIO18)
SDA (MOSI)	GPIO23
SAO (MISO)	GPIO19
NCS	GPIO5

接收机引脚	ESP32 引脚
GND	GND
VIN	VCC（按接收机而定，也可用 3.3V）
Signal (TX)	GPIO4

Latest commit

History

Folders and files

Repository files navigation

🚁 Flix 飞控 · 耀坤整理版

📌 这是什么

✨ 核心特性

🚁 真的能飞

📁 目录结构（本整理版重新整理）

🛩️ 耀坤 S3 / 微辣火龙果 2.0 双板适配（yaokun-organized 分支）

关键改动一览

中文 / 英文双版本

编译与烧录（耀坤 S3，默认板型）

编译与烧录（微辣火龙果 2.0，编译期选板）

打包发布件

控制台命令（中文版实际显示）

无线模式：默认 ESP-NOW + 热点共存

ESP-NOW 遥控的四个必查项

飞行能力边界（务必先读）

🚀 快速开始

1. 编译固件

2. 烧录与调试

3. 运行 Gazebo 仿真

4. 无线遥控

飞机热点名规则（耀坤版）

🔌 硬件清单

🔧 接线图

简化连接图

接线要点

📚 推荐阅读顺序

🔌 社区资源

📜 开源协议与致谢

⚠️ 免责声明

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

🛩️ 耀坤 S3 / 微辣火龙果 2.0 双板适配（`yaokun-organized` 分支）