ESP-Drone 通信协议全解析:基于 ESP-IDF 的 Wi-Fi/UDP/CRTP 三层通信架构
ESP-Drone 通信协议全解析:基于 ESP-IDF 的 Wi-Fi/UDP/CRTP 三层通信架构
本文系统讲解 ESP-Drone 开源四轴飞控固件的通信体系:从「APP 应用层 — CRTP 协议层 — UDP 传输层 — Wi-Fi 物理层」的层级结构出发,逐一剖析 ESP32/ESP32-S2 的 Wi-Fi 性能参数与 AP 模式编程框架、UDP 端口与包校验(CKSUM)机制,以及继承自 Crazyflie 项目的 CRTP(CrazyRealtimeTransferProtocol)报文格式、端口分配与任务调度实现。读完本文,你将掌握 ESP-Drone 与上位机(手机 APP、PC cfclient、cflib)之间的数据通路原理,能够根据源码定位 Wi-Fi 初始化、UDP 收发任务与 CRTP 端口回调的完整调用链,并学会通过 menuconfig 调整发射功率、SSID 等关键配置。
通信层级结构
ESP-Drone 的通信系统采用与 Crazyflie 一脉相承的分层设计,通信双端(上位机与飞控)在各层形成一一对应关系,见下表:
| 终端 | 手机/PC | ESP-Drone |
|---|---|---|
| 应用层 | APP | 飞控固件 |
| 协议层 | CRTP | CRTP |
| 传输层 | UDP | UDP |
| 物理层 | Wi-Fi STA(Station) | Wi-Fi AP(Access Point) |
在该结构中,ESP-Drone 作为 Wi-Fi AP(接入点) 自建热点,手机或 PC 以 STA(站点) 模式接入;UDP 作为无连接传输层承载数据;CRTP 作为轻量协议层定义报文语义;最上层由 APP(如手机遥控软件)与飞控固件(stabilizer 等模块)完成业务交互。
Wi-Fi 通信
Wi-Fi 性能参数
ESP32 Wi-Fi 性能
| 项目 | 参数 |
|---|---|
| 模式 | STA 模式、AP 模式、STA+AP 共存模式 |
| 协议 | IEEE 802.11b/g/n,以及 802.11 LR(乐鑫专有),支持软件切换 |
| 安全性 | WPA、WPA2、WPA2-Enterprise、WPS |
| 主要特性 | AMPDU、HT40、QoS |
| 支持距离 | 乐鑫专属协议下 1 km |
| 传输速率 | 20 Mbit/s TCP 吞吐量、30 Mbit/s UDP |
ESP32-S2 Wi-Fi 性能
| 项目 | 参数 |
|---|---|
| 模式 | STA 模式、AP 模式、STA+AP 共存模式 |
| 协议 | IEEE 802.11b/g/n,支持软件切换 |
| 安全性 | WPA、WPA2、WPA2-Enterprise、WPS |
| 主要特性 | AMPDU、HT40、QoS |
| 支持距离 | 乐鑫专属协议下 1 km |
| 传输速率 | 20 Mbit/s TCP 吞吐量、30 Mbit/s UDP |
以上距离与速率为 ESP32/ESP32-S2 芯片平台的公开特性参数,实际表现受天线设计、信道环境与供电等因素影响。完整特性可参考乐鑫官方文档中对应芯片的 Wi-Fi 特性列表。
基于 ESP-IDF 的 Wi-Fi 编程框架
ESP-Drone 的 Wi-Fi 功能完全构建在 ESP-IDF 之上,编程模型可概括为三步:
- 应用层调用 Wi-Fi 驱动 API(
esp_wifi.h中的esp_wifi_init等)完成 Wi-Fi 初始化; - Wi-Fi 驱动对开发人员透明。当事件(如 STA 连接/断开)发生时,驱动向默认事件循环(default event loop)发布
event,应用程序可根据需求编写并注册handle回调程序; - 网络接口组件
esp_netif提供了一系列与 Wi-Fi 驱动event默认关联的handle程序。例如 ESP32 作为 AP 时,当有用户接入,esp_netif将自动启动 DHCP 服务。
这一框架在仓库中的完整落地实现位于 wifi_esp32.c:
- 第 265-266 行依次调用
esp_netif_init()与esp_event_loop_create_default()创建默认事件循环,第 267 行通过esp_netif_create_default_wifi_ap()创建 AP 网络接口; - 第 270 行使用
WIFI_INIT_CONFIG_DEFAULT()获取初始化配置结构体后调用esp_wifi_init(&cfg)完成驱动初始化; - 第 273-277 行注册
wifi_event_handler事件回调,该回调监听WIFI_EVENT_AP_STACONNECTED/WIFI_EVENT_AP_STADISCONNECTED,打印接入/离开的 STA 的 MAC 地址与 AID; - 第 298-301 行以
WIFI_MODE_AP模式启动并设置信道。
注意:Wi-Fi 初始化之前应使用
WIFI_INIT_CONFIG_DEFAULT获取初始化配置结构体,对该结构体进行个性化配置后再执行初始化。要格外防范结构体成员未初始化导致的问题——当 ESP-IDF 升级为结构体新增成员时,这一隐患尤其突出(wifi_esp32.c 正是采用先取默认结构体再初始化的正确写法)。
AP 模式工作流程
在 wifiInit() 中,AP 模式的建立遵循以下流程(wifi_esp32.c):
- 创建 UDP 收/发 FreeRTOS 队列(各 16 个
UDPPacket槽位,并注册到队列监控器); - 初始化
esp_netif与默认事件循环,创建默认 Wi-Fi AP 接口; - 通过
esp_wifi_get_mac(ESP_IF_WIFI_AP, mac)读取 AP MAC 地址,将 SSID 拼装为BASE_SSID_MAC形式:sprintf(WIFI_SSID, "%s_%02X%02X%02X%02X%02X%02X", CONFIG_WIFI_BASE_SSID, ...); - 填充
wifi_config_t的.ap字段(信道、最大连接数、认证模式WIFI_AUTH_WPA_WPA2_PSK、SSID 与密码),密码为空时自动降级为WIFI_AUTH_OPEN; - 调用
esp_wifi_set_mode(WIFI_MODE_AP)、esp_wifi_set_config、esp_wifi_start()启动 AP; - 手动设置静态 IP
192.168.43.42,掩码255.255.255.0,先esp_netif_dhcps_stop再esp_netif_set_ip_info最后esp_netif_dhcps_start重启 DHCP 服务; - 完成 UDP server socket 创建并拉起发送/接收两个任务。
其中 Wi-Fi 接入参数(SSID、密码、信道、最大连接数)均由 Kconfig.projbuild 中的 menuconfig 选项控制:
| 配置项 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|
WIFI_BASE_SSID |
ESP-DRONE |
1-16 字符 | Wi-Fi 基础 SSID,最终 SSID 为 BASE_SSID-MAC |
WIFI_PASSWORD |
12345678 |
8-64 字符 | Wi-Fi 密码 |
WIFI_CHANNEL |
6 |
1-13 | Wi-Fi / ESP-Now 信道 |
WIFI_MAX_STA_CONN |
3 |
1-6 | 最大同时接入的 STA 数 |
提高 Wi-Fi 通信距离
增大 Wi-Fi 发射功率可以直接提升 PHY 增益与通信距离。操作方法为在 idf.py menuconfig 中依次进入:
Component config >> PHY >> Max WiFi TX power (dBm)
将 Max WiFi TX power 改为 20。
实际上,ESP-Drone 仓库已在 sdkconfig.defaults 中默认写入:
CONFIG_ESP32_PHY_MAX_WIFI_TX_POWER=20
CONFIG_ESP32_PHY_MAX_TX_POWER=20
即出厂的默认配置已将最大发射功率设为 20 dBm,用户按需调整即可。
UDP 通信
UDP 端口号
ESP-Drone 通过 Wi-Fi AP 上运行 UDP 服务与上位机通信,端口分配如下:
| App | 方向 | ESP-Drone |
|---|---|---|
| 192.168.43.42::2399 | TX/RX | 192.168.43.42::2390 |
即飞控在 192.168.43.42:2390 上监听,上位机从 192.168.43.42:2399 与之收发。源码中端口号定义于 wifi_esp32.c:
#define UDP_SERVER_PORT 2390
#define UDP_SERVER_BUFSIZE 64
socket() 创建后 bind() 到 htons(UDP_SERVER_PORT)(wifi_esp32.c),即完成监听端口的绑定。
UDP 包结构
UDP 传输的数据包为 CRTP + 校验信息(CKSUM),帧格式如下:
/* Frame format:
* +=============+-----+-----+
* | CRTP | CKSUM |
* +=============+-----+-----+
*/
- CRTP:按照 CRTP 包结构定义,包含 Header + Data(详见下文 CRTP 协议部分);
- CKSUM:校验信息,大小为 1 字节,将 CRTP 包按字节累加得到。
接收缓冲区大小与包长度限制在 wifi_esp32.h 中定义:
// 32 bytes is enough for CRTP packets (30+1) + checksum 1
#define WIFI_RX_TX_PACKET_SIZE (32)
typedef struct
{
uint8_t size;
uint8_t data[WIFI_RX_TX_PACKET_SIZE];
} UDPPacket;
可见 32 字节刚好容纳 31 字节 CRTP 包(Header + 30 字节数据)加 1 字节 CKSUM,UDP 包内不包含任何额外协议头。
CKSUM 计算方法
校验和采用简单的逐字节累加、取模 256 的算法。飞控侧实现见 wifi_esp32.c:
static uint8_t calculate_cksum(void *data, size_t len)
{
unsigned char *c = data;
int i;
unsigned char cksum = 0;
for (i = 0; i < len; i++) {
cksum += *(c++);
}
return cksum;
}
上位机侧以 Python 为例的计算逻辑与之一致:
# 计算 raw 的 cksum,并将其添加到包尾
raw = (pk.header,) + pk.datat
cksum = 0
for i in raw:
cksum += i
cksum %= 256
raw = raw + (cksum,)
收发的完整调用链
UDP 收发由两个独立 FreeRTOS 任务完成(wifi_esp32.c):
udp_server_rx_task:循环recvfrom()读取数据;若长度超过WIFI_RX_TX_PACKET_SIZE则丢弃;取出包尾字节作为 CKSUM,与calculate_cksum(rx_buffer, len - 1)比对,通过后去掉 CKSUM、将剩余 CRTP 数据封装为UDPPacket送入接收队列udpDataRx,供上层wifiGetDataBlocking()阻塞取出;udp_server_tx_task:从发送队列udpDataTx取出待发送包,在包尾追加calculate_cksum(outPacket.data, outPacket.size)计算出的校验字节,再通过sendto()发回source_addr(即最近一次通信的上位机地址)。
上层通过 wifi_esp32.h 暴露的 wifiGetDataBlocking(UDPPacket *in) 与 wifiSendData(uint32_t size, uint8_t *data) 接口与 UDP 收发任务对接,这两个接口也是 CRTP 链路层(link layer)接入 Wi-Fi 传输的桥梁。
CRTP 协议
协议概述
ESP-Drone 项目继承了 Crazyflie 项目使用的 CRTP(CrazyRealtimeTransferProtocol) 协议,用于飞行指令发送、飞行数据回传、参数设置等场景。
CRTP 实现了无状态设计,不需要握手步骤,任何命令均可在任意时刻发送。但对于一些 log/param/mem 命令,需先下载 TOC(目录),协助主机正确发送信息。已实现的 Python API(cflib)支持下载 param/log/mem 的 TOC,确保能够使用全部功能。
CRTP 包结构
CRTP 包大小为 32 字节:1 字节 Header + 31 字节 Payload(源码中数据区上限 CRTP_MAX_DATA_SIZE 定义为 30,加上 Header 共 31 字节,见 crtp.h)。Header 记录端口(4 位)、保留位(2 位)与通道(2 位):
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
| Port | Res. | Chan. |
+---+---+---+---+---+---+---+---+
| DATA 0 |
+---+---+---+---+---+---+---+---+
: : : : : : : : :
+---+---+---+---+---+---+---+---+
| DATA 30 |
+---+---+---+---+---+---+---+---+
| 字段 | 字节 | 位 | 描述 |
|---|---|---|---|
| Header | 0 | 0 ~ 1 | 目标数据通道 |
| \ | 0 | 2 ~ 3 | 保留,用于传输层 |
| \ | 0 | 4 ~ 7 | 目标数据端口 |
| Data | 1 ~ 31 | 0 ~ 7 | 数据包中的数据 |
对应的 C 结构体定义在 crtp.h,其中 Header 通过位域拆分为 channel : 2、reserved : 2、port : 4,并提供了构造 Header 的宏:
#define CRTP_HEADER(port, channel) (((port & 0x0F) << 4) | (channel & 0x0F))
端口分配
CRTP 通过端口(Port)路由到不同功能模块,各端口定义见 crtp.h 中的 CRTPPort 枚举,含义如下:
| 端口号 | 数据端口 | 用途 |
|---|---|---|
| 0 | Console | Console 使用 consoleprintf 函数将调试信息输出到 PC 端 |
| 2 | Parameters | 读写飞控参数。参数可在源码中用宏定义(如 PARAM_GROUP_START / PARAM_ADD) |
| 3 | Commander | 发送 roll/pitch/yaw/thrust 控制指令 |
| 4 | Memory access | 访问非易失性存储,如 1-wire 访问和 I2C 访问(仅支持 Crazyflie 2.0) |
| 5 | Log | 设置日志变量,日志变量将定期发送至飞控,在源码中用宏定义 |
| 6 | Localization | 本地化相关数据包 |
| 7 | Generic Setpoint | 允许发送设置点和控制模式 |
| 13 | Platform | 用于 misc platform 控制,如调试和掉电等 |
| 14 | Client-side debugging | 用于调试 PC 端 UI 界面程序,仅存在于 Crazyflie Python API 中 |
| 15 | Link layer | 用于控制和访问通信链路层 |
任务与回调机制
固件中大部分连接到端口的模块以任务的方式实现:如果有传入的 CRTP 包在消息队列中传递,任务则在队列上阻塞等待。启动时,每个任务及其它模块需要在通信链路层为预定义的端口注册。
从 crtp.c 源码可以看到完整的实现:
crtpInit()创建长度为CRTP_TX_QUEUE_SIZE(120)的发送队列,并创建crtpTxTask/crtpRxTask两个任务(crtp.c);- 每个端口一个接收队列,由
crtpInitTaskQueue(CRTPPort portId)按需创建(队列深度CRTP_RX_QUEUE_SIZE= 16),任务通过crtpReceivePacket/crtpReceivePacketBlock/crtpReceivePacketWait阻塞或轮询取包(crtp.c); crtpRegisterPortCB(int port, CrtpCallback cb)为端口注册回调函数(每端口仅一个回调,后注册者覆盖前者);crtpRxTask从链路层取包后,依据p.port分发到对应端口的队列与回调;crtpTxTask从发送队列取包并调用link->sendPacket下发到链路层(crtp.c);- 链路层通过
crtpSetLink(struct crtpLinkOperations *lk)注入,crtpLinkOperations结构体(crtp.h)定义setEnable、sendPacket、receivePacket、isConnected、reset五个函数指针,Wi-Fi/UDP 即作为这样一种 link 接入 CRTP 栈; - 协议栈内置统计:
crtp日志组以 500 ms 为周期上报rxRate/txRate(crtp.c),可配合 log 功能观测链路吞吐。
以指挥官端口为例,crtp_commander.c 在初始化时注册了端口 3(CRTP_PORT_SETPOINT)与端口 7(CRTP_PORT_SETPOINT_GENERIC)的回调:
crtpInit();
crtpRegisterPortCB(CRTP_PORT_SETPOINT, commanderCrtpCB);
crtpRegisterPortCB(CRTP_PORT_SETPOINT_GENERIC, commanderCrtpCB);
端口 3 通道 0 上的报文由 crtpCommanderRpytDecodeSetpoint() 解码(crtp_commander_rpyt.c),其载荷布局为:
struct CommanderCrtpLegacyValues
{
float roll; // deg
float pitch; // deg
float yaw; // deg
uint16_t thrust;
} __attribute__((packed));
解码时对推力做钳制(MIN_THRUST 1000、MAX_THRUST 60000,低于 1000 视为解锁/零推力),并依据 altHoldMode / posHoldMode / posSetMode 等飞行模式将 roll/pitch/yaw 映射为角速度或角度设定值;模式切换由 setCommandermode() 完成,相关状态以 flightmode 参数组(althold/poshold/posSet/yawMode/stabMode*)暴露给上位机读写。端口 7 的通道 0 用于通用设置点解码,通道 1 用于元命令(如 notifySetpointsStop,见 crtp_commander.c)。
CRTP 协议支持包:cflib
cflib 是 CRTP 协议的 Python 支持包,提供了通信协议的应用层接口,可用于构建上位机,与 Crazyflie 系列四轴飞行器通信并控制飞行器。固件中每一个使用 CRTP 协议的组件,在 cflib 中都有一个脚本与其对应。
- 源工程仓库:
crazyflie-lib-python; - 适配 ESP-Drone 的 cflib 工程:
qljz1993/crazyflie-lib-python,使用前需要切换到esplane分支。
基于 CRTP 协议的应用开发
各平台工程模板
由于 ESP-Drone 完整兼容 CRTP 协议,可直接复用 Crazyflie 生态中基于 CRTP 开发的客户端工程作为开发模板,包括:
crazyflie2-ios-client—— iOS 客户端工程;crazyflie2-windows-uap-client—— Windows UAP 客户端工程;crazyflie-android-client—— Android 客户端工程;- 安卓版本客户端使用指南与开发环境搭建指南(源自 Bitcraze 官方 wiki)。
其中 Android 端对 ESP-Drone 的用户尤其实用:手机以 STA 模式接入飞控的 AP 热点(SSID 形如 ESP-DRONE_XXXXXXXXXXXX),即可通过 UDP + CRTP 直接遥控飞行。
cfclient 上位机
cfclient 是 Crazyflie 源工程的上位机软件,完全实现了 CRTP 协议中定义的功能,可以加快飞机的调试过程。ESP-Drone 项目对该上位机进行了裁剪和调整,以匹配自身功能设计需求(如 flightmode 参数组、位置保持等扩展模式)。其控制界面如下:
cfclient 的具体使用说明可查阅 gettingstarted.rst 中的 PC 端 cfclient 章节。
小结
至此,一条完整的数据通路已经清晰:手机/PC 端 APP 通过 Wi-Fi STA 接入 ESP-Drone 的 AP 热点,将 CRTP 报文封装进 UDP 包(附 1 字节 CKSUM)发送至 192.168.43.42:2390;飞控侧的 udp_server_rx_task 校验 CKSUM 后把 CRTP 包送入队列,crtpRxTask 再按端口分发到 Console、Parameters、Commander、Log 等任务或回调,实现遥控指令下发、参数读写与遥测数据回传。开发者既可以直接参考 wifi_esp32.c 与 crtp.c 理解底层实现,也可以基于 cflib(esplane 分支)或 cfclient 快速搭建自己的上位机应用。
