docs: Specify the recommended network.WLAN.IF_[AP|STA] constants.

Removes the deprecated network.[AP|STA]_IF form from the docs.

This work was funded through GitHub Sponsors.

Signed-off-by: Angus Gratton <[email protected]>

Author: projectgus

docs/esp32/quickref.rst

@@ -79,19 +79,19 @@ Networking
 WLAN
 ^^^^
 
-The :mod:`network` module::
+The :class:`network.WLAN` class in the :mod:`network` module::
 
     import network
 
-    wlan = network.WLAN(network.STA_IF) # create station interface
+    wlan = network.WLAN(network.WLAN.IF_STA) # create station interface
     wlan.active(True)       # activate the interface
     wlan.scan()             # scan for access points
     wlan.isconnected()      # check if the station is connected to an AP
     wlan.connect('ssid', 'key') # connect to an AP
     wlan.config('mac')      # get the interface's MAC address
     wlan.ipconfig('addr4')  # get the interface's IPv4 addresses
 
-    ap = network.WLAN(network.AP_IF) # create access-point interface
+    ap = network.WLAN(network.WLAN.IF_AP) # create access-point interface
     ap.config(ssid='ESP-AP') # set the SSID of the access point
     ap.config(max_clients=10) # set how many clients can connect to the network
     ap.active(True)         # activate the interface
@@ -100,7 +100,7 @@ A useful function for connecting to your local WiFi network is::
 
     def do_connect():
         import network
-        wlan = network.WLAN(network.STA_IF)
+        wlan = network.WLAN(network.WLAN.IF_STA)
         wlan.active(True)
         if not wlan.isconnected():
             print('connecting to network...')
@@ -124,7 +124,8 @@ to reconnect forever).
 LAN
 ^^^
 
-To use the wired interfaces one has to specify the pins and mode ::
+To use the wired interfaces via :class:`network.LAN` one has to specify the pins
+and mode ::
 
     import network
 

docs/esp8266/quickref.rst

@@ -49,27 +49,27 @@ The :mod:`esp` module::
 Networking
 ----------
 
-The :mod:`network` module::
+The :class:`network.WLAN` class in the :mod:`network` module::
 
     import network
 
-    wlan = network.WLAN(network.STA_IF) # create station interface
+    wlan = network.WLAN(network.WLAN.IF_STA) # create station interface
     wlan.active(True)       # activate the interface
     wlan.scan()             # scan for access points
     wlan.isconnected()      # check if the station is connected to an AP
     wlan.connect('ssid', 'key') # connect to an AP
     wlan.config('mac')      # get the interface's MAC address
     wlan.ipconfig('addr4')  # get the interface's IPv4 addresses
 
-    ap = network.WLAN(network.AP_IF) # create access-point interface
+    ap = network.WLAN(network.WLAN.IF_AP) # create access-point interface
     ap.active(True)         # activate the interface
     ap.config(ssid='ESP-AP') # set the SSID of the access point
 
 A useful function for connecting to your local WiFi network is::
 
     def do_connect():
         import network
-        wlan = network.WLAN(network.STA_IF)
+        wlan = network.WLAN(network.WLAN.IF_STA)
         wlan.active(True)
         if not wlan.isconnected():
             print('connecting to network...')

docs/esp8266/tutorial/network_basics.rst

@@ -1,14 +1,15 @@
 Network basics
 ==============
 
-The network module is used to configure the WiFi connection.  There are two WiFi
-interfaces, one for the station (when the ESP8266 connects to a router) and one
-for the access point (for other devices to connect to the ESP8266).  Create
+The :class:`network.WLAN` class in the :mod:`network` module is used to
+configure the WiFi connection.  There are two WiFi interfaces, one for
+the station (when the ESP8266 connects to a router) and one for the
+access point (for other devices to connect to the ESP8266).  Create
 instances of these objects using::
 
     >>> import network
-    >>> sta_if = network.WLAN(network.STA_IF)
-    >>> ap_if = network.WLAN(network.AP_IF)
+    >>> sta_if = network.WLAN(network.WLAN.IF_STA)
+    >>> ap_if = network.WLAN(network.WLAN.IF_AP)
 
 You can check if the interfaces are active by::
 
@@ -57,7 +58,7 @@ connect to your WiFi network::
 
     def do_connect():
         import network
-        sta_if = network.WLAN(network.STA_IF)
+        sta_if = network.WLAN(network.WLAN.IF_STA)
         if not sta_if.isconnected():
             print('connecting to network...')
             sta_if.active(True)

docs/library/espnow.rst

@@ -56,7 +56,7 @@ A simple example would be:
     import espnow
 
     # A WLAN interface must be active to send()/recv()
-    sta = network.WLAN(network.STA_IF)  # Or network.AP_IF
+    sta = network.WLAN(network.WLAN.IF_STA)  # Or network.WLAN.IF_AP
     sta.active(True)
     sta.disconnect()      # For ESP8266
 
@@ -76,7 +76,7 @@ A simple example would be:
     import espnow
 
     # A WLAN interface must be active to send()/recv()
-    sta = network.WLAN(network.STA_IF)
+    sta = network.WLAN(network.WLAN.IF_STA)
     sta.active(True)
     sta.disconnect()   # Because ESP8266 auto-connects to last Access Point
 
@@ -182,14 +182,14 @@ Configuration
 Sending and Receiving Data
 --------------------------
 
