Skip to content
php-baremetal REGISTRY
Publish a package

php-baremetal/esp32-wifi-hal

bm-hal MIT

ESP32 implementation of the WiFi HAL (bm_wifi_hal.h) over esp_wifi / esp_netif / esp_event. Every driver call runs on the esp32-executor task; another family ships its own <fam>-wifi-hal.

platform: ESP32

The ESP32 side of ext-wifi: the whole Wi-Fi lifecycle (radio init, scan, station, access point, connection state) over esp_wifi, esp_netif and esp_event. It implements bm_wifi_hal.h from ext-wifi (contract 1.2), and runs every driver call made for PHP on the executor task of esp32-executor.

Key Value
Type bm-hal
Platform esp32 (extra.baremetal.platform)
Provides php-baremetal/wifi-hal 1.2.0
Requires php-baremetal/esp32-executor
ESP-IDF components esp_wifi, esp_netif, esp_event, nvs_flash

Install

Projects do not require it. A project requires php-baremetal/ext-wifi, and conductor adds php-baremetal/esp32-wifi-hal (and with it esp32-executor) because the project's SDK ("sdk": "esp32@^2.0") has the platform esp32:

bash
composer require php-baremetal/ext-wifi

The SDK accepts ext-wifi only on a board with a radio: the ESP32-S3 boards, and the Waveshare ESP32-P4-WIFI6, where the same esp_wifi calls reach an ESP32-C6 companion over ESP-Hosted (build-tested only).

Behaviour on ESP32

The executor rule. The PHP task's stack is in PSRAM, and the Wi-Fi driver may touch the flash (NVS, PHY calibration). So every esp_wifi_*, esp_netif_* and nvs_flash_* call is wrapped in executor_run_sync() and runs on the executor task (core 0, internal-RAM stack); the PHP task waits. If the executor queue stays full for 1000 ms the call fails. Waiting for a scan or for the IP address happens on the PHP task, on an event group. Deliberate exceptions, all on the default event loop task (which also has an internal-RAM stack): the automatic reconnect after a dropped association calls esp_wifi_connect(), and the end of a scan reads the driver's list there.

Init. The first call runs nvs_flash_init() (erasing and re-initialising the nvs partition when it reports no free pages or a newer format), then esp_wifi_init() with WIFI_INIT_CONFIG_DEFAULT(), and registers handlers for WIFI_EVENT, IP_EVENT_STA_GOT_IP and IP_EVENT_STA_LOST_IP. lwIP and the default event loop are already started by the SDK host. The station and access point interfaces are created on first use and kept.

Mode. The mode follows the roles in use: station, access point, both (APSTA), or none, in which case the radio is stopped.

Scan. All channels, the default active scan. bm_wifi_hal_scan_start() starts it and returns (false when a scan is already running or the driver refuses, for example while the station is joining). When the driver reports the end, the list (up to 48 access points) is copied to a buffer, the driver's list is freed, and SCAN_DONE goes to the listener; bm_wifi_hal_scan_results() copies from that buffer, -1 after a failed scan. The blocking bm_wifi_hal_scan() is the same plus a wait of up to 15 s, after which the scan is aborted (still one SCAN_DONE) and the call returns -1.

Connect. WIFI_ALL_CHANNEL_SCAN with WIFI_CONNECT_AP_BY_SIGNAL (the strongest access point with the SSID). With a password: threshold WIFI_AUTH_WPA2_PSK, PMF capable, WPA3 SAE with both hunt-and-peck and hash-to-element (WPA3_SAE_PWE_BOTH); without: open. An attempt in progress (associating, associated, or between retries) is cancelled first, before the new configuration is set. Each connect, disconnect and timeout starts a new attempt generation and posts a marker to the event loop. Station events the old attempt raised before the cancel are queued ahead of the marker, so they are recognised and dropped: they never count as a retry or a give-up of the new attempt. An old association the listener had heard ends with exactly one STA_DISCONNECTED (BY_USER). bm_wifi_hal_sta_connect_ex() takes the number of automatic retries of a failed or dropped association (sta disconnected, reason=.. -- retrying on the console): -1 retries forever, and the count starts again at every address. Two password refusals in a row before the first address give up at once. bm_wifi_hal_sta_connect() is the waiting form with 10 retries. With wait false the call returns once the attempt has started. With wait true and no address within the timeout the attempt is stopped, so the board cannot connect after reporting failure, and STA_GAVE_UP (reason OTHER, code 0) is delivered before the call returns false. A waiting connect that succeeds returns true after the listener has heard STA_GOT_IP.

