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.

Package · Extension

Wi-Fi from PHP

Scan, join a network or open an access point from PHP. The firmware never connects by itself and keeps no credentials in its configuration. Neutral extension; conductor adds the Wi-Fi HAL for your platform.

ext-wifi gives the script control of the board's Wi-Fi 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 can join it directly. Both roles can run at the same time. In the event-driven runtime it also raises events for what happens on the radio: the station connects, drops or gives up, a scan ends, a station joins the access point.

The SDK brings up the TCP/IP stack and the event loop on every board, but on a Wi-Fi board it never joins a network and never reads credentials: connecting is always a call in your script. Once connected, whatever uses the network works over it, ext-web included.

Requirements

Requires Why
php-baremetal/wifi-hal (virtual) ^1.1 The radio driver lifecycle: init, scan, station, access point, and the driver events. On ESP32 it is php-baremetal/esp32-wifi-hal (platform esp32, over esp_wifi, esp_netif, esp_event, nvs_flash), which also brings php-baremetal/esp32-executor.
php-baremetal/ext-events ^1.1 The event bus the Wi-Fi events travel on (wifi_events()).
php-baremetal/events-hal (virtual) ^1.3 The lock that guards the station state, which the driver events update from their own task. On ESP32 it is php-baremetal/esp32-events-hal, already brought by ext-events.

You never require the HAL yourself. Conductor reads the platform from extra.baremetal.sdk (esp32@^2.0 gives esp32) and adds php-baremetal/esp32-wifi-hal while Composer resolves. The PHP module is wifi. Since ext-wifi 1.1.0 it requires ext-events, which Composer installs with it. The functions work in every runtime; the events are delivered in the event-driven runtime (in init-loop nothing delivers them, and wifi_events() throws in web-server).

Boards

The SDK checks the board when it builds:

Board network ext-wifi
wifi (ESP32-S3 boards such as the Waveshare ESP32-S3-Zero, the ESP32-S3-DevKitC-1, the Waveshare ESP32-S3-Touch-LCD-1.85B) Required to get any network. "network": "on" without ext-wifi is a build error: board '...' connects over Wi-Fi from PHP: composer require php-baremetal/ext-wifi.
wifi-c6 (Waveshare ESP32-P4-WIFI6: an ESP32-C6 companion over ESP-Hosted) Same as wifi; the companion link is started at boot. Builds, not yet verified on hardware.
Wired network on a chip with a radio (Waveshare ESP32-S3-ETH) Optional; Wi-Fi then runs next to Ethernet.
No radio (Waveshare ESP32-P4-ETH, Waveshare ESP32-P4-Pico, generic ESP32-P4) Build error: board '...' has no Wi-Fi: remove php-baremetal/ext-wifi.

Install

  1. Install conductor once per machine

    composer global require php-baremetal/conductor keeps the plugin active during the first solve of a new project.

  2. Create the project

    phpbm init my-wifi writes composer.json with conductor, the package registry, and the SDK, board, runtime and storage you pick.

  3. Require the extension

    composer require php-baremetal/ext-wifi

  4. Build and flash

    phpbm flash builds the firmware and flashes it; phpbm monitor opens the serial console.

The resulting composer.json for a Waveshare ESP32-S3-Zero (N8R8), with the credentials in a .env file that is baked into the firmware and kept out of the sources and of git:

json composer.json
{
  "name": "acme/my-wifi",
  "type": "project",
  "repositories": [
    { "type": "composer", "url": "https://repository.php-baremetal.com", "canonical": true }
  ],
  "require": {
    "php-baremetal/conductor": "^1.0",
    "php-baremetal/ext-wifi": "^1.0"
  },
  "config": {
    "allow-plugins": { "php-baremetal/conductor": true },
    "platform": { "php": "8.5.11" }
  },
  "extra": {
    "baremetal": {
      "sdk": "esp32@^2.0",
      "board": "waveshare-esp32-s3-zero-n8r8",
      "runtime": "init-loop",
      "storage": "embedded",
      "env": ".env"
    }
  }
}
ini .env
WIFI_SSID=my-network
WIFI_PASSWORD=my-password

A first script

php project-src/index.php
<?php
function setup(): void
{
    $ssid = getenv('WIFI_SSID') ?: '';
    $pass = getenv('WIFI_PASSWORD') ?: null;

    echo "connecting to '$ssid'...\n";
    if (wifi_connect($ssid, $pass)) {
        printf("connected: %s (%d dBm)\n", wifi_ip(), wifi_rssi());
    } else {
        echo "connect failed\n";
    }
}

function loop(int $tick): void
{
    echo wifi_connected() ? "online " . wifi_ip() . "\n" : "offline\n";
    usleep(5000000);
}

PHP API at a glance

Function Returns Meaning
wifi_scan(bool $wait = true) array or false; bool with wait: false Networks in range: ssid, bssid, rssi, channel, auth; or start a scan and return.
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 and wait for an IP address, or start joining and return; $power_save sets 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 Station state (Idle, Connecting, Connected, Online) and the network asked for or in use.
wifi_ip(), wifi_rssi() ?string, ?int Station address and signal, 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_events() Baremetal\Wifi\Events Turn on the Wi-Fi events.
wifi_available() bool Whether the radio comes up.

No function throws for a Wi-Fi failure: each reports it in its return value (and, with the events, in ConnectFailed::$reason or Disconnected::$reason).

Dependencies

Notes

  • wifi_scan() and wifi_connect() block the script while they wait (up to 15 s for a scan, $timeout_ms for a connect). In the event-driven runtime nothing else is delivered meanwhile: there, use wait: false and the events.
  • With the web-server runtime on a Wi-Fi board, connect in the init script (the runtime option init), which runs once before the server starts.
  • The first Wi-Fi call initialises the radio and the nvs flash partition. See How it runs for what that means for stored settings.

Related