php-baremetal/php-esp32-sdk

SDK First-party

The esp32 SDK: boards, the PHP build recipe, runtimes, storages and the ESP-IDF toolchain for ESP32-P4 and ESP32-S3. phpbm downloads and drives it.

SDK · Modules

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

bash in the project folder
composer require php-baremetal/ext-wifi

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).

ini .env.example
WIFI_SSID=
WIFI_PASSWORD=
json composer.json, extra.baremetal
{
  "sdk": "esp32@^2.0",
  "board": "waveshare-esp32-s3-zero-n8r8",
  "runtime": "init-loop",
  "storage": "embedded",
  "env": ".env"
}
php project-src/index.php
<?php
$SSID = $_ENV['WIFI_SSID'] ?? '';
$PASS = $_ENV['WIFI_PASSWORD'] ?? '';   // empty for an open network

function setup(): void
{
    global $SSID, $PASS;

    $aps = wifi_scan();   // array of APs, or false if the scan itself failed
    foreach ($aps ?: [] as $ap) {
        printf("  %-32s ch%-3d %4d dBm  %s\n",
               $ap['ssid'] !== '' ? $ap['ssid'] : '(hidden)',
               $ap['channel'], $ap['rssi'], $ap['auth']);
    }

    if ($SSID === '') {
        echo "\nno WIFI_SSID set -- copy .env.example to .env and fill it in to connect\n";
        return;
    }

    echo "\nconnecting to '" . $SSID . "'...\n";
    if (wifi_connect($SSID, $PASS !== '' ? $PASS : null)) {
        echo "connected! IP " . wifi_ip() . "  (" . wifi_rssi() . " dBm)\n";
    } else {
        echo "connect failed -- check the credentials in .env\n";
    }
}

function loop(int $tick): void
{
    if (wifi_connected()) {
        echo "tick $tick: online, IP " . wifi_ip() . ", rssi " . wifi_rssi() . " dBm\n";
    } else {
        echo "tick $tick: offline\n";
    }
    delay(5000);
}

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.

php project-src/index.php
<?php
const AP_SSID = 'php-baremetal';
const AP_PASS = 'baremetal';   // >= 8 chars for WPA2; '' (empty) for an open network

function setup(): void
{
    if (wifi_ap_start(AP_SSID, AP_PASS !== '' ? AP_PASS : null)) {
        echo "access point '" . AP_SSID . "' is up at " . wifi_ap_ip() . "\n";
    } else {
        echo "failed to start the access point\n";
    }
}

function loop(int $tick): void
{
    echo "tick $tick: " . wifi_ap_clients() . " device(s) connected to " . AP_SSID . "\n";
    delay(5000);
}
Danger A short password opens the network

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 and wifi_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: under init-loop the next loop() runs after the call; under event-driven no event is delivered, and HTTP requests queue up and may time out. With wait: false both 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 the nvs partition 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, null or 0).
  • 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 $retries times (10 by default, -1 forever), except a refused password: while the connect has never had an address, two refusals in a row give up at once (ConnectFailed with wrong-password), whatever $retries is. 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 $retries times (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 (ConnectFailed in event-driven with wifi_events()). Watch wifi_connected() and call wifi_connect() again, or pass retries: -1 to wifi_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_conn defaults 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; pass power_save: PowerSave::None to wifi_connect() to keep the radio on (ext-wifi 1.2.0 and later). This is separate from the power-save option (light sleep); Wi-Fi with power-save on 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.

json composer.json, extra.baremetal
{
  "runtime": "web-server",
  "options": { "init": "connect.php", "port": 8080 }
}
php project-src/connect.php
<?php
if (!wifi_connect($_ENV['WIFI_SSID'] ?? '', $_ENV['WIFI_PASSWORD'] ?? null)) {
    exit("wifi: connect failed\n");
}
echo "online at ", wifi_ip(), "\n";

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.
Last updated 2026-11-15 · v2.0.x Edit on GitHub Report issue