ESP-Drone 通信协议全解析:基于 ESP-IDF 的 Wi-Fi/UDP/CRTP 三层通信架构

原创2026-09-17 23:21:301,870 阅读
文章标签:无人机嵌入式硬件开发机器人

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 之上,编程模型可概括为三步:

  1. 应用层调用 Wi-Fi 驱动 API(esp_wifi.h 中的 esp_wifi_init 等)完成 Wi-Fi 初始化;
  2. Wi-Fi 驱动对开发人员透明。当事件(如 STA 连接/断开)发生时,驱动向默认事件循环(default event loop)发布 event,应用程序可根据需求编写并注册 handle 回调程序;
  3. 网络接口组件 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):

  1. 创建 UDP 收/发 FreeRTOS 队列(各 16 个 UDPPacket 槽位,并注册到队列监控器);
  2. 初始化 esp_netif 与默认事件循环,创建默认 Wi-Fi AP 接口;
  3. 通过 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, ...);
  4. 填充 wifi_config_t 的 .ap 字段(信道、最大连接数、认证模式 WIFI_AUTH_WPA_WPA2_PSK、SSID 与密码),密码为空时自动降级为 WIFI_AUTH_OPEN;
  5. 调用 esp_wifi_set_mode(WIFI_MODE_AP)、esp_wifi_set_config、esp_wifi_start() 启动 AP;
  6. 手动设置静态 IP 192.168.43.42,掩码 255.255.255.0,先 esp_netif_dhcps_stop 再 esp_netif_set_ip_info 最后 esp_netif_dhcps_start 重启 DHCP 服务;
  7. 完成 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 开发的客户端工程作为开发模板,包括:

  1. crazyflie2-ios-client —— iOS 客户端工程;
  2. crazyflie2-windows-uap-client —— Windows UAP 客户端工程;
  3. crazyflie-android-client —— Android 客户端工程;
  4. 安卓版本客户端使用指南与开发环境搭建指南(源自 Bitcraze 官方 wiki)。

其中 Android 端对 ESP-Drone 的用户尤其实用:手机以 STA 模式接入飞控的 AP 热点(SSID 形如 ESP-DRONE_XXXXXXXXXXXX),即可通过 UDP + CRTP 直接遥控飞行。

cfclient 上位机

cfclient 是 Crazyflie 源工程的上位机软件,完全实现了 CRTP 协议中定义的功能,可以加快飞机的调试过程。ESP-Drone 项目对该上位机进行了裁剪和调整,以匹配自身功能设计需求(如 flightmode 参数组、位置保持等扩展模式)。其控制界面如下:

cfclient 上位机控制界面

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 快速搭建自己的上位机应用。

登录后查看全文
esp-drone