wifi_manager
wifi_manager gets a board onto Wi-Fi without putting a password in your
code. It joins a network the board already knows. When none is in range, it
can turn the board into a small access point with a setup page, so you pick
the network and type its password on your phone. The board remembers every
network it joins.
import wifi_manager
ip = wifi_manager.connect()
It runs on MicroPython and CircuitPython. It’s part of the omnipython
package, so a firmware that freezes OmniPython already has it. Otherwise:
import omip
omip.install("omnipython")
omip comes with OmniPython firmware. On other MicroPython firmware, run
mip.install("github:PyDevices/omnipython/lib/omip.py") once to put it on the board.
On CircuitPython, copy lib/wifi_manager.py to the board’s /lib.
Three kinds of app
How you call it depends on what your app does without a network. Here are the three cases: an app that can’t work without the network, one that works offline, and one that only needs Wi-Fi while you maintain it.
The app needs the network
A voice assistant, a dashboard or anything that fetches what it shows is no
use offline. Call connect() before anything else. It returns once the board
has an address, and if no known network is in range it stays in setup mode
until you’ve given it one:
import wifi_manager
ip = wifi_manager.connect(hostname="kitchen-panel")
A weak link fails a join now and then. connect() tries every known network
twice before it decides none is there, so a board at the edge of your router’s
range still joins at boot rather than showing the setup page. If your board
lives somewhere marginal, call it with setup=False a couple of times first,
and only then without.
The app works without it
A synthesizer that can also stream, or a sensor that uploads when it can,
should start at once and join quietly when it can. Pass setup=False:
connect() then returns None instead of starting setup mode, and the app
carries on offline.
ip = wifi_manager.connect(setup=False, hostname="devkit")
if ip is None:
print("offline")
Give the user a way to add a network later, such as a “Wi-Fi setup” button,
that calls wifi_manager.run(). run() starts setup mode even when a known
network is in range, and waits until you’ve picked a new one.
Call run() from your main loop, not from inside a timer or a button’s
callback. Setup mode keeps your app’s timers (and LVGL) running by delivering
them from its own waits, and it can’t do that from inside one of them. From a
callback, hand the work on: set a flag your loop checks, or use
micropython.schedule.
Wi-Fi only for maintenance
A watch or a battery sensor doesn’t need Wi-Fi to do its job. You only want it when you’re updating files or poking at the REPL, and a radio left on drains the battery. Join when you ask for it, start WebREPL, and turn both off when you’re done:
import network
import webrepl
import wifi_manager
def wifi_on():
ip = wifi_manager.connect(setup=False, hostname="watch")
if ip:
webrepl.start() # the password is PASS in /webrepl_cfg.py
return ip
def wifi_off():
wifi_manager.cancel() # in case setup mode is waiting
webrepl.stop()
network.WLAN(network.STA_IF).active(False)
If no known network is in range, offer run() to add one. Call cancel()
when the user leaves while setup mode is still waiting: run() returns
None and the access point goes away. Keep the board awake while Wi-Fi is
on, because a light sleep drops the link.
Reaching the board over Wi-Fi
With the board’s remote access on, mcuctl and Workbench can reach it without a cable. Each interpreter uses the files it already reads, so stock firmware needs nothing from PyDevices.
MicroPython. Put a secrets.py on the board with WIFI_SSID and
WIFI_PASSWORD, then run mcuctl wifi enable over USB. It shows you the change
and writes two files: /webrepl_cfg.py with PASS = "..." (4 to 9 characters),
and a block at the top of boot.py that joins the network with network.WLAN
and calls webrepl.start(). Set a hostname when you connect, and the board
answers as NAME.local:
mcuctl put secrets.py /secrets.py
mcuctl wifi enable
mcuctl exec -d ws://kitchen-panel.local "print(1 + 1)"
mcuctl wifi disable puts both files back as they were. If the board has
wifi_manager, the block tries wifi_manager.connect(setup=False) first, so
it joins any network the board remembers; without it the block joins the one in
secrets.py.
CircuitPython. The same secrets.py, or CIRCUITPY_WIFI_SSID and
CIRCUITPY_WIFI_PASSWORD already in settings.toml. mcuctl wifi enable puts
the missing settings, and CIRCUITPY_WEB_API_PASSWORD, at the top of
settings.toml; reset the board and it serves CircuitPython’s web workflow.
CircuitPython has no WebREPL, so webrepl_cfg.py is MicroPython-only.
wifi_manager reads the same settings.toml and secrets.py.
WebREPL and the web workflow have no encryption, so treat their passwords as a courtesy lock on your own network. mcuctl’s Connect over Wi-Fi has the details.
Slow replies: turn off power saving
By default an ESP32 saves power by letting its Wi-Fi radio sleep between the access point’s beacons. Anything sent to the board waits until the radio next wakes. A stream that only sends barely notices. An app that asks and waits for each reply pays that delay on every request: a picture, a REPL line, a ping. That includes request-and-reply protocols like the camera examples and WebREPL.
On a P4 sending 27 KB camera pictures one request at a time, at -60 to -65 dBm:
Link |
Median per picture |
Slowest |
|---|---|---|
Ethernet |
62 ms |
103 ms |
Wi-Fi, power saving on (the default) |
300 to 690 ms |
7.9 s |
Wi-Fi, power saving off |
110 to 210 ms |
2.4 s |
Turn it off when your app talks back and forth or needs low latency:
import wifi
wifi.radio.power_management = wifi.PowerManagement.NONE
On MicroPython without wifi, network.WLAN(network.STA_IF).config(pm=network.WLAN.PM_NONE)
does the same. It costs battery, so leave it on for a board that only
checks in now and then.
Power saving also makes pings lie. An idle board in power saving answers
pings in 100 to 900 ms however good the signal is. To judge the link, read
the signal strength (wifi.radio.ap_info.rssi) instead, or measure with
power saving off.
Setup mode
When setup mode starts, the board shows how to reach it, on its display when it has one and always on the REPL:
Join the network named after the board, such as
omnipython-a1b2c3(the board’s name), with the password shown. A phone camera can join from the QR code.The phone opens the setup page by itself. If it doesn’t, browse to http://192.168.4.1.
Pick your network, type its password, press Join.
The board joins, remembers the network and carries on. If the password was wrong, the page says so and you can try again. A hidden network goes in “Other” on the page.
Setup mode started by connect() also looks for a known network every
minute, so a board that booted while the router was down joins by itself
once it’s back. Setup mode started by run() doesn’t: you asked for a new
network, so it waits for one.
The page is drawn in LVGL when the board has lvgl and display_driver,
otherwise with pygraphics on board_config.display_drv. With neither, the
REPL is the only screen. The QR code needs lv.qrcode, or adafruit_miniqr
for the pygraphics page.
Which networks it knows
connect() knows the network in secrets.py (WIFI_SSID and
WIFI_PASSWORD), the one in CircuitPython’s settings.toml
(CIRCUITPY_WIFI_SSID and CIRCUITPY_WIFI_PASSWORD), and every network it
has joined before. Once a board has joined, you can delete secrets.py.
When it knows one network, it joins it straight away. When it knows more, it
scans first and tries the known networks it saw, strongest first, then the
known networks it didn’t see, because a scan misses a weak network about
half the time. A scan holds the board for a few seconds, which is why one
network goes without it. Then it goes round once more. Each attempt waits up to
timeout seconds (20 by default), but a missing network ends it after about
six seconds and a wrong password after about fourteen.
A board with a fixed address (ifconfig() set before the join) counts as
connected only once the station has a link, so it joins at boot and rejoins
after a drop.
wifi.connect_from_secrets() is deprecated. It calls connect() with
setup=False and ntp=True, and only exists for boards whose boot.py still
calls it. Use connect() in new code.
Remembered networks live here, with their passwords in plain text, as in
secrets.py:
Where |
Store |
|---|---|
MicroPython on ESP32 |
NVS namespace |
Other MicroPython ports |
|
CircuitPython |
|
It keeps 16 at most.
Reference
Call |
Does |
|---|---|
|
Joins a known network and returns its IPv4 address. With none in range, runs setup mode, or returns |
|
Starts setup mode now and returns the address of the network joined, or |
|
Ends a waiting setup mode without a network. Call it from a timer or another app. |
|
The remembered SSIDs. |
|
Forgets one remembered network, or all of them. A network still in |
display_drv defaults to board_config.display_drv when there is one.
hostname is set before the join so DHCP and mDNS see it, and defaults to
the board’s name.
ntp=True sets the clock once a network is joined. wait=False starts
joining the first known network and returns None at once, for an app that
can’t stall: poll wifi.radio.connected, or call it again after a drop (on
CircuitPython a join can’t run in the background, so it waits). module names
the module that holds WIFI_SSID and WIFI_PASSWORD when it isn’t secrets.
Setting |
Default |
Meaning |
|---|---|---|
|
|
The setup access point’s name; |
|
|
Seconds to wait for one network |
|
|
Seconds between looks for a known network while |
|
|
CircuitPython: where the record starts in |
|
|
MicroPython ports without |