diff --git a/components/esp_wifi/include/esp_now.h b/components/esp_wifi/include/esp_now.h index de41a87936..923bac0eb4 100644 --- a/components/esp_wifi/include/esp_now.h +++ b/components/esp_wifi/include/esp_now.h @@ -190,7 +190,7 @@ esp_err_t esp_now_unregister_send_cb(void); * - ESP_ERR_ESPNOW_NOT_INIT : ESPNOW is not initialized * - ESP_ERR_ESPNOW_ARG : invalid argument * - ESP_ERR_ESPNOW_INTERNAL : internal error - * - ESP_ERR_ESPNOW_NO_MEM : out of memory + * - ESP_ERR_ESPNOW_NO_MEM : out of memory, when this happens, you can delay a while before sending the next data * - ESP_ERR_ESPNOW_NOT_FOUND : peer is not found * - ESP_ERR_ESPNOW_IF : current WiFi interface doesn't match that of peer */ diff --git a/components/esp_wifi/include/esp_wifi.h b/components/esp_wifi/include/esp_wifi.h index 3d62c5c297..db22a28456 100644 --- a/components/esp_wifi/include/esp_wifi.h +++ b/components/esp_wifi/include/esp_wifi.h @@ -498,7 +498,7 @@ esp_err_t esp_wifi_get_ps(wifi_ps_type_t *type); * @brief Set protocol type of specified interface * The default protocol is (WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) * - * @attention Currently we only support 802.11b or 802.11bg or 802.11bgn mode + * @attention Support 802.11b or 802.11bg or 802.11bgn or LR mode * * @param ifx interfaces * @param protocol_bitmap WiFi protocol bitmap diff --git a/docs/en/api-guides/wifi.rst b/docs/en/api-guides/wifi.rst index dc4a7b4056..b2bd1a4986 100644 --- a/docs/en/api-guides/wifi.rst +++ b/docs/en/api-guides/wifi.rst @@ -5,8 +5,9 @@ Wi-Fi Driver {IDF_TARGET_NAME} Wi-Fi Feature List ------------------------------------ -- Support Station-only mode, AP-only mode, Station/AP-coexistence mode -- Support IEEE 802.11B, IEEE 802.11G, IEEE 802.11N and APIs to configure the protocol mode +- Support 4 virtual WiFi interfaces, which are 4 STA, AP, Sniffer and reserved. +- Support station-only mode, AP-only mode, station/AP-coexistence mode +- Support IEEE 802.11b, IEEE 802.11g, IEEE 802.11n, and APIs to configure the protocol mode - Support WPA/WPA2/WPA3/WPA2-Enterprise and WPS - Support AMPDU, HT40, QoS and other key features - Support Modem-sleep @@ -1202,37 +1203,31 @@ API esp_wifi_set_config() can be used to configure the AP. The table below descr Wi-Fi Protocol Mode +++++++++++++++++++++++++ -Currently, the IDF supports the following protocol modes: +Currently, the ESP-IDF supports the following protocol modes: + +.. list-table:: + :header-rows: 1 + :widths: 15 55 + + * - Protocol Mode + - Description + * - 802.11b + - Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B) to set the station/AP to 802.11b-only mode. + * - 802.11bg + - Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) to set the station/AP to 802.11bg mode. + * - 802.11g + - Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) and esp_wifi_config_11b_rate(ifx, true) to set the station/AP to 802.11g mode. + * - 802.11bgn + - Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) to set the station/ AP to BGN mode. + * - 802.11gn + - Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) and esp_wifi_config_11b_rate(ifx, true) to set the station/AP to 802.11gn mode. + * - 802.11 BGNLR + - Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR) to set the station/AP to BGN and the LR mode. + * - 802.11 LR + - Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR) to set the station/AP only to the LR mode. + + **This mode is an Espressif-patented mode which can achieve a one-kilometer line of sight range. Please make sure both the station and the AP are connected to an ESP device.** -+--------------------+------------------------------------------------------------+ -| Protocol Mode | Description | -+====================+============================================================+ -| 802.11 B | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B) to set | -| | the station/AP to 802.11B-only mode. | -| | | -+--------------------+------------------------------------------------------------+ -| 802.11 BG | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_ | -| | PROTOCOL_11G) to set the station/AP to 802.11BG mode. | -| | | -+--------------------+------------------------------------------------------------+ -| 802.11 BGN | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| | -| | WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) to set the station/ | -| | AP to BGN mode. | -| | | -+--------------------+------------------------------------------------------------+ -| 802.11 BGNLR | Call esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B| | -| | WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR) | -| | to set the station/AP to BGN and the | -| | Espressif-specific mode. | -+--------------------+------------------------------------------------------------+ -| 802.11 LR | Call esp_wifi_set_protocol (ifx, WIFI_PROTOCOL_LR) to set | -| | the station/AP only to the Espressif-specific mode. | -| | | -| | **This mode is an Espressif-patented mode which can achieve| -| | a one-kilometer line of sight range. Please, make sure both| -| | the station and the AP are connected to an | -| | ESP device** | -+--------------------+------------------------------------------------------------+ Long Range (LR) +++++++++++++++++++++++++ @@ -1292,7 +1287,7 @@ The reception sensitivity of LR has about 4 dB gain than the traditional 802.11B LR Throughput ************************* -The LR rate has very limited throughput because the raw PHY data rate LR is 1/2 Mbits and 1/4 Mbits. +The LR rate has very limited throughput, because the raw PHY data rates is 1/2 Mbps and 1/4 Mbps. When to Use LR ************************* @@ -1624,8 +1619,9 @@ Preconditions of Using :cpp:func:`esp_wifi_80211_tx` Data rate +++++++++++++++++++++++++++++++++++++++++++++++ - - If there is no Wi-Fi connection, the data rate is 1 Mbps. - - If there is Wi-Fi connection and the packet is from station to AP or from AP to station, the data rate is same as the Wi-Fi connection. Otherwise the data rate is 1 Mbps. + - The default data rate is 1 Mbps. + - Can set any rate through :cpp:func:`esp_wifi_config_80211_tx_rate()` API. + - Can set any bandwidth through :cpp:func:`esp_wifi_set_bandwidth()` API. Side-Effects to Avoid in Different Scenarios +++++++++++++++++++++++++++++++++++++++++++++++++++++ diff --git a/docs/en/api-reference/network/esp_now.rst b/docs/en/api-reference/network/esp_now.rst index 83df9f2cb9..9cbc63c8a2 100644 --- a/docs/en/api-reference/network/esp_now.rst +++ b/docs/en/api-reference/network/esp_now.rst @@ -64,8 +64,14 @@ When ``esp_now_deinit()`` is called, all of the information of paired devices wi Add Paired Device ----------------- -Call ``esp_now_add_peer()`` to add the device to the paired device list before you send data to this device. The maximum number of paired devices is twenty. If security is enabled, the LMK must be set. You can send ESP-NOW data via both the Station and the SoftAP interface. -Make sure that the interface is enabled before sending ESP-NOW data. A device with a broadcast MAC address must be added before sending broadcast data. The range of the channel of paired devices is from 0 to 14. If the channel is set to 0, data will be sent on the current channel. Otherwise, the channel must be set as the channel that the local device is on. +Call ``esp_now_add_peer()`` to add the device to the paired device list before you send data to this device. If security is enabled, the LMK must be set. You can send ESP-NOW data via both the Station and the SoftAP interface. Make sure that the interface is enabled before sending ESP-NOW data. +.. only:: esp32c2 + The maximum number of paired devices is 20, and the paired encryption devices are no more than 4, the default is 2. +.. only:: esp32c3 + The maximum number of paired devices is 20, and the paired encryption devices are no more than 10, the default is 6. +.. only:: esp32 or esp32s2 esp32s3 + The maximum number of paired devices is 20, and the paired encryption devices are no more than 16, the default is 6. +A device with a broadcast MAC address must be added before sending broadcast data. The range of the channel of paired devices is from 0 to 14. If the channel is set to 0, data will be sent on the current channel. Otherwise, the channel must be set as the channel that the local device is on. Send ESP-NOW Data ----------------- diff --git a/docs/zh_CN/api-guides/wifi.rst b/docs/zh_CN/api-guides/wifi.rst index dd114c6c7b..0affb05114 100644 --- a/docs/zh_CN/api-guides/wifi.rst +++ b/docs/zh_CN/api-guides/wifi.rst @@ -4,6 +4,7 @@ {IDF_TARGET_NAME} Wi-Fi 功能列表 ------------------------------------ +- 支持 4 个虚拟接口，即STA、AP、Sniffer 和 reserved。 - 支持仅 station 模式、仅 AP 模式、station/AP 共存模式 - 支持使用 IEEE 802.11B、IEEE 802.11G、IEEE 802.11N 和 API 配置协议模式 - 支持 WPA/WPA2/WPA2-企业版和 WPS @@ -1091,35 +1092,36 @@ API esp_wifi_set_config() 可用于配置 AP。下表详细介绍了各个字段 Wi-Fi 协议模式 +++++++++++++++++++++++++ -目前，IDF 支持以下协议模式： +目前，ESP-IDF 支持以下协议模式： -+--------------+------------------------------------------------------------------------------------------------------------------+ -| 协议模式 | 描述 | -+--------------+------------------------------------------------------------------------------------------------------------------+ -| 802.11b | 调用函数 :cpp:func:`esp_wifi_set_protocol` (ifx, WIFI_PROTOCOL_11B)，将 | -| | station/AP 设置为仅 802.11b 模式。 | -+--------------+------------------------------------------------------------------------------------------------------------------+ -| 802.11bg | 调用函数 :cpp:func:`esp_wifi_set_protocol` (ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G)，将 station/AP 设置为 | -| | 802.11bg 模式。 | -+--------------+------------------------------------------------------------------------------------------------------------------+ -| 802.11bgn | 调用函数 :cpp:func:`esp_wifi_set_protocol` (ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N)，将 | -| | station/AP 设置为 802.11bgn 模式。 | -+--------------+------------------------------------------------------------------------------------------------------------------+ -| 802.11 BGNLR | 调用函数 :cpp:func:`esp_wifi_set_protocol` | -| | (ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR)，将 station/AP 设置为 802.11bgn | -| | 和乐鑫专属模式。 | -+--------------+------------------------------------------------------------------------------------------------------------------+ -| 802.11 LR | 调用函数 :cpp:func:`esp_wifi_set_protocol` (ifx, WIFI_PROTOCOL_LR)，将 | -| | station/AP 设置为仅乐鑫专属模式。 | -| | | -| | **此模式是乐鑫的专利模式，可以达到 1 公里视线范围。请确保 | -| | station 和 AP 同时连接至 ESP 设备。** | -+--------------+------------------------------------------------------------------------------------------------------------------+ +.. list-table:: + :header-rows: 1 + :widths: 15 55 -远程 (LR) + * - 协议模式 + - 描述 + * - 802.11b + - 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B)，将 station/AP 设置为仅 802.11b 模式。 + * - 802.11bg + - 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G)，将 station/AP 设置为 802.11bg 模式。 + * - 802.11g + - 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G) 和 esp_wifi_config_11b_rate(ifx, true)，将 station/AP 设置为 802.11g 模式。 + * - 802.11bgn + - 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N)，将 station/AP 设置为 802.11bgn 模式。 + * - 802.11gn + - 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N) 和 esp_wifi_config_11b_rate(ifx, true)，将 station/AP 设置为 802.11gn 模式。 + * - 802.11 BGNLR + - 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_11B|WIFI_PROTOCOL_11G|WIFI_PROTOCOL_11N|WIFI_PROTOCOL_LR)，将 station/AP 设置为 802.11bgn 和 LR 模式。 + * - 802.11 LR + - 调用函数 esp_wifi_set_protocol(ifx, WIFI_PROTOCOL_LR)，将 station/AP 设置为 LR 模式。 + + **此模式是乐鑫的专利模式，可以达到 1 公里视线范围。请确保 station 和 AP 同时连接至 ESP 设备。** + + +长距离 (LR) +++++++++++++++++++++++++ -远程 (LR) 模式是乐鑫的一项专利 Wi-Fi 模式，可达到 1 公里视线范围。与传统 802.11b 模式相比，接收灵敏度更高，抗干扰能力更强，传输距离更长。 +长距离 (LR) 模式是乐鑫的一项专利 Wi-Fi 模式，可达到 1 公里视线范围。与传统 802.11b 模式相比，接收灵敏度更高，抗干扰能力更强，传输距离更长。 LR 兼容性 ************************* @@ -1174,7 +1176,7 @@ LR 的接收灵敏度比传统的 802.11B 模式高 4 dB，理论上，传输距 LR 吞吐量 ************************* -因为原始 PHY 数据传输速率为 1×2 Mbit 和 1/4 Mbit，LR 的吞吐量有限。 +因为原始 PHY 数据传输速率为 1/2 Mbps 和 1/4 Mbps，LR 的吞吐量有限。 何时使用 LR ************************* @@ -1453,8 +1455,9 @@ Wi-Fi 80211 数据包发送 传输速率 +++++++++++++++++++++++++++++ - - 如果没有 Wi-Fi 连接，传输速率为 1 Mbps。 - - 如果有 WiFi 连接，且数据包是从 station 到 AP 或从 AP 到 station，则传输速率与 Wi-Fi 连接相同。否则，传输速率为 1 Mbps。 + - 默认传输速率为 1 Mbps。 + - 可以通过函数 :cpp:func:`esp_wifi_config_80211_tx_rate()` 设置任意速率。 + - 可以通过函数 :cpp:func:`esp_wifi_set_bandwidth()` 设置任意带宽。 在不同情况下需要避免的副作用 +++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -2405,4 +2408,4 @@ Wi-Fi AMPDU .. toctree:: :hidden: - wireshark-user-guide \ No newline at end of file + wireshark-user-guide diff --git a/docs/zh_CN/api-reference/network/esp_now.rst b/docs/zh_CN/api-reference/network/esp_now.rst index 1c58c1efe7..e81a82a31b 100644 --- a/docs/zh_CN/api-reference/network/esp_now.rst +++ b/docs/zh_CN/api-reference/network/esp_now.rst @@ -64,8 +64,14 @@ ESP-NOW 采用 CCMP 方法保护供应商特定动作帧的安全，具体可参 添加配对设备 ----------------- -在将数据发送到其他设备之前，请先调用 ``esp_now_add_peer()`` 将其添加到配对设备列表中。配对设备的最大数量是 20。如果启用了加密，则必须设置 LMK。ESP-NOW 数据可以从 Station 或 Softap 接口发送。 -确保在发送 ESP-NOW 数据之前已启用该接口。在发送广播数据之前必须添加具有广播 MAC 地址的设备。配对设备的信道范围是从 0 ～14。如果信道设置为 0，数据将在当前信道上发送。否则，必须使用本地设备所在的通道。 +在将数据发送到其他设备之前，请先调用 ``esp_now_add_peer()`` 将其添加到配对设备列表中。如果启用了加密，则必须设置 LMK。ESP-NOW 数据可以从 Station 或 Softap 接口发送。确保在发送 ESP-NOW 数据之前已启用该接口。 +.. only:: esp32c2 + 配对设备的最大数量是 20，其中加密设备的数量不超过 4，默认值是 2。 +.. only:: esp32c3 + 配对设备的最大数量是 20，其中加密设备的数量不超过 10，默认值是 6。 +.. only:: esp32 or esp32s2 or esp32s3 + 配对设备的最大数量是 20，其中加密设备的数量不超过 16，默认值是 6。 +在发送广播数据之前必须添加具有广播 MAC 地址的设备。配对设备的信道范围是从 0 ～14。如果信道设置为 0，数据将在当前信道上发送。否则，必须使用本地设备所在的通道。 发送 ESP-NOW 数据 -----------------