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>

4 files changed, 109 insertions, 2 deletions

diff --git a/docs/library/espnow.rst b/docs/library/espnow.rst
index 1bcc9d762..379e60486 100644
--- a/docs/library/espnow.rst
+++ b/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)
diff --git a/docs/library/network.WLAN.rst b/docs/library/network.WLAN.rst
index 3c401acb4..09fefc592 100644
--- a/docs/library/network.WLAN.rst
+++ b/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)
diff --git a/tests/multi_espnow/70_channel.py b/tests/multi_espnow/70_channel.py
new file mode 100644
index 000000000..f3e8b947b
--- /dev/null
+++ b/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)
diff --git a/tests/multi_espnow/70_channel.py.exp b/tests/multi_espnow/70_channel.py.exp
new file mode 100644
index 000000000..d85539660
--- /dev/null
+++ b/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