Display Configuration

Cuttlefish UI talks to physical displays through a display block in your cuttlefish.config.ts. You pick a built-in display profile (or name a driver) and tell Cuttlefish which pins it’s wired to; when you build, it generates the right driver code for you.

This page covers the display wizard, the common profiles, the full list of configuration fields, touch input, and — for unusual displays — how to wire up a brand-new driver.

Display wizard

The wizard asks which display you have and how it is wired, then writes the settings for you. It is the fastest way to get a screen running.

Run it from your project directory:

npx @typecad/ui --config

If you do not have a project yet, create one first with npx @typecad/cuttlefish create.

The wizard asks which display you are using, which pins it is connected to, how the screen is rotated, whether to smooth text edges (antialiasing), and how touch is wired. Each question suggests the common answer — press Enter to accept it.

Before anything is written, the wizard shows you the finished settings and asks you to confirm. It then does three things:

1. Writes the display settings into cuttlefish.config.ts. The rest of the file is left alone.
2. Adds a preview script to package.json, so npm run preview shows your screen in a browser.
3. Creates a starter screen file if you do not have one yet.

The wizard warns you if the display and the touch panel are set to the same pin.

You can run the wizard again at any time. Your previous answers are filled in, and nothing is changed without your confirmation.

Minimal SPI example (ST7796S TFT)

import type { CuttlefishConfig } from '@typecad/cuttlefish/api';

const config: CuttlefishConfig = {
  entry: './src/app.ui',
  target: 'esp32s3',
  board: 'esp32s3_devkitc/esp32s3/procpu',
  framework: '@typecad/framework-zephyr',
  frameworkData: { buildTarget: 'esp32s3_devkitc/esp32s3/procpu' },
  output: { framework: 'zephyr', outDir: './out' },
  display: {
    profile: 'st7796-zephyr',
    cs: 5,
    dc: 17,
    rst: 16,
    spiFrequency: 80000000,
    colorOrder: 'bgr',
    invertDisplay: false,
    antialias: true,
  },
};

export default config;

Minimal mono example (SSD1306 OLED)

display: {
  profile: 'ssd1306-zephyr',
  width: 128,
  height: 64,
  rotation: 0,
}

The mono profile drives direct display.* drawing — the HTML/CSS UI adapter does not lower to 1-bit panels.

Profile fields

Scroll tuning (scroll)

All fields optional — defaults derive from the declared touch hardware:

Built-in profiles

Registered display drivers

Beyond the built-in profiles, the transpiler registers drivers you can target directly by setting driver (and width/height/colorFormat):

The Zephyr framework generates native display/touch adapters — no third-party display library dependency. The display devicetree overlay, pinctrl remux, DMA, and backlight alias, plus the matching prj.conf Kconfig symbols (CONFIG_DISPLAY, CONFIG_SPI, CONFIG_I2C, CONFIG_DMA), are generated from a usage scan of your code. See Zephyr framework for details.

¹ The ST7796S and ILI9341 are driven over raw spi_write() with manual CS/DC/RST GPIO — the adapter deliberately bypasses Zephyr’s mipi-dbi-spi bridge and disables the in-tree panel drivers (CONFIG_ST7796S / CONFIG_ILI9341).

² The SSD1306 profile uses a page framebuffer under the GFX runtime for direct display.* drawing; the @typecad/ui HTML/CSS adapter does not lower to mono displays.

Touch input

Add a touch block to enable touch. Two controllers have native adapters, both polled directly (no in-tree driver): FT6336U (capacitive, over I2C) and XPT2046 (resistive, over SPI). Controllers not listed here need a custom adapter (below).

FT6336U (I2C capacitive)

touch: {
  library: 'FT6336U',
  i2cAddress: 0x38,             // default 0x38
  i2cFrequency: 400000,         // default 400 kHz
  sda: 8,                       // I2C wiring — configures the bus pinctrl
  scl: 9,                       // in the devicetree overlay
  resetPin: 4,                  // hardware-reset GPIO
  irq: 15,                      // optional (polled; not required for detection)
  calibration: { xMin: 0, xMax: 320, yMin: 0, yMax: 480 },
}

XPT2046 (SPI resistive)

touch: {
  library: 'XPT2046_Touchscreen',
  cs: 14,                       // touch chip-select (separate from display CS)
  irq: 2,                       // optional
  calibration: { xMin: 200, xMax: 3900, yMin: 240, yMax: 3800 },
}

touch: {
  adapter: './my-touch-adapter',
  calibration: { xMin, xMax, yMin, yMax },
  minPressure: 10,
}

// legacy analog-resistive shape (Arduino era)
touch: {
  library: 'Adafruit_TouchScreen',
  analogPins: { xp, yp, xm, ym, rx },
  calibration: { xMin, xMax, yMin, yMax },
}

Custom adapter

touch: {
  adapter: './my-touch-adapter',
  calibration: { xMin, xMax, yMin, yMax },
}

Calibration

calibration maps raw touch-controller readings to display pixels: { xMin, xMax, yMin, yMax }. minPressure filters out feather-light touches (resistive controllers only; capacitive controllers skip this gate).

Touch config fields

Next: Authoring API for the ui.* functions and the .ui file format.