diff options
Diffstat (limited to 'docs/library/network.rst')
| -rw-r--r-- | docs/library/network.rst | 119 |
1 files changed, 88 insertions, 31 deletions
diff --git a/docs/library/network.rst b/docs/library/network.rst index 251e68c76..27fa0dcb2 100644 --- a/docs/library/network.rst +++ b/docs/library/network.rst @@ -14,14 +14,20 @@ module. For example:: - # configure a specific network interface + # connect/ show IP config a specific network interface # see below for examples of specific drivers import network + import utime nic = network.Driver(...) + if not nic.isconnected(): + nic.connect() + print("Waiting for connection...") + while not nic.isconnected(): + utime.sleep(1) print(nic.ifconfig()) - # now use socket as usual - import socket + # now use usocket as usual + import usocket as socket addr = socket.getaddrinfo('micropython.org', 80)[0][-1] s = socket.socket() s.connect(addr) @@ -29,51 +35,102 @@ For example:: data = s.recv(1000) s.close() -.. only:: port_wipy +Common network adapter interface +================================ - .. _network.Server: +This section describes an (implied) abstract base class for all network +interface classes implemented by different ports of MicroPython for +different hardware. This means that MicroPython does not actually +provide `AbstractNIC` class, but any actual NIC class, as described +in the following sections, implements methods as described here. - class Server - ============ +.. class:: AbstractNIC(id=None, ...) - The ``Server`` class controls the behaviour and the configuration of the FTP and telnet - services running on the WiPy. Any changes performed using this class' methods will - affect both. +Instantiate a network interface object. Parameters are network interface +dependent. If there are more than one interface of the same type, the first +parameter should be `id`. - Example:: + .. method:: active([is_active]) - import network - server = network.Server() - server.deinit() # disable the server - # enable the server again with new settings - server.init(login=('user', 'password'), timeout=600) + Activate ("up") or deactivate ("down") the network interface, if + a boolean argument is passed. Otherwise, query current state if + no argument is provided. Most other methods require an active + interface (behavior of calling them on inactive interface is + undefined). - Constructors - ------------ + .. method:: connect([service_id, key=None, \*, ...]) - .. class:: network.Server(id, ...) + Connect the interface to a network. This method is optional, and + available only for interfaces which are not "always connected". + If no parameters are given, connect to the default (or the only) + service. If a single parameter is given, it is the primary identifier + of a service to connect to. It may be accompanied by a key + (password) required to access said service. There can be further + arbitrary keyword-only parameters, depending on the networking medium + type and/or particular device. Parameters can be used to: a) + specify alternative service identifer types; b) provide additional + connection parameters. For various medium types, there are different + sets of predefined/recommended parameters, among them: - Create a server instance, see ``init`` for parameters of initialization. + * WiFi: `bssid` keyword to connect by BSSID (MAC address) instead + of access point name - Methods - ------- + .. method:: disconnect() + + Disconnect from network. + + .. method:: isconnected() + + Returns ``True`` if connected to network, otherwise returns ``False``. + + .. method:: scan(\*, ...) + + Scan for the available network services/connections. Returns a + list of tuples with discovered service parameters. For various + network media, there are different variants of predefined/ + recommended tuple formats, among them: + + * WiFi: (ssid, bssid, channel, RSSI, authmode, hidden). There + may be further fields, specific to a particular device. - .. method:: server.init(\*, login=('micro', 'python'), timeout=300) + The function may accept additional keyword arguments to filter scan + results (e.g. scan for a particular service, on a particular channel, + for services of a particular set, etc.), and to affect scan + duration and other parameters. Where possible, parameter names + should match those in connect(). - Init (and effectively start the server). Optionally a new ``user``, ``password`` - and ``timeout`` (in seconds) can be passed. + .. method:: status() - .. method:: server.deinit() + Return detailed status of the interface, values are dependent + on the network medium/technology. - Stop the server + .. method:: ifconfig([(ip, subnet, gateway, dns)]) - .. method:: server.timeout([timeout_in_seconds]) + 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 + 4-tuple with the required information. For example:: - Get or set the server timeout. + nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) - .. method:: server.isrunning() + .. method:: config('param') + config(param=value, ...) - Returns ``True`` if the server is running, ``False`` otherwise. + 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 + parameters and status values. 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 + parameter can be queried at a time:: + + # Set WiFi access point name (formally known as ESSID) and WiFi channel + ap.config(essid='My AP', channel=11) + # Query params one by one + print(ap.config('essid')) + print(ap.config('channel')) + # Extended status information also available this way + print(sta.config('rssi')) .. only:: port_pyboard |