Board Targets

A board target names the hardware your firmware runs on — the qualified Zephyr build target (west build -b <target>). There are no board packages to install: the board catalog (generated from your installed Zephyr tree) generates a project-local board module (.cuttlefish/board.ts + board.json) on your first build.

What’s in the Generated Board Module

• Pin map — every physical pin named by its datasheet notation (GPIO2, PA5, P0.28), with capability flags (digital, analog, PWM, interrupt, pull-ups) derived from the board’s devicetree and the SoC pinctrl data in your Zephyr tree
• LED / BUTTON — placed from the board’s devicetree when it declares them (led0/sw0 nodes)
• Connector labels — silkscreen aliases like D0–D10, A0–A5, SDA/SCL where the board declares them; each points at the same pin as its datasheet name
• Bus instances — one export per bus controller the board’s devicetree wires (I2C0, SPI0, UART0, USB0, …)
• Hardware gateway — the module re-exports each hardware class from @typecad/hal only when this board supports it (Watchdog, PWM, ADC, DAC, I2CTarget, …; GPIO/Thread/Time/Sensor are always present)
• Build target — the qualified Zephyr board target, carried into the build

The transpiler reads the module’s manifest (board.json) to lower pins to devicetree controllers, generate the build overlay, and pick the flash runner.

Board Targets from the Catalog

There is no curated list — every board variant in your Zephyr tree is a target, addressed by bare board id or qualified target:

cuttlefish create --target <board> accepts either form (run cuttlefish board sync after west update so new boards in your tree are picked up).

Using a Board Target

import { GPIO, I2CTarget, LED, I2C0 } from '@typecad/board';

// LED is a typed pin export
const led = new GPIO(LED, GPIO.OUTPUT);
led.toggle();

// The bus instance names the controller for a target device
const sensor = new I2CTarget(I2C0, 0x44, { hz: 400000 });

Pin Discovery

Every pad the board’s devicetree controllers cover is exported as a typed pin constant by its datasheet name — GPIO2 on ESP32s, PA5 in STM32 port notation, P0_28 for the nRF P0.28 pad — alongside silkscreen aliases (D0–D10, A0–A5, SDA, MOSI, …) that point at the same Pin object as their datasheet counterpart. LED and BUTTON come from the board’s devicetree when it declares them:

import { LED, BUTTON } from '@typecad/board';

// LED and BUTTON are Pins like any other — pass them to GPIO,
// use them as interrupt sources, and so on.

Custom Hardware

Custom PCBs designed in typeCAD don’t need a board target — a hardware contract narrows the board module to exactly the pads the PCB wires. See Contracts.

Board Definition Schema

{
  "version": 1,
  "identifier": "esp32s3_devkitc/esp32s3/procpu",  // the qualified target
  "soc": "esp32s3",                                 // the SoC half of the target
  "pinNames": ["GPIO1", "GPIO2", "..."],            // datasheet names (the manifest)
  "constants": {
    "pins.all.0.number": 1,                         // HAL pin numbers
    "pins.all.0.name": "GPIO1",
    "pins.all.0.capabilities.pwm": true,            // from the harvested silicon routes
    "peripherals.i2c.count": 2,
    "zephyr.soc": "esp32s3",                        // chip-resolution key
    "zephyr.probeMethods.0.id": "jlink",            // debug probe table
    "build.frameworks.zephyr": "esp32s3_devkitc/esp32s3/procpu"
  },
  "source": { "generatorRev": 18, "fingerprint": "..." }  // regen provenance
}

Multi-Function Pins

A single physical pad often serves multiple roles — the manifest’s capability flags capture this. When you use PA1 as an ADC and drive the same pad as a GPIO output, the transpiler detects the conflict and reports a diagnostic.

Contracts for Custom Hardware

If you’re designing a custom PCB with typeCAD, you don’t need a board target. Instead, use a contract file — a .contract.json exported from your typeCAD project that describes which MCU pins are physically connected. The transpiler generates a board module narrowed to exactly those pins automatically.

See Contracts for details on integrating typeCAD hardware designs with Cuttlefish firmware.