docs: Update docs to replace ifconfig with ipconfig.

felixdoerre · felixdoerre · commit d6b76f31c3d2 · 2024-06-20T18:34:13.000Z
Signed-off-by: Felix Dörre &lt;felix@dogcraft.de&gt;
diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst
@@ -89,7 +89,7 @@ The :mod:`network` module::
     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.ifconfig()         # get the interface's IP/netmask/gw/DNS addresses
+    wlan.ipconfig('addr4')  # get the interface's IPv4 addresses
 
     ap = network.WLAN(network.AP_IF) # create access-point interface
     ap.config(ssid='ESP-AP') # set the SSID of the access point
@@ -107,7 +107,7 @@ A useful function for connecting to your local WiFi network is::
             wlan.connect('ssid', 'key')
             while not wlan.isconnected():
                 pass
-        print('network config:', wlan.ifconfig())
+        print('network config:', wlan.ipconfig('addr4'))
 
 Once the network is established the :mod:`socket <socket>` module can be used
 to create and use TCP/UDP sockets as usual, and the ``requests`` module for
@@ -130,7 +130,7 @@ To use the wired interfaces one has to specify the pins and mode ::
 
     lan = network.LAN(mdc=PIN_MDC, ...)   # Set the pin and mode configuration
     lan.active(True)                      # activate the interface
-    lan.ifconfig()                        # get the interface's IP/netmask/gw/DNS addresses
+    lan.ipconfig('addr4')                 # get the interface's IPv4 addresses
 
 
 The keyword arguments for the constructor defining the PHY type and interface are:
diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst
@@ -59,7 +59,7 @@ The :mod:`network` module::
     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.ifconfig()         # get the interface's IP/netmask/gw/DNS addresses
+    wlan.ipconfig('addr4')  # get the interface's IPv4 addresses
 
     ap = network.WLAN(network.AP_IF) # create access-point interface
     ap.active(True)         # activate the interface
@@ -76,7 +76,7 @@ A useful function for connecting to your local WiFi network is::
             wlan.connect('ssid', 'key')
             while not wlan.isconnected():
                 pass
-        print('network config:', wlan.ifconfig())
+        print('network config:', wlan.ipconfig('addr4'))
 
 Once the network is established the :mod:`socket <socket>` module can be used
 to create and use TCP/UDP sockets as usual.
diff --git a/docs/esp8266/tutorial/network_basics.rst b/docs/esp8266/tutorial/network_basics.rst
@@ -19,10 +19,10 @@ You can check if the interfaces are active by::
 
 You can also check the network settings of the interface by::
 
-    >>> ap_if.ifconfig()
-    ('192.168.4.1', '255.255.255.0', '192.168.4.1', '8.8.8.8')
+    >>> ap_if.ipconfig('addr4')
+    ('192.168.4.1', '255.255.255.0')
 
-The returned values are: IP address, netmask, gateway, DNS.
+The returned values are: IP address and netmask.
 
 Configuration of the WiFi
 -------------------------
@@ -45,8 +45,8 @@ To check if the connection is established use::
 
 Once established you can check the IP address::
 
-    >>> sta_if.ifconfig()
-    ('192.168.0.2', '255.255.255.0', '192.168.0.1', '8.8.8.8')
+    >>> sta_if.ipconfig('addr4')
+    ('192.168.0.2', '255.255.255.0')
 
 You can then disable the access-point interface if you no longer need it::
 
@@ -64,7 +64,7 @@ connect to your WiFi network::
             sta_if.connect('<ssid>', '<key>')
             while not sta_if.isconnected():
                 pass
-        print('network config:', sta_if.ifconfig())
+        print('network config:', sta_if.ipconfig('addr4'))
 
 Sockets
 -------
diff --git a/docs/library/network.LAN.rst b/docs/library/network.LAN.rst
@@ -10,7 +10,7 @@ Example usage::
 
     import network
     nic = network.LAN(0)
-    print(nic.ifconfig())
+    print(nic.ipconfig("addr4"))
 
     # now use socket as usual
     ...
diff --git a/docs/library/network.WIZNET5K.rst b/docs/library/network.WIZNET5K.rst
@@ -13,7 +13,7 @@ Example usage::
 
     import network
     nic = network.WIZNET5K(pyb.SPI(1), pyb.Pin.board.X5, pyb.Pin.board.X4)
-    print(nic.ifconfig())
+    print(nic.ipconfig("addr4"))
 
     # now use socket as usual
     ...
@@ -51,20 +51,7 @@ Constructors
 Methods
 -------
 
-.. method:: WIZNET5K.isconnected()
-
-   Returns ``True`` if the physical Ethernet link is connected and up.
-   Returns ``False`` otherwise.
-
-.. method:: WIZNET5K.ifconfig([(ip, subnet, gateway, dns)])
-
-   Get/set IP address, subnet mask, gateway and DNS.
-
-   When called with no arguments, this method returns a 4-tuple with the above information.
-
-   To set the above values, pass a 4-tuple with the required information.  For example::
-
-    nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
+This class implements most methods from `AbstractNIC <AbstractNIC>`, which are documented there. Additional methods are:
 
 .. method:: WIZNET5K.regs()
 
