tests/multi_espnow: Add channel setting test, add some docs.

Test currently passes. It was added so it can be used to check for
regressions when fixing channel selection for AP mode in a follow-up
commit.

Also add some docs about how channel setting is observed to work for
ESP-NOW.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <angus@redyak.com.au>

docs/library/espnow.rst

@@ -441,7 +441,9 @@ must first register the sender and use the same encryption keys as the sender
 
         - *channel*: The wifi channel (2.4GHz) to communicate with this peer.
           Must be an integer from 0 to 14. If channel is set to 0 the current
-          channel of the wifi device will be used. (default=0)
+          channel of the wifi device will be used, if channel is set to another
+          value then this must match the channel currently configured on the
+          interface (see :func:`WLAN.config`). (default=0)
 
         - *ifidx*: (ESP32 only) Index of the wifi interface which will be
           used to send data to this peer. Must be an integer set to
@@ -470,6 +472,9 @@ must first register the sender and use the same encryption keys as the sender
           registered.
         - ``OSError(num, "ESP_ERR_ESPNOW_FULL")`` if too many peers are
           already registered.
+        - ``OSError(num, "ESP_ERR_ESPNOW_CHAN")`` if a channel value was
+          set that doesn't match the channel currently configured for this
+          interface.
         - ``ValueError()`` on invalid keyword args or values.
 
 .. method:: ESPNow.del_peer(mac)

docs/library/network.WLAN.rst

@@ -126,7 +126,7 @@ Methods
    =============  ===========
    mac            MAC address (bytes)
    ssid           WiFi access point name (string)
-   channel        WiFi channel (integer)
+   channel        WiFi channel (integer). Depending on the port this may only be supported on the AP interface.
    hidden         Whether SSID is hidden (boolean)
    security       Security protocol supported (enumeration, see module constants)
    key            Access key (string)

tests/multi_espnow/70_channel.py

@@ -0,0 +1,89 @@
+# Test that ESP-NOW picks up the channel configuration for STA
+# mode on ESP32.
+#
+# Note that setting the channel on a peer in ESP-NOW on modern ESP-IDF only
+# checks it against the configured channel, it doesn't ever change the radio
+# channel
+import sys
+import time
+
+try:
+    import network
+    import espnow
+except ImportError:
+    print("SKIP")
+    raise SystemExit
+
+# ESP8266 doesn't support config('channel') on the STA interface,
+# and the channel parameter to add_peer doesn't appear to set the
+# channel either.
+if sys.platform == "esp8266":
+    print("SKIP")
+    raise SystemExit
+
+
+timeout_ms = 1000
+default_pmk = b"MicroPyth0nRules"
+
+CHANNEL = 3
+WRONG_CHANNEL = 8
+
+
+def init_sta():
+    sta = network.WLAN(network.WLAN.IF_STA)
+    e = espnow.ESPNow()
+    e.active(True)
+    sta.active(True)
+    sta.disconnect()  # Force AP disconnect for any saved config, important so the channel doesn't change
+    sta.config(channel=CHANNEL)
+    e.set_pmk(default_pmk)
+    return sta, e
+
+
+# Receiver
+def instance0():
+    sta, e = init_sta()
+    multitest.globals(PEER=sta.config("mac"))
+    multitest.next()
+    print(sta.config("channel"))
+    while True:
+        peer, msg = e.recv(timeout_ms)
+        if peer is None:
+            print("Timeout")
+            break
+        print(msg)
+    e.active(False)
+
+
+# Sender
+def instance1():
+    sta, e = init_sta()
+    multitest.next()
+    peer = PEER
+
+    # both instances set channel via sta.config(), above
+    msg = b"sent to right channel 1"
+    e.add_peer(peer, channel=CHANNEL)
+    for _ in range(3):
+        e.send(peer, msg)
+    e.del_peer(peer)
+    print(sta.config("channel"))
+
+    sta.config(channel=WRONG_CHANNEL)
+    msg = b"sent to wrong channel"
+    e.add_peer(peer, channel=WRONG_CHANNEL)
+    for _ in range(3):
+        e.send(peer, msg)
+    e.del_peer(peer)
+    print(sta.config("channel"))
+
+    # switching back to the correct channel should also work
+    sta.config(channel=CHANNEL)
+    msg = b"sent to right channel 2"
+    e.add_peer(peer, channel=CHANNEL)
+    for _ in range(3):
+        e.send(peer, msg)
+    e.del_peer(peer)
+    print(sta.config("channel"))
+
+    e.active(False)

tests/multi_espnow/70_channel.py.exp

@@ -0,0 +1,13 @@
+--- instance0 ---
+3
+b'sent to right channel 1'
+b'sent to right channel 1'
+b'sent to right channel 1'
+b'sent to right channel 2'
+b'sent to right channel 2'
+b'sent to right channel 2'
+Timeout
+--- instance1 ---
+3
+8
+3