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

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>

Author: projectgus

docs/library/espnow.rst

@@ -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
 ----------
 

docs/library/network.WLAN.rst

@@ -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

ports/esp32/modespnow.c

@@ -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);
 

ports/esp32/network_wlan.c

@@ -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) },