Joining a network

One widget that scans, asks for a password on the panel, and remembers it.

Getting an ESP32 onto WiFi is the same work every time: scan without freezing the screen, show what was found, take a password, say something useful when it fails, and keep the answer so the next boot is silent. WiFi Setup is that work as a single widget. Drop it on a screen and the generator writes the whole flow.

It is on the palette for the Espressif chips only - ESP32, S2, S3 and C3. On an STM32 or an RP2040 the tile is greyed with the reason, because the code behind it is the Arduino WiFi library.

The flow

Search, select, enter pass, verify. Four states, and the password is typed at exactly one of them - on the device, by the person holding it.

State	On screen	Leaves by
Search	"Searching…", then the list	a scan finishing, or Search again
Select	Networks strongest first, with a lock where one is needed	picking one
Enter pass	A masked field and a keyboard	the keyboard's tick, or its cross
Verify	"Joining…", then joined, or why not	success, or back to the list

An open network skips the middle step: there is nothing to type.

Settings

Setting	Default	What it does
Title	Select network	The heading above the list.
Go to when joined	(none)	The screen to move to once it is on the network. Only fires while this screen is the one on show, so a background reconnect does not pull somebody off whatever they were reading.
Go to on Back	(none)	Puts a Back button on the list. Worth setting: without it the only way off this screen is to join something, which strands anybody who opened it by accident.
Reconnect on boot	on	Rejoins the stored network at startup without asking.
Join timeout	20 s	How long to wait before giving up and saying so.
Show Forget	on	A button that clears the stored network and starts a fresh scan.
Access point	Off	Off, when it cannot join, or always on. See below.

Where the password goes

The widget writes two settings, and your design has to declare them: wifi.ssid and wifi.pass. The second must be marked secret, and the designer says so if it is not.

A secret is different from an ordinary setting in three ways, and all three exist to make one rule structural rather than a matter of care:

Nothing reads it back. The generated lw_config.h has no accessor that returns a secret as a string - only one that fills a buffer for the connection code and one that says whether there is a value at all. A label cannot show what it cannot obtain.
It is never in your design. A secret carries no default, so it does not travel with a copy, a published project or an export. The Settings panel shows "Set on device" instead of a value.
It is never exported. The settings file names the keys it left out rather than writing them. Knowing a key exists is not knowing its value.

There is no field anywhere in the designer for typing a station password, and no reveal control on the device - LVGL normally shows each character for a second and a half as it is typed, and the generated lv_conf.h turns that off.

Access point mode

The board can be its own network, either as a fallback when it cannot join anything or all the time. Unlike a station password, the access point's is configured in the design - it has to be, because an access point publishes the password people need in order to reach it. There is no earlier moment at which somebody could have entered one.

Setting	What it does
AP name	What the network is called.
AP password	Empty leaves it open. Otherwise eight characters minimum: `softAP()` given a shorter one returns success and brings the network up open without saying so, which is why the designer refuses that range rather than warning about it.
Do not broadcast	The network is there but does not appear in a scan. You join it by typing the name.

What a design can read

The network is a set of variable sources, so an IP address goes on a label through an ordinary binding.

Value	Type	Notes
IP address	Text	Empty until it has joined.
Network name	Text	What it is joined to.
Signal strength	Integer, dBm	About -50 is excellent, -85 barely usable. -100 means not joined.
Signal bars	Integer	0 to 4, for an indicator.
Connected	Boolean
Last problem	Text	Why the last attempt failed. Worth putting on screen.
Access point running / name / address	Boolean, Text, Text	Offered only when the widget runs an access point.

The text ones need a Text variable.

Two things the hardware does

Scanning drops an existing connection. On the ESP32 the radio cannot do both, so the widget only ever scans from the picker, never behind a working link - and when you open the picker while already joined, it remembers what you were on and rejoins it if you leave without picking anything. Search again from a working link therefore costs you a few seconds offline, not the network. Forget is the one thing that clears that memory, which is what makes it different from Back.

ADC2 does not work while WiFi is on. On the classic ESP32 that is GPIO 0, 2, 4, 12-15 and 25-27. An analog input on one of those reads garbage once the radio comes up, so the designer refuses the combination and points you at ADC1 - GPIO 32 to 39.

When it fails

Three different things go wrong and each says so, because "failed" on its own sends people to reset a router when they mistyped a key:

That network is not in range - the SSID was not found.
Wrong password - the access point refused the key.
Timed out - nothing answered inside the join timeout.

In the preview

A browser cannot scan, so preview shows a plausible list and walks the real flow - pick, type, join, succeed, fail - with the same masking and the same failure text. It is the one part of the designer that is a simulation rather than the thing itself, and it is there so the layout and the failure screen get looked at before anything is flashed.