overview.md

eyebrow	Package · Extension
lede	System functions for board scripts: non-blocking delay, uptime, restart and reset reason, chip identity, internal RAM and PSRAM figures. Needs a sys-hal provider for your platform.
see_also	href meta ./usage/php-api.md 6 min href meta ./recipes/health-report.md Recipe href meta ./recipes/measure-elapsed-time.md Recipe href meta label package:php-baremetal/esp32-sys-hal HAL esp32-sys-hal href meta label package:php-baremetal/ext-store#docs/overview.md Extension ext-store (persist across resets)
prev	label href No previous page #
next	label href PHP API ./usage/php-api.md

System extension

ext-sys adds the functions a board script reaches for constantly: sys_delay() (and its alias delay()) to sleep without blocking the CPU, the time since boot, a reboot and the reason for the last one, the chip's model, CPU frequency, MAC address and SDK version, and how much internal RAM and PSRAM is free. All of them are plain global functions; there are no classes and no constants.

When to use it

In almost every board script. Use it to wait between steps without burning CPU, to time things, to log the chip and the reason it last restarted, to watch memory while the firmware runs, and to restart the board when something goes wrong.

Requirements

ext-sys requires the virtual php-baremetal/sys-hal: it needs a sys-hal provider for your platform, which supplies the actual clock, reset and memory readings. On ESP32 the provider is php-baremetal/esp32-sys-hal. PHP >=8.3, the version the firmware embeds.

Install

Require the extension and the provider for your platform by name; a virtual reached through a package is not resolved to a provider automatically:

composer require php-baremetal/ext-sys php-baremetal/esp32-sys-hal

When the packages come from a local checkout, add path repositories first:

{
    "repositories": [
        { "type": "path", "url": "../packages/ext-sys" },
        { "type": "path", "url": "../packages/esp32-sys-hal" }
    ],
    "require": {
        "php-baremetal/ext-sys": "^1.0",
        "php-baremetal/esp32-sys-hal": "^1.0"
    }
}

Rebuild and flash; the functions are then callable from index.php. Nothing to configure.

API at a glance

Group	Functions
Timing	sys_delay(), delay(), sys_uptime_ms(), sys_micros()
Control	sys_restart(), sys_reset_reason()
Identity	sys_chip_model(), sys_cpu_freq_mhz(), sys_mac(), sys_idf_version()
Memory	sys_heap_free(), sys_heap_size(), sys_psram_free(), sys_psram_size(), sys_psram_largest_free()
Presence	sys_available()

The unprefixed heap_free(), heap_size(), psram_free(), psram_size() and psram_largest_free() still work but are deprecated. Full signatures and return values: PHP API.

<?php
printf("%s @ %d MHz, IDF %s\n", sys_chip_model(), sys_cpu_freq_mhz(), sys_idf_version());
printf("mac %s, last reset %s\n", sys_mac(), sys_reset_reason());
printf("heap  %d / %d bytes\n", sys_heap_free(), sys_heap_size());
printf("psram %d / %d bytes\n", sys_psram_free(), sys_psram_size());

$t0 = sys_uptime_ms();
delay(250);
printf("slept %d ms\n", sys_uptime_ms() - $t0);

Dependencies

Relation	Value
require	php >=8.3, php-baremetal/sys-hal ^1.0 (virtual)
Provider on ESP32	php-baremetal/esp32-sys-hal
provide	nothing

Notes

• Counters wrap. PHP integers are 32-bit on the board. sys_micros() turns negative after about 35.8 minutes of uptime, sys_uptime_ms() after about 24.8 days. See Measure elapsed time safely.
• Sleep in every loop. A loop that never calls sys_delay() holds the core and trips the task watchdog; the board resets and the next boot reports task_wdt.
• Delay resolution is one scheduler tick. A delay shorter than a tick may not sleep at all.
• sys_restart() never returns. Code after it does not run; save what must survive first.
• Use these for memory, not memory_get_usage(). The engine allocates from the chip's heap (PSRAM where the board has it), which memory_get_usage() does not see. Without PSRAM every sys_psram_* function returns 0.