Note

This is the documentation for the latest development branch and may refer to features that are not available in released versions. If you are looking for the documentation for a specific release, use the drop-down menu on the left and select the desired version.

network Module API Manual

Overview

This module is primarily used to configure and view network parameters. After configuration is complete, the socket module can be used for network communication.

LAN Class

Reference documentation: Micropython LAN

This class is the configuration interface for wired networks. Example code is as follows:

import network
nic = network.LAN()
print(nic.ifconfig())

# After configuration, you can use socket as usual
...

Constructor

• class network.LAN() ¶

  Creates a wired Ethernet object.

Methods

• LAN.active([state]) ¶

  Activate or deactivate the network interface. Pass the boolean argument True to activate, and False to deactivate. If no argument is passed, the current status is returned.

• LAN.isconnected() ¶

  Returns True to indicate that the network is connected, and returns False to indicate that it is not connected.

• LAN.ifconfig([(ip, subnet, gateway, dns)]) ¶

  Get or set IP-level network interface parameters, including IP address, subnet mask, gateway, and DNS server. When called without arguments, it returns a tuple containing the above information; to set parameters, pass a tuple containing the IP address, subnet mask, gateway, and DNS. For example:

  nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
  

• LAN.config(config_parameters) ¶

  Get or set network interface parameters. Currently, only setting or getting the MAC address is supported. For example:

  import network
  lan = network.LAN()
  # Set MAC address
  lan.config(mac="42:EA:D0:C2:0D:83")
  # Get MAC address
  print(lan.config("mac"))
  

WLAN Class

Reference documentation: Micropython WLAN

This class provides the WiFi network configuration interface. Example code is as follows:

import network
import time

SSID = "TEST"
PASSWORD = "12345678"

sta = network.WLAN(network.STA_IF)

sta.connect(SSID, PASSWORD)

timeout = 10  # Unit: seconds
start_time = time.time()

while not sta.isconnected():
    if time.time() - start_time > timeout:
        print("Connection timed out")
        break
    time.sleep(1)  # Please wait a moment before connecting

print(sta.ifconfig())

print(sta.status())

# Disconnecting from the network here is just a test. In actual application, you may not need to disconnect
sta.disconnect()
print("Network disconnected")
print(sta.status())

Constructor

• class network.WLAN(*interface_id*)

  Creates a WLAN network interface object. Supported interface types include network.STA_IF (i.e., station mode, connecting to an upstream WiFi access point) and network.AP_IF (i.e., access point mode, allowing other devices to connect). Different interface types have different methods. For example, only STA mode supports connecting to an access point via WLAN.connect().

Methods

• WLAN.active()

  Queries whether the current interface is active

• WLAN.connect(ssid=None, key=None, [info = None])

  Connects to the specified ssid or info, where info is the result returned by scan.

  Only available in Sta mode

• WLAN.disconnect()

  In Sta mode, disconnects the current WiFi network connection. In Ap mode, a specified mac can be passed in to disconnect a device.

• WLAN.scan()

  Scans for available WiFi networks. This method is only valid in STA mode. The returned list contains information about each network, for example:

  # print(sta.scan())
  [{"ssid":"XCTech", "bssid":xxxxxxxxx, "channel":3, "rssi":-76, "security":"SECURITY_WPA_WPA2_MIXED_PSK", "band":"2.4G", "hidden":0},...]
  

• WLAN.status([param])

  Returns information about the current network connection. When no parameter is passed, returns the current connection status. For example:

  # Check connection status, equivalent to sta.isconnected()
  print(sta.status())
  
  # Check the signal quality of the connection
  print(sta.status("rssi"))
  

  Supported configuration parameters include:

  • In Sta mode

    • rssi: Connection signal quality

    • ap: Name of the connected hotspot

  • In Ap mode

    • stations: Returns information about connected devices

• WLAN.isconnected()

  Returns whether it is connected to a hotspot

  Only available in Sta mode

• WLAN.ifconfig([(ip, subnet, gateway, dns)])

  Gets or sets the IP-level network interface parameters. When called without parameters, returns a 4-tuple containing the IP address, subnet mask, gateway, and DNS server; when parameters are passed in, sets these values. For example:

  sta.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
  

• WLAN.config(param)

  Gets or sets the configuration parameters of the network interface. Use keyword argument syntax when setting parameters; pass the parameter name when querying. For example:

  # Check the auto_reconnect configuration
  print(sta.config('auto_reconnect'))
  
  # Set auto reconnect
  sta.config(auto_reconnect = True)
  

  Supported configuration parameters include:

  • In Sta mode

    • mac: mac address

    • auto_reconnect: Whether to auto reconnect

  • In Ap mode

    • ssid: Hotspot name. When this parameter is passed in, it will configure and start the hotspot. key and security can be used simultaneously to specify the password and security type

    • key: Hotspot password. In encryption mode, the length should be 8 to 64 characters; omit this parameter in open mode

    • security: Hotspot security type. ssid must be passed in at the same time when configuring. The current value can also be queried via ap.config('security')

    • info: Current hotspot information, can only be queried

    • country: Country code

  Common security types in AP mode are as follows. The actual available types depend on the WiFi driver used by the development board. Unsupported types will cause configuration to fail and return False.

  • SECURITY_OPEN: Open hotspot, no password used

  • SECURITY_WPA_TKIP_PSK: WPA-PSK (TKIP)

  • SECURITY_WPA2_AES_PSK: WPA2-PSK (AES), recommended

  • SECURITY_WPA2_MIXED_PSK: WPA2-PSK (AES/TKIP mixed mode)

  Create a WPA2 encrypted hotspot:

  import network
  
  ap = network.WLAN(network.AP_IF)
  result = ap.config(
      ssid='CanMV_AP',
      key='12345678',
      security=ap.SECURITY_WPA2_AES_PSK,
  )
  print(result)
  print(ap.config('security'))
  

  When creating an open hotspot, omit key and set the security type to SECURITY_OPEN:

  ap.config(ssid='CanMV_Open', security=ap.SECURITY_OPEN)
  

  When security is not specified, passing in key defaults to SECURITY_WPA2_AES_PSK; when key is not passed in, it defaults to SECURITY_OPEN.

• WLAN.stop()

  Stops starting the hotspot

  Only available in Ap mode

• WLAN.info()

  Queries the current hotspot information

  Only available in Ap mode