Storage
Where the PHP sources and the assets live on the board: embedded in a read-only image in flash, or on the microSD card and copied with phpbm sync.
A project picks one storage with extra.baremetal.storage. Both storages run the same PHP: only the place of the
files differs. The source directory is src (default project-src) and the entry script is entry inside it
(default index.php); see the
phpbm project guide.
embedded |
microsd |
|
|---|---|---|
| Where the sources are | A read-only FAT image in the storage flash partition |
The folder /sdcard/app of the microSD card |
| Mount point | /app |
/sdcard, sources in /sdcard/app |
| Requires | Nothing | Capability microsd: the board needs a microSD slot |
| Changing a script | Rebuild and flash | phpbm sync (no build, no flash) |
| Writable by PHP | No | Yes, everywhere on the card; /sdcard/app is managed by phpbm sync |
The project's assets (images and other files, see Assets) choose their storage folder by folder, independently of the code.
embedded
The build packs the whole source directory, plus the embedded assets, into a FAT image (the storage.cmake
of the storage calls fatfs_create_rawflash_image(storage "${PHPBM_APP_SRC}" FLASH_IN_PROJECT), where phpbm sets
PHPBM_APP_SRC to the folder it prepared). The image is written to the storage partition together with the app,
by phpbm flash.
- Size. The partition is sized from the sources and the
embeddedassets: the space they use, rounded to 4 KB units, plus 64 KB and one eighth, rounded up to a multiple of 64 KB, at least 128 KB. - Flash budget. What the storage and the package partitions leave is the firmware's. If that is under 1024 KB
the build stops and suggests a board with more flash or the
microsdstorage. See Memory, flash and partitions. - Read-only. At boot the partition is mapped into memory and mounted at
/app. Writes to it fail. PHP reads scripts through the flash cache, with no flash operation. - OPcache. With the
opcacheextension, timestamp validation is always off: the image changes only with a flash.
Write data that PHP produces somewhere else: an ext-store key, or a microSD card.
microsd
The sources live on the card, so a script changes in seconds and the flash holds only the firmware. The
firmware mounts the card at /sdcard, and the sources are in /sdcard/app. The rest of the card is free for
the scripts' own data.
Boards and pins
The board file describes the slot (see Board files); a board without a microsd
block cannot use this storage, unless the project adds one with
board overrides. The chip decides the type:
| Board | Slot type | Pins |
|---|---|---|
waveshare-esp32-s3-eth |
spi |
cs 4, sclk 7, mosi 6, miso 5 |
waveshare-esp32-s3-touch-lcd-1.85b |
spi |
cs 13, sclk 15, mosi 14, miso 16 |
waveshare-esp32-p4-eth |
sdio |
SDMMC slot 0 on its default pins, card power switch on GPIO 45 (pwr_en) |
waveshare-esp32-p4-wifi6 |
sdio |
SDMMC slot 0 on its default pins |
waveshare-esp32-p4-pico |
sdio |
SDMMC slot 0 on its default pins |
spi(ESP32-S3): the card uses the SPI3 host. The Waveshare ESP32-S3-ETH keeps SPI2 for its W5500.sdio(ESP32-P4): SDMMC slot 0 in 4-bit mode, powered by the on-chip LDO channel 4. Without pins in the board file the defaults areclk43,cmd44,d039,d140,d241,d342 and no power pin. SDMMC slot 1 stays free for the Wi-Fi companion link.
If the first mount fails the firmware retries at a low frequency (the P4 in 1-bit mode). To use other pins,
change them with board overrides; on a board without a slot, the same overrides
can add one. The pins must be GPIO numbers of the chip (0-48 on the
ESP32-S3, 0-54 on the ESP32-P4), and a spi slot needs all four.
phpbm sync
phpbm flash copies the sources, and the microsd assets, to the card after flashing. phpbm sync
copies them without building or flashing. Both talk to the firmware over the serial console.
-
Step 1: The firmware listens at boot
After mounting the card it waits 1.5 seconds for a sync request on the console.
-
Step 2: Only the difference is copied
driver/tools/sync.pytells the firmware the folders it manages (app, plus eachmicrosdasset folder), lists the files in them, compares size and sha256 with the local ones, deletes what is no longer in the project and sends what changed. A file is written under a temporary name and renamed, so an interrupted copy leaves the old file. The rest of the card is never listed, written or deleted. -
Step 3: The board restarts
The firmware prints
phpbm: sync session over, restartingand restarts, then runs the new sources.
Files named .env and the project's env file are skipped. The env file is built into the firmware and read
as $_ENV and getenv(); the card never holds it.
Limits
- File names. Printable ASCII only, no trailing
.or space, none of\ : " * < > ? |, no name ending in.partor.old, and a path under 256 bytes. The card's names are case-insensitive, so two names that differ only in case are refused. - OPcache. With the
opcacheextension the optionopcache-validate(default off) makes OPcache check script timestamps, for PHP files the program itself writes on the card. Off, the sources change only with a flash or a sync, which restart the board. - No card, no program. The firmware stops with
--- stopped: no microSD card ---when the card cannot be mounted, and with--- stopped: no <entry> on the microSD card (run phpbm sync) ---when the entry script is missing. Then it restarts afterrestart-delay.
Assets
Assets are files the program reads, such as the images of the Slate: .png files are
converted to .sli by phpbm, .sli files are copied as they are. They are declared folder by folder in
extra.baremetal.assets, each folder with its storage (see the
phpbm project guide):
On the board a file is at the storage's mount point plus its path in the project, with .png changed to .sli:
| In the project | Storage | On the board | Changes with |
|---|---|---|---|
assets/ui/icons/coffee.png |
embedded |
/app/assets/ui/icons/coffee.sli |
phpbm flash |
assets/photos/beans.png |
microsd |
/sdcard/assets/photos/beans.sli |
phpbm flash or phpbm sync |
| Code storage | embedded assets |
microsd assets |
|---|---|---|
embedded |
In the flash image, with the sources | On the card: the firmware mounts the card too |
microsd |
Refused by phpbm: there is no flash image | On the card, next to /sdcard/app |
embeddedassets go into the read-only image of thestoragepartition, and count in its size (see Memory, flash and partitions).microsdassets with the code in flash. The firmware mounts the card at/sdcardafter the image, on the board's slot (see Boards and pins), and listens forphpbm syncfor 1.5 seconds, like amicrosdfirmware. The board needs a microSD slot. Without a card the program still runs: the firmware printsphpbm: microSD not mounted (<error>): its assets are not available, and reading those files fails. With the code in flash,is_dir('/sdcard')returnsfalseeven when the card is mounted, while the files under it (/sdcard/assets/photos/beans.sli) work: to check for the card, check for one of its files instead.- Copying to the card.
phpbm flashcopies themicrosdassets after flashing, andphpbm synccopies them without building, as for the sources. A folder may not be inside/sdcard/appwhen the code is on the card.
Managed folders
phpbm sync changes only the folders it manages: /sdcard/app when the code is on the card, and each declared
microsd asset folder (/sdcard/assets/photos in the example). Inside them the card mirrors the project: a file
removed from the project is deleted from the card. Everything else on the card is never listed, written or
deleted: data the program writes, files an OTA update keeps there, other folders next to the asset folders. The
sync creates the parent folders a managed folder needs, and never removes them. A folder that stops being managed (removed
from extra.baremetal.assets, or moved to embedded) keeps its files on the card: delete them by hand if they are
no longer needed. An empty microsd folder stays managed: emptying it clears its files on the card at the next sync.