docs/network: First step to describe standard network class interface.

This adds description of implied AbstractNIC base class, which should be
"subclasses" and implemented by a particular network device class.

This is just an initial step in that direction, the API and description
will be elabotated further.

1 files changed, 106 insertions, 3 deletions

diff --git a/docs/library/network.rst b/docs/library/network.rst
index 75640250f7..27fa0dcb2f 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,6 +35,103 @@ For example::
     data = s.recv(1000)
     s.close()
 
+Common network adapter interface
+================================
+
+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:: AbstractNIC(id=None, ...)
+
+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`.
+
+    .. method:: active([is_active])
+
+        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).
+
+    .. method:: connect([service_id, key=None, \*, ...])
+
+       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:
+
+       * WiFi: `bssid` keyword to connect by BSSID (MAC address) instead
+         of access point name
+
+    .. 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.
+
+       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().
+
+    .. method:: status()
+
+       Return detailed status of the interface, values are dependent
+       on the network medium/technology.
+
+    .. method:: ifconfig([(ip, subnet, gateway, dns)])
+
+       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::
+
+        nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
+
+    .. method:: config('param')
+                config(param=value, ...)
+
+       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
 
     class CC3K