# CF-Drone

**Repository Path**: forestfloat/CF-Drone

## Basic Information

- **Project Name**: CF-Drone
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-09-11
- **Last Updated**: 2026-09-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CF-Drone 飞控固件

基于 **ESP32 / ESP32-C3** 的四旋翼飞控固件，适用 ESP32 + 6500/9250 姿态传感器的飞控。
固件由开源项目 **flix** 改写增强而来。

> **硬件资料**
> 完美适配琛光 E1 系列无人机，嘉立创开源平台工程链接：https://oshwhub.com/songge8/project_qqqyfdkm

> **编译要求**
> - Arduino IDE 2.3.x 以上版本（不支持 1.8.19）
> - 安装 ESP32 开发板核心库（esp32 by Espressif Systems）及依赖（MAVLink、FlixPeriph、SBUS 等）
> - 开发板可选：ESP32 Dev Module 或 WeMOS D1 MINI ESP32

---

## 一、整体框架

固件采用「主程序 + src/ 模块化 + 条件编译」结构：根目录只保留主程序
`CF-Drone.ino`（核心全局状态变量 + `setup()` 初始化 + `loop()` 主循环调度），
全部功能按 Arduino 工程规范拆分到 `src/` 下的子目录，每个模块一对
`cf_<模块名>.cpp`/`.h` 文件（`src/` 子目录由 Arduino 构建系统递归编译），
第三方基础库独立存放于 `src/flix/`；`board_config.h` 通过宏自动适配
ESP32 与 ESP32-C3。**每个子目录内均有 README.md 详细说明模块用途与机制。**

### 1. 目录结构与用途

| 分类 | 目录 | 用途 |
|------|------|------|
| **入口** | [CF-Drone.ino](CF-Drone.ino) | 主程序：核心全局状态 + `setup()` 初始化 + `loop()` 主循环调度 |
| **板级配置** | [src/config/](src/config/README.md) | 电机/电池/RC/IMU/LED 引脚等硬件的双板差异配置 + 全局功能开关 |
| **第三方基础库** | [src/flix/](src/flix/README.md) | flix 开源库：vector / quaternion / lpf / pid / util |
| **传感器** | [src/imu/](src/imu/README.md) | MPU9250 陀螺仪/加速度计读取、量程配置、校准 |
| **姿态估算** | [src/estimate/](src/estimate/README.md) | 姿态解算：陀螺积分 + 加速度重力修正的互补滤波 |
| **控制** | [src/control/](src/control/README.md) | 飞行控制：模式解析 + 角度环/角速率环双环串级 PID |
| **执行** | [src/motors/](src/motors/README.md) | 4 路电机 PWM 输出（MOSFET 直驱 / ESC 两模式） |
| **输入** | [src/rc/](src/rc/README.md) | SBUS 遥控器接收、通道识别与校准 |
| **通讯** | [src/wifi/](src/wifi/README.md) | Wi-Fi AP/STA 模式与 UDP 收发 |
| | [src/mavlink/](src/mavlink/README.md) | MAVLink 遥测与地面站指令处理 |
| | [src/web_rc/](src/web_rc/README.md) | 网页遥控服务器（HTTP + JSON 协议，含前端界面 `web_rc_html.h`） |
| **安全** | [src/safety/](src/safety/README.md) | 故障保护：遥控失联降高、Web 失联、倒置保护、自动模式中断 |
| **外设** | [src/battery/](src/battery/README.md) | 电池电压采样与低电告警 |
| | [src/led/](src/led/README.md) | 板载状态 LED：解锁慢闪/告警快闪 |
| **系统** | [src/time/](src/time/README.md) | 全局时间戳 `t`/`dt`、循环频率统计 |
| | [src/log/](src/log/README.md) | RAM 飞行日志：解锁后按高频采样，环形缓冲供导出 |
| | [src/parameters/](src/parameters/README.md) | 参数持久化：闪存存储所有可调参数（PID/引脚/RC 通道等） |
| | [src/cli/](src/cli/README.md) | 串口命令行接口：`print()` 统一打印、命令解析执行 |

### 2. 主循环执行流程

```
loop()
│
├── readIMU()           1. 读取陀螺/加速度计，扣偏 + 安装方向修正
├── step()              2. 更新全局时间 t 与步长 dt，统计循环频率
├── readRC()            3. 读取 SBUS 遥控（归一化写入 control*）
├── readWebRC()         4. 处理网页遥控 HTTP 请求（同样写入 control*）
├── estimate()          5. 姿态估算
│     └── applyGyro()    陀螺积分（短期高精度）
│     └── applyAcc()     加速度重力修正（长期防漂移）
├── control()           6. 飞行控制
│     ├── interpretControls()   解析开关→飞行模式
│     ├── interpretWebRC()      网页按钮→解锁/模式切换
│     ├── failsafe()            故障保护（失联降高/倒置停机）
│     ├── controlAttitude()     外环：角度→期望角速率（STAB/ALTHOLD）
│     ├── controlRates()        内环：角速率→期望力矩
│     └── controlTorque()       力矩→4 电机油门映射
├── sendMotors()        7. 输出 PWM 占空比到电机
├── handleInput()       8. 串口命令行
├── processMavlink()    9. MAVLink 遥测收发
├── logData()          10. RAM 飞行日志采样
├── syncParameters()   11. 参数变更写回闪存
└── updateLED()        12. 状态 LED 更新
```

