ext-sys

This package is part of php-baremetal.

What it is for

ext-sys adds the system functions a board script needs. All of them are plain global functions:

• timing: sys_delay() and its alias delay() wait without blocking the CPU; sys_uptime_ms() and sys_micros() give the time since boot;
• control: sys_restart() reboots the board, sys_reset_reason() says why it last booted;
• identity: chip model, CPU frequency, MAC address and SDK version;
• memory: free and total internal RAM and PSRAM, and the largest free PSRAM block.

It needs a sys-hal provider for your platform; on ESP32 that is php-baremetal/esp32-sys-hal.

When to use it

In almost every board script: to wait between steps, 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.

Install

Require the provider for your platform explicitly next to the extension:

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

Example

<?php
printf("%s @ %d MHz, IDF %s, MAC %s\n",
    sys_chip_model(), sys_cpu_freq_mhz(), sys_idf_version(), sys_mac());
printf("last reset: %s\n", sys_reset_reason());          // "poweron", "panic", "task_wdt", ...
printf("internal RAM free: %d / %d bytes\n", sys_heap_free(), sys_heap_size());
printf("PSRAM free:        %d / %d bytes\n", sys_psram_free(), sys_psram_size());

while (true) {
    printf("up %d ms\n", sys_uptime_ms());
    delay(1000);                                          // yields the core, not a busy-wait
}

The output appears on the board's serial console.

Documentation

• Overview: requirements, install, the API at a glance, limits.
• PHP API: every function, its return values and edge cases.
• Print a health report: chip identity, reset reason and memory on the console.
• Measure elapsed time safely: intervals that survive the counter wrap.
• Restart on a condition: reboot when memory runs low or a check fails.

Changelog

See CHANGELOG.md.

AI usage

AI is used as a tool here, on top of human engineering. The architecture, the design decisions and the hardware bring-up are done by hand. AI mostly helps with the documentation and with mechanical work that can be verified. The full policy, including what is expected of contributions made with AI, is in AI_USAGE.md.

Not for you? No worries at all. Nobody is forcing it on you, and a free, open-source project you didn't spend a minute or a cent on owes you no explanation anyway. Take it or leave it, no hard feelings.

And for everyone who's on board: when contributing, please follow the guidelines in AI_USAGE.md. Thanks!

License

MIT. See LICENSE.