diff --git a/docs/library/network.WLAN.rst b/docs/library/network.WLAN.rst
@@ -107,7 +107,7 @@ Methods
 
    Get or set general network interface parameters. These methods allow to work
    with additional parameters beyond standard IP configuration (as dealt with by
-   `WLAN.ifconfig()`). These include network-specific and hardware-specific
+   `AbstractNIC.ipconfig()`). These include network-specific and hardware-specific
    parameters. For setting parameters, keyword argument syntax should be used,
    multiple parameters can be set at once. For querying, parameters name should
    be quoted as a string, and only one parameter can be queries at time::
diff --git a/docs/library/network.WLANWiPy.rst b/docs/library/network.WLANWiPy.rst
@@ -20,7 +20,7 @@ This class provides a driver for the WiFi network processor in the WiPy. Example
     wlan.connect('your-ssid', auth=(WLAN.WPA2, 'your-key'))
     while not wlan.isconnected():
         time.sleep_ms(50)
-    print(wlan.ifconfig())
+    print(wlan.ipconfig("addr4"))
 
     # now use socket as usual
     ...
@@ -96,16 +96,10 @@ Methods
    In case of STA mode, returns ``True`` if connected to a WiFi access point and has a valid IP address.
    In AP mode returns ``True`` when a station is connected, ``False`` otherwise.
 
-.. method:: WLANWiPy.ifconfig(if_id=0, config=['dhcp' or configtuple])
+.. method:: WlanWiPy.ipconfig('param')
+            WlanWiPy.ipconfig(param=value, ...)
 
-   With no parameters given returns a 4-tuple of *(ip, subnet_mask, gateway, DNS_server)*.
-
-   if ``'dhcp'`` is passed as a parameter then the DHCP client is enabled and the IP params
-   are negotiated with the AP.
-
-   If the 4-tuple config is given then a static IP is configured. For instance::
-
-      wlan.ifconfig(config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
+   See :ref:`AbstractNIC.ipconfig <AbstractNIC.ipconfig>`. Supported parameters are: ``dhcp4``, ``addr4``, ``gw4``.
 
 .. method:: WLANWiPy.mode([mode])
 
diff --git a/docs/library/network.rst b/docs/library/network.rst
@@ -24,7 +24,7 @@ For example::
         print("Waiting for connection...")
         while not nic.isconnected():
             time.sleep(1)
-    print(nic.ifconfig())
+    print(nic.ipconfig("addr4"))
 
     # now use socket as usual
     import socket
@@ -35,6 +35,8 @@ For example::
     data = s.recv(1000)
     s.close()
 
+.. _AbstractnNIC:
+
 Common network adapter interface
 ================================
 
@@ -113,8 +115,49 @@ parameter should be `id`.
          connected to the AP.  The list contains tuples of the form
          (MAC, RSSI).
 
+.. _AbstractNIC.ipconfig:
+.. method:: AbstractNIC.ipconfig('param')
+            AbstractNIC.ipconfig(param=value, ...)
+
+       Get or set interface-specific IP-configuration interface parameters.
+       Supported parameters are the following (availability of a particular
+       parameter depends on the port and the specific network interface):
+
+       * ``dhcp4`` (``True/False``) obtain an IPv4 address, gateway and dns
+         server via DHCP. This method does not block and wait for an address
+         to be obtained. To check if an address was obtained, use the read-only
+         property ``has_dhcp4``.
+       * ``gw4`` Get/set the IPv4 default-gateway.
+       * ``dhcp6`` (``True/False``) obtain a DNS server via stateless DHCPv6.
+         Obtaining IP Addresses via DHCPv6 is currently not implemented.
+       * ``autoconf6`` (``True/False``) obtain a stateless IPv6 address via
+         the network prefix shared in router advertisements. To check if a
+         stateless address was obtained, use the read-only
+         property ``has_autoconf6``.
+       * ``addr4`` (e.g. ``192.168.0.4/24``) obtain the current IPv4 address
+         and network mask as ``(ip, subnet)``-tuple, regardless of how this
+         address was obtained. This method can be used to set a static IPv4
+         address either as ``(ip, subnet)``-tuple or in CIDR-notation.
+       * ``addr6`` (e.g. ``fe80::1234:5678``) obtain a list of current IPv6
+         addresses as ``(ip, state, preferred_lifetime, valid_lifetime)``-tuple.
+         This include link-local, slaac and static addresses.
+         ``preferred_lifetime`` and ``valid_lifetime`` represent the remaining
+         valid and preferred lifetime of each IPv6 address, in seconds.
+         ``state`` indicates the current state of the address:
+
+         * ``0x08`` - ``0x0f`` indicates the address is tentative, counting the
+           number of probes sent.
+         * ``0x10`` The address is deprecated (but still valid)
+         * ``0x30`` The address is preferred (and valid)
+         * ``0x40`` The address is duplicated and can not be used.
+
+         This method can be used to set a static IPv6
+         address, by setting this parameter to the address, like ``fe80::1234:5678``.
+
 .. method:: AbstractNIC.ifconfig([(ip, subnet, gateway, dns)])
 
+       .. note:: This function is deprecated, use `ipconfig()` instead.
+
        Get/set IP-level network interface parameters: IP address, subnet mask,
        gateway and DNS server. When called with no arguments, this method returns
        a 4-tuple with the above information. To set the above values, pass a
@@ -127,7 +170,7 @@ parameter should be `id`.
 
        Get or set general network interface parameters. These methods allow to work
        with additional parameters beyond standard IP configuration (as dealt with by
-       `ifconfig()`). These include network-specific and hardware-specific
+       `ipconfig()`). These include network-specific and hardware-specific
        parameters. For setting parameters, the keyword argument
        syntax should be used, and multiple parameters can be set at once. For
        querying, a parameter name should be quoted as a string, and only one
