Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/ext-wifi

bm-ext MIT

wifi_scan/connect/ap_start (STA + SoftAP from PHP), as a php-baremetal extension package. WiFi-capable SoCs only; the arch WiFi HAL is a separate package.

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

$ssid string required

Network name, 1 to 32 bytes; any other length throws \ValueError.

$password ?string optional, default null

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.

$channel int optional, default 1

Wi-Fi channel. While the station is connected the radio follows the station's channel.

$max_conn int optional, default 4

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 init-loop: an access point
<?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