From 7a900fe51ee29d59fc318073b7a2cb463f7a1f0a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Felix=20D=C3=B6rre?= Date: Mon, 18 Mar 2024 00:57:22 +0000 Subject: [PATCH] docs: Update docs to replace ifconfig with ipconfig. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Felix Dörre --- docs/esp32/quickref.rst | 6 +-- docs/esp8266/quickref.rst | 4 +- docs/esp8266/tutorial/network_basics.rst | 12 +++--- docs/library/network.LAN.rst | 2 +- docs/library/network.WIZNET5K.rst | 12 +----- docs/library/network.rst | 53 +++++++++++++++++++++++- docs/mimxrt/quickref.rst | 2 +- docs/reference/mpremote.rst | 4 +- 8 files changed, 68 insertions(+), 27 deletions(-) diff --git a/docs/esp32/quickref.rst b/docs/esp32/quickref.rst index 6c07c584d3..784fe5f941 100644 --- a/docs/esp32/quickref.rst +++ b/docs/esp32/quickref.rst @@ -80,7 +80,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 @@ -98,7 +98,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 ` module can be used to create and use TCP/UDP sockets as usual, and the ``requests`` module for @@ -121,7 +121,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 index ed21997370..b130ce65db 100644 --- 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 ` 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 index dc3cd3dd5e..9d74a6283a 100644 --- 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('', '') 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 index 375e02cefe..45e3124115 100644 --- 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.ifconfig("addr4")) # now use socket as usual ... diff --git a/docs/library/network.WIZNET5K.rst b/docs/library/network.WIZNET5K.rst index c13d43a376..765c83006d 100644 --- 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 ... @@ -56,16 +56,6 @@ Methods 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')) - .. method:: WIZNET5K.regs() Dump the WIZnet5x00 registers. Useful for debugging. diff --git a/docs/library/network.rst b/docs/library/network.rst index cc50884294..39a84e4161 100644 --- 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 @@ -113,8 +113,46 @@ parameter should be `id`. connected to the AP. The list contains tuples of the form (MAC, RSSI). +.. method:: AbstractNIC.ipconfig('param') + AbstractNIC.ipconfig(param=value, ...) + + Get or set interface-specific ip-configuration interface parameters. + Supported parameters are (availability subject to compile-time flags): + + * ``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. + .. method:: AbstractNIC.ifconfig([(ip, subnet, gateway, dns)]) + Deprecated, only non-lwip ports. 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 @@ -195,6 +233,19 @@ 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 (availability subject to compile-time flags): + + * ``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 index 1a73929bed..79d2a1551e 100644 --- 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 index 08ef5d31ff..e1a99e68cb 100644 --- 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.