`network` — network configuration¶

This module provides network drivers and routing configuration. To use this module, a MicroPython variant/build with network capabilities must be installed. Network drivers for specific hardware are available within this module and are used to configure hardware network interface(s). Network services provided by configured interfaces are then available for use via the usocket module.

For example:

# 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 usocket as usual
import usocket as socket
addr = socket.getaddrinfo('micropython.org', 80)[0][-1]
s = socket.socket()
s.connect(addr)
s.send(b'GET / HTTP/1.1\r\nHost: micropython.org\r\n\r\n')
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 MicroPython ports 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 network.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.

network.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).

network.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 to a specific BSSID (MAC address)

network.disconnect()¶

Disconnect from network.

network.isconnected()¶

Returns True if connected to network, otherwise returns False.

network.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().

network.status()¶

Return detailed status of the interface, values are dependent on the network medium/technology.
network.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'))
network.config('param')¶

network.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'))

class WLAN¶

This class provides a driver for the WiFi network processor in the WiPy. Example usage:

import network
import time
# setup as a station
wlan = network.WLAN(mode=WLAN.STA)
wlan.connect('your-ssid', auth=(WLAN.WPA2, 'your-key'))
while not wlan.isconnected():
    time.sleep_ms(50)
print(wlan.ifconfig())

# now use socket as usual
...

Constructors¶

class network.WLAN(id=0, ...)¶: Create a WLAN object, and optionally configure it. See init() for params of configuration.

Note

The WLAN constructor is special in the sense that if no arguments besides the id are given, it will return the already existing WLAN instance without re-configuring it. This is because WLAN is a system feature of the WiPy. If the already existing instance is not initialized it will do the same as the other constructors an will initialize it with default values.

Methods¶

wlan.init(mode, *, ssid, auth, channel, antenna)¶

Set or get the WiFi network processor configuration.

Arguments are:

mode can be either WLAN.STA or WLAN.AP.

ssid is a string with the ssid name. Only needed when mode is WLAN.AP.

auth is a tuple with (sec, key). Security can be None, WLAN.WEP, WLAN.WPA or WLAN.WPA2. The key is a string with the network password. If sec is WLAN.WEP the key must be a string representing hexadecimal values (e.g. ‘ABC1DE45BF’). Only needed when mode is WLAN.AP.

channel a number in the range 1-11. Only needed when mode is WLAN.AP.

antenna selects between the internal and the external antenna. Can be either WLAN.INT_ANT or WLAN.EXT_ANT.

For example, you can do:

# create and configure as an access point
wlan.init(mode=WLAN.AP, ssid='wipy-wlan', auth=(WLAN.WPA2,'www.wipy.io'), channel=7, antenna=WLAN.INT_ANT)

or:

# configure as an station
wlan.init(mode=WLAN.STA)

wlan.connect(ssid, *, auth=None, bssid=None, timeout=None)¶

Connect to a WiFi access point using the given SSID, and other security parameters.

auth is a tuple with (sec, key). Security can be None, WLAN.WEP, WLAN.WPA or WLAN.WPA2. The key is a string with the network password. If sec is WLAN.WEP the key must be a string representing hexadecimal values (e.g. ‘ABC1DE45BF’).

bssid is the MAC address of the AP to connect to. Useful when there are several APs with the same ssid.

timeout is the maximum time in milliseconds to wait for the connection to succeed.

wlan.scan()¶: Performs a network scan and returns a list of named tuples with (ssid, bssid, sec, channel, rssi). Note that channel is always None since this info is not provided by the WiPy.

wlan.disconnect()¶: Disconnect from the WiFi access point.

wlan.isconnected()¶: In case of STA mode, returns True if connected to a WiFi access point and has a valid IP address. In AP mode returns True when a station is connected, False otherwise.

wlan.ifconfig(if_id=0, config=['dhcp' or configtuple])¶

With no parameters given returns a 4-tuple of (ip, subnet_mask, gateway, DNS_server).

if 'dhcp' is passed as a parameter then the DHCP client is enabled and the IP params are negotiated with the AP.

If the 4-tuple config is given then a static IP is configured. For instance:

wlan.ifconfig(config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))

wlan.mode([mode])¶: Get or set the WLAN mode.

wlan.ssid([ssid])¶: Get or set the SSID when in AP mode.

wlan.auth([auth])¶: Get or set the authentication type when in AP mode.

wlan.channel([channel])¶: Get or set the channel (only applicable in AP mode).

wlan.antenna([antenna])¶: Get or set the antenna type (external or internal).

wlan.mac([mac_addr])¶: Get or set a 6-byte long bytes object with the MAC address.

wlan.irq(*, handler, wake)¶

Create a callback to be triggered when a WLAN event occurs during machine.SLEEP mode. Events are triggered by socket activity or by WLAN connection/disconnection.

handler is the function that gets called when the IRQ is triggered.

wake must be machine.SLEEP.

Returns an IRQ object.

Constants¶

WLAN.STA¶

WLAN.AP¶: selects the WLAN mode

WLAN.WEP¶

WLAN.WPA¶

WLAN.WPA2¶: selects the network security

WLAN.INT_ANT¶

WLAN.EXT_ANT¶: selects the antenna type

network — network configuration¶