Board Definitions

A board definition is a small description of a board — its pins, what each one can do, how much memory it has — that Cuttlefish uses to check your code and build the right firmware.

What’s in a Board Definition

A board definition is a TypeScript package that exports a BoardDefinition object with:

• Pin map — every physical pin, its capabilities (digital, analog, PWM, interrupt), and any aliases
• Peripheral instances — peripherals (built-in features like I2C, SPI, a timer, or ADC), with their pin assignments
• Memory layout — flash, SRAM, EEPROM sizes
• Features — multicore, deep sleep, watchdog, WiFi, Bluetooth
• Build targets — framework-specific identifiers for compilation

The transpiler uses this data to validate pin usage, detect peripheral conflicts, estimate memory use, and generate correct build commands.

Available Board Packages

Using a Board Package

import { D13, LED, I2C0, Board } from '@typecad/board-arduino-uno';

// D13 is a typed pin object
const led = D13.asOutput();
led.toggle();

// I2C0 is a pre-configured bus instance
I2C0.begin(100000);

// Board aggregates everything
console.log(Board.pins.pwm);    // all PWM-capable pins
console.log(Board.peripherals); // all peripheral instances

Pin Discovery

Each board exports typed pin objects and discovery collections:

import { pins, PeripheralPins } from '@typecad/board-arduino-uno';

pins.pwm       // [D3, D5, D6, D9, D10, D11]
pins.analog    // [A0, A1, A2, A3, A4, A5]
pins.interrupt // [D2, D3]
pins.digital   // [D0..D13]

PeripheralPins.I2C0  // { sda: A4, scl: A5 }
PeripheralPins.SPI0  // { mosi: D11, miso: D12, sck: D13, ss: D10 }
PeripheralPins.UART0 // { tx: D1, rx: D0 }

Creating Custom Board Definitions

A custom board definition is a TypeScript package that exports a BoardDefinition object. Scaffold a new project with cuttlefish create, then author the board definition following the schema below. For the board-scaffolding workflow, see the @typecad/create tooling.

Board Definition Schema

interface BoardDefinition {
  id: string;               // e.g., "arduino-uno"
  name: string;             // e.g., "Arduino Uno Rev3"
  vendor: string;
  description: string;
  architecture: string;     // avr, esp32, etc.
  mcu: string;              // e.g., "ATmega328P"
  clockSpeed: number;       // in Hz
  memory: {
    flash: number;          // in bytes
    sram: number;           // in bytes
    eeprom?: number;        // in bytes
  };
  pins: PinDefinition[];
  peripherals: {
    i2c?: PeripheralInstance[];
    spi?: PeripheralInstance[];
    uart?: PeripheralInstance[];
    adc?: PeripheralInstance[];
    pwm?: PeripheralInstance[];
    timers?: TimerInstance[];
  };
  features?: {
    multicore?: boolean;
    deepSleep?: boolean;
    watchdog?: boolean;
    wifi?: boolean;
    bluetooth?: boolean;
    dma?: boolean;
  };
  build: {
    targets: BuildTarget[];
  };
}

Multi-Function Pins

A single physical pin often serves multiple roles. The board definition captures this:

// A4 on Arduino Uno is both an analog input and I2C data line
{
  name: 'A4',
  number: 18,
  capabilities: ['analog_in', 'digital', 'i2c_sda'],
  functions: { i2c0: 'sda', adc0: 'channel4' },
  aliases: ['SDA']
}

When you use A4.readAnalog() and I2C0.begin() in the same sketch, 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 to create a full board definition package. 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 narrowed board definition automatically.

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