ext-wifi · PHP API
Access point
Turn the board into a Wi-Fi access point with a DHCP server, alone or next to a station connection.
wifi_ap_start()
wifi_ap_start(string $ssid, ?string $password = null, int $channel = 1, int $max_conn = 4): bool
Returns bool.
Parameters
-
$ssidstringrequired Network name, 1 to 32 bytes; any other length throws
\ValueError.-
$password?stringoptional, defaultnull WPA2-PSK passphrase of 8 to 63 characters, or exactly 64 hex digits (more than 64 bytes or a NUL byte throws
\ValueError).null,''or anything shorter than 8 characters opens the network with no password.-
$channelintoptional, default1 Wi-Fi channel. While the station is connected the radio follows the station's channel.
-
$max_connintoptional, default4 How many stations may join at once.
Returns true when the network is up, false when the driver refused the settings (for example an invalid
channel). Calling it again replaces the settings; if the driver refuses the new ones, the running access point
stays up with its previous settings and no event is raised. With the station role also on, both run together: starting
or stopping the access point never touches the station, and switching the station on never stops the access
point (the driver's internal restart raises no event). With wifi_events() every call raises one
ApStarted ($ssid, $ip), also when it replaces the settings of an access point already up. A start undone by
a wifi_ap_stop() before the radio has finished starting raises neither ApStarted nor ApStopped;
wifi_ap_active() is false afterwards.
wifi_ap_stop()
wifi_ap_stop(): bool
Returns bool.
Closes the access point and returns true. A station connection stays up; with no role left, the radio
stops. With the events it raises ApStopped, whose $clients says how many stations were joined before the
stop. ClientLeft may or may not arrive for the stations the stop drops (on ESP32 it usually comes first,
with code 2): reset the script's list of clients on ApStopped. With the access point already down it
returns true and raises nothing.
wifi_ap_ip() and wifi_ap_clients()
wifi_ap_ip(): ?string
Returns ?string.
The board's address on its own network, or null when the access point is not up. With the ESP-IDF defaults
it is 192.168.4.1, and joined devices get their addresses from the board's DHCP server.
wifi_ap_clients(): int
Returns int.
How many stations are joined right now; 0 when the access point is down. With the events, every station
that joins or leaves raises ClientJoined or ClientLeft, with its MAC address ($mac) and the count after
the change ($clients).
wifi_ap_active()
wifi_ap_active(): bool
Returns bool.
true while the access point is up. Since ext-wifi 1.1.0.
wifi_available()
wifi_available(): bool
Returns bool.
true when the radio comes up. The first call brings up the Wi-Fi driver, without joining or opening a
network; false means it could not (on a board whose Wi-Fi is an ESP32-C6 companion, the companion did not
start). The function exists only when ext-wifi is in the firmware: to write a script that also runs without
it, test function_exists('wifi_available') first.
Example
<?php
const AP_SSID = 'php-baremetal';
const AP_PASS = 'baremetal'; // 8 characters or more
function setup(): void
{
if (!wifi_ap_start(AP_SSID, AP_PASS)) {
exit("cannot start the access point\n");
}
printf("join '%s' and reach the board at %s\n", AP_SSID, wifi_ap_ip());
}
function loop(int $tick): void
{
printf("%d device(s) joined\n", wifi_ap_clients());
usleep(5000000);
}
Related
- Station PHP API
- Events PHP API
- Access point fallback Recipe