Power save. bm_wifi_hal_sta_set_power_save() calls esp_wifi_set_ps() on the executor: NONE is WIFI_PS_NONE, MIN is WIFI_PS_MIN_MODEM (the ESP-IDF default, kept until the first call) and MAX is WIFI_PS_MAX_MODEM (the station's listen interval is the driver's default, 3 beacons). The mode applies at once, to an association already up as well, and stays for the following connects; a call with the mode already set does not reach the driver. The driver refuses NONE while Bluetooth shares the radio: the call returns false, logs power save .. refused, and the previous mode stays. Modem sleep only concerns the station: the access point keeps its radio on.

Access point. SSID and password as given; WPA2-PSK when the password has 8 or more characters, otherwise open. Channel and maximum stations are passed to the driver unchecked.

State. The station IP and the SSID asked for are kept under a spinlock, updated by the events, so wifi_connected(), wifi_ip() and wifi_ssid() never call the driver. The SSID stays after a give-up, until the next connect or disconnect. wifi_rssi() asks the driver only while connected. The access point's station count comes from its join and leave events.

Events

bm_wifi_hal_set_listener() installs one listener. Every call to it is made from the ESP-IDF default event loop task, one event at a time, in the order the events happen, never from an interrupt and never with a lock held. What the PHP side causes (a waiting connect that timed out, an aborted scan) is posted to the same loop, so it is delivered from that task too.

The listener and the end of a scan run on that task's stack (CONFIG_ESP_SYSTEM_EVENT_TASK_STACK_SIZE, 2304 bytes in the SDK). Measured on the board: 1416 to 1592 bytes still free after the first scan and the first IP address. To measure again, build with BM_WIFI_HAL_LOG_EVT_STACK defined to 1 (it is 0 by default): the HAL then logs the high-water mark once after the first SCAN_DONE and once after the first STA_GOT_IP (event task stack high-water mark after the first ...: N bytes).

Event When Fields
STA_CONNECTED WIFI_EVENT_STA_CONNECTED for the current attempt none
STA_DISCONNECTED WIFI_EVENT_STA_DISCONNECTED, only if STA_CONNECTED was delivered reason, code, retrying
STA_GOT_IP IP_EVENT_STA_GOT_IP for the current attempt ip
STA_LOST_IP IP_EVENT_STA_LOST_IP while associated none
STA_GAVE_UP no retry left, a retry that could not start, or a waiting connect that timed out reason, code
SCAN_DONE once per started scan, success or not none
AP_STARTED WIFI_EVENT_AP_START after bm_wifi_hal_ap_start(), or that call on an access point already up none
AP_STOPPED WIFI_EVENT_AP_STOP after bm_wifi_hal_ap_stop() clients before the stop
AP_CLIENT_JOINED / AP_CLIENT_LEFT WIFI_EVENT_AP_STACONNECTED / WIFI_EVENT_AP_STADISCONNECTED mac, clients after the change

With no retry left, a station that was associated gets STA_DISCONNECTED (retrying false), then STA_GAVE_UP with the same reason. Two password refusals in a row (only counted before the connect's first address) give up the same way at once with WRONG_PASSWORD, whatever the number of retries, -1 included. A single refusal is retried like any other reason, because a weak link or a busy access point can raise one for a correct password (with no retry left it gives up with WRONG_PASSWORD); any other reason starts the count again. Every other reason, NOT_FOUND included, uses the retries. bm_wifi_hal_sta_disconnect(), and a connect that cancels one in progress, give STA_DISCONNECTED with reason BY_USER only when the station was associated, and never STA_GAVE_UP.

Reasons (code is the raw ESP-IDF wifi_err_reason_t):

Reason ESP-IDF codes
WRONG_PASSWORD WIFI_REASON_AUTH_FAIL (202), WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT (15), WIFI_REASON_HANDSHAKE_TIMEOUT (204), while the connect has not had an address yet
NOT_FOUND before the association: WIFI_REASON_NO_AP_FOUND (201), WIFI_REASON_NO_AP_FOUND_W_COMPATIBLE_SECURITY (210), WIFI_REASON_NO_AP_FOUND_IN_AUTHMODE_THRESHOLD (211), WIFI_REASON_NO_AP_FOUND_IN_RSSI_THRESHOLD (212)
LOST once STA_CONNECTED was delivered: every code not asked for that is not a refusal counted as WRONG_PASSWORD, WIFI_REASON_AUTH_LEAVE (3) of a switched-off access point included; before the association WIFI_REASON_BEACON_TIMEOUT (200), and after the connect's first address also WIFI_REASON_CONNECTION_FAIL (205), WIFI_REASON_AUTH_FAIL (202), WIFI_REASON_4WAY_HANDSHAKE_TIMEOUT (15), WIFI_REASON_HANDSHAKE_TIMEOUT (204) and WIFI_REASON_AUTH_EXPIRE (2)
BY_USER a disconnect asked for: bm_wifi_hal_sta_disconnect() or a new connect
OTHER every other code before the association (WIFI_REASON_AUTH_EXPIRE (2) included); a waiting connect that timed out (code 0)

License

MIT.