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.
This commit is contained in:
Paul Sokolovsky
parent
50de6d2fab
commit
cd64b3082e
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue