ext-wifi · PHP API
Station
Scan for networks and join one as a station, waiting for the result or not; read the station state and the network in use.
wifi_scan()
wifi_scan(bool $wait = true): array|bool
Returns array|bool.
Parameters
-
$waitbooloptional, defaulttrue truewaits for the scan and returns its list;falsestarts it and returns at once. Since ext-wifi 1.1.0.
Scans every channel and returns up to 48 networks, or false when the scan could not start or did not finish
within 15 s. Each entry:
| Key | Type | Content |
|---|---|---|
ssid |
string |
Network name; '' for a hidden network. |
bssid |
string |
Access point MAC, lowercase, e.g. a4:cf:12:3b:9e:01. |
rssi |
int |
Signal in dBm, e.g. -58. |
channel |
int |
Primary channel. |
auth |
string |
open, wep, wpa, wpa2, wpa/wpa2, wpa2-ent, wpa3, wpa2/wpa3, wapi or unknown. |
The scan turns the station role on if it was off. It blocks the script while it runs, typically a few seconds.
With wait: false it returns true once the scan has started, false when it cannot start (one is already
running, the station is connecting, or the radio does not come up); a scan that did not start raises no
ScanDone. The list comes in the ScanDone event ($networks, same entries) after
wifi_events(); without the events, a later wifi_scan() scans again. A waiting scan also
raises ScanDone, delivered after the call returns.
No scan is possible while the station is connecting, the automatic retries included: the driver refuses it
and wifi_scan() returns false. With retries: -1 and no access point in range that lasts for good; call
wifi_disconnect(), scan, then connect again.
wifi_connect()
wifi_connect(string $ssid, ?string $password = null, int $timeout_ms = 30000, bool $wait = true, int $retries = 10, Baremetal\Wifi\PowerSave $power_save = PowerSave::Minimum): bool
Returns bool.
Parameters
-
$ssidstringrequired Network name, 1 to 32 bytes; any other length throws
\ValueError(must be 1 to 32 bytes long).-
$password?stringoptional, defaultnull The passphrase: 8 to 63 characters, or exactly 64 hex digits for a raw key. More than 64 bytes or a NUL byte throws
\ValueError.nullor''joins an open network.-
$timeout_msintoptional, default30000 How long to wait for an IP address, with
$waittrue only. A value of 0 or less means 30000. Before ext-wifi 1.0.2 the default was 15000.-
$waitbooloptional, defaulttrue truewaits for the IP address.falsestarts the connect and returns at once:truewhen it started,falsewhen it could not. The outcome comes as theOnlineorConnectFailedevent; a start refused by the driver returnsfalseand raises noConnectFailed. Since ext-wifi 1.1.0.-
$retriesintoptional, default10 Automatic retries after a failed or dropped association, the first association included (the first attempt itself is not counted). The count starts again at every IP address.
0never retries,-1retries forever. Two password refusals in a row, before the connect ever had an IP address, give up at once, whatever$retriesis,-1included:ConnectFailedwithReason::WrongPassword. A single refusal (a weak link or a busy access point can cause one with a correct password) is retried like any other reason; with no retry left the connect gives up withReason::WrongPassword. Every other reason, a missing network included, uses the retries. A value below-1throws\ValueError(wifi_connect(): $retries must be -1 (forever) or more). Since ext-wifi 1.1.0.-
$power_saveBaremetal\Wifi\PowerSaveoptional, defaultPowerSave::Minimum How much the station's radio sleeps while connected:
PowerSave::None,PowerSave::Minimum(the platform's default, the behaviour before ext-wifi 1.2.0) orPowerSave::Maximum. Set before the connect starts and kept until the nextwifi_connect(). Anything else throws\TypeError. A mode the platform refuses (on ESP32,Nonewhile Bluetooth shares the radio) makes the call returnfalsewithout connecting. See Power save. Since ext-wifi 1.2.0.
With the defaults it behaves as before ext-wifi 1.1.0, with one difference: a password refused twice in a row
before the first IP address now ends the attempt at once (before 1.1.0 it was retried up to 10 times). A
wrong password fails sooner; two refusals in a row with a correct password, on a weak link, fail too. It
returns true once the board has an IP address. On the way:
- a current association is dropped first, so calling it again switches networks;
- every channel is scanned and the strongest access point with that name is chosen;
- with a password, WPA2-PSK is the minimum, and WPA3 (SAE) and WPA2/WPA3 transition networks are accepted;
- a failed or dropped association during the attempt is retried, up to
$retriestimes (two password refusals in a row are not retried further).
A call while another connect is in progress cancels it (with the events, Disconnected with Reason::ByUser
if it was associated, never ConnectFailed).
On timeout it stops the attempt (so the board cannot connect after the call reported failure) and returns
false. Wrong credentials, a missing network and a slow DHCP server all show up as false, after
$timeout_ms at the latest; the driver logs the disconnect reason on the console (sta disconnected, reason=..), and
ConnectFailed::$reason tells them apart (wrong-password, not-found; other for the timeout).
Power save
While the station is associated, the radio can sleep between the access point's beacons (modem sleep). The
$power_save argument of wifi_connect() chooses how much:
| Case | Value | Radio | When |
|---|---|---|---|
PowerSave::None |
none |
Always on. | A weak access point (a phone hotspot, far away) or traffic that must answer fast: no stalls waiting for the radio to wake up, at the cost of more current. |
PowerSave::Minimum |
minimum |
Sleeps, wakes for every DTIM beacon. | The default: what the platform does by itself (on ESP32 the ESP-IDF default). |
PowerSave::Maximum |
maximum |
Sleeps longest, wakes at the listen interval (3 beacons). | Battery boards that seldom talk: least current, most latency, and broadcast frames can be missed. |
On a weak link modem sleep can make HTTP stall: on an ESP32-S3 joined to a phone hotspot, Minimum gave a
ping of about 700 ms on average with 5 % loss, None about 150 ms with no loss. If requests time out on such a
network, connect with None:
<?php
use Baremetal\Wifi\PowerSave;
wifi_connect(getenv('WIFI_SSID') ?: '', getenv('WIFI_PASSWORD') ?: null, power_save: PowerSave::None);
The mode stays until the next wifi_connect(), which sets its own (Minimum when not given); the access
point is not affected (its radio is always on). The SDK option power-save (light sleep of the whole chip)
is a separate setting.
wifi_disconnect()
wifi_disconnect(): bool
Returns bool.
Leaves the network, or cancels a connect in progress, and stops retries. Always returns true. The state goes
to Idle; with the events, Disconnected (Reason::ByUser, $retrying false) comes when the station was
associated. The station role stays on, so a scan does not have to restart it.
wifi_connected()
wifi_connected(): bool
Returns bool.
true while the station has an IP address. It turns false as soon as the link drops.
wifi_state() and wifi_ssid()
wifi_state(): Baremetal\Wifi\State
Returns Baremetal\Wifi\State.
The station state: State::Idle (no network asked for), State::Connecting (associating, also during the
retries), State::Connected (associated, no IP address yet) or State::Online (with an IP address). It is
kept up to date in every runtime, with or without wifi_events(), which also lists how it moves.
Since ext-wifi 1.1.0.
wifi_ssid(): ?string
Returns ?string.
The network asked for or in use, or null in Idle. Since ext-wifi 1.1.0.
wifi_ip() and wifi_rssi()
wifi_ip(): ?string
Returns ?string.
The station's IPv4 address, e.g. 192.168.1.42, or null when not connected.
wifi_rssi(): ?int
Returns ?int.
The current signal of the joined access point in dBm, or null when not connected.
When the link drops
When the access point goes away after a successful connect, the driver reconnects on its own, up to
$retries times (10 by default); every time it gets an address the count starts again. The attempts come
about every 2.5 s, so with the default the driver gives up when the access point is gone for more than about
25 s; after that the station stays down (State::Idle). With retries: -1 it never gives up. Otherwise watch
wifi_connected() and call wifi_connect() again:
<?php
function loop(int $tick): void
{
if (!wifi_connected()) {
echo "offline, reconnecting\n";
wifi_connect(getenv('WIFI_SSID') ?: '', getenv('WIFI_PASSWORD') ?: null);
}
usleep(10000000);
}
In the event-driven runtime, the events say the same without polling: Disconnected with
$retrying for each drop, ConnectFailed when the retries run out.
Related
- Access point PHP API
- Events PHP API
- How it runs Reference
- Connect with credentials from .env Recipe