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 socket 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 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 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 by BSSID (MAC address) instead of access point name

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


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(('', '', '', ''))
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
# Extended status information also available this way

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.

    Note1: The start_ap() function must be called after setting AP mode to configure the AP.

    Note2: 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 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).
  • network.WINC.MODE_P2P

    Enable Peer-to-Peer mode, also known as WiFiDirect. This mode is similar to AP, it allows two devices to connect and exchange data directly. Note: This mode is Not implemented Yet.


    This mode enables WiFi module firmware update. Note: Do NOT use unless you know what you’re doing, modules are shipped with the latest FW update there’s 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 function takes a little while to return.

winc.start_ap(SSID, key=None, security=OPEN, channel=1)

When running in AP mode this function 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 network.WINC.OPEN or network.WINC.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.


Returns a tuple 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 of tuples 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 at “/firmware/fw_dump.bin”


Programs the wifi shield with binary image found at “/firmware/m2m_aio_3a0.bin”.


This method returns the connected client IP.


This function blocks and waits for a client to connect. If timeout is 0 this will block forever.



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.


For networks that need a password for all users.


For connecting to a 802.1X based password protected network.


For networks that need a separate password per user.