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.

Changelog

[2.0.0] - Unreleased (previews: 2.0.0-alpha.N)

2.0 is a rewrite: the firmware is a Composer project built by phpbm, and this repository is the ESP32 SDK that phpbm downloads and drives. Until 2.0.0 is released, every push to the sdk branch publishes a preview 2.0.0-alpha.N on the sdk-preview pre-release, which phpbm installs by default. Previews are not ready for use: anything can still change.

Changed

  • Native packages can be written in C++. A package without sources compiles src/*.c and src/*.cpp; phpbm.h has C linkage when included from C++. The rules (C linkage for the module entry and the registered symbols) are in Writing native packages.
  • A project is a composer.json. extra.baremetal names the SDK ("sdk": "esp32@^2.0"), the board, the runtime and the storage, plus optional src, entry, env, options and board-overrides. config.platform.php is the PHP version of the firmware.
  • Features are packages. Extensions (ext-gpio, ext-i2c, ext-wifi, …), drivers and PHP extensions (php-baremetal/php-<name>) come from the registry with composer require. The php-baremetal/conductor plugin installs them and adds the ESP32 HAL each one needs.
  • Boards are JSON files under boards/, selected by id (e.g. waveshare-esp32-s3-eth). phpbm discover lists the boards that match the connected chip.
  • ESP-IDF v6.1, installed by phpbm toolchain:install.
  • ESP32-S3 runs at 240 MHz (chips/esp32s3/sdkconfig); the ESP-IDF default is 160 MHz.
  • ESP32-S3 has a 32 KB instruction cache (chips/esp32s3/sdkconfig); the ESP-IDF default is 16 KB. Code that runs from flash (PHP, drawing) is faster; it takes 16 KB of internal RAM.
  • ESP32-S3 main task stack 16 KB (chips/esp32s3/sdkconfig; 32 KB elsewhere, host/sdkconfig.defaults). The main task only boots, mounts and unmounts the storage, restarts and sleeps (PHP has its own task); it uses under 1 KB of its stack (measured on the board, also after a PHP script with deep recursion, PCRE, JSON and sorting, and before a deep sleep). The 16 KB go back to internal RAM: Wi-Fi starts next to a Slate scene with ~32 KB to spare.
  • SDK releases are versioned archives listed in a release index with their sha256. A project locks the version it uses in phpbm.lock.

Added

  • Project assets (extra.baremetal.assets, needs php-baremetal/spec 1.3): the flash image holds the sources and the embedded assets (BuildPlan::imageDir(), sized with them); with microsd assets the firmware mounts the microSD card also when the code is in flash (PHPBM_ASSETS_MICROSD), and phpbm flash and phpbm sync copy the assets to the card. The sync server changes only the folders the host manages (/sdcard/app with the code on the card, and each microsd asset folder) and never the rest of the card. Its protocol is now version 2: a board flashed by an earlier preview must be flashed again before syncing. A phpbm that still vendors spec 1.2 (phpbm 0.2.x) keeps building projects without assets: the driver then reads no assets and puts the sources in the image.
  • Package options: native packages declare options; the build defines PHPBM_OPTION_<NAME> for each.
  • board-overrides can add a block the board does not have, written whole with its type (needs php-baremetal/spec 1.3): for example a spi microSD slot on generic-esp32s3-octal. Before writing anything the build checks the SDK's blocks (microsd, network) as they are after the overrides, used or not: a type the chip supports, every pin the type needs (spi microSD: cs, sclk, mosi, miso; w5500: cs, int, rst, sclk, mosi, miso; emac: rst) and each pin a GPIO number of the chip (0-48 on the ESP32-S3, 0-54 on the ESP32-P4; -1 for none on rst and the sdio pwr_en). A missing pin is an error that names it, not a C compile error. A block key whose variable the build sets itself (network.component, or extensions of an added php block) is an error too.
  • Option type set (a list of allowed values): the build defines PHPBM_OPTION_<NAME><VALUE> as 1 or 0 for each allowed value and PHPBM_OPTION<NAME> as the comma-separated chosen values (needs php-baremetal/spec 1.2).
  • init-loop runtime: calls bm_events_service() of ext-events (when the firmware has it) after each loop(), so object releases run, the slots of undelivered events go back and event warnings are printed. Docs: events, web and I2C pages describe the event slots of ext-events 1.0.3 instead of a 32-message queue.
  • Fonts: the build compiles the fonts phpbm resolves (BuildPlan::$fonts) into the display_fonts[] table read by ext-display; packages may declare extra.baremetal.fonts.
  • Board blocks display, i2c and led (Waveshare ESP32-S3-Touch-LCD-1.85B, Waveshare ESP32-S3-Zero), readable by packages through bm_board.h; the build writes them into phpbm_board.c.
  • Runtimes init-loop, event-driven and web-server; storages embedded and microsd, the latter synced over the serial port with phpbm sync.
  • PHP 8.3, 8.4 and 8.5, each with the optional extensions bcmath, ctype, date, filter, mbstring, opcache, openssl (partial API), pdo, pdo_sqlite, session, sqlite3, tokenizer and zlib.
  • Options network, on-error, restart-delay, firmware-reserve, optimization, log (the firmware's log level), power-save (automatic light sleep) and request-timeout, plus loop-interval (init-loop) and init / port (web-server).
  • Networks: on-chip Wi-Fi, Ethernet through the ESP32-P4 EMAC or a W5500, and Wi-Fi through an ESP32-C6 companion.
  • Boards: Espressif ESP32-S3-DevKitC-1 (N8R2, N8R8, N16R8), Freenove ESP32-S3 WROOM Board Lite (N16R8, N16R16), Waveshare ESP32-S3-Zero (and N8R8), ESP32-S3-ETH, ESP32-S3-Touch-LCD-1.85B, ESP32-P4-ETH, ESP32-P4-Pico, ESP32-P4-WIFI6, and generic ESP32-S3 (quad or octal PSRAM) and ESP32-P4 boards.
  • phpbm_runtime_request_scoped() in the host API (phpbm.h), implemented by each runtime: true in web-server. esp32-events-hal 1.0.2 passes it to ext-events, which refuses event sources there.
  • Packages may declare extra.baremetal.board-blocks (used by phpbm to offer board features).
  • Documentation for users and for SDK development.

Removed

  • The TOML project configuration and the phpflash tool: use phpbm.
  • The extensions built into the firmware: each one is now its own package.

The 1.x firmware (v1.5.0 and older) has its own changelog: legacy CHANGELOG.