-A wifi interface (``network.STA_IF`` or ``network.AP_IF``) must be
+A wifi interface (``network.WLAN.IF_STA`` or ``network.WLAN.IF_AP``) must be
 `active()<network.WLAN.active>` before messages can be sent or received,
 but it is not necessary to connect or configure the WLAN interface.
 For example::
 
     import network
 
-    sta = network.WLAN(network.STA_IF)
+    sta = network.WLAN(network.WLAN.IF_STA)
     sta.active(True)
     sta.disconnect()    # For ESP8266
 
@@ -445,8 +445,8 @@ must first register the sender and use the same encryption keys as the sender
 
         - *ifidx*: (ESP32 only) Index of the wifi interface which will be
           used to send data to this peer. Must be an integer set to
-          ``network.STA_IF`` (=0) or ``network.AP_IF`` (=1).
-          (default=0/``network.STA_IF``). See `ESPNow and Wifi Operation`_
+          ``network.WLAN.IF_STA`` (=0) or ``network.WLAN.IF_AP`` (=1).
+          (default=0/``network.WLAN.IF_STA``). See `ESPNow and Wifi Operation`_
           below for more information.
 
         - *encrypt*: (ESP32 only) If set to ``True`` data exchanged with
@@ -588,7 +588,7 @@ api-reference/network/esp_now.html#api-reference>`_. For example::
         elif err.args[1] == 'ESP_ERR_ESPNOW_NOT_FOUND':
             e.add_peer(peer)
         elif err.args[1] == 'ESP_ERR_ESPNOW_IF':
-            network.WLAN(network.STA_IF).active(True)
+            network.WLAN(network.WLAN.IF_STA).active(True)
         else:
             raise err
 
@@ -645,7 +645,7 @@ A small async server example::
     import asyncio
 
     # A WLAN interface must be active to send()/recv()
-    network.WLAN(network.STA_IF).active(True)
+    network.WLAN(network.WLAN.IF_STA).active(True)
 
     e = aioespnow.AIOESPNow()  # Returns AIOESPNow enhanced with async support
     e.active(True)
@@ -747,8 +747,8 @@ ESPNow and Wifi Operation
 -------------------------
 
 ESPNow messages may be sent and received on any `active()<network.WLAN.active>`
-`WLAN<network.WLAN()>` interface (``network.STA_IF`` or ``network.AP_IF``), even
-if that interface is also connected to a wifi network or configured as an access
+`WLAN<network.WLAN()>` interface (``network.WLAN.IF_STA`` or ``network.WLAN.IF_AP``),
+even if that interface is also connected to a wifi network or configured as an access
 point. When an ESP32 or ESP8266 device connects to a Wifi Access Point (see
 `ESP32 Quickref <../esp32/quickref.html#networking>`__) the following things
 happen which affect ESPNow communications:
@@ -832,8 +832,8 @@ Other issues to take care with when using ESPNow with wifi are:
     import network, time
 
     def wifi_reset():   # Reset wifi to AP_IF off, STA_IF on and disconnected
-      sta = network.WLAN(network.STA_IF); sta.active(False)
-      ap = network.WLAN(network.AP_IF); ap.active(False)
+      sta = network.WLAN(network.WLAN.IF_STA); sta.active(False)
+      ap = network.WLAN(network.WLAN.IF_AP); ap.active(False)
       sta.active(True)
       while not sta.active():
           time.sleep(0.1)

docs/library/network.WLAN.rst

@@ -8,7 +8,7 @@ This class provides a driver for WiFi network processors.  Example usage::
 
     import network
     # enable station interface and connect to WiFi access point
-    nic = network.WLAN(network.STA_IF)
+    nic = network.WLAN(network.WLAN.IF_STA)
     nic.active(True)
     nic.connect('your-ssid', 'your-key')
     # now use sockets as usual
@@ -18,8 +18,8 @@ Constructors
 .. class:: WLAN(interface_id)
 
 Create a WLAN network interface object. Supported interfaces are
-``network.STA_IF`` (station aka client, connects to upstream WiFi access
-points) and ``network.AP_IF`` (access point, allows other WiFi clients to
+``network.WLAN.IF_STA`` (station aka client, connects to upstream WiFi access
+points) and ``network.WLAN.IF_AP`` (access point, allows other WiFi clients to
 connect). Availability of the methods below depends on interface type.
 For example, only STA interface may `WLAN.connect()` to an access point.
 
@@ -75,7 +75,7 @@ Methods
     Return the current status of the wireless connection.
 
     When called with no argument the return value describes the network link status.
-    The possible statuses are defined as constants:
+    The possible statuses are defined as constants in the :mod:`network` module:
 
         * ``STAT_IDLE`` -- no connection and no activity,
         * ``STAT_CONNECTING`` -- connecting in progress,

docs/reference/mpremote.rst

@@ -477,7 +477,7 @@ An example ``config.py`` might look like:
     """,], # Print out nearby WiFi networks.
         "wl_ipconfig": [
     "exec",
-    "import network; sta_if = network.WLAN(network.STA_IF); print(sta_if.ipconfig('addr4'))",
+    "import network; sta_if = network.WLAN(network.WLAN.IF_STA); print(sta_if.ipconfig('addr4'))",
     """,], # Print ip address of station interface.
         "test": ["mount", ".", "exec", "import test"], # Mount current directory and run test.py.
         "demo": ["run", "path/to/demo.py"], # Execute demo.py on the device.