@@ -195,6 +238,20 @@ The following are functions available in the network module.
 
     The default hostname is typically the name of the board.
 
+.. function:: ipconfig('param')
+              ipconfig(param=value, ...)
+
+       Get or set global IP-configuration parameters.
+       Supported parameters are the following (availability of a particular
+       parameter depends on the port and the specific network interface):
+
+       * ``dns`` Get/set DNS server. This method can support both, IPv4 and
+         IPv6 addresses.
+       * ``prefer`` (``4/6``) Specify which address type to return, if a domain
+         name has both A and AAAA records. Note, that this does not clear the
+         local DNS cache, so that any previously obtained addresses might not
+         change.
+
 .. function:: phy_mode([mode])
 
     Get or set the PHY mode.
diff --git a/docs/mimxrt/quickref.rst b/docs/mimxrt/quickref.rst
@@ -528,7 +528,7 @@ Ethernet.  Example usage::
     lan.active(True)
 
 If there is a DHCP server in the LAN, the IP address is supplied by that server.
-Otherwise, the IP address can be set with lan.ifconfig().  The default address
+Otherwise, the IP address can be set with lan.ipconfig(addr4="...").  The default address
 is 192.168.0.1.
 
 Teensy 4.1 does not have an Ethernet jack on the board, but PJRC offers an
diff --git a/docs/reference/mpremote.rst b/docs/reference/mpremote.rst
@@ -469,9 +469,9 @@ An example ``config.py`` might look like:
     for ap in wl.scan():
         print(ap)
     """,], # Print out nearby WiFi networks.
-        "wl_ifconfig": [
+        "wl_ipconfig": [
     "exec",
-    "import network; sta_if = network.WLAN(network.STA_IF); print(sta_if.ifconfig())",
+    "import network; sta_if = network.WLAN(network.STA_IF); 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.
diff --git a/docs/wipy/quickref.rst b/docs/wipy/quickref.rst
@@ -184,18 +184,18 @@ WLAN (WiFi)
 
 See :ref:`network.WLAN <network.WLAN>` and :mod:`machine`. ::
 
-    import machine
+    import machine, network
     from network import WLAN
 
     # configure the WLAN subsystem in station mode (the default is AP)
     wlan = WLAN(mode=WLAN.STA)
     # go for fixed IP settings
-    wlan.ifconfig(config=('192.168.0.107', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
+    network.ipconfig(dns='8.8.8.8')
+    wlan.ipconfig(addr4='192.168.0.107/24', gw4='192.168.0.1')
     wlan.scan()     # scan for available networks
     wlan.connect(ssid='mynetwork', auth=(WLAN.WPA2, 'mynetworkkey'))
     while not wlan.isconnected():
         pass
-    print(wlan.ifconfig())
     # enable wake on WLAN
     wlan.irq(trigger=WLAN.ANY_EVENT, wake=machine.SLEEP)
     # go to sleep
diff --git a/docs/wipy/tutorial/wlan.rst b/docs/wipy/tutorial/wlan.rst
@@ -50,14 +50,15 @@ Assigning a static IP address when booting
 If you want your WiPy to connect to your home router after boot-up, and with a fixed
 IP address so that you can access it via telnet or FTP, use the following script as /flash/boot.py::
 
-   import machine
+   import machine, network
    from network import WLAN
    wlan = WLAN() # get current object, without changing the mode
 
    if machine.reset_cause() != machine.SOFT_RESET:
        wlan.init(WLAN.STA)
        # configuration below MUST match your home router settings!!
-       wlan.ifconfig(config=('192.168.178.107', '255.255.255.0', '192.168.178.1', '8.8.8.8'))
+       network.ipconfig(dns='8.8.8.8')
+       wlan.ipconfig(addr4='192.168.0.107/24', gw4='192.168.0.1')
 
    if not wlan.isconnected():
        # change the line below to match your network ssid, security and password