### 3. 输入统一模型（重要）

无论来自 **SBUS 遥控 / MAVLink 地面站 / Web 网页遥控**，最终都归一化写入统一的
`controlRoll / controlPitch / controlYaw / controlThrottle / controlMode` 五个全局变量
（范围约 [-1,1]）。控制循环只读取这组变量，无需关心输入来源，从而支持多路输入并存。

### 4. 飞行模式（模式开关三挡）

| 模式 | 值 | 控制方式 |
|------|----|----------|
| `RAW` | 0 | 直接力矩控制，不启用反馈环（危险，调试用） |
| `ACRO` | 1 | 角速率模式：操纵杆直接设定目标角速率 |
| `STAB` | 2 | 自稳模式：操纵杆设定倾角 + 偏航速率（默认） |
| `ALTHOLD` | 3 | 气压计定高（当前为未实现 stub） |
| `AUTO` | 4 | 自动/地面站控制（也用于失联自动降高） |

### 5. 控制系统结构（双环串级 PID）

```
期望角度 ──? [角度环 PID] ──? 期望角速率 ──? [角速率环 PID] ──? 期望力矩 ──? 电机油门映射 ──? 电机
   ▲                                 ▲                                        │
   │                                 │                                        ▼
 估计姿态(四元数)                   估计角速率(陀螺滤波)                  4路PWM
```

- 外环（角度环）：STAB/ALTHOLD 模式下把期望倾角转换为期望角速率
- 内环（角速率环）：把期望角速率转换为期望力矩
- 最后按 X 型布局把力矩分配到 4 个电机，叠加到基础油门

---

## 二、主要功能

- 双板支持（ESP32 / ESP32-C3）自动编译适配
- 三路遥控输入：SBUS 无线遥控、MAVLink 地面站、Web 网页遥控
- 网页遥控器（AP 热点，浏览器访问 `http://192.168.4.1:8080`）
- MAVLink 遥测（可配合 QGroundControl）
- 参数闪存持久化，串口/MAVLink 在线调参
- 故障保护：遥控失联自动降高、倒置保护停机、低电告警
- 状态 LED 提示、RAM 飞行日志

## 三、常用调试命令

通过串口控制台输入（`help` 查看全部）：

| 命令 | 说明 |
|------|------|
| `p <name> <value>` | 设置参数（如 `p MOT_PIN_FL 14`） |
| `preset` | 重置参数存储（修改参数后执行） |
| `ca` | 校准陀螺仪/加速度计 |
| `cr` | 校准 RC 遥控器 |
| `arm` / `disarm` | 解锁 / 上锁 |
| `mfl/mfr/mrl/mrr` | 单个电机测试（务必不装桨叶） |
| `raw/stab/acro/auto` | 切换飞行模式 |
| `log dump` | 导出飞行日志 |
| `help` | 查看全部命令 |

---

# 更新日志

## 20260913
* 工程模块化重构：根目录仅保留 `CF-Drone.ino`（全局状态 + 初始化/主循环），
  其余功能按 Arduino 工程规范拆分至 `src/` 各子目录的 `.cpp`/`.h`
* 第三方基础库（vector/quaternion/lpf/pid/util）独立存放于 `src/flix/`
* 每个子目录新增 README.md 模块说明，更新根目录 README

## 20260417
* 修复调试日志显示不全的BUG，并优化提示命令显示

## 20260416
* 降低遥控器调试常规日志的打印频率
* 服务端无法准确的监控网络信号质量，前端已经准确实现，清理服务端的网络监控

## 20260415
* 增加LED状态提示，开发板状态LED解锁慢闪，低电、失联等警告状态快闪
* 电机引脚参数化，可通过调试控制台设置
* WIFI用户名密码参数化，可通过调试控制台设置
* 修复网络延迟计算逻辑错误
* 适当提高网页遥控发包频率到20Hz,为了不影响性能，建议不要超过20Hz
* 更新一些常规功能

## 20260328
* 重构WEB遥控器底层逻辑
* 清理WEB遥控器服务端冗余

## 20260327
* 大幅优化WEB遥控器
* 添加web遥控器调试功能
* 增加倒置保护，飞机长时间倒置判定为异常，停机避免损失扩大