Board files
A board is one JSON file in boards/: the chip, the memory, the console and the peripherals with their pins. This page lists every key, its values and what the SDK does with it.
The board id used in extra.baremetal.board is the file name without .json: boards/waveshare-esp32-s3-eth.json
is the board waveshare-esp32-s3-eth. When the SDK is loaded every file is checked against its chip; a failed
check stops phpbm with a message naming the file. To add a board, see
Adding a board or chip; the boards that exist are in
Supported boards.
Keys of the board
| Key | Required | Meaning |
|---|---|---|
name |
yes | Product name. Printed in the start-up line of the firmware. |
chip |
yes | A chip of the SDK: a directory in chips/ (esp32s3, esp32p4). |
psram |
no | PSRAM type. Must be one the chip lists (table below). Selects chips/<chip>/sdkconfig.<psram>. |
flash |
yes | Flash size as a whole number of megabytes with MB, e.g. 16MB. Sets the flash size of the image and the partition table. |
flash-mode |
no | Flash bus width. quad is the default; octal is accepted on the ESP32-S3. |
revision |
no | Silicon revision family the firmware targets. ESP32-P4 only: v1 (default) or v3. |
console |
no | uart (default) or usb-jtag. Selects host/sdkconfig/console-<value>. |
| any other key | no | A peripheral block (below). |
Every other key of the file must be an object with a non-empty type.
PSRAM, flash mode and revision per chip
| Chip | psram |
flash-mode |
revision |
|---|---|---|---|
esp32s3 |
quad, octal |
quad, octal |
none: a revision is an error |
esp32p4 |
hex |
quad |
v1, v3 |
psram: the PSRAM wiring of the module (for example the N16R8 DevKitC has octal, the N8R2 quad).flash-mode:octalis for modules with octal flash. It addschips/esp32s3/sdkconfig.flash-octal.revision:v1builds for P4 chips older than revision 3,v3for revision v3.1 and later. A chip of the other family refuses to boot the image.phpbm discoverprints the revision of the connected chip.console:usb-jtaguses the chip's built-in USB serial,uartthe UART pins.
A revision or a flash-mode the chip has no sdkconfig fragment for is rejected at build time, and a psram
the chip does not list is rejected when the SDK is loaded. Messages are listed at the end of this page.
Peripheral blocks
A block is named after a peripheral, and its type says which kind the board has. Two kinds of block exist:
- Blocks the SDK implements,
microsdandnetwork: the firmware has its own code for each type, so the type must be one the chip supports.chips/<chip>/chip.jsonlists them, and any other type is an error. - Blocks read by packages, such as
display,i2c,touchandled: the type is the name of a driver, checked by the driver'sonboard()when the script runs. The chip does not list them, so a new driver needs no SDK change. Two blocks of the same kind take different names, for exampleledandled-2.
| Chip | microsd types |
network types |
|---|---|---|
esp32s3 |
spi |
w5500, wifi |
esp32p4 |
sdio |
emac, wifi-c6 |
The microsd and network blocks also make runtimes and storages available: storage: microsd needs a
microsd block, runtime: web-server needs a network block.
A device wired to the board by hand is not a board block: build it with its constructor and explicit pins, for
example new Ws2812(pin: 5, count: 30).
All keys of a block other than type reach the build as PHPBM_<BLOCK>_<KEY> (upper case). A value must be a
number, a string or a boolean.
Packages read a block through bm_board.h (bm-common): the build writes every block into phpbm_board.c, and a
package calls bm_board_type(), bm_board_int() or bm_board_str() with the block and key. Values must be
integers (a boolean becomes 1 or 0) or strings there. Drivers offer onboard() to build from the board's block.
microsd
| Type | Keys | Notes |
|---|---|---|
spi |
cs, sclk, mosi, miso |
SPI card on explicit pins. |
sdio |
clk, cmd, d0, d1, d2, d3, pwr_en |
SDMMC slot 0, 4-bit. Defaults when absent: clk 43, cmd 44, d0 39, d1 40, d2 41, d3 42. pwr_en is the card power switch; absent or -1 means none. |
Every pin of a spi slot is required. Every pin given must be a GPIO number of the chip: an integer from 0 to 48
on the ESP32-S3, from 0 to 54 on the ESP32-P4 (pwr_en may also be -1). The build checks this before it compiles
anything, whether the project uses the card or not.
network
| Type | Keys | Notes |
|---|---|---|
wifi |
none | The chip's own radio. The script connects with php-baremetal/ext-wifi. |
wifi-c6 |
none | Wi-Fi through a companion ESP32-C6. Also connected with ext-wifi. |
w5500 |
cs, int, rst, sclk, mosi, miso |
SPI Ethernet controller; the pins are those of its SPI wiring. |
emac |
rst |
The P4's on-chip Ethernet MAC; rst is the PHY reset pin. |
Every key listed for w5500 and emac is required, and each must be a GPIO number of the chip (0-48 on the
ESP32-S3, 0-54 on the ESP32-P4); rst may also be -1 when the reset pin is not wired. The build checks this
before it compiles anything, whether the network is on or not.
Network describes how each type is brought up.
display
| Type | Keys | Notes |
|---|---|---|
st77916 |
sclk, d0, d1, d2, d3, cs, rst, bl, width, height, te |
QSPI panel: clock, four data lines, chip select, reset, backlight, the size in pixels and the panel's TE (tearing effect) pin, which pulses once per refresh; te is optional; onVsync() and St77916::onboard(vsync: true) need it. Used by Waveshare ESP32-S3-Touch-LCD-1.85B (TE on GPIO 18). |
i2c
| Type | Keys | Notes |
|---|---|---|
i2c |
sda, scl |
The board's on-board I2C bus (touch controller, sensors). Used by Waveshare ESP32-S3-Touch-LCD-1.85B. |
touch
| Type | Keys | Notes |
|---|---|---|
cst816s |
width, height, int, rst, address, mirror-x, mirror-y, swap-xy, double-tap |
CST816S capacitive touch controller on the board's i2c bus: the screen size in pixels, the INT and reset GPIOs and the orientation; address defaults to 0x15, double-tap (bool, default true) turns the chip's double tap detection on or off (on: a single tap is reported about 260 ms after the release), and only width and height are required. events() needs int. Used by Waveshare ESP32-S3-Touch-LCD-1.85B (INT on GPIO 4, reset on GPIO 1, 360 x 360). See Touch input. |
led
| Type | Keys | Notes |
|---|---|---|
ws2812 |
pin, order |
One addressable LED on pin; order is the colour order (rgb, grb). Used by Waveshare ESP32-S3-Zero (GPIO 48, rgb), Espressif ESP32-S3-DevKitC-1 and Freenove ESP32-S3 WROOM Board Lite (GPIO 48, grb). |
sk6812 |
pin, order |
Same wiring as ws2812, for SK6812 LEDs. |
Error messages
| Message | Cause |
|---|---|
boards/x.json: 'microsd' must be an object |
A key other than the board keys holds something that is not an object. |
boards/x.json: 'microsd.type' must be a non-empty string |
A peripheral block without a type. |
boards/x.json: chip 'abc' does not exist |
chip names no directory in chips/. |
boards/x.json: chip 'esp32s3' does not support psram 'hex' |
The psram is not in the chip's list. |
boards/x.json: chip 'esp32s3' does not support microsd 'sdio' |
A microsd or network type the chip does not list. |
board x: unsupported flash size '16' (use e.g. 4MB) |
flash is not a whole number followed by MB. |
board x: chip 'esp32s3' has no revision 'v1' |
revision with no matching fragment for the chip. |
board x: chip 'esp32p4' does not support flash-mode 'octal' |
flash-mode with no matching fragment for the chip. |
board x: chip 'esp32s3' does not support microsd 'sdio' (it supports spi) |
A microsd or network block added by board overrides with a type the chip does not list. |
board x: microsd.cs is missing (a 'spi' microsd needs cs, sclk, mosi, miso) |
A pin the block's type needs is not there (here a spi slot without cs). |
board x: microsd.clk must be a GPIO number from 0 to 54 |
A pin that is not an integer in the chip's range. |
board x: network.rst must be a GPIO number from 0 to 54, or -1 for none |
The same, for a pin that may also be -1. |
board x: network.cs must be a number or a string |
A block value that is an array or an object. |
board x: led.gain must be an integer or a string |
A block value that is a decimal number: phpbm_board.c holds integers and strings only. |
To change a pin in a project without editing the board file, use board overrides.