Arduino-ESP32 ESP-NOW 通信库完全指南Peer 管理、加密传输与多设备实战【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32导读ESP-NOW 是乐鑫Espressif为 ESP32 系列芯片设计的一种无连接connectionless通信协议它允许设备之间在**不需要接入点AP**的情况下直接进行低功耗、低延迟、高吞吐的数据交换。本指南基于 Arduino-ESP32 仓库中内置的ESP_NOW库文档原文系统讲解ESP_NOW_Class与ESP_NOW_Peer两大核心类的全部 API并结合仓库源码、示例工程与多设备验证测试给出可直接复制运行的广播、单播、加密与串口流式传输方案。读完本文你将掌握如何在 ESP32 设备间搭建去中心化的点对点通信网络并理解其底层实现原理。一、ESP-NOW 协议概述与适用场景ESP-NOW 是一种专为 ESP32 设备间通信设计的协议核心特点是无需 AP 中转设备直接点对点通信适合局域网内的直连场景低功耗、低延迟、高吞吐相比传统 Wi-Fi 连接开销更小、响应更快应用广泛可用于智能灯、遥控设备、传感器等物联网场景。该库为 ESP-NOW 通信提供了一套易用的接口涵盖初始化、添加/移除 Peer、发送/接收数据包等完整流程。需要特别注意的是文档原文 中的明确说明本库仅在 ESP32 系列芯片上测试过与 ESP8266 或其他非 ESP32 平台的互操作性不作保证。从源码看这一约束也有硬性实现依据ESP32_NOW.h 与 ESP32_NOW.cpp 均以CONFIG_ESP_HOSTED_ENABLED宏做编译期防护——当芯片只有 Hosted外挂 Wi-Fi 协处理器模式而缺乏原生 Wi-Fi 时编译会直接发出ESP-NOW is only supported in SoCs with native Wi-Fi support警告。库元数据library.properties也声明architecturesesp32即仅面向 ESP32 平台。二、ESP_NOW_Class全局管理类ESP_NOW_Class是管理 ESP-NOW 通信的主类仓库在 ESP32_NOW.h 中定义并默认提供全局实例ESP_NOW见 ESP32_NOW.h 与 ESP32_NOW.cpp。它继承自 ArduinoPrint因此还支持流式写接口。2.1 begin —— 初始化 ESP-NOWbool begin(const uint8_t *pmk NULL);pmk可选参数若启用加密传入成对主密钥Pairwise Master KeyPMK长度为 16 字节返回值初始化成功返回true失败返回false必须在调用其他任何 ESP-NOW 功能之前调用。源码实现揭示了 begin 内部的完整初始化链路ESP32_NOW.cpp若已初始化_esp_now_has_begun直接返回true幂等调用esp_wifi_start()启动 Wi-Fi调用esp_now_get_version()获取 ESP-NOW 版本号据此设置max_data_lenv1.0 为 250 字节ESP_NOW_MAX_DATA_LENv2.0 为 1470 字节ESP_NOW_MAX_DATA_LEN_V2调用esp_now_init()初始化协议栈为已登记的 Peer 统一设置 PHY 速率_esp_now_set_all_peers_rate()若传入pmk调用esp_now_set_pmk(pmk)设置主密钥注册接收回调_esp_now_rx_cb与发送完成回调_esp_now_tx_cb。2.2 end —— 结束通信并释放资源bool end();结束 ESP-NOW 通信并释放库占用的全部资源。从实现看ESP32_NOW.cppend()会先遍历并移除所有已注册的 Peer再调用esp_now_deinit()反初始化协议栈最后清空内部 Peer 列表。2.3 查询当前 Peer 数量int getTotalPeerCount(); // 当前已添加的 Peer 总数 int getEncryptedPeerCount(); // 使用加密的 Peer 数量两者均返回 Peer 数量出错时返回 -1。例如在 ESP-NOW 尚未初始化时实现会打印ESP-NOW not initialized并返回 -1ESP32_NOW.cpp。它们底层分别读取esp_now_get_peer_num()返回结构体中的total_num与encrypt_num字段。2.4 版本与最大数据长度源码补充 API文档之外源码还提供了两个极具实用价值的查询方法ESP32_NOW.hint getMaxDataLen() const; // 当前固件支持的最大单包数据长度 int getVersion() const; // 当前 ESP-NOW 协议版本这两个方法在未初始化时返回 -1并在初始化后分别返回 250/1470 与 1/2ESP32_NOW.cpp。所有官方示例在begin()之后都会打印Serial.printf(ESP-NOW version: %d, max data length: %d\n, ESP_NOW.getVersion(), ESP_NOW.getMaxDataLen());2.5 onNewPeer —— 新 Peer 数据回调当收到来自未注册 Peer的数据时可通过onNewPeer注册回调函数来处理void onNewPeer(void (*cb)(const esp_now_recv_info_t *info, const uint8_t *data, int len, void *arg), void *arg);cb回调函数指针arg可选传递给回调的用户自定义参数。回调函数签名void cb(const esp_now_recv_info_t *info, const uint8_t *data, int len, void *arg);info接收数据包的信息含源/目的 MAC 地址等data接收到的数据指针len接收数据的长度arg用户自定义参数。源码层面onNewPeer只是将回调保存在静态变量new_cb/new_arg中ESP32_NOW.cpp真正的分发逻辑在接收回调_esp_now_rx_cb中ESP32_NOW.cpp先判断目的地址是否为广播地址0xFF:FF:FF:FF:FF:FF若源地址不是已注册 Peer 且new_cb非空则调用new_cb并返回——这正是动态发现新设备的机制否则在内部 Peer 列表中查找源 MAC 对应的ESP_NOW_Peer对象调用其onReceive(data, len, broadcast)虚方法。2.6 write —— 向所有 Peer 直接发送源码补充 API由于ESP_NOW_Class继承自Print它还提供了流式写接口ESP32_NOW.hsize_t write(const uint8_t *data, size_t len); // 向所有已注册 Peer 发送无需指定 MAC size_t write(uint8_t data); // 单字节重载write底层调用esp_now_send(nullptr, data, len)nullptr表示广播给所有已登记 Peer超长数据会被截断到max_data_lenESP32_NOW.cpp。配套的availableForWrite()返回当前可写字节数。三、ESP_NOW_PeerPeer 设备类ESP_NOW_Peer表示 ESP-NOW 网络中的一个对端设备ESP32_NOW.h。它是一个抽象类必须由子类继承并在子类中实现onReceive与onSent两个虚方法以正确处理连接与收发事件。3.1 构造函数ESP_NOW_Peer(const uint8_t *mac_addr, uint8_t channel, wifi_interface_t iface, const uint8_t *lmk);mac_addr对端设备的 MAC 地址6 字节channel通信信道iface使用的 Wi-Fi 接口WIFI_IF_STA或WIFI_IF_APlmk可选若启用加密传入本地主密钥Local Master KeyLMK。从 ESP32_NOW.cpp 可以看到构造函数会保存 MAC、信道、接口并根据lmk是否为空设置encrypt标志位同时设置默认 PHY 速率配置#define DEFAULT_ESPNOW_RATE_CONFIG { \ .phymode WIFI_PHY_MODE_11G, \ .rate WIFI_PHY_RATE_1M_L, \ .ersu false, \ .dcm false \ }默认以 802.11g、1 Mbps 长前导Long preamble速率通信可通过setRate()覆盖。3.2 add / remove —— 注册与注销 Peerbool add(); // 将对端添加到 ESP-NOW 网络成功返回 true bool remove(); // 将对端从网络移除成功返回 trueadd()内部调用esp_now_add_peer()完成注册ESP32_NOW.cpp。底层辅助函数_esp_now_add_peerESP32_NOW.cpp展示了关键细节若该 MAC 已是 Peer返回ESP_ERR_ESPNOW_EXIST填充esp_now_peer_info_t信道、接口、加密标志与 LMK注册成功后把ESP_NOW_Peer*存入静态数组_esp_now_peers容量ESP_NOW_MAX_TOTAL_PEER_NUM若 ESP-NOW 已在运行还会调用esp_now_set_peer_rate_config()应用该 Peer 的 PHY 速率。remove()则调用esp_now_del_peer()并把内部数组中对应条目清空ESP32_NOW.cpp。3.3 send —— 发送数据size_t send(const uint8_t *data, int len);data待发送数据指针len数据长度字节返回值实际发送的字节数出错返回 0。实现ESP32_NOW.cpp会先校验 ESP-NOW 已初始化且 Peer 已添加否则报Peer not added.并返回 0然后通过ESP_NOW.getMaxDataLen()获取上限并将超长数据截断最后调用esp_now_send(mac, data, len)定向发送。3.4 addr —— MAC 地址读写const uint8_t * addr() const; // 获取对端 MAC 地址 void addr(const uint8_t *mac_addr); // 设置对端 MAC 地址注意源码实现ESP32_NOW.cppaddr()的设置版本在 Peer 已添加且 ESP-NOW 已在运行时会失败返回false并提示请在添加 Peer 之前或启动 ESP-NOW 之前调用 addr()。因此 MAC 地址应尽量在构造对象时确定。3.5 getChannel / setChannel —— 信道读写uint8_t getChannel() const; // 获取通信信道 void setChannel(uint8_t channel); // 设置通信信道setChannel()在 Peer 已添加时会调用esp_now_mod_peer()实时修改底层 Peer 信息ESP32_NOW.cpp未运行时则仅更新内部字段。3.6 getInterface / setInterface —— Wi-Fi 接口读写wifi_interface_t getInterface() const; // 获取 Wi-Fi 接口 void setInterface(wifi_interface_t iface); // 设置 Wi-Fi 接口WIFI_IF_STA / WIFI_IF_AP行为与信道读写一致已运行时通过esp_now_mod_peer()实时生效ESP32_NOW.cpp。3.7 速率配置 setRate / getRate源码补充 APIbool setRate(const esp_now_rate_config_t *rate_config); esp_now_rate_config_t getRate() const;setRate()用于配置 Peer 的 PHY 速率传nullptr恢复默认配置ESP32_NOW.cpp。限制只能在 Peer 添加之前或 ESP-NOW 启动之前调用否则返回false并打印错误提示——这与addr()的行为一致属于运行期不可变配置项。3.8 isEncrypted / setKey —— 加密状态bool isEncrypted() const; // 是否启用加密 void setKey(const uint8_t *lmk); // 设置本地主密钥LMKsetKey()传入非空 LMK 即启用加密传入nullptr则关闭Peer 已添加时通过esp_now_mod_peer()实时更新ESP32_NOW.cpp。3.9 onReceive / onSent —— 子类必须实现的虚方法// 处理来自该 Peer 的接收数据 void onReceive(const uint8_t *data, int len, bool broadcast); // 处理向该 Peer 发送数据的完成事件 void onSent(bool success);onReceive参数data为数据指针len为长度broadcast为true表示广播消息、false表示单播onSent参数success为true表示发送成功。基类提供了打印日志的默认实现ESP32_NOW.h上层子类必须按需重写。发送完成回调_esp_now_tx_cb会根据目标 MAC 在 Peer 列表中查找对应对象并触发其onSentESP32_NOW.cpp。3.10 operator bool源码补充 APIESP_NOW_Peer还重载了operator bool()ESP32_NOW.cpp返回内部added标志可直接用if (peer)判断该 Peer 是否已成功注册。四、加密机制PMK 与 LMK仓库的 Network 示例ESP_NOW_Network.ino头部注释对 ESP-NOW 加密机制做了权威说明现归纳如下ESP-NOW 采用CCMP 加密方法IEEE Std. 802.11-2012保护厂商自定义 Action 帧设备维护一个PMKPrimary Master Key和若干LMKLocal Master Key两者长度均需为16 字节PMK 用于以 AES-128 算法加密 LMK。若未设置 PMK则使用默认 PMKbegin(pmk)传入的正是该密钥配对设备的 LMK 用于以 CCMP 方法加密数据帧。每台设备最多支持 6 个不同的 LMK若未设置 LMK则帧不加密广播组播帧不支持加密因此以广播地址注册的 Peer 必须传nullptr作为 LMKPMK 必须全网一致LMK 只需在配对设备之间一致。Network 示例中的密钥定义可供参考#define ESPNOW_EXAMPLE_PMK pmk1234567890123 #define ESPNOW_EXAMPLE_LMK lmk1234567890123 // 使用方式ESP_NOW.begin((const uint8_t *)ESPNOW_EXAMPLE_PMK);五、实战示例从广播到组网仓库libraries/ESP_NOW/examples/下提供了 4 个示例ESP_NOW_Broadcast_Master、ESP_NOW_Broadcast_Slave、ESP_NOW_Serial、ESP_NOW_Network其中前三个由文档直接引用。5.1 广播主设备Broadcast Master示例文件ESP_NOW_Broadcast_Master.ino核心思路创建一个以广播地址0xFF:FF:FF:FF:FF:FF为目标的 Peer向网络内所有设备广播消息。全局常量ESP_NOW.BROADCAST_ADDR即广播地址ESP32_NOW.h。#include Arduino.h #include ESP32_NOW.h #include WiFi.h #include esp_mac.h // MAC2STR / MACSTR 宏 #define ESPNOW_WIFI_CHANNEL 6 // 必须继承 ESP_NOW_Peer class ESP_NOW_Broadcast_Peer : public ESP_NOW_Peer { public: ESP_NOW_Broadcast_Peer(uint8_t channel, wifi_interface_t iface, const uint8_t *lmk) : ESP_NOW_Peer(ESP_NOW.BROADCAST_ADDR, channel, iface, lmk) {} ~ESP_NOW_Broadcast_Peer() { remove(); } bool begin() { if (!ESP_NOW.begin() || !add()) { log_e(Failed to initialize ESP-NOW or register the broadcast peer); return false; } return true; } bool send_message(const uint8_t *data, size_t len) { if (!send(data, len)) { log_e(Failed to broadcast message); return false; } return true; } }; ESP_NOW_Broadcast_Peer broadcast_peer(ESPNOW_WIFI_CHANNEL, WIFI_IF_STA, nullptr); void setup() { Serial.begin(115200); WiFi.mode(WIFI_STA); WiFi.setChannel(ESPNOW_WIFI_CHANNEL); while (!WiFi.STA.started()) delay(100); if (!broadcast_peer.begin()) { Serial.println(Failed to initialize broadcast peer); delay(5000); ESP.restart(); } Serial.printf(ESP-NOW version: %d, max data length: %d\n, ESP_NOW.getVersion(), ESP_NOW.getMaxDataLen()); } void loop() { char data[32]; static uint32_t msg_count 0; snprintf(data, sizeof(data), Hello, World! #% PRIu32, msg_count); broadcast_peer.send_message((uint8_t *)data, sizeof(data)); delay(5000); }要点Wi-Fi 需先设为 STA 模式并固定信道WiFi.setChannel(ESPNOW_WIFI_CHANNEL)广播 Peer 使用WIFI_IF_STA接口且 LMK 传nullptr广播帧不支持加密。5.2 广播从设备Broadcast Slave示例文件ESP_NOW_Broadcast_Slave.ino核心思路从设备不预先注册任何 Peer而是借助ESP_NOW.onNewPeer回调动态发现并注册主设备class ESP_NOW_Peer_Class : public ESP_NOW_Peer { public: ESP_NOW_Peer_Class(const uint8_t *mac_addr, uint8_t channel, wifi_interface_t iface, const uint8_t *lmk) : ESP_NOW_Peer(mac_addr, channel, iface, lmk) {} bool add_peer() { return add(); } // 重写接收回调 void onReceive(const uint8_t *data, size_t len, bool broadcast) { Serial.printf(Received a message from master MACSTR (%s)\n, MAC2STR(addr()), broadcast ? broadcast : unicast); Serial.printf( Message: %s\n, (char *)data); } }; std::vectorESP_NOW_Peer_Class * masters; // 未知设备发来消息时回调 void register_new_master(const esp_now_recv_info_t *info, const uint8_t *data, int len, void *arg) { if (memcmp(info-des_addr, ESP_NOW.BROADCAST_ADDR, 6) 0) { Serial.printf(Unknown peer MACSTR sent a broadcast message\n, MAC2STR(info-src_addr)); ESP_NOW_Peer_Class *new_master new ESP_NOW_Peer_Class( info-src_addr, ESPNOW_WIFI_CHANNEL, WIFI_IF_STA, nullptr); if (!new_master-add_peer()) { delete new_master; return; } masters.push_back(new_master); } } void setup() { Serial.begin(115200); WiFi.mode(WIFI_STA); WiFi.setChannel(ESPNOW_WIFI_CHANNEL); while (!WiFi.STA.started()) delay(100); if (!ESP_NOW.begin()) { /* 处理失败 */ } ESP_NOW.onNewPeer(register_new_master, nullptr); Serial.println(Setup complete. Waiting for a master to broadcast a message...); }示例注释特别提醒masters容器应存储指针而非对象以避免 vector 重分配时产生悬垂指针。onReceive中的broadcast参数在底层由_esp_now_rx_cb通过比较目的地址与BROADCAST_ADDR计算得出ESP32_NOW.cpp。5.3 串口流式传输ESP_NOW_Serial示例文件ESP_NOW_Serial.ino配套类见 ESP32_NOW_Serial.h 与 ESP32_NOW_Serial.cpp。ESP_NOW_Serial_Class同时继承Stream与ESP_NOW_Peer把 ESP-NOW 通道伪装成一个串口两个 ESP32 之间可以像操作Serial一样互相收发数据。示例采用单播unicast模式并指出关键事实不同接口使用不同的 MAC 地址设备可分别处于 AP 或 Station 模式唯一要求是处于同一 Wi-Fi 信道。#include Arduino.h #include ESP32_NOW_Serial.h #include MacAddress.h #include WiFi.h #include esp_wifi.h #define ESPNOW_WIFI_MODE_STATION 1 #define ESPNOW_WIFI_CHANNEL 1 #if ESPNOW_WIFI_MODE_STATION #define ESPNOW_WIFI_MODE WIFI_STA #define ESPNOW_WIFI_IF WIFI_IF_STA #else #define ESPNOW_WIFI_MODE WIFI_AP #define ESPNOW_WIFI_IF WIFI_IF_AP #endif // 对端设备 MAC 地址按实际情况修改 const MacAddress peer_mac({0xF4, 0x12, 0xFA, 0x40, 0x64, 0x4C}); ESP_NOW_Serial_Class NowSerial(peer_mac, ESPNOW_WIFI_CHANNEL, ESPNOW_WIFI_IF); void setup() { Serial.begin(115200); WiFi.mode(ESPNOW_WIFI_MODE); WiFi.setChannel(ESPNOW_WIFI_CHANNEL, WIFI_SECOND_CHAN_NONE); while (!(WiFi.STA.started() || WiFi.AP.started())) delay(100); NowSerial.begin(115200); Serial.printf(ESP-NOW version: %d, max data length: %d\n, ESP_NOW.getVersion(), ESP_NOW.getMaxDataLen()); } void loop() { while (NowSerial.available()) Serial.write(NowSerial.read()); // 收 while (Serial.available() NowSerial.availableForWrite()) { // 发 if (NowSerial.write(Serial.read()) 0) break; } delay(1); }实现层面的亮点ESP32_NOW_Serial.cpp发送缓冲使用 FreeRTOS RingbufferxRingbufferCreatewrite()将数据压入环形缓冲后由发送回调驱动发送接收缓冲使用 FreeRTOS QueuexQueueCreateonReceive逐字节入队available()/read()/peek()对应队列操作自动分包与超长截断checkForTxData()每次最多取ESP_NOW.getMaxDataLen()字节天然适配 v1250B与 v21470B两种协议版本且begin()会按版本自动设置缓冲大小v2 为 4096v1 为 1024均容纳约 3-4 个包失败重传onSent(false)时最多重传 5 次超过后丢弃该包若构造时remove_on_fail为true则直接移除 Peer。5.4 多设备自组网ESP_NOW_Network示例文件ESP_NOW_Network.ino这是最复杂的示例演示如何构建一个自动选主的自组织网络流程如下每个设备根据自身 MAC 地址后 3 字节生成一个priority设备通过广播地址周期性广播自己的优先级各设备监听广播并登记其他设备的优先级借助onNewPeer回调动态new出 Peer全部 Peer 就绪后优先级最高的设备自动成为 master其余为 slaveslave 每 5 秒向 master 上报随机数据并每隔REPORT_INTERVAL条消息向其他 slave 发送Hello!master 计算收到的数据平均值定期回传给所有 slave。其中esp_now_data_t结构体使用__attribute__((packed))确保内存紧凑、无填充字节并给出了 v1/v2 的负载上限参考typedef struct { uint32_t count; uint32_t priority; uint32_t data; bool ready; char str[7]; } __attribute__((packed)) esp_now_data_t;该示例同时演示了 PMK/LMK 的实际用法ESP_NOW.begin((const uint8_t *)ESPNOW_EXAMPLE_PMK)设置全网主密钥Peer 构造时传入ESPNOW_EXAMPLE_LMK启用加密广播 Peer 除外。六、多设备验证测试九阶段全面覆盖仓库在 tests/validation/esp_now/test_esp_now.py 提供了双设备master/slave的自动化验证脚本从测试视角再次印证了本文所有 API 的行为约定阶段覆盖内容1初始化、未 begin 时的边界行为getVersion/getMaxDataLen/getTotalPeerCount均返回 -1、master 广播触发onNewPeer2slave 广播 broadcast标志位验证3-4双向单播master→slave、slave→master5Peer 管理总数/加密数统计、addr()读写、setRate()边界已添加时调用必须失败、setKey后加密数变化6加密单播7最大长度负载严格断言收发字节数等于max_data_len即 250 或 14708Peer 移除/重新添加operator bool由 true→false→true总数 2→1→29end()/begin()生命周期 ESP_NOW.write()向所有 Peer 发送此外每个示例目录下的ci.yml都声明了requires: CONFIG_SOC_WIFI_SUPPORTEDy即 CI 仅在支持 Wi-Fi 的 SoC 上运行这些示例。七、使用注意事项与最佳实践综合文档、源码与示例总结以下实战要点芯片限制仅 ESP32 系列原生 Wi-Fi SoC受支持Hosted 模式芯片编译时会直接告警见 ESP32_NOW.h必须begin()先行所有查询类 APIgetVersion、getMaxDataLen、getTotalPeerCount等在未初始化时返回 -1发送类 API 返回 0固定信道所有设备必须处于同一 Wi-Fi 信道示例统一使用WiFi.setChannel()且 Peer 的信道要与实际一致继承而非直接用ESP_NOW_Peer是抽象类必须子类化并实现onReceive/onSentadd/remove/send是protected方法需通过子类公开包装见 ESP32_NOW.h运行期不可变项addr()设置与setRate()必须在 Peer 添加前或 ESP-NOW 启动前调用否则失败广播不加密广播 Peer 的 LMK 必须为nullptrPMK 全网一致、LMK 仅需配对设备一致两者均为 16 字节负载上限v1.0 单包最大 250 字节、v2.0 最大 1470 字节超出部分会被send()/write()自动截断务必用ESP_NOW.getMaxDataLen()动态查询数据包结构推荐使用__attribute__((packed))结构体承载业务字段见 Network 示例避免跨设备字节对齐不一致。结语从 API 文档 到 库源码从四个可直接运行的示例到覆盖九个阶段的自动化测试Arduino-ESP32 的 ESP-NOW 库提供了从单播、广播、加密到串口流式与自组网的完整能力。无论是制作一对遥控器、一组传感器节点还是构建去中心化的多设备网络这套 API 都能让你以最少的样板代码实现设备间的直接通信。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Arduino-ESP32 ESP-NOW 通信库完全指南Peer 管理、加密传输与多设备实战【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32导读ESP-NOW 是乐鑫Espressif为 ESP32 系列芯片设计的一种无连接connectionless通信协议它允许设备之间在**不需要接入点AP**的情况下直接进行低功耗、低延迟、高吞吐的数据交换。本指南基于 Arduino-ESP32 仓库中内置的ESP_NOW库文档原文系统讲解ESP_NOW_Class与ESP_NOW_Peer两大核心类的全部 API并结合仓库源码、示例工程与多设备验证测试给出可直接复制运行的广播、单播、加密与串口流式传输方案。读完本文你将掌握如何在 ESP32 设备间搭建去中心化的点对点通信网络并理解其底层实现原理。一、ESP-NOW 协议概述与适用场景ESP-NOW 是一种专为 ESP32 设备间通信设计的协议核心特点是无需 AP 中转设备直接点对点通信适合局域网内的直连场景低功耗、低延迟、高吞吐相比传统 Wi-Fi 连接开销更小、响应更快应用广泛可用于智能灯、遥控设备、传感器等物联网场景。该库为 ESP-NOW 通信提供了一套易用的接口涵盖初始化、添加/移除 Peer、发送/接收数据包等完整流程。需要特别注意的是文档原文 中的明确说明本库仅在 ESP32 系列芯片上测试过与 ESP8266 或其他非 ESP32 平台的互操作性不作保证。从源码看这一约束也有硬性实现依据ESP32_NOW.h 与 ESP32_NOW.cpp 均以CONFIG_ESP_HOSTED_ENABLED宏做编译期防护——当芯片只有 Hosted外挂 Wi-Fi 协处理器模式而缺乏原生 Wi-Fi 时编译会直接发出ESP-NOW is only supported in SoCs with native Wi-Fi support警告。库元数据library.properties也声明architecturesesp32即仅面向 ESP32 平台。二、ESP_NOW_Class全局管理类ESP_NOW_Class是管理 ESP-NOW 通信的主类仓库在 ESP32_NOW.h 中定义并默认提供全局实例ESP_NOW见 ESP32_NOW.h 与 ESP32_NOW.cpp。它继承自 ArduinoPrint因此还支持流式写接口。2.1 begin —— 初始化 ESP-NOWbool begin(const uint8_t *pmk NULL);pmk可选参数若启用加密传入成对主密钥Pairwise Master KeyPMK长度为 16 字节返回值初始化成功返回true失败返回false必须在调用其他任何 ESP-NOW 功能之前调用。源码实现揭示了 begin 内部的完整初始化链路ESP32_NOW.cpp若已初始化_esp_now_has_begun直接返回true幂等调用esp_wifi_start()启动 Wi-Fi调用esp_now_get_version()获取 ESP-NOW 版本号据此设置max_data_lenv1.0 为 250 字节ESP_NOW_MAX_DATA_LENv2.0 为 1470 字节ESP_NOW_MAX_DATA_LEN_V2调用esp_now_init()初始化协议栈为已登记的 Peer 统一设置 PHY 速率_esp_now_set_all_peers_rate()若传入pmk调用esp_now_set_pmk(pmk)设置主密钥注册接收回调_esp_now_rx_cb与发送完成回调_esp_now_tx_cb。2.2 end —— 结束通信并释放资源bool end();结束 ESP-NOW 通信并释放库占用的全部资源。从实现看ESP32_NOW.cppend()会先遍历并移除所有已注册的 Peer再调用esp_now_deinit()反初始化协议栈最后清空内部 Peer 列表。2.3 查询当前 Peer 数量int getTotalPeerCount(); // 当前已添加的 Peer 总数 int getEncryptedPeerCount(); // 使用加密的 Peer 数量两者均返回 Peer 数量出错时返回 -1。例如在 ESP-NOW 尚未初始化时实现会打印ESP-NOW not initialized并返回 -1ESP32_NOW.cpp。它们底层分别读取esp_now_get_peer_num()返回结构体中的total_num与encrypt_num字段。2.4 版本与最大数据长度源码补充 API文档之外源码还提供了两个极具实用价值的查询方法ESP32_NOW.hint getMaxDataLen() const; // 当前固件支持的最大单包数据长度 int getVersion() const; // 当前 ESP-NOW 协议版本这两个方法在未初始化时返回 -1并在初始化后分别返回 250/1470 与 1/2ESP32_NOW.cpp。所有官方示例在begin()之后都会打印Serial.printf(ESP-NOW version: %d, max data length: %d\n, ESP_NOW.getVersion(), ESP_NOW.getMaxDataLen());2.5 onNewPeer —— 新 Peer 数据回调当收到来自未注册 Peer的数据时可通过onNewPeer注册回调函数来处理void onNewPeer(void (*cb)(const esp_now_recv_info_t *info, const uint8_t *data, int len, void *arg), void *arg);cb回调函数指针arg可选传递给回调的用户自定义参数。回调函数签名void cb(const esp_now_recv_info_t *info, const uint8_t *data, int len, void *arg);info接收数据包的信息含源/目的 MAC 地址等data接收到的数据指针len接收数据的长度arg用户自定义参数。源码层面onNewPeer只是将回调保存在静态变量new_cb/new_arg中ESP32_NOW.cpp真正的分发逻辑在接收回调_esp_now_rx_cb中ESP32_NOW.cpp先判断目的地址是否为广播地址0xFF:FF:FF:FF:FF:FF若源地址不是已注册 Peer 且new_cb非空则调用new_cb并返回——这正是动态发现新设备的机制否则在内部 Peer 列表中查找源 MAC 对应的ESP_NOW_Peer对象调用其onReceive(data, len, broadcast)虚方法。2.6 write —— 向所有 Peer 直接发送源码补充 API由于ESP_NOW_Class继承自Print它还提供了流式写接口ESP32_NOW.hsize_t write(const uint8_t *data, size_t len); // 向所有已注册 Peer 发送无需指定 MAC size_t write(uint8_t data); // 单字节重载write底层调用esp_now_send(nullptr, data, len)nullptr表示广播给所有已登记 Peer超长数据会被截断到max_data_lenESP32_NOW.cpp。配套的availableForWrite()返回当前可写字节数。三、ESP_NOW_PeerPeer 设备类ESP_NOW_Peer表示 ESP-NOW 网络中的一个对端设备ESP32_NOW.h。它是一个抽象类必须由子类继承并在子类中实现onReceive与onSent两个虚方法以正确处理连接与收发事件。3.1 构造函数ESP_NOW_Peer(const uint8_t *mac_addr, uint8_t channel, wifi_interface_t iface, const uint8_t *lmk);mac_addr对端设备的 MAC 地址6 字节channel通信信道iface使用的 Wi-Fi 接口WIFI_IF_STA或WIFI_IF_APlmk可选若启用加密传入本地主密钥Local Master KeyLMK。从 ESP32_NOW.cpp 可以看到构造函数会保存 MAC、信道、接口并根据lmk是否为空设置encrypt标志位同时设置默认 PHY 速率配置#define DEFAULT_ESPNOW_RATE_CONFIG { \ .phymode WIFI_PHY_MODE_11G, \ .rate WIFI_PHY_RATE_1M_L, \ .ersu false, \ .dcm false \ }默认以 802.11g、1 Mbps 长前导Long preamble速率通信可通过setRate()覆盖。3.2 add / remove —— 注册与注销 Peerbool add(); // 将对端添加到 ESP-NOW 网络成功返回 true bool remove(); // 将对端从网络移除成功返回 trueadd()内部调用esp_now_add_peer()完成注册ESP32_NOW.cpp。底层辅助函数_esp_now_add_peerESP32_NOW.cpp展示了关键细节若该 MAC 已是 Peer返回ESP_ERR_ESPNOW_EXIST填充esp_now_peer_info_t信道、接口、加密标志与 LMK注册成功后把ESP_NOW_Peer*存入静态数组_esp_now_peers容量ESP_NOW_MAX_TOTAL_PEER_NUM若 ESP-NOW 已在运行还会调用esp_now_set_peer_rate_config()应用该 Peer 的 PHY 速率。remove()则调用esp_now_del_peer()并把内部数组中对应条目清空ESP32_NOW.cpp。3.3 send —— 发送数据size_t send(const uint8_t *data, int len);data待发送数据指针len数据长度字节返回值实际发送的字节数出错返回 0。实现ESP32_NOW.cpp会先校验 ESP-NOW 已初始化且 Peer 已添加否则报Peer not added.并返回 0然后通过ESP_NOW.getMaxDataLen()获取上限并将超长数据截断最后调用esp_now_send(mac, data, len)定向发送。3.4 addr —— MAC 地址读写const uint8_t * addr() const; // 获取对端 MAC 地址 void addr(const uint8_t *mac_addr); // 设置对端 MAC 地址注意源码实现ESP32_NOW.cppaddr()的设置版本在 Peer 已添加且 ESP-NOW 已在运行时会失败返回false并提示请在添加 Peer 之前或启动 ESP-NOW 之前调用 addr()。因此 MAC 地址应尽量在构造对象时确定。3.5 getChannel / setChannel —— 信道读写uint8_t getChannel() const; // 获取通信信道 void setChannel(uint8_t channel); // 设置通信信道setChannel()在 Peer 已添加时会调用esp_now_mod_peer()实时修改底层 Peer 信息ESP32_NOW.cpp未运行时则仅更新内部字段。3.6 getInterface / setInterface —— Wi-Fi 接口读写wifi_interface_t getInterface() const; // 获取 Wi-Fi 接口 void setInterface(wifi_interface_t iface); // 设置 Wi-Fi 接口WIFI_IF_STA / WIFI_IF_AP行为与信道读写一致已运行时通过esp_now_mod_peer()实时生效ESP32_NOW.cpp。3.7 速率配置 setRate / getRate源码补充 APIbool setRate(const esp_now_rate_config_t *rate_config); esp_now_rate_config_t getRate() const;setRate()用于配置 Peer 的 PHY 速率传nullptr恢复默认配置ESP32_NOW.cpp。限制只能在 Peer 添加之前或 ESP-NOW 启动之前调用否则返回false并打印错误提示——这与addr()的行为一致属于运行期不可变配置项。3.8 isEncrypted / setKey —— 加密状态bool isEncrypted() const; // 是否启用加密 void setKey(const uint8_t *lmk); // 设置本地主密钥LMKsetKey()传入非空 LMK 即启用加密传入nullptr则关闭Peer 已添加时通过esp_now_mod_peer()实时更新ESP32_NOW.cpp。3.9 onReceive / onSent —— 子类必须实现的虚方法// 处理来自该 Peer 的接收数据 void onReceive(const uint8_t *data, int len, bool broadcast); // 处理向该 Peer 发送数据的完成事件 void onSent(bool success);onReceive参数data为数据指针len为长度broadcast为true表示广播消息、false表示单播onSent参数success为true表示发送成功。基类提供了打印日志的默认实现ESP32_NOW.h上层子类必须按需重写。发送完成回调_esp_now_tx_cb会根据目标 MAC 在 Peer 列表中查找对应对象并触发其onSentESP32_NOW.cpp。3.10 operator bool源码补充 APIESP_NOW_Peer还重载了operator bool()ESP32_NOW.cpp返回内部added标志可直接用if (peer)判断该 Peer 是否已成功注册。四、加密机制PMK 与 LMK仓库的 Network 示例ESP_NOW_Network.ino头部注释对 ESP-NOW 加密机制做了权威说明现归纳如下ESP-NOW 采用CCMP 加密方法IEEE Std. 802.11-2012保护厂商自定义 Action 帧设备维护一个PMKPrimary Master Key和若干LMKLocal Master Key两者长度均需为16 字节PMK 用于以 AES-128 算法加密 LMK。若未设置 PMK则使用默认 PMKbegin(pmk)传入的正是该密钥配对设备的 LMK 用于以 CCMP 方法加密数据帧。每台设备最多支持 6 个不同的 LMK若未设置 LMK则帧不加密广播组播帧不支持加密因此以广播地址注册的 Peer 必须传nullptr作为 LMKPMK 必须全网一致LMK 只需在配对设备之间一致。Network 示例中的密钥定义可供参考#define ESPNOW_EXAMPLE_PMK pmk1234567890123 #define ESPNOW_EXAMPLE_LMK lmk1234567890123 // 使用方式ESP_NOW.begin((const uint8_t *)ESPNOW_EXAMPLE_PMK);五、实战示例从广播到组网仓库libraries/ESP_NOW/examples/下提供了 4 个示例ESP_NOW_Broadcast_Master、ESP_NOW_Broadcast_Slave、ESP_NOW_Serial、ESP_NOW_Network其中前三个由文档直接引用。5.1 广播主设备Broadcast Master示例文件ESP_NOW_Broadcast_Master.ino核心思路创建一个以广播地址0xFF:FF:FF:FF:FF:FF为目标的 Peer向网络内所有设备广播消息。全局常量ESP_NOW.BROADCAST_ADDR即广播地址ESP32_NOW.h。#include Arduino.h #include ESP32_NOW.h #include WiFi.h #include esp_mac.h // MAC2STR / MACSTR 宏 #define ESPNOW_WIFI_CHANNEL 6 // 必须继承 ESP_NOW_Peer class ESP_NOW_Broadcast_Peer : public ESP_NOW_Peer { public: ESP_NOW_Broadcast_Peer(uint8_t channel, wifi_interface_t iface, const uint8_t *lmk) : ESP_NOW_Peer(ESP_NOW.BROADCAST_ADDR, channel, iface, lmk) {} ~ESP_NOW_Broadcast_Peer() { remove(); } bool begin() { if (!ESP_NOW.begin() || !add()) { log_e(Failed to initialize ESP-NOW or register the broadcast peer); return false; } return true; } bool send_message(const uint8_t *data, size_t len) { if (!send(data, len)) { log_e(Failed to broadcast message); return false; } return true; } }; ESP_NOW_Broadcast_Peer broadcast_peer(ESPNOW_WIFI_CHANNEL, WIFI_IF_STA, nullptr); void setup() { Serial.begin(115200); WiFi.mode(WIFI_STA); WiFi.setChannel(ESPNOW_WIFI_CHANNEL); while (!WiFi.STA.started()) delay(100); if (!broadcast_peer.begin()) { Serial.println(Failed to initialize broadcast peer); delay(5000); ESP.restart(); } Serial.printf(ESP-NOW version: %d, max data length: %d\n, ESP_NOW.getVersion(), ESP_NOW.getMaxDataLen()); } void loop() { char data[32]; static uint32_t msg_count 0; snprintf(data, sizeof(data), Hello, World! #% PRIu32, msg_count); broadcast_peer.send_message((uint8_t *)data, sizeof(data)); delay(5000); }要点Wi-Fi 需先设为 STA 模式并固定信道WiFi.setChannel(ESPNOW_WIFI_CHANNEL)广播 Peer 使用WIFI_IF_STA接口且 LMK 传nullptr广播帧不支持加密。5.2 广播从设备Broadcast Slave示例文件ESP_NOW_Broadcast_Slave.ino核心思路从设备不预先注册任何 Peer而是借助ESP_NOW.onNewPeer回调动态发现并注册主设备class ESP_NOW_Peer_Class : public ESP_NOW_Peer { public: ESP_NOW_Peer_Class(const uint8_t *mac_addr, uint8_t channel, wifi_interface_t iface, const uint8_t *lmk) : ESP_NOW_Peer(mac_addr, channel, iface, lmk) {} bool add_peer() { return add(); } // 重写接收回调 void onReceive(const uint8_t *data, size_t len, bool broadcast) { Serial.printf(Received a message from master MACSTR (%s)\n, MAC2STR(addr()), broadcast ? broadcast : unicast); Serial.printf( Message: %s\n, (char *)data); } }; std::vectorESP_NOW_Peer_Class * masters; // 未知设备发来消息时回调 void register_new_master(const esp_now_recv_info_t *info, const uint8_t *data, int len, void *arg) { if (memcmp(info-des_addr, ESP_NOW.BROADCAST_ADDR, 6) 0) { Serial.printf(Unknown peer MACSTR sent a broadcast message\n, MAC2STR(info-src_addr)); ESP_NOW_Peer_Class *new_master new ESP_NOW_Peer_Class( info-src_addr, ESPNOW_WIFI_CHANNEL, WIFI_IF_STA, nullptr); if (!new_master-add_peer()) { delete new_master; return; } masters.push_back(new_master); } } void setup() { Serial.begin(115200); WiFi.mode(WIFI_STA); WiFi.setChannel(ESPNOW_WIFI_CHANNEL); while (!WiFi.STA.started()) delay(100); if (!ESP_NOW.begin()) { /* 处理失败 */ } ESP_NOW.onNewPeer(register_new_master, nullptr); Serial.println(Setup complete. Waiting for a master to broadcast a message...); }示例注释特别提醒masters容器应存储指针而非对象以避免 vector 重分配时产生悬垂指针。onReceive中的broadcast参数在底层由_esp_now_rx_cb通过比较目的地址与BROADCAST_ADDR计算得出ESP32_NOW.cpp。5.3 串口流式传输ESP_NOW_Serial示例文件ESP_NOW_Serial.ino配套类见 ESP32_NOW_Serial.h 与 ESP32_NOW_Serial.cpp。ESP_NOW_Serial_Class同时继承Stream与ESP_NOW_Peer把 ESP-NOW 通道伪装成一个串口两个 ESP32 之间可以像操作Serial一样互相收发数据。示例采用单播unicast模式并指出关键事实不同接口使用不同的 MAC 地址设备可分别处于 AP 或 Station 模式唯一要求是处于同一 Wi-Fi 信道。#include Arduino.h #include ESP32_NOW_Serial.h #include MacAddress.h #include WiFi.h #include esp_wifi.h #define ESPNOW_WIFI_MODE_STATION 1 #define ESPNOW_WIFI_CHANNEL 1 #if ESPNOW_WIFI_MODE_STATION #define ESPNOW_WIFI_MODE WIFI_STA #define ESPNOW_WIFI_IF WIFI_IF_STA #else #define ESPNOW_WIFI_MODE WIFI_AP #define ESPNOW_WIFI_IF WIFI_IF_AP #endif // 对端设备 MAC 地址按实际情况修改 const MacAddress peer_mac({0xF4, 0x12, 0xFA, 0x40, 0x64, 0x4C}); ESP_NOW_Serial_Class NowSerial(peer_mac, ESPNOW_WIFI_CHANNEL, ESPNOW_WIFI_IF); void setup() { Serial.begin(115200); WiFi.mode(ESPNOW_WIFI_MODE); WiFi.setChannel(ESPNOW_WIFI_CHANNEL, WIFI_SECOND_CHAN_NONE); while (!(WiFi.STA.started() || WiFi.AP.started())) delay(100); NowSerial.begin(115200); Serial.printf(ESP-NOW version: %d, max data length: %d\n, ESP_NOW.getVersion(), ESP_NOW.getMaxDataLen()); } void loop() { while (NowSerial.available()) Serial.write(NowSerial.read()); // 收 while (Serial.available() NowSerial.availableForWrite()) { // 发 if (NowSerial.write(Serial.read()) 0) break; } delay(1); }实现层面的亮点ESP32_NOW_Serial.cpp发送缓冲使用 FreeRTOS RingbufferxRingbufferCreatewrite()将数据压入环形缓冲后由发送回调驱动发送接收缓冲使用 FreeRTOS QueuexQueueCreateonReceive逐字节入队available()/read()/peek()对应队列操作自动分包与超长截断checkForTxData()每次最多取ESP_NOW.getMaxDataLen()字节天然适配 v1250B与 v21470B两种协议版本且begin()会按版本自动设置缓冲大小v2 为 4096v1 为 1024均容纳约 3-4 个包失败重传onSent(false)时最多重传 5 次超过后丢弃该包若构造时remove_on_fail为true则直接移除 Peer。5.4 多设备自组网ESP_NOW_Network示例文件ESP_NOW_Network.ino这是最复杂的示例演示如何构建一个自动选主的自组织网络流程如下每个设备根据自身 MAC 地址后 3 字节生成一个priority设备通过广播地址周期性广播自己的优先级各设备监听广播并登记其他设备的优先级借助onNewPeer回调动态new出 Peer全部 Peer 就绪后优先级最高的设备自动成为 master其余为 slaveslave 每 5 秒向 master 上报随机数据并每隔REPORT_INTERVAL条消息向其他 slave 发送Hello!master 计算收到的数据平均值定期回传给所有 slave。其中esp_now_data_t结构体使用__attribute__((packed))确保内存紧凑、无填充字节并给出了 v1/v2 的负载上限参考typedef struct { uint32_t count; uint32_t priority; uint32_t data; bool ready; char str[7]; } __attribute__((packed)) esp_now_data_t;该示例同时演示了 PMK/LMK 的实际用法ESP_NOW.begin((const uint8_t *)ESPNOW_EXAMPLE_PMK)设置全网主密钥Peer 构造时传入ESPNOW_EXAMPLE_LMK启用加密广播 Peer 除外。六、多设备验证测试九阶段全面覆盖仓库在 tests/validation/esp_now/test_esp_now.py 提供了双设备master/slave的自动化验证脚本从测试视角再次印证了本文所有 API 的行为约定阶段覆盖内容1初始化、未 begin 时的边界行为getVersion/getMaxDataLen/getTotalPeerCount均返回 -1、master 广播触发onNewPeer2slave 广播 broadcast标志位验证3-4双向单播master→slave、slave→master5Peer 管理总数/加密数统计、addr()读写、setRate()边界已添加时调用必须失败、setKey后加密数变化6加密单播7最大长度负载严格断言收发字节数等于max_data_len即 250 或 14708Peer 移除/重新添加operator bool由 true→false→true总数 2→1→29end()/begin()生命周期 ESP_NOW.write()向所有 Peer 发送此外每个示例目录下的ci.yml都声明了requires: CONFIG_SOC_WIFI_SUPPORTEDy即 CI 仅在支持 Wi-Fi 的 SoC 上运行这些示例。七、使用注意事项与最佳实践综合文档、源码与示例总结以下实战要点芯片限制仅 ESP32 系列原生 Wi-Fi SoC受支持Hosted 模式芯片编译时会直接告警见 ESP32_NOW.h必须begin()先行所有查询类 APIgetVersion、getMaxDataLen、getTotalPeerCount等在未初始化时返回 -1发送类 API 返回 0固定信道所有设备必须处于同一 Wi-Fi 信道示例统一使用WiFi.setChannel()且 Peer 的信道要与实际一致继承而非直接用ESP_NOW_Peer是抽象类必须子类化并实现onReceive/onSentadd/remove/send是protected方法需通过子类公开包装见 ESP32_NOW.h运行期不可变项addr()设置与setRate()必须在 Peer 添加前或 ESP-NOW 启动前调用否则失败广播不加密广播 Peer 的 LMK 必须为nullptrPMK 全网一致、LMK 仅需配对设备一致两者均为 16 字节负载上限v1.0 单包最大 250 字节、v2.0 最大 1470 字节超出部分会被send()/write()自动截断务必用ESP_NOW.getMaxDataLen()动态查询数据包结构推荐使用__attribute__((packed))结构体承载业务字段见 Network 示例避免跨设备字节对齐不一致。结语从 API 文档 到 库源码从四个可直接运行的示例到覆盖九个阶段的自动化测试Arduino-ESP32 的 ESP-NOW 库提供了从单播、广播、加密到串口流式与自组网的完整能力。无论是制作一对遥控器、一组传感器节点还是构建去中心化的多设备网络这套 API 都能让你以最少的样板代码实现设备间的直接通信。【免费下载链接】arduino-esp32Arduino core for the ESP32 family of SoCs项目地址: https://gitcode.com/GitHub_Trending/ar/arduino-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
