Lerking/micropython
1
0
Fork 0
mirror of https://github.com/micropython/micropython.git synced 2025-12-16 09:50:15 +01:00
Code Issues Actions 27 Packages Projects Releases Wiki Activity

esp32,docs: Add constants and documentation for espnow data rates.

Browse Source 
Changes are:
- Add constants for some of the supported ESP-NOW data rates.
- Add constants for switching an ESP32 WLAN radio in/out of
  Long Range mode.
- Document the new constants and their usage.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <angus@redyak.com.au>
This commit is contained in:
Angus Gratton
2025-11-20 12:52:56 +11:00
committed by Damien George
parent de2ace72e9
commit 7e10d22134
4 changed files with 107 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
docs/library/espnow.rst
View File

@@ -164,13 +164,15 @@ Configuration
wait forever. The timeout can also be provided as arg to
`recv()`/`irecv()`/`recvinto()`.
*rate*: (ESP32 only) Set the transmission speed for
ESPNow packets. Must be set to a number from the allowed numeric values
in `enum wifi_phy_rate_t
<https://docs.espressif.com/projects/esp-idf/en/v5.2.3/esp32/
*rate*: (ESP32 only) Set the transmission data rate for ESPNow packets.
The default setting is `espnow.RATE_1M`. It's recommended to use one of
the other ``espnow.RATE_nnn`` constants to set this, but it's also
possible to pass an integer corresponding to the `enum wifi_phy_rate_t
<https://docs.espressif.com/projects/esp-idf/en/v5.5.1/esp32/
api-reference/network/esp_wifi.html#_CPPv415wifi_phy_rate_t>`_. This
parameter is actually *write-only* due to ESP-IDF not providing any
means for querying the radio interface's rate parameter.
See also `espnow-long-range`.
.. data:: Returns:
@@ -574,6 +576,45 @@ Constants
espnow.MAX_TOTAL_PEER_NUM(=20)
espnow.MAX_ENCRYPT_PEER_NUM(=6)
The following constants correspond to different transmit data rates on ESP32
only. Lower data rates are generally more reliable over long distances:
.. data:: espnow.RATE_LORA_250K
espnow.RATE_LORA_500K
See `espnow-long-range`.
.. data:: espnow.RATE_1M
espnow.RATE_2M
espnow.RATE_5M
espnow.RATE_6M
espnow.RATE_11M
espnow.RATE_12M
espnow.RATE_24M
espnow.RATE_54M
Unless using the two proprietary long range data rates, only the sender must
configure the data rate.
.. _espnow-long-range:
Long Range Mode
---------------
(ESP32 Only, except ESP32-C2)
To use the `espnow.RATE_LORA_250K` and `espnow.RATE_LORA_500K` data rates,
first set the `WLAN` interface object to long-range mode, i.e.::
import network, espnow
sta = network.WLAN(network.WLAN.IF_STA)
sta.active(True)
sta.config(channel=6, protocol=WLAN.PROTOCOL_LR) # Set on sender & receiver
e = espnow.ESPNow()
e.config(rate=espnow.RATE_LORA_250K) # Needed on sender only
For more information about the limitations of long-range mode, see `WLAN.PROTOCOL_LR`.
Exceptions
----------

32
docs/library/network.WLAN.rst
View File

@@ -145,6 +145,7 @@ Methods
reconnects Number of reconnect attempts to make (integer, 0=none, -1=unlimited)
txpower Maximum transmit power in dBm (integer or float)
pm WiFi Power Management setting (see below for allowed values)
protocol (ESP32 Only.) WiFi Low level 802.11 protocol. See `WLAN.PROTOCOL_DEFAULTS`.
============= ===========
Constants
@@ -161,3 +162,34 @@ Constants
* ``PM_POWERSAVE``: enable WiFi power management with additional power
savings and reduced WiFi performance
* ``PM_NONE``: disable wifi power management
ESP32 Protocol Constants
------------------------
The following ESP32-only constants relate to the ``WLAN.config(protocol=...)``
network interface parameter:
.. data:: WLAN.PROTOCOL_DEFAULTS
A bitmap representing all of the default 802.11 Wi-Fi modes supported by
the chip. Consult `ESP-IDF Wi-Fi Protocols`_ documentation for details.
.. data:: WLAN.PROTOCOL_LR
This value corresponds to the `Espressif proprietary "long-range" mode`_,
which is not compatible with standard Wi-Fi devices. By setting this
protocol it's possible for an ESP32 STA in long-range mode to connect to
an ESP32 AP in long-range mode, or to use `ESP-NOW long range modes
<espnow-long-range>`.
This mode can be bitwise ORed with some standard 802.11 protocol bits
(including `WLAN.PROTOCOL_DEFAULTS`) in order to support a mix of standard
Wi-Fi modes as well as LR mode, consult the `Espressif long-range
documentation`_ for more details.
Long range mode is not supported on ESP32-C2.
.. _ESP-IDF Wi-Fi Protocols: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/wifi.html#wi-fi-protocol-mode
.. _Espressif proprietary "long-range" mode:
.. _Espressif long-range documentation: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/wifi.html#long-range-lr

