企业官网建设流程全解析

ESP-Drone 快速入门实战指南：硬件组装、Wi-Fi 连接控制与 cfclient 飞控调试全流程

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

本指南基于 ESP-Drone（基于乐鑫 ESP32/ESP32-S2/ESP32-S3 的迷你无人机开源飞控方案）官方 Getting Started 文档撰写，完整覆盖从认识硬件体系、搭建开发与调试环境，到使用手机 APP 与 PC 端 cfclient 完成连接、飞行控制、在线调参与数据监控的完整链路。读完本文，你将掌握 ESP-Drone 的模块化硬件组成、Wi-Fi 直连控制机制、飞控参数语义，以及一套可以直接照着做的起飞前检查流程。

ESP-Drone 是什么

ESP-Drone 是乐鑫（Espressif）推出的基于 ESP32/ESP32-S2/ESP32-S3 芯片的飞行开发板方案。它最大的特点是以 Wi-Fi 为核心通信能力：手机 APP 或游戏手柄可以通过 Wi-Fi 网络直接连接并控制无人机，无需额外的遥控器射频模块。整个方案硬件结构简单、代码架构清晰、支持功能扩展，非常适合 STEAM 教育、无人机入门教学和二次开发场景。

需要特别说明的是，ESP-Drone 的部分代码移植自开源项目 Crazyflie，并继承其 GPL3.0 开源协议（详见 README.md 中 Third Party Copyrighted Code 一节的说明，其中注明core/crazyflie移植自 Crazyflie 2021.01 版本，对应 commit b448553）。

核心特性

• 自稳定模式（Stabilize mode）：自动控制机身水平，保持平稳飞行。
• 定高模式（Height-hold mode）：自动控制油门输出，使无人机保持在固定高度飞行。
• 定点模式（Position-hold mode）：自动控制机身角度，使无人机保持在固定空间位置。
• PC 上位机调试：使用 cfclient 进行静态/动态调试。
• APP 控制：通过手机 APP 经 Wi-Fi 轻松控制。
• 游戏手柄控制：通过 cfclient 使用游戏手柄控制。

其中，定高模式与定点模式需要依赖扩展板上的对应传感器才能实现，具体传感器组合见下文组件表。

模块化组件体系

ESP-Drone 2.0 采用模块化设计思路，由主控板与若干扩展板组成：主控制板集成 ESP32-S2 模组和支持基础飞行的必要传感器，并提供硬件扩展接口；扩展板则搭载各类扩展传感器，对接主控制板的扩展接口，用于实现高级飞行功能。

从源码结构看，定点模块的驱动分别由 components/drivers/spi_devices/pmw3901/flowdeck_v1v2.c（PMW3901 光流传感器，通过 SPI 读取运动数据）和 components/drivers/i2c_devices/vl53l1/zranger2.c（VL53L1X 飞行时间测距传感器，通过 I2C 获取离地高度）实现；气压模块与指南针模块的驱动则位于 components/core/crazyflie/hal/src/sensors_mpu6050_hm5883L_ms5611.c。其中flowdeck_v1v2.c会创建一个flowdeckTask任务循环调用pmw3901ReadMotion()读取光流运动量，正是定点模式的数据来源。

更多硬件细节（原理图、PCB、管脚分配）可参阅 硬件参考文档。

支撑技术栈：ESP-IDF 与 Crazyflie

ESP-IDF是乐鑫为 ESP32/ESP32-S2/ESP32-S3 提供的物联网开发框架，它既包含构建软件项目所需的库与头文件等核心组件，也提供构建、烧录、调试、测量等开发与量产阶段常用的工具。ESP-Drone 固件基于 ESP-IDF 构建，当前仓库要求使用 ESP-IDF release/v5.0 分支作为开发环境（见 README.md）。

Crazyflie是 Bitcraze 的开源四旋翼项目，它为 ESP-Drone 提供了大量可直接复用的飞控软件资产：

• 支持多种传感器组合，可以轻松实现定高、定点等高级飞行模式；
• 基于 FreeRTOS 编写，将复杂的无人机系统分解为多个不同优先级的软件任务；
• 设计了功能完备的 cfclient 上位机和 CRTP 通信协议，便于调试、测量和控制。

在 components/core/crazyflie/modules/src/system.c 中可以看到这套任务化架构的落地：systemLaunch()负责创建 stabilizer、commander、console、wifilink、estimator_kalman 等一系列 FreeRTOS 任务；而 sdkconfig.defaults 中的CONFIG_FREERTOS_HZ=1000等配置则体现了为飞控实时性所做的系统级调优（系统时钟节拍 1000 Hz，即 1 ms 一个 tick）。

准备工作

1. 硬件组装

请按照下图流程组装 ESP32-S2-Drone V1.2（详见 硬件参考文档 中的硬件概览与管脚资源分配）：

• 将四个 716 电机（可选 720 电机）与减震橡胶圈安装到机架；
• 安装 46mm A/B 螺旋桨（可选 55mm 螺旋桨）；
• 接好 300mAh 1s LiPo 电池（可选 350mAh）与充电板。

