mirror of
https://github.com/micropython/micropython.git
synced 2026-01-04 11:10:14 +01:00
196 lines
7.9 KiB
ReStructuredText
196 lines
7.9 KiB
ReStructuredText
.. currentmodule:: network
|
|
.. _network.WLAN:
|
|
|
|
class WLAN -- control built-in WiFi interfaces
|
|
==============================================
|
|
|
|
This class provides a driver for WiFi network processors. Example usage::
|
|
|
|
import network
|
|
# enable station interface and connect to WiFi access point
|
|
nic = network.WLAN(network.WLAN.IF_STA)
|
|
nic.active(True)
|
|
nic.connect('your-ssid', 'your-key')
|
|
# now use sockets as usual
|
|
|
|
Constructors
|
|
------------
|
|
.. class:: WLAN(interface_id)
|
|
|
|
Create a WLAN network interface object. Supported interfaces are
|
|
``network.WLAN.IF_STA`` (station aka client, connects to upstream WiFi access
|
|
points) and ``network.WLAN.IF_AP`` (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
|
|
-------
|
|
|
|
.. method:: WLAN.active([is_active])
|
|
|
|
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.
|
|
|
|
.. method:: WLAN.connect(ssid=None, key=None, *, bssid=None)
|
|
|
|
Connect to the specified wireless network, using the specified key.
|
|
If *bssid* is given then the connection will be restricted to the
|
|
access-point with that MAC address (the *ssid* must also be specified
|
|
in this case).
|
|
|
|
.. method:: WLAN.disconnect()
|
|
|
|
Disconnect from the currently connected wireless network.
|
|
|
|
.. method:: WLAN.scan()
|
|
|
|
Scan for the available wireless networks.
|
|
Hidden networks -- where the SSID is not broadcast -- will also be scanned
|
|
if the WLAN interface allows it.
|
|
|
|
Scanning is only possible on STA interface. Returns list of tuples with
|
|
the information about WiFi access points:
|
|
|
|
(ssid, bssid, channel, RSSI, security, hidden)
|
|
|
|
*bssid* is hardware address of an access point, in binary form, returned as
|
|
bytes object. You can use `binascii.hexlify()` to convert it to ASCII form.
|
|
|
|
There are five values for security:
|
|
|
|
* 0 -- open
|
|
* 1 -- WEP
|
|
* 2 -- WPA-PSK
|
|
* 3 -- WPA2-PSK
|
|
* 4 -- WPA/WPA2-PSK
|
|
|
|
and two for hidden:
|
|
|
|
* 0 -- visible
|
|
* 1 -- hidden
|
|
|
|
.. method:: WLAN.status([param])
|
|
|
|
Return the current status of the wireless connection.
|
|
|
|
When called with no argument the return value describes the network link status.
|
|
The possible statuses are defined as constants in the :mod:`network` module:
|
|
|
|
* ``STAT_IDLE`` -- no connection and no activity,
|
|
* ``STAT_CONNECTING`` -- connecting in progress,
|
|
* ``STAT_WRONG_PASSWORD`` -- failed due to incorrect password,
|
|
* ``STAT_NO_AP_FOUND`` -- failed because no access point replied,
|
|
* ``STAT_CONNECT_FAIL`` -- failed due to other problems,
|
|
* ``STAT_GOT_IP`` -- connection successful.
|
|
|
|
When called with one argument *param* should be a string naming the status
|
|
parameter to retrieve, and different parameters are supported depending on the
|
|
mode the WiFi is in.
|
|
|
|
In STA mode, passing ``'rssi'`` returns a signal strength indicator value, whose
|
|
format varies depending on the port (this is available on all ports that support
|
|
WiFi network interfaces, except for CC3200).
|
|
|
|
In AP mode, passing ``'stations'`` returns a list of connected WiFi stations
|
|
(this is available on all ports that support WiFi network interfaces, except for
|
|
CC3200). The format of the station information entries varies across ports,
|
|
providing either the raw BSSID of the connected station, the IP address of the
|
|
connected station, or both.
|
|
|
|
.. method:: WLAN.isconnected()
|
|
|
|
In case of STA mode, returns ``True`` if connected to a WiFi access
|
|
point and has a valid IP address. In AP mode returns ``True`` when a
|
|
station is connected. Returns ``False`` otherwise.
|
|
|
|
.. method:: WLAN.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(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
|
|
|
|
.. method:: WLAN.config('param')
|
|
WLAN.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
|
|
`AbstractNIC.ipconfig()`). These include network-specific and hardware-specific
|
|
parameters. For setting parameters, keyword argument syntax should be used,
|
|
multiple parameters can be set at once. For querying, parameters name should
|
|
be quoted as a string, and only one parameter can be queries at time::
|
|
|
|
# Set WiFi access point name (formally known as SSID) and WiFi channel
|
|
ap.config(ssid='My AP', channel=11)
|
|
# Query params one by one
|
|
print(ap.config('ssid'))
|
|
print(ap.config('channel'))
|
|
|
|
Following are commonly supported parameters (availability of a specific parameter
|
|
depends on network technology type, driver, and :term:`MicroPython port`).
|
|
|
|
============= ===========
|
|
Parameter Description
|
|
============= ===========
|
|
mac MAC address (bytes)
|
|
ssid WiFi access point name (string)
|
|
channel WiFi channel (integer). Depending on the port this may only be supported on the AP interface.
|
|
hidden Whether SSID is hidden (boolean)
|
|
security Security protocol supported (enumeration, see module constants)
|
|
key Access key (string)
|
|
hostname The hostname that will be sent to DHCP (STA interfaces) and mDNS (if supported, both STA and AP). (Deprecated, use :func:`network.hostname` instead)
|
|
reconnects Number of reconnect attempts to make (integer, 0=none, -1=unlimited)
|
|
txpower Maximum transmit power in dBm (integer or float)
|
|
pm WiFi Power Management setting (see below for allowed values)
|
|
protocol (ESP32 Only.) WiFi Low level 802.11 protocol. See `WLAN.PROTOCOL_DEFAULT`.
|
|
============= ===========
|
|
|
|
Constants
|
|
---------
|
|
|
|
.. data:: WLAN.PM_PERFORMANCE
|
|
WLAN.PM_POWERSAVE
|
|
WLAN.PM_NONE
|
|
|
|
Allowed values for the ``WLAN.config(pm=...)`` network interface parameter:
|
|
|
|
* ``PM_PERFORMANCE``: enable WiFi power management to balance power
|
|
savings and WiFi performance
|
|
* ``PM_POWERSAVE``: enable WiFi power management with additional power
|
|
savings and reduced WiFi performance
|
|
* ``PM_NONE``: disable wifi power management
|
|
|
|
|
|
ESP32 Protocol Constants
|
|
------------------------
|
|
|
|
The following ESP32-only constants relate to the ``WLAN.config(protocol=...)``
|
|
network interface parameter:
|
|
|
|
.. data:: WLAN.PROTOCOL_DEFAULT
|
|
|
|
A bitmap representing all of the default 802.11 Wi-Fi modes supported by
|
|
the chip. Consult `ESP-IDF Wi-Fi Protocols`_ documentation for details.
|
|
|
|
.. data:: WLAN.PROTOCOL_LR
|
|
|
|
This value corresponds to the `Espressif proprietary "long-range" mode`_,
|
|
which is not compatible with standard Wi-Fi devices. By setting this
|
|
protocol it's possible for an ESP32 STA in long-range mode to connect to
|
|
an ESP32 AP in long-range mode, or to use `ESP-NOW long range modes
|
|
<espnow-long-range>`.
|
|
|
|
This mode can be bitwise ORed with some standard 802.11 protocol bits
|
|
(including `WLAN.PROTOCOL_DEFAULT`) in order to support a mix of standard
|
|
Wi-Fi modes as well as LR mode, consult the `Espressif long-range
|
|
documentation`_ for more details.
|
|
|
|
Long range mode is not supported on ESP32-C2.
|
|
|
|
.. _ESP-IDF Wi-Fi Protocols: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/wifi.html#wi-fi-protocol-mode
|
|
.. _Espressif proprietary "long-range" mode:
|
|
.. _Espressif long-range documentation: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/wifi.html#long-range-lr
|