diff options
Diffstat (limited to 'docs/library')
| -rw-r--r-- | docs/library/espnow.rst | 49 | ||||
| -rw-r--r-- | docs/library/network.WLAN.rst | 32 |
2 files changed, 77 insertions, 4 deletions
diff --git a/docs/library/espnow.rst b/docs/library/espnow.rst index 84e9e9465..4b4b058f8 100644 --- a/docs/library/espnow.rst +++ b/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 ---------- diff --git a/docs/library/network.WLAN.rst b/docs/library/network.WLAN.rst index ee0ef490f..27d6b383a 100644 --- a/docs/library/network.WLAN.rst +++ b/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 |