Wi-Fi
Scan, join a network or open the board's own access point from PHP with ext-wifi. The firmware never connects by itself and keeps no credentials: connecting is a call in your script.
ext-wifi gives the script control of the board's radio. As a station it scans for networks and joins one, waiting until it has an IP address. As an access point it opens the board's own network, with a DHCP server, so a phone or laptop joins it directly. Both roles can run at the same time.
Install
The conductor adds the ESP32 HAL (esp32-wifi-hal) for you: never require it. ext-wifi works in every runtime
and does not need ext-events.
Which boards have Wi-Fi
| Network type | Boards | ext-wifi |
|---|---|---|
wifi |
espressif-esp32-s3-devkitc-1-n16r8, -n8r2, -n8r8, freenove-esp32-s3-wroom-lite-n16r8, -n16r16, generic-esp32s3-quad, generic-esp32s3-octal, waveshare-esp32-s3-touch-lcd-1.85b, waveshare-esp32-s3-zero, waveshare-esp32-s3-zero-n8r8 |
Required to get any network |
wifi-c6 |
waveshare-esp32-p4-wifi6: an ESP32-C6 companion chip over SDIO |
Required; the firmware starts the link to the companion whenever ext-wifi is installed |
w5500 |
waveshare-esp32-s3-eth: wired, and the ESP32-S3 has a radio |
Optional: Wi-Fi then runs next to Ethernet |
| none or wired without a radio | waveshare-esp32-p4-eth, waveshare-esp32-p4-pico, generic-esp32p4 |
Not supported: the build fails with board '...' has no Wi-Fi: remove php-baremetal/ext-wifi |
On a wifi or wifi-c6 board, the network option set to on (or a runtime that needs the network) without
ext-wifi is a build error: board '...' connects over Wi-Fi from PHP: composer require php-baremetal/ext-wifi.
Wired boards get an address before PHP starts; see Network. waveshare-esp32-p4-wifi6
builds with ext-wifi, but Wi-Fi has not been verified on the hardware yet.
The main functions
| Function | Returns | Meaning |
|---|---|---|
wifi_scan(bool $wait = true) |
array or bool |
Networks in range, up to 48: ssid, bssid, rssi, channel, auth. With wait: false it starts the scan and returns true; the result comes as ScanDone. |
wifi_connect(string $ssid, ?string $password = null, int $timeout_ms = 30000, bool $wait = true, int $retries = 10, PowerSave $power_save = PowerSave::Minimum) |
bool |
Join a network. By default it waits for an IP address; with wait: false it returns at once and the outcome comes as events. $retries is how many times the driver retries a failed or dropped association (-1 forever); two password refusals in a row give up at once. $power_save (Baremetal\Wifi\PowerSave: None, Minimum, Maximum) is how much the radio sleeps while connected. |
wifi_disconnect() |
bool |
Leave the network. |
wifi_connected() |
bool |
Whether the station has an IP address. |
wifi_state(), wifi_ssid() |
Baremetal\Wifi\State, ?string |
idle, connecting, connected or online, and the network asked for. |
wifi_events() |
Baremetal\Wifi\Events |
Turns on the Wi-Fi events (event-driven runtime). |
wifi_ip(), wifi_rssi() |
?string, ?int |
Station address and signal in dBm; null when not connected. |
wifi_ap_start(string $ssid, ?string $password = null, int $channel = 1, int $max_conn = 4) |
bool |
Open the board's own network. |
wifi_ap_stop() |
bool |
Close it. |
wifi_ap_ip(), wifi_ap_clients() |
?string, int |
Access point address and number of joined stations. |
wifi_ap_active() |
bool |
Whether the access point is up. |
wifi_available() |
bool |
Whether the radio comes up. |
No function throws for a Wi-Fi failure: each reports it in its return value. Signatures and the other details are in the ext-wifi package.
Join a network
08-network-web/wifi-connect scans, then connects with the credentials of the project's env file.
Copy its .env.example to .env and fill it in; the file is baked into the firmware and read as $_ENV, and it
stays out of the sources and out of git (see the
env file).
Credentials are never a project setting: the SSID and password go into each call. Besides the env file they can come from ext-store, for example collected by a setup page on an access point.
Open an access point
08-network-web/wifi-ap opens a network and reports how many devices joined. Join it with a phone
or laptop: the board runs a DHCP server, and with the ESP-IDF defaults its own address is 192.168.4.1.
An access point password shorter than 8 characters is not an error: the network starts open, with no password.
null and '' also open it. Check the length yourself when the password comes from user input.
For an access point with a web page on it, combine ext-wifi with ext-web in the event-driven
runtime: 08-network-web/wifi-ap-s3-rgb-manage serves a colour control page for the onboard RGB LED
over HTTP and WebSocket from the board's own access point.
Events
In the event-driven runtime, wifi_events() makes the radio report what happens instead of being polled:
StateChanged, Online, ConnectFailed, Disconnected and ScanDone for the station, ApStarted,
ApStopped, ClientJoined and ClientLeft for the access point. Pair it with wifi_scan(wait: false) and
wifi_connect(..., wait: false, retries: -1) (started from the ScanDone listener: the driver refuses a scan
while the station joins) and nothing blocks while the board joins and keeps rejoining a network. A start the
driver refuses returns false and raises no event. 08-network-web/wifi-events prints every event. The classes, the states and the failure reasons are
in the ext-wifi package, page usage/events.md. wifi_events() throws in the web-server runtime, where no
events are delivered.
Behaviour on the board
- Blocking.
wifi_scan()waits up to 15 s andwifi_connect()up to$timeout_ms(a value of 0 or less means 30000; 15000 before ext-wifi 1.0.2). The script is blocked while it waits: underinit-loopthe nextloop()runs after the call; underevent-drivenno event is delivered, and HTTP requests queue up and may time out. Withwait: falseboth return at once and the outcome comes as events (ScanDone,Online,ConnectFailed). The other functions return within milliseconds. - The first call sets up the radio. The first
wifi_available(), scan, connect or access point call initialises thenvspartition and the Wi-Fi driver. If the partition is full or in a newer format it is erased and formatted again. If setup fails, every function reports failure (false,nullor0). - Which task does the work. Driver calls run on the executor task (core 0); the PHP task waits for them. If the executor queue stays full for 1 s the call fails.
- Connecting. All channels are scanned and the strongest access point with that SSID is chosen. With a
password the minimum is WPA2-PSK, and WPA3 is accepted. The SSID is 1 to 32 bytes and the password 8 to 63
characters or 64 hex digits; a longer value or a NUL byte throws
\ValueError. A failed or dropped association is retried up to$retriestimes (10 by default,-1forever), except a refused password: while the connect has never had an address, two refusals in a row give up at once (ConnectFailedwithwrong-password), whatever$retriesis. A single refusal is retried, because a weak link can cause one with a correct password; before ext-wifi 1.1.0 a wrong password was retried up to 10 times. - When the link drops. The driver reconnects on its own, up to
$retriestimes (10 by default), and the count starts again at every address it gets; with the default, after 10 failures in a row (about 25 s) the station stays down (ConnectFailedinevent-drivenwithwifi_events()). Watchwifi_connected()and callwifi_connect()again, or passretries: -1towifi_connect()to keep trying forever. - Credentials stay in RAM. The driver does not write SSIDs or passwords to flash.
- Access point. The radio follows the station's channel while the station is connected.
$max_conndefaults to 4. - Power. By default the station uses the ESP-IDF default, modem sleep while connected
(
PowerSave::Minimum). On a weak access point (a phone hotspot) modem sleep can stall HTTP; passpower_save: PowerSave::Nonetowifi_connect()to keep the radio on (ext-wifi 1.2.0 and later). This is separate from thepower-saveoption (light sleep); Wi-Fi withpower-saveon has not been verified on hardware. See Power saving.
With the web-server runtime
The web-server runtime needs a network, and on a Wi-Fi board it does not connect for
you. Connect in the init script, which runs once before the server starts and has the same time limit as a
request. If the script fails, the program ends.
With event-driven and ext-web, connect or open the access point in the entry script before serve_http();
a wifi_connect(..., wait: false) there returns before the address exists, so use the blocking form.
Common errors
| Symptom | Cause |
|---|---|
connect failed (wifi_connect() returns false) |
Wrong credentials, network not in range or a slow DHCP server, all after $timeout_ms. The console prints sta disconnected, reason=... |
wifi_scan() returns false |
The scan could not start or did not finish within 15 s. |
| The access point has no password | The password was null, empty or under 8 characters. |
serve_http(): no network interface (turn the network option on, or connect with ext-wifi first) |
serve_http() ran before wifi_connect() or wifi_ap_start(). |
Build error has no Wi-Fi: remove php-baremetal/ext-wifi |
The board has no radio. |
Wi-Fi calls fail on waveshare-esp32-p4-wifi6 |
The ESP32-C6 companion did not answer at boot; the console says so. |
eh_init_evt: major version mismatch — OTA coprocessor from host at boot on waveshare-esp32-p4-wifi6 |
The ESP32-C6 runs the firmware the board shipped with, which reports version 0.0.0 to esp_hosted 3.0.9. Wi-Fi still works; the SDK does not update the C6. |