class WINC – WiFi shield driver

The WINC class drives the Atmel WINC1500 802.11 b/g/n WiFi module on the OpenMV WiFi Shield. Available on the OpenMV Cam M4, M7, H7, H7 Plus and Pure Thermal (the STM32 boards that the WiFi shield was designed for). For boards with built-in WiFi (OpenMV Cam N6, OpenMV Cam RT1062, Arduino Giga) use WLAN instead.

Example – connect to an access point and print the address:

import network

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

print("status:    ", "connected" if wlan.isconnected() else "off")
print("rssi:      ", wlan.rssi(), "dBm")
print("interface: ", wlan.ifconfig())
print("netinfo:   ", wlan.netinfo())

Example – bring up an open access point and wait for a client:

import network

wlan = network.WINC(mode=network.WINC.MODE_AP)
wlan.start_ap("OpenMV-Cam", security=network.WINC.OPEN, channel=6)

print("waiting for a station to associate...")
print(wlan.wait_for_sta(timeout=None))

Constructors

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

Create a WINC driver object and bring up the WiFi shield.

mode selects the operating mode the module starts in:

Note

In AP mode the WINC1500 has hardware limits:

  • Only one client can connect at a time.

  • Only OPEN or WEP security are supported.

  • A WiFi-module firmware bug causes any bound sockets to stop working when the client disconnects. Set a timeout on the server socket so it raises an exception that you can use to re-open it.

Methods

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

Bring the WiFi shield up or down.

With no argument, return the current state – True while the shield is initialised and the radio is up, False otherwise.

active(True) performs the WINC1500 firmware handshake over SPI and brings the radio up in the configured mode. It is a no-op if the interface is already active. connect() auto-calls this if it has not been called yet; for any other method (scan(), rssi(), netinfo(), …) you must call active(True) first.

active(False) shuts the radio back down (the WINC drops to BSP-only mode) and releases the SPI pins.

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

Associate with the WiFi network ssid using password key, security mode security (one of OPEN, WPA_PSK or the 802.1X constant) on radio channel. security and channel are keyword-only.

After connecting use the socket module to open TCP/UDP ports.

This method blocks until the association completes or fails.

config(ssid: str, key: str | None = None, *, security: int = WINC.WPA_PSK, channel: int = 1) → None

Alias of connect(). Provided for compatibility with code that calls config on other network interfaces.

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

Alias of connect() used after constructing the object with mode=MODE_AP to configure and start the access point. The AP only supports OPEN or WEP security; if WEP is used key is required.

disconnect() → None

In STA mode, disassociate from the currently associated access point. The shield stays active; call connect() to re-associate. No-op when not currently associated.

isconnected() → bool

In STA mode return True when associated with an access point and an IPv4 address has been obtained (via DHCP or ifconfig()). Returns False while still in the authenticating / associating / DHCP phase.

connected_sta() → List[str]

In AP mode, return a list containing the IP address of the currently connected client (or an empty list if no client is connected).

wait_for_sta(timeout: int | None) → List[str]

In AP mode, block until a client connects and return a list containing the client’s IP address. timeout is the maximum wait in milliseconds; pass None to wait indefinitely.

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

Get or set IPv4 interface parameters. The 4-tuple contains (ip, subnet, gateway, dns) as dotted-quad strings.

Called with no argument: returns the current configuration.

Called with a 4-tuple: sets a static IP configuration in place of the DHCP-acquired one.

Example – pin a static IP before connecting:

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=network.WINC.WPA_PSK)

Note

WINC does not implement the modern AbstractNIC.ipconfig() API; use ifconfig() here.

netinfo() → Tuple[int, int, str, str, str]

Return a 5-tuple describing the current association:

  • [0] RSSI as an int (dBm).

  • [1] Security mode – one of the security constants.

  • [2] SSID string.

  • [3] BSSID as an "XX:XX:XX:XX:XX:XX" MAC string.

  • [4] IPv4 address as a dotted-quad string.

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

Scan for nearby access points. Returns a list of 6-tuples:

  • [0] SSID string.

  • [1] BSSID as an "XX:XX:XX:XX:XX:XX" MAC string.

  • [2] Channel number.

  • [3] RSSI in dBm.

  • [4] Security mode – one of the security constants.

  • [5] Reserved (always 1).

Can be called without first associating with a network.

rssi() → int

Return the RSSI in dBm of the currently associated access point. Roughly: -30 is excellent, -67 is OK for streaming, -80 is marginal, -90 and below is unusable. Only meaningful in STA mode while isconnected() is True.

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

Return a 7-tuple describing the WINC1500 firmware and driver versions:

  • [0] Firmware major.

  • [1] Firmware minor.

  • [2] Firmware patch.

  • [3] Driver major.

  • [4] Driver minor.

  • [5] Driver patch.

  • [6] Chip hardware revision.

fw_dump(path: str) → None

Read the WINC1500’s internal flash and write the resulting firmware image to the file at path on the OpenMV’s filesystem. Use this to back up the currently-installed image before calling fw_update().

Requires the module to have been constructed with mode=MODE_FIRMWARE.

fw_update(path: str) → None

Erase the WINC1500’s internal flash and program it with the binary image at path. The image must match the layout expected by the OpenMV firmware (typically supplied by Atmel / Microchip with the WINC SDK).

The call blocks for several seconds while the flash is programmed and verified. Power-cycle the OpenMV Cam after the call returns so the WINC1500 starts from the new image.

Requires the module to have been constructed with mode=MODE_FIRMWARE.

Constants

OPEN: int

Security value for an unencrypted network. Pass to the security argument of connect() / start_ap().

WPA_PSK: int

Security value for WPA/WPA2 with a pre-shared key. The default for connect().

Note

A WPA/WPA2 Enterprise (802.1X) security value also exists. The firmware exposes it under the name 802_1X, which is not a valid Python identifier – access it via getattr(network.WINC, "802_1X").

MODE_STA: int

Station mode – connect to an access point as a client. The default constructor mode.

MODE_AP: int

Access-point mode – the WINC becomes the AP that clients associate with.

MODE_P2P: int

WiFi-Direct (peer-to-peer) mode.

MODE_BSP: int

Initialise the WINC board-support package only – the radio is not brought up. Used by the firmware-update flow.

MODE_FIRMWARE: int

Firmware-update mode. Required by fw_dump() and fw_update().