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")

wlan.ifconfig()

Constructors

class network.WINC(mode: int = MODE_STATION) → None

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:

  • network.WINC.MODE_STATION

    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.

    Note

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

  • network.WINC.MODE_FIRMWARE:

    This mode enables WiFi module firmware update.

Note

mode can also be network.STA_IF (station aka client, connects to upstream WiFi access points) and and network.AP_IF (access point, allows other WiFi clients to connect). Availability of the methods below depends on interface type. For example, only STA interface may WLAN.connect() to an access point.

Methods

active(is_active: bool | None = None) → bool

Activate (“up”) or deactivate (“down”) network interface, if boolean argument is passed. Otherwise, query current state if no argument is provided. Most other methods require active interface.

connect(ssid: str, key: str | None = None, security: int = WPA_PSK, channel: int = 1) → None

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

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

Note

This method takes a little while to return.

start_ap(ssid: str, key: str | None = None, security: int = OPEN, channel: int = 1) → None

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() → None

Disconnect from the wifi network.

isconnected() → bool

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

connected_sta() → List[str]

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

wait_for_sta(timeout: int) → List[str]

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.

ifconfig(config: Tuple[str, str, str, str] | None = None) → Tuple[str, str, str, str]

Returns a tuple containing:

  • [0]: IP Address String (XXX.XXX.XXX.XXX)

  • [1]: Subnet Address String (XXX.XXX.XXX.XXX)

  • [2]: Gateway String (XXX.XXX.XXX.XXX)

  • [3]: DNS Address String (XXX.XXX.XXX.XXX)

While connected to the network.

You may optionally pass a tuple/list of the ip_addr, subnet_addr, gateway_addr, and dns_addr strings in ipv4 (XXX.XXX.XXX.XXX) format to set a static IP address versus an address obtained through DHCP (which happens by default).

Example usage:

wlan = network.WINC()
wlan.ifconfig(('192.168.1.100', '255.255.255.0', '192.168.1.1', '192.168.1.1'))
wlan.connect(SSID, key=KEY, security=wlan.WPA_PSK)
netinfo() → Tuple[int, int, str, str, str]

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.

scan() → List[Tuple[str, str, int, int, int, int]]

Returns a list containing:

  • [0]: Set Service Identifier String (SSID)

  • [1]: MAC Address String (XX:XX:XX:XX:XX:XX) (BSSID)

  • [2]: Channel Number (int)

  • [3]: RSSI - received signal strength indicator (int)

  • [4]: Authorization Type (see constants)

  • [5]: 1 (int)

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

rssi() → int

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

fw_version() → Tuple[int, int, int, int, int, int, int]

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)

fw_dump(path: str) → None

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

fw_update(path: str) → None

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

Constants

OPEN: int

For connecting to an open wifi network.

WPA_PSK: int

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

802_1X: int

Network is secured with WPA/WPA2 Enterprise.

MODE_STA: int

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

MODE_AP: int

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

MODE_P2P: int

Start in wifi-direct mode.

MODE_BSP: int

Init BSP.

MODE_FIRMWARE: int

Setup in firmware update mode.