board.yaml

The declarative hardware description that drives flashing, pin safety, simulator display, and custom builds. Validated by kog board validate and by JSON Schema in your editor.

Blessed board

extends: waveshare-esp32-s3-touch-lcd-1.46b

Full schema

schema: kog/board@1
id: my-board                     # unique slug
name: My Board                   # display name

soc:
  chip: esp32s3                  # esp32 | esp32s3 | esp32c3 | esp32p4
  flash_mb: 16
  psram: { type: octal, size_mb: 8 }   # type: none | quad | octal

display:
  controller: st7789             # must be in the compiled driver set for no-compile tiers
  bus: spi                       # spi | i80 | rgb | qspi | mipi_dsi
  width: 240
  height: 320
  color_format: rgb565
  byte_swap: false
  rotation: 0                    # 0 | 90 | 180 | 270
  refresh_hz: 60
  backlight: { pin: 27, active: high, pwm: true }
  bus_config:                    # shape depends on `bus`; spi shown
    sclk: 14
    mosi: 13
    cs: 15
    dc: 2
    rst: -1
    freq_hz: 40000000

touch:
  controller: cst816s            # gt911 | cst816s | ft6x36 | xpt2046 | none
  bus: i2c
  addr: 0x15
  i2c: { sda: 33, scl: 32, freq_hz: 400000 }
  int: 21
  rst: -1

inputs:
  encoder: none                  # or { a: <pin>, b: <pin>, button: <pin> }
  buttons:
    - { id: boot, pin: 0, active: low }

native_modules: []               # names of components in native/ (custom builds only)

Semantics worth knowing

• Every pin named here becomes reserved. The hardware API refuses to claim them, naming the owner — and the generated per-project Pin type excludes them at compile time.
• bus_config shape follows the bus: spi (sclk/mosi/cs/dc/rst/freq), rgb (pclk/de/hsync/vsync/data lanes/timings), i80, qspi, mipi_dsi — the schema documents each variant.
• The CLI resolves how to run this board (prebuilt / generic image + config / custom compile) automatically — see Boards.