Boards & custom hardware

Everything Kog knows about your hardware lives in one declarative file: board.yaml. It describes the chip, memory, display, touch controller, and pins — and it drives flashing, pin safety, the simulator's display shape, and (if you ever need it) custom firmware builds.

Blessed boards

For boards we test and host prebuilt images for, board.yaml is one line of identity:

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

Current blessed boards:

Board	Chip	Display
Waveshare ESP32-S3-Touch-LCD-1.46B	ESP32-S3 (PSRAM)	round touch LCD
ESP32-2432S028R "Cheap Yellow Display"	ESP32	ILI9341 320×240, resistive touch

Any board with known controllers — still no compiling

If your board's display and touch controllers are in Kog's compiled-in driver set (common controllers over SPI, i80, RGB, QSPI, and MIPI-DSI buses), you write a full board.yaml and Kog runs it on a generic prebuilt image — your board description is flashed alongside as a configuration blob, read at boot:

schema: kog/board@1
id: my-custom-panel
soc: { chip: esp32s3, flash_mb: 16, psram: { type: octal, size_mb: 8 } }
display:
  controller: st7789
  bus: spi
  width: 240
  height: 320
  bus_config: { sclk: 14, mosi: 13, cs: 15, dc: 2, rst: -1, freq_hz: 40000000 }
  backlight: { pin: 27, active: high }
touch:
  controller: cst816s
  bus: i2c
  i2c: { sda: 33, scl: 32, freq_hz: 400000 }
  int: 21
inputs:
  buttons: [{ id: boot, pin: 0, active: low }]

kog board validate checks it against the published schema (your editor gets autocomplete from the JSON Schema too).

Fully custom: kog firmware build

If you need an unsupported controller, custom native code, or non-standard system config, the CLI compiles a runtime for you, from the same board.yaml:

npx kog firmware build

The first run installs a pinned, managed copy of the embedded toolchain into ~/.kog/toolchains — you don't install or configure anything yourself, and your project doesn't change shape. A native/ directory of custom components (drivers, native modules) is linked in automatically if present.

All three paths — blessed, generic, custom — use the identical kog dev / kog flash workflow. The tier is an implementation detail the CLI resolves and reports:

✔ board.yaml → waveshare-esp32-s3-touch-lcd-1.46b (blessed, prebuilt runtime v1.0)