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():
    print("Waiting for connection...")
    while not nic.isconnected():

# now use usocket as usual
import usocket as socket
addr = socket.getaddrinfo('', 80)[0][-1]
s = socket.socket()
s.send(b'GET / HTTP/1.1\r\nHost:\r\n\r\n')
data = s.recv(1000)

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

Disconnect from network.


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


Query dynamic status information of the interface. When called with no argument the return value describes the network link status. Otherwise param should be a string naming the particular status parameter to retrieve.

The return types and values are dependent on the network medium/technology. Some of the parameters that may be supported are:

  • WiFi STA: use 'rssi' to retrieve the RSSI of the AP signal
  • WiFi AP: use 'stations' to retrieve a list of all the STAs connected to the AP. The list contains tuples of the form (MAC, RSSI).
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(('', '', '', ''))
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. 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

class WINC – wifi shield driver

The WINC class is used for controlling the wifi shield.

Example usage:

import network

wlan = network.WINC()
wlan.connect("SSID", "KEY")



class network.WINC([mode=MODE_STATION])

Creates a winc driver object and connects to the wifi shield which uses I/O pins P0, P1, P2, P3, P6, P7, and P8.

mode controls the mode the WINC module works in:


    The module connects to an access point as a client. This is the default mode.

  • network.WINC.MODE_AP

    The module will create an AP (Access Point) and accept connections from a client.


    The start_ap() method must be called after setting AP mode to configure the AP.

    Also, the WINC1500 has some limitations in its AP implementation:

    • Only one client can connect at a time.
    • Only OPEN or WEP security are supported.
    • There’s a bug in the WiFi Module FW, when the client disconnects any bound sockets are lost (they just stop working). As a workaround, set a timeout for the server socket to force it to raise an exception and then reopen it (See the example script).

    This mode enables WiFi module firmware update.


    Do NOT use unless you know what you’re doing, modules are shipped with the latest FW update there is no need to update the FW.


winc.connect(ssid[, key=None[, security=WPA_PSK]])

Connect to a wifi network with ssid ssid using key key with security security.

After connecting to the network use the usocket module to open TCP/UDP ports to send and receive data.


This method takes a little while to return.

winc.start_ap(ssid[, key=None[, security=OPEN[, channel=1]]])

When running in AP mode this method must be called after creating a WINC object to configure and start the AP .

  • ssid: The AP SSID (must be set).
  • key: The AP encryption key. A Key is required only if security is WEP.
  • security: AP security mode (only OPEN or WEP are supported).
  • channel: WiFi channel, change this if you have another AP running at the same channel.

Disconnect from the wifi network.


Returns True if connected to an access point and an IP address has been obtained.


This method returns a list containing the connected client’s IP adress.


This method blocks and waits for a client to connect. If timeout is 0 this will block forever. This method returns a list containing the connected client’s IP adress.


Returns a list containing:

  • [0]: RSSI - received signal strength indicator (int)
  • [1]: Authorization Type (see constants)
  • [2]: Set Service Identifier String (SSID)
  • [3]: MAC Address String (XX:XX:XX:XX:XX:XX) (BSSID)
  • [4]: IP Address String (XXX.XXX.XXX.XXX)

While connected to the network.


Returns a list containing:

  • [0]: Channel Number (int)
  • [1]: RSSI - received signal strength indicator (int)
  • [2]: Authorization Type (see constants)
  • [3]: MAC Address String (XX:XX:XX:XX:XX:XX) (BSSID)
  • [4]: Set Service Identifier String (SSID)

You don’t need to be connected to call this.


Returns the received signal strength indicator (int) of the currently connected network.


Returns a tuple containing the wifi shield firmware version number.

  • [0]: Firmware Major Version Number (int)
  • [1]: Firmware Minor Version Number (int)
  • [2]: Firmware Patch Version Number (int)
  • [3]: Driver Major Version Number (int)
  • [4]: Driver Minor Version Number (int)
  • [5]: Driver Patch Version Number (int)
  • [6]: Hardware Revision Number - Chip ID (int)

Dumps the wifi shield firmware to a binary file at path. You must have put the module into firmware mode to use this.


Programs the wifi shield with binary image found at path. You must have put the module into firmware mode to use this.



For connecting to an open wifi network.


For connecting to a WEP based password protected network.


For connecting to a WPA/PSK based password protected network.


Start in station mode (i.e. connect to a network).


Start in access point mode (i.e. become the network).


Setup in firmware update mode.