ESP-Drone 完整上手指南：用 ESP32-S2 做一架手机可控的四旋翼

ESP-Drone 完整上手指南：用 ESP32-S2 做一架手机可控的四旋翼

【免费下载链接】esp-droneMini Drone/Quadcopter Firmware for ESP32 and ESP32-S Series SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-drone

你有没有想过，一台 ESP32-S2 模组、一颗 MPU6050、4 个 716 小电机，就能飞起来一架姿态可控的四旋翼？乐鑫官方的ESP-Drone方案就是为这个目标做的：它是一套跑在 ESP32 / ESP32-S2 / ESP32-S3 上的无人机飞控固件，通过 Wi-Fi 接收手机 APP 或游戏手柄发来的飞行指令，飞控内核移植自 Bitcraze 的 Crazyflie 开源工程（GPL3.0 协议），从传感器驱动到 PID 闭环全部可读可改。

一图看懂 ESP-Drone

一句话定义：ESP-Drone = Crazyflie 飞控内核 + ESP-IDF 平台 + Wi-Fi 无线链路，外加一套完全公开原理图和 PCB 的硬件。

硬件是"主板 + 扩展板"的模块化结构：主板（ESP32-S2-WROVER + MPU6050）负责基础飞行，扩展板按需插上——PMW3901 光流 + VL53L1X 激光测距实现室内定点，MS5611 气压计实现定高，HMC5883L 罗盘实现无头模式。软件侧则是一整套 FreeRTOS 多任务飞控，配合 CRTP 通信协议，让你能在 PC 端（cfclient）实时看姿态、调参数。

为什么选它：对比商业无人机和 Crazyflie 本体

和成品无人机比，核心差别在"黑盒 vs 白盒"：

• 大疆等消费级无人机的飞控算法、协议、固件全部封闭，你最多通过官方 SDK 做有限应用；ESP-Drone 的每个电机 PWM 值从哪来、哪个任务算的、优先级多少，都能在 components/core/crazyflie/ 里逐行看到。
• 硬件同样全开：主板原理图、PCB、BOM 都在 hardware/ESP32_S2_Drone_V1_2/ 目录里，Gerber 文件可直接投板打样，不用买整机。

和 Crazyflie 本体比，ESP-Drone 换掉了两颗"贵部件"：

代价是通信链路从专用射频换成 Wi-Fi，延迟和稳定性依赖你的 Wi-Fi 环境，文档里也给了把 Wi-Fi 发射功率调到 20dBm 来提升距离的配置项（Component config >> PHY >> Max WiFi TX power）。

核心能力拆解：硬件层、软件层、交互层

硬件层：主板负责飞，扩展板负责"看得更准"

主板上的关键配置，对照 docs/zh_CN/rst/hardware.rst 可以快速验证：

• 主控：ESP32-S2-WROVER，Wi-Fi 走 AP 模式，无人机本身就是个热点；
• 姿态传感器：MPU6050 接 I2C0（SDA=GPIO11, SCL=GPIO10），DMP 数据就绪时拉 GPIO12 中断，飞控主循环靠它节拍驱动；
• 电机：4 个 716 无刷……不，是 716 有刷电机，PWM 接 GPIO5/6/3/4，换 720 电机要在menuconfig里把 motor type 改成brushed 720 motor；
• 电量监测：VBAT 分压后进 GPIO2（ADC_7_BAT）；
• 扩展口：SPI + I2C + GPIO 一排排针，扩展板插上去自动识别（extend board version默认auto detect）。

对你意味着什么：不装扩展板，它是一架"自稳模式"玩具；装上定点模块后，同一套代码立刻解锁悬停——扩展板不是换固件，而是换传感器来源。

软件层：一个 FreeRTOS 任务表撑起整架飞机

固件入口在 main/main.c 的app_main()，只做三件事：初始化 NVS（Wi-Fi 存储用）、platformInit()、systemLaunch()。真正干活的是十几个 FreeRTOS 任务，其中优先级最高的是STABILIZER_TASK，它把"传感器读取 → 姿态估计 → 目标点处理 → PID 输出电机功率"串成一条闭环。其他关键任务：

• SENSORS_TASK：读传感器并预处理，陀螺仪上电后用 1024 组环形缓冲算方差和均值做校准，加速度计再取 200 组样本实测当地重力加速度；
• KALMAN_TASK：状态估计。互补滤波和卡尔曼滤波两套都实现了，注意定点模式下必须切到卡尔曼滤波；
• PARAM / LOG / MEM：通过 CRTP 协议实现远程改参数、看波形、读写存储——这就是 cfclient 调试功能的底层；
• WIFILINK / UDP-TX / UDP-RX：把 CRTP 包和 UDP 包互转，UDP 端口是 2390。

控制器层面继承了 Crazyflie 全部三套实现（PID、Mellinger、INDI），在controllerPid等函数的注册表里切换。官方只对 PID 做过参数整定，另外两套属于"代码在、参数要你自己调"的状态。

交互层：CRTP 协议 + Wi-Fi，三种遥控方式

通信栈自下而上是：Wi-Fi AP（SSID 为ESP-DRONE_XXXX，XXXX 来自 MAC 尾号）→ UDP → CRTP。CRTP 包固定 32 字节：1 字节 Header（4 位端口 + 2 位通道 + 2 位保留）+ 31 字节 Payload + 1 字节和校验，无状态设计、无需握手。端口分工清晰：2 号读参数、3 号发控制指令（roll/pitch/yaw/thrust）、5 号发日志、13 号平台控制（调试、断电）。

三种控制入口你都可以用：

1. 手机 APP（Android/iOS，源码开源）：虚拟摇杆 + 飞行模式开关，最省心；
2. cfclient 上位机：Python 写的 PC 客户端，姿态驾驶仪、PID 在线整定、实时波形全都有，调试首选；
3. 游戏手柄：ESP-BOX3 手柄走 ESP-NOW，或普通手柄经 cfclient 绑定 4 个轴（Roll/Pitch/Yaw/Thrust）+ 1 个模式切换键。

快速上手：从 clone 代码到第一次起飞的最短路径

第 0 步：硬件装起来

基础配置：主板 ×1、716 电机 ×4、46mm A/B 桨各 2、300mAh 1S 锂电池 ×1、充电板 ×1、排针 ×2。桨要分 A/B 正反装，上电自检时电机转动方向要和桨标一致。

第 1 步：装 ESP-IDF（认准分支）

用release/v5.0分支的 ESP-IDF，装完先编译一个官方 example 验证工具链完整性。这是文档反复强调的前置条件，版本不对后面全是坑。

第 2 步：clone 并编译烧录

git clone https://gitcode.com/GitHub_Trending/es/esp-drone cd esp-drone idf.py set-target esp32s2 idf.py build idf.py -p /dev/ttyUSB0 flash monitor

set-target会自动把硬件版本选成ESP32_S2_DRONE_V1_2；想编译 ESP32 版本（ESPlane-FC-V1 老硬件）就set-target esp32，老硬件还需要把模组 GPIO14 飞线到 MPU6050 的 INT 脚。

第 3 步：APP 连接并起飞

1. 飞机上电，绿灯快闪说明系统就绪，红灯亮代表电量低，别飞；
2. 手机 Wi-Fi 扫描，连ESP-DRONE_XXXX，密码12345678；
3. APP 点Connect，飞机绿灯闪烁表示链路建立；
4. 先在地面轻推油门确认电机响应，再轻推方向杆确认偏航方向对，然后起飞。

默认参数（Mode2、Deadzone 0.2、max roll/pitch 15°、max thrust 90、min thrust 25）对新手足够安全，不需要先动高级设置。

二次开发方向：官方留了这些口子给你

方向一：PID 在线整定 + 自定义控制器

cfclient 的 param 功能可以在线改 PID 参数、实时生效、不用重新烧录（掉电不保存，定稿后记得改回源码）。整定方法文档写得很细：先 Rate 模式把 KI/KD 清零单调 KP，固定住机身只让它前后翻，加到临界振荡再退 5~10 个点；然后 KI 取 KP 的 50% 起步往上加；最后才进 Attitude 层。

想换算法的话，控制器注册表就长这样：

static ControllerFcns controllerFunctions[] = { {.init = controllerPidInit, .update = controllerPid, .name = "PID"}, {.init = controllerMellingerInit, .update = controllerMellinger, .name = "Mellinger"}, {.init = controllerINDIInit, .update = controllerINDI, .name = "INDI"}, };

照着init/test/update/name四件套实现你自己的控制器注册进去即可。注意 Mellinger、INDI 没有现成参数，整定过程有风险，先在低空、有网保护的环境下做。

方向二：换传感器、加扩展板

传感器接入走的是函数指针结构体sensorsImplementation_t（init / test / acquire / readGyro / readAcc / readMag / readBaro……），实现一套赋值进注册表就能整体替换。驱动文件按总线分目录放在 components/drivers/：i2c_devices/（mpu6050、ms5611、hmc5883l、vl53l0x、vl53l1x）、spi_devices/（pmw3901）、deck/（扩展板总线驱动）。加一个新 I2C 传感器的最短路径：仿照i2c_devices/ms5611/写一个子目录 + CMakeLists，再挂进sensors.c的抽象层。

方向三：基于 CRTP 做自己的上位机

CRTP 是 32 字节定长包 + 和校验，Python 侧有现成的 cflib 分支可参考。你想做个网页遥控器、把姿态数据推到 Grafana、或者批量控多机，都可以在 UDP 2390 端口上自己封包，固件侧的端口注册机制是现成的。

适合谁，以及哪些坑先说在前面

适合你，如果你：想逐行读懂一个完整的飞控闭环（传感器→滤波→估计→PID→电机）；做 STEAM/课堂教学，需要一套"拆得开"的样机；或者想在 ESP32 上玩姿态估计、控制器算法的移植对比。

不适合你，如果你：要消费级飞行体验（续航、图传、抗风都不是它的目标）、或需要官方长期质保——乐鑫从 2022 年 12 月起对该项目仅提供有限支持，维护靠社区 PR。

几个高频坑：

• ESP32-S2 上 KALMAN_TASK 优先级不能调高，单核芯片算卡尔曼吃 CPU，调高会触发 task watchdog。任务优先级在 components/config/include/config.h 里改，S2 建议 1，ESP32（双核）可以 2；
• 定高/定点模式没有扩展板就开不了，别以为刷个固件就能悬停；
• 换 Mellinger/INDI 控制器 = 从零整定参数，第一次飞务必有人兜着；
• 300mAh 1S 电池满电也就几分钟续航，演示前先算好电量；
• 上电校准需要"机身完全静止放平"，陀螺仪校准期间别碰它，否则基准值直接算偏。

写在最后

ESP-Drone 给的不是一架"能飞的无人机"，而是一份麻雀虽小五脏俱全的飞控全栈教材：主板飞起来只需要 10 行左右的app_main()，但往下追一层，就是完整的 Crazyflie 任务体系。

下一步动作很具体：clone 下来，set-target esp32s2编译烧录，起飞之前先打开 docs/zh_CN/ 里的飞控系统一章，再顺着 components/core/crazyflie/modules/src/stabilizer.c 把 STABILIZER_TASK 从 setpoint 读到电机输出这一圈走一遍——读完这一圈，你就真正上手了。

【免费下载链接】esp-droneMini Drone/Quadcopter Firmware for ESP32 and ESP32-S Series SoCs.项目地址: https://gitcode.com/GitHub_Trending/es/esp-drone