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	Flash target
Waveshare ESP32-S3-Touch-LCD-1.46B	ESP32-S3 (PSRAM)	round touch LCD	waveshare-1.46b
ESP32-2432S028R "Cheap Yellow Display"	ESP32	SPI 320×240, resistive touch	cyd
ESP32-2432S028R, classic panel	ESP32	same board, ILI9341-generation glass (BGR + mirrored scan)	cyd-classic

Which CYD do I have?

The CYD ships two panel generations behind the same silkscreen, and they can't be told apart by looking at the board (or over USB — both are plain ESP32). Flash the standard cyd image first. If the screen comes up left/right mirrored with orange buttons where the UI should be blue, your unit is the classic generation — reflash with kog flash --board cyd-classic (the browser flasher offers the same choice). Touch works identically on both.

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)