注意：如果使用 720 电机，需要通过menuconfig -> ESPDrone Config -> motors config将电机类型设置为brushed 720 motor（对应 main/Kconfig.projbuild 中的MOTOR_BRUSHED_720配置项）。

2. 下载安装 ESP-Drone APP

ESP-Drone APP 同时支持 Android 与 iOS：

• Android：扫描官方文档提供的二维码下载安装；
• iOS：在 App Store 中搜索 ESP-Drone 下载安装。

APP 的源代码分别托管在 ESP-Drone-Android 与 ESP-Drone-iOS 两个仓库中，如需二次开发可以参考。

3. 安装 cfclient（可选，用于高级调试）

cfclient 是 PC 端调试上位机，仅在进行高级调试时需要安装。

# 1. 下载源代码 git clone https://github.com/qljz1993/crazyflie-clients-python.git # 2. 进入下载目录 cd crazyflie-clients-python # 3. 安装 cfclient 客户端 pip3 install -e . # 4. 启动客户端 cfclient

安装完成后需要配置遥控器（游戏手柄）：

1. 配置 4 个控制轴：Roll（翻滚）、Pitch（俯仰）、Yaw（偏航）、Thrust（油门）；
2. 配置一个按键为Assisted control，用于飞行模式切换。

手机 APP 使用指南

建立 Wi-Fi 连接

ESP-Drone 设备本身充当一个 Wi-Fi AP（热点）。在手机 Wi-Fi 列表中找到并连接即可：

SSID: ESP-DRONE_XXXX （XXXX 根据 MAC 地址生成） PASSWORD: 12345678

连接成功后，手机与无人机之间便建立了 Wi-Fi 链路，APP 通过 UDP 协议与飞控通信。这一机制在源码中有清晰的实现：在 components/drivers/general/wifi/wifi_esp32.c 的wifiInit()中，固件读取 ESP32 的 AP MAC 地址，将 SSID 拼接为CONFIG_WIFI_BASE_SSID+_+ MAC 后 6 字节的十六进制形式（对应文档中的ESP-DRONE_XXXX），并采用WIFI_AUTH_WPA_WPA2_PSK加密认证。同时固件会在 AP 上绑定静态 IP192.168.43.42，并开启 2390 端口的 UDP 收发任务（udp_server_rx_task/udp_server_tx_task），APP 正是通过该 UDP 通道收发 CRTP 控制数据。

SSID、密码、信道等参数均可在编译期通过 menuconfig 修改，对应 main/Kconfig.projbuild 中 "wireless config" 菜单下的配置项：

个性化设置

连接后可根据应用场景在 APP 中自定义飞行设置，或直接使用以下默认配置：

默认配置： Flight control settings 1. Mode: Mode2 2. Deadzone: 0.2 3. Roll trim: 0.0 4. Pitch trim: 0.0 5. Advanced flight control: true 6. Advanced flight control preferences 1. max roll/pitch angle: 15 2. max yaw angle: 90 3. max thrust: 90 4. min thrust: 25 5. X-Mode: true Controller settings 1. use full travel for thrust: false 2. virtual joystick size: 100 App settings 1. Screen rotation lock: true 2. full screen mode: true 3. show console: true

其中各参数含义如下：

• Mode / Deadzone：摇杆模式（Mode2 为美国手：左摇杆控制油门/偏航，右摇杆控制俯仰/翻滚）与摇杆死区（0.2，用于过滤摇杆微小漂移）；
• Roll/Pitch trim：翻滚/俯仰角度修正量（0.0 表示不修正）；
• Advanced flight control：是否启用高级飞行控制（解锁最大角度与最大油门限制）；
• max roll/pitch angle（15 度）/ max yaw angle（90 度）：高级模式下允许的最大俯仰/翻滚角度与最大偏航角速度；
• max thrust（90%）/ min thrust（25%）：油门输出上限与下限；
• X-Mode：电机呈 X 形布局（而非 + 形），与机架安装方式对应。

这些角度/油门上限最终会约束飞控的姿态控制环输出。从源码结构看，姿态控制由 components/core/crazyflie/modules/src/stabilizer.c 驱动，其内部使用 controller_pid.c 的 PID 控制律，将期望角度与传感器实测角度之差换算为电机油门指令，再经 power_distribution_stock.c 分配到 M1-M4 四个电机。

控制飞行

1. 打开 APP，点击Connect按钮连接飞机。连接成功后，无人机上的 LED绿灯闪烁；
2. 轻推Thrust（油门）摇杆，无人机起飞；
3. 在 APP 上滑动摇杆，控制无人机方向。

PC cfclient 使用指南

cfclient 是 Crazyflie 源工程的上位机，完整实现了 CRTP 协议中定义的功能，可显著加快调试速度。ESP-Drone 项目对该上位机进行了裁剪和调整以满足自身功能需求。cfclient 使用 JSON 文件存储配置信息。

飞行设置

基本飞行控制（Basic Flight Control）

1. 飞行模式：分为基本模式（Normal mode，适合初学者）与高级模式（Advanced mode，解锁最大角度与最大油门）。
2. 自动模式（Assisted mode）：
   • 定海拔模式（Altitude-hold mode）：保持飞行海拔，需要气压计支持；
   • 定点模式（Position-hold mode）：保持当前位置，需要光流传感器和 TOF 传感器支持；
   • 定高模式（Height-hold mode）：保持相对地面高度（触发时需高于地面 40 cm），需要 TOF 支持；
   • 悬停模式（Hover mode）：保持高于地面 40 cm，并悬停在起飞点，需要光流和 TOF 支持。
3. 角度修正（Trim）：
   • Roll Trim（翻滚角修正）：绕机身前后方向水平轴旋转的修正，用于补偿传感器的水平安装偏差；
   • Pitch Trim（俯仰角修正）：绕机身左右方向水平轴旋转的修正，同样用于补偿传感器的水平安装偏差。

注意：在自动模式下，油门摇杆会变为高度控制摇杆（此时油门控制器相当于高度控制器）。

高级飞行控制（Advanced Flight Control）

1. Max angle（最大倾角）：设置允许的最大俯仰和翻滚角度（roll/pitch）；
2. Max yaw rate（最大自旋速度）：设置允许的偏航速度（yaw）；
3. Max thrust（最大油门）：设置油门上限；
4. Min thrust（最小油门）：设置油门下限；
5. Slew limit（压摆极限）：防止油门骤降。当油门低于该值时，下降速度将被限定；
6. Slew rate（压摆率）：油门低于压摆极限之后允许的最大下降速率。

配置输入设备（Configure Input Device）

按照 cfclient 的提示，将遥控器（游戏手柄）的各个摇杆绑定到对应的控制通道（Roll / Pitch / Yaw / Thrust 及辅助按键）即可。

飞行数据（Flight Data）

在 cfclient 的 "Flight Control" 标签页可以查看无人机实时状态，右下角显示详细数据：

1. Target：目标角度；
2. Actual：测量角度；
3. Thrust：当前油门值；
4. M1/M2/M3/M4：四个电机的实际输出。

在线调参（Tune Online Parameters）

在 cfclient 中可以在线调整 PID 参数，实现实时的飞控参数调试。

注意事项：

1. 修改的参数实时生效，避免了频繁烧录固件的麻烦；
2. 可以在代码中通过宏定义配置哪些参数允许被上位机实时修改；
3. 在线修改仅用于调试，参数在掉电后不会保存。

这套机制在固件侧由参数注册系统支撑：飞控中的可调参数通过 components/core/crazyflie/modules/src/param.c 注册，并通过 CRTP 协议（components/core/crazyflie/modules/src/crtp.c）与上位机交互；同理，遥测数据通过 components/core/crazyflie/modules/src/log.c 的日志系统按配置周期上报，供上位机实时绘制波形。

飞行数据监控（Monitor Flight Data）

• 在Tab Log configuration和Tab Log Blocks标签页配置需要监控的参数（如姿态角、角速度等）；
• 在Tab Plotter标签页配置实时波形绘制，可监控陀螺仪、加速度计等传感器数据，例如加速度计三个轴的实时曲线。

螺旋桨方向

• 按照下图所示位置安装A、B 两种螺旋桨（A/B 桨叶旋转方向相反，用于抵消反扭矩）；
• 在飞行器上电自检时，检查四个螺旋桨转向是否正确。

螺旋桨的转向与电机布局（X-Mode / +-Mode）相关，main/Kconfig.projbuild 中的电机引脚配置（MOTOR01_PIN~MOTOR04_PIN）与 components/drivers/general/motors/motors_def_cf2.c 中的电机定义共同决定了每个电机对应的 PWM 输出引脚与转向分配。

起飞前检查清单（Preflight Check）

每次飞行前，请逐项完成以下检查：

1. 将无人机头部朝前放置，尾部（天线部分）朝向自己；
2. 将无人机置于水平面上，待机身稳定时再上电；
3. 在 cfclient 上观察机身是否置平；
4. 通信建立后，观察机尾 LED 是否绿灯快速闪烁；
5. 观察机头 LED 是否红灯熄灭（红灯亮起代表电量不足）；
6. 轻推 APP 左侧的油门摇杆（左手控制），检查飞机能否快速响应；
7. 拨动 APP 右侧的摇杆（右手控制），检查方向控制是否正确；
8. 全部通过后，起飞吧！

继续深入

• 硬件原理图、PCB 与管脚分配：参见 docs/en/rst/hardware.rst，其中包含 ESP32-S2-Drone V1.2、ESPlane-V2-S2、ESPlane-FC-V1 三款开发板的支持说明与menuconfig目标硬件选择方法；
• 固件启动流程：参见 main/main.c，app_main依次完成 NVS Flash 初始化（为 Wi-Fi 做准备）、platformInit()平台初始化与systemLaunch()系统任务启动；
• 构建配置：参见 sdkconfig.defaults 与各芯片变体配置sdkconfig.defaults.esp32s2/sdkconfig.defaults.esp32s3；
• 项目特性总览与支持策略：参见 README.md。

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