Contracts

Dev-board targets are the easy case. For your board, a contract — a JSON file naming the MCU and every pin you wired — replaces the board catalog: the generated module contains only your pins, under the names you chose, and nothing else exists to reach.

reference

the contract file

myboard.contract.json

Exported from a typeCAD/pcb project and consumed here. Pin-name matching is deliberate: pad-form board names become the exported constant; compound pin names split into segments; non-pad board names become functional aliases (LED, TX, SCL).

Example first

myboard.contract.json

{
  "version": 1,
  "mcu": { "symbol": "MCU_ST_STM32:STM32F411CEU6" },
  "connectedPins": {
    "6":  { "pinName": "XTAL1/PB6", "pinType": "bidirectional", "boardName": "SCL", "net": "SCL" },
    "7":  { "pinName": "PB7", "pinType": "bidirectional", "boardName": "SDA", "net": "SDA" },
    "14": { "pinName": "PA0", "pinType": "bidirectional", "boardName": "LED", "net": "LED" }
  },
  "availablePeripherals": { "i2c": true, "spi": false, "uart": false }
}

Field	Meaning
mcu.symbol	The KiCAD symbol of the MCU — the only mcu field read
connectedPins	Keyed by pin number: pinName (compound names split on / and -), pinType (KiCAD direction), boardName (functional alias like LED/TX, or the pad name), net
externalComponents	reference, dnp, symbol, value, footprint — what hangs on the pin
availablePeripherals	i2c/spi/uart are true only when every pin the peripheral needs is wired
power pins	Excluded — power and ground never export as GPIO

reference

configuring it

soc + contract

Contracts and dev-boards are mutually exclusive: soc + contract instead of board. The framework generates an out-of-tree Zephyr board for the silicon, and the narrowed board module drops out of the usual build.

Example first

typecad-hal.config.ts

import type { TypecadConfig } from '@typecad/hal/config';

const config: TypecadConfig = {
  soc: 'stm32f411xe',                       // the silicon, not a dev board
  contract: './hardware/myboard.contract.json',
  framework: '@typecad/framework-zephyr',
  frameworkData: { buildTarget: 'typecad_f411_dev' },
  zephyr: {
    customBoard: true,                       // generate the out-of-tree board
  },
};

export default config;

The hardware half of this story — exporting the contract from a .kicad_pcb — lives in the pcb docs. Contracts pair with the import workflow: design the board in typeCAD, flash the firmware against the same pins.

Previous Boards & Targets Next The CLI