From cd64b3082e501f5a54cb15ab3087be91c8f90338 Mon Sep 17 00:00:00 2001 From: Paul Sokolovsky Date: Sun, 9 Apr 2017 13:21:35 +0300 Subject: [PATCH] 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. --- docs/library/network.rst | 109 +++++++++++++++++++++++++++++++++++++-- 1 file 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