16
ports/esp32/modespnow.c
View File

@@ -817,6 +817,22 @@ static const mp_rom_map_elem_t espnow_globals_dict_table[] = {
{ MP_ROM_QSTR(MP_QSTR_KEY_LEN), MP_ROM_INT(ESP_NOW_KEY_LEN)},
{ MP_ROM_QSTR(MP_QSTR_MAX_TOTAL_PEER_NUM), MP_ROM_INT(ESP_NOW_MAX_TOTAL_PEER_NUM)},
{ MP_ROM_QSTR(MP_QSTR_MAX_ENCRYPT_PEER_NUM), MP_ROM_INT(ESP_NOW_MAX_ENCRYPT_PEER_NUM)},
#if !CONFIG_IDF_TARGET_ESP32C2
{ MP_ROM_QSTR(MP_QSTR_RATE_LORA_250K), MP_ROM_INT(WIFI_PHY_RATE_LORA_250K)},
{ MP_ROM_QSTR(MP_QSTR_RATE_LORA_500K), MP_ROM_INT(WIFI_PHY_RATE_LORA_500K)},
#endif
// Note: specifying long preamble versions for the lower bit rates apart
// from the non-802.11b 6Mbit rate, for more robust error correction
{ MP_ROM_QSTR(MP_QSTR_RATE_1M), MP_ROM_INT(WIFI_PHY_RATE_1M_L)},
{ MP_ROM_QSTR(MP_QSTR_RATE_2M), MP_ROM_INT(WIFI_PHY_RATE_2M_L)},
{ MP_ROM_QSTR(MP_QSTR_RATE_5M), MP_ROM_INT(WIFI_PHY_RATE_5M_L)},
{ MP_ROM_QSTR(MP_QSTR_RATE_6M), MP_ROM_INT(WIFI_PHY_RATE_6M)},
{ MP_ROM_QSTR(MP_QSTR_RATE_11M), MP_ROM_INT(WIFI_PHY_RATE_11M_L)},
{ MP_ROM_QSTR(MP_QSTR_RATE_12M), MP_ROM_INT(WIFI_PHY_RATE_12M)},
{ MP_ROM_QSTR(MP_QSTR_RATE_24M), MP_ROM_INT(WIFI_PHY_RATE_24M)},
{ MP_ROM_QSTR(MP_QSTR_RATE_54M), MP_ROM_INT(WIFI_PHY_RATE_54M)},
};
static MP_DEFINE_CONST_DICT(espnow_globals_dict, espnow_globals_dict_table);

14
ports/esp32/network_wlan.c
View File

@@ -79,6 +79,15 @@ static bool mdns_initialised = false;
static uint8_t conf_wifi_sta_reconnects = 0;
static uint8_t wifi_sta_reconnects;
// The rules for this default are defined in the documentation of esp_wifi_set_protocol()
// rather than in code, so we have to recreate them here.
#if CONFIG_SOC_WIFI_HE_SUPPORT
// Note: No Explicit support for 5GHz here, yet
#define WIFI_PROTOCOL_DEFAULT (WIFI_PROTOCOL_11B | WIFI_PROTOCOL_11G | WIFI_PROTOCOL_11N | WIFI_PROTOCOL_11AX)
#else
#define WIFI_PROTOCOL_DEFAULT (WIFI_PROTOCOL_11B | WIFI_PROTOCOL_11G | WIFI_PROTOCOL_11N)
#endif
// This function is called by the system-event task and so runs in a different
// thread to the main MicroPython task. It must not raise any Python exceptions.
static void network_wlan_wifi_event_handler(void *event_handler_arg, esp_event_base_t event_base, int32_t event_id, void *event_data) {
@@ -771,6 +780,11 @@ static const mp_rom_map_elem_t wlan_if_locals_dict_table[] = {
{ MP_ROM_QSTR(MP_QSTR_SEC_WPA_ENT), MP_ROM_INT(WIFI_AUTH_WPA_ENTERPRISE) },
#endif
{ MP_ROM_QSTR(MP_QSTR_PROTOCOL_DEFAULT), MP_ROM_INT(WIFI_PROTOCOL_DEFAULT) },
#if !CONFIG_IDF_TARGET_ESP32C2
{ MP_ROM_QSTR(MP_QSTR_PROTOCOL_LR), MP_ROM_INT(WIFI_PROTOCOL_LR) },
#endif
{ MP_ROM_QSTR(MP_QSTR_PM_NONE), MP_ROM_INT(WIFI_PS_NONE) },
{ MP_ROM_QSTR(MP_QSTR_PM_PERFORMANCE), MP_ROM_INT(WIFI_PS_MIN_MODEM) },
{ MP_ROM_QSTR(MP_QSTR_PM_POWERSAVE), MP_ROM_INT(WIFI_PS_MAX_MODEM) },