mirror of
https://github.com/sascha-hemi/pycom-documentation.git
synced 2026-03-21 08:06:34 +01:00
157 lines
6.1 KiB
Markdown
157 lines
6.1 KiB
Markdown
# WLAN
|
||
|
||
This class provides a driver for the WiFi network processor in the module. Example usage:
|
||
|
||
```python
|
||
import network
|
||
import time
|
||
# setup as a station
|
||
wlan = network.WLAN(mode=network.WLAN.STA)
|
||
wlan.connect('your-ssid', auth=(network.WLAN.WPA2, 'your-key'))
|
||
while not wlan.isconnected():
|
||
time.sleep_ms(50)
|
||
print(wlan.ifconfig())
|
||
|
||
# now use socket as usual
|
||
```
|
||
|
||
## Quick Usage Example
|
||
|
||
```python
|
||
import machine
|
||
from network import WLAN
|
||
|
||
# configure the WLAN subsystem in station mode (the default is AP)
|
||
wlan = WLAN(mode=WLAN.STA)
|
||
# go for fixed IP settings (IP, Subnet, Gateway, DNS)
|
||
wlan.ifconfig(config=('192.168.0.107', '255.255.255.0', '192.168.0.1', '192.168.0.1'))
|
||
wlan.scan() # scan for available networks
|
||
wlan.connect(ssid='mynetwork', auth=(WLAN.WPA2, 'my_network_key'))
|
||
while not wlan.isconnected():
|
||
pass
|
||
print(wlan.ifconfig())
|
||
```
|
||
|
||
## Constructors
|
||
|
||
### class network.WLAN\(id=0, ...\)
|
||
|
||
Create a WLAN object, and optionally configure it. See [`init`](wlan.md#wlan-init-mode-ssid-none-auth-none-channel-1-antenna-none-power_save-false-hidden-false) for params of configuration.
|
||
|
||
{% hint style="info" %}
|
||
The WLAN constructor is special in the sense that if no arguments besides the `id` are given, it will return the already existing WLAN instance without re-configuring it. This is because WLAN is a system feature of the WiPy. If the already existing instance is not initialised it will do the same as the other constructors an will initialise it with default values.
|
||
{% endhint %}
|
||
|
||
## Methods
|
||
|
||
### wlan.init\(mode, \* , ssid=None, auth=None, channel=1, antenna=None, power\_save=False, hidden=False\)
|
||
|
||
Set or get the WiFi network processor configuration.
|
||
|
||
Arguments are:
|
||
|
||
* `mode` can be either `WLAN.STA`, `WLAN.AP`, or `WLAN.STA_AP`.
|
||
* `ssid` is a string with the SSID name. Only needed when mode is `WLAN.AP`.
|
||
* `auth` is a tuple with \(sec, key\). Security can be `None`, `WLAN.WEP`, `WLAN.WPA`, or `WLAN.WPA2`. The key is a string with the network password.
|
||
* If `sec` is `WLAN.WEP` the key must be a string representing hexadecimal values \(e.g. `ABC1DE45BF`\). Only needed when mode is `WLAN.AP`.
|
||
* `channel` a number in the range 1-11. Only needed when mode is `WLAN.AP`.
|
||
* `antenna` selects between the internal and the external antenna. Can be either `WLAN.INT_ANT`, `WLAN.EXT_ANT`. With our development boards it defaults to using the internal antenna, but in the case of an OEM module, the antenna pin \(`P12`\) is not used, so it’s free to be
|
||
|
||
used for other things.
|
||
|
||
* `power_save` enables or disables power save functions in `STA` mode.
|
||
* `hidden` only valid in `WLAN.AP` mode to create an access point with a hidden SSID when set to `True`.
|
||
|
||
For example, you can do:
|
||
|
||
```python
|
||
# create and configure as an access point
|
||
wlan.init(mode=WLAN.AP, ssid='wipy-wlan', auth=(WLAN.WPA2,'www.wipy.io'), channel=7, antenna=WLAN.INT_ANT)
|
||
```
|
||
|
||
or
|
||
|
||
```python
|
||
# configure as an station
|
||
wlan.init(mode=WLAN.STA)
|
||
```
|
||
|
||
### wlan.deinit\(\)
|
||
|
||
Disables the WiFi radio.
|
||
|
||
### wlan.connect\(ssid, \* , auth=None, bssid=None, timeout=None, ca\_certs=None, keyfile=None, certfile=None, identity=None\)
|
||
|
||
Connect to a wifi access point using the given SSID, and other security parameters.
|
||
|
||
* `auth` is a tuple with `(sec, key)`. Security can be `None`, `WLAN.WEP`, `WLAN.WPA`, `WLAN.WPA2` or `WLAN.WPA2_ENT`. The key is a string with the network password.
|
||
* If `sec` is `WLAN.WEP` the key must be a string representing hexadecimal values \(e.g. `ABC1DE45BF`\).
|
||
* If `sec` is `WLAN.WPA2_ENT` then the `auth` tuple can have either 3 elements: `(sec, username, password)`, or just 1: `(sec,)`. When passing the 3 element tuple, the`keyfile` and `certifle` arguments must not be given.
|
||
* `bssid` is the MAC address of the AP to connect to. Useful when there are several APs with the same SSID.
|
||
* `timeout` is the maximum time in milliseconds to wait for the connection to succeed.
|
||
* `ca_certs` is the path to the CA certificate. This argument is not mandatory.
|
||
* `keyfile` is the path to the client key. Only used if `username` and `password` are not part of the `auth` tuple.
|
||
* `certfile` is the path to the client certificate. Only used if `username` and `password` are not part of the `auth` tuple.
|
||
* `identity` is only used in case of `WLAN.WPA2_ENT` security. Needed by the server.
|
||
|
||
{% hint style="info" %}
|
||
The ESP32 only handles certificates with `pkcs8` format \(but not the "Traditional SSLeay RSAPrivateKey" format\). The private key should be RSA coded with 2048 bits at maximum.
|
||
{% endhint %}
|
||
|
||
### wlan.scan\(\)
|
||
|
||
Performs a network scan and returns a list of named tuples with `(ssid, bssid, sec, channel, rssi)`. Note that channel is always `None` since this info is not provided by the WiPy.
|
||
|
||
### wlan.disconnect\(\)
|
||
|
||
Disconnect from the WiFi access point.
|
||
|
||
### 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, `False` otherwise.
|
||
|
||
### wlan.ifconfig\(id=0, config=\['dhcp' or configtuple\]\)
|
||
|
||
When `id` is 0, the configuration will be get/set on the Station interface. When `id` is 1 the configuration will be done for the AP interface.
|
||
|
||
With no parameters given returns a 4-tuple of `(ip, subnet_mask, gateway, DNS_server)`.
|
||
|
||
If `dhcp` is passed as a parameter then the DHCP client is enabled and the IP params are negotiated with the AP.
|
||
|
||
If the 4-tuple config is given then a static IP is configured. For instance:
|
||
|
||
```python
|
||
wlan.ifconfig(config=('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
|
||
```
|
||
|
||
### wlan.mode\(\[mode\]\)
|
||
|
||
Get or set the WLAN mode.
|
||
|
||
### wlan.ssid\(\[ssid\]\)
|
||
|
||
Get or set the SSID when in AP mode.
|
||
|
||
### wlan.auth\(\[auth\]\)
|
||
|
||
Get or set the authentication type when in AP mode.
|
||
|
||
### wlan.channel\(\[channel\]\)
|
||
|
||
Get or set the channel \(only applicable in AP mode\).
|
||
|
||
### wlan.antenna\(\[antenna\]\)
|
||
|
||
Get or set the antenna type \(external or internal\).
|
||
|
||
### wlan.mac\(\)
|
||
|
||
Get a 6-byte long `bytes` object with the WiFI MAC address.
|
||
|
||
## Constants
|
||
|
||
* WLAN mode: `WLAN.STA`, `WLAN.AP`, `WLAN.STA_AP`
|
||
* WLAN network security: `WLAN.WEP`, `WLAN.WPA`, `WLAN.WPA2`, `WLAN.WPA2_ENT`
|
||
* Antenna type: `WLAN.INT_ANT`, `WLAN.EXT_ANT`
|
||
|