Project Config

The mental model

The Core’s definition (in definitions/) is the menu: it lists which pads exist, what each pad can do, the available clock levels, and the on-board peripherals. Your config.json is the order. coregen validates the order against the menu, then does the wiring — resolving alternate-function numbers, solving the PLL, computing I²C timing, and emitting handles.

The single most important idea: most things are derived, not declared. You almost never name a peripheral directly. You assign pad functions, and coregen infers the peripherals from them:

Quickstart

Smallest valid file — LED blink, no peripherals:

{
  "core": "Core.ST.L4.2",
  "clock": "max",
  "pads": {}
}

A real project — one I²C tile on a USB-powered L4:

{
  "core": "Core.ST.L4.2",
  "clock": "max",
  "usb": { "enabled": true },
  "pads": {
    "4": "I2C1.CLK",
    "5": "I2C1.DAT"
  },
  "interfaces": {
    "I2C1": { "speed": 400000 }
  },
  "tiles": [
    { "tile": "Sense.I.6P6", "bus": "I2C1", "instance": 0 }
  ]
}

After editing, regenerate with make generate (coregen also runs automatically on a normal make). Never hand-edit generated files between coregen:begin/coregen:end markers — re-running coregen clobbers them. Change the config instead.

Top-level fields

coregen reads a fixed allowlist of keys. Anything not listed here is silently ignored — a typo’d key is not an error, it just does nothing.

core — pick the MCU/core (required)

Selects definitions/<Core>.json. Prefer the public name (the DB stem also works).

clock — performance level

A clock-level name the Core defines (typically "low", "medium", "high", "max"), not a frequency. "default" resolves to the tile’s schema default. coregen solves the PLL and applies any required voltage scaling. An unknown level is a hard error. Note the clock also gates bus speeds — see I²C below.

Pads & functions

The heart of the file. Key = pad number as a string ("4", not 4); value = a function the Core definition lists for that pad. coregen validates every entry — a bad pad or unavailable function prints the available options and exits.

• SPI CS is software-managed. SPI*.CS pads become plain GPIO outputs driven by hal_spi_set_cs() — not hardware NSS. Not configurable.
• ADC is single-ended positive only. Differential negative inputs aren’t emitted; coregen emits one core_adc1 handle today.
• A bus needs all its pads. An I2C bus needs both CLK and DAT; SPI needs CLK + MOSI + MISO.

Interfaces — tune the buses

Keyed by peripheral name (I2C1, SPI1, USART2, TIM2, …). Only tunes a bus a pad already created.

I²C

SPI

USART / UART

Timer / PWM

Channels come from the TIM<n>.<ch> pad functions; duty cycle is set at runtime via the core_pwm API, not in config. There is no pwm, capture, timers, or iwdg section.

GPIO & tiles

gpio — per-pin electrical details

Optional refinements for pads set to GPIO.IN/GPIO.OUT (key = pad number string).

tiles — attach drivers to buses

coregen emits a per-tile handle like tile_sense_i_6p6_i2c1_0 and adds the driver to the build. Valid tile names are the TILE_DRIVER_MAP dict in coregen.py.

USB & bootloader

usb

USB requires a USB-capable MCU (L4 or H5); on other cores it’s a no-op/warning.

bootloader

Sets the BOOTLOADER / ROM_DFU Make variables. See Bootloading. timer.tick_ms feeds the Studio simulation tick only — not a hardware tick.

Keys that are silently ignored

coregen reads a fixed allowlist; the raw config is never handed to the templates. These keys are read by nothing and have no effect, even though older docs described some of them. Because unknown keys are ignored rather than rejected, using them is harmless but does nothing.

Validation & errors

coregen is mostly fail-fast — a bad config exits before any compile, so it won’t silently generate wrong code.

• Exits on: a pad that doesn’t exist or a function not available on it; an unknown clock level; an I²C speed out of set or its kernel clock too low; an SPI mode/prescaler out of range; an unknown tile, a tile on an unconfigured bus, or an SPI tile whose cs_pad doesn’t resolve; an invalid bootloader.
• Warns (non-fatal) on: a core name not matching the definition; an interfaces entry with no backing pads; a USB request on a non-USB Core.
• Silent: unknown/typo’d top-level keys, and omitted optional fields (they take their defaults).

Recipes

GPIO in + out, falling-edge interrupt with pull-up

{
  "core": "Core.ST.L0.1",
  "clock": "max",
  "pads": { "11": "GPIO.OUT", "8": "GPIO.IN" },
  "gpio": { "8": { "pull": "up", "exti": "falling" } }
}

Two I²C buses at different speeds, three tiles

{
  "core": "Core.ST.L4.1",
  "clock": "max",
  "pads": {
    "4": "I2C1.CLK", "5": "I2C1.DAT",
    "2": "I2C3.CLK", "8": "I2C3.DAT"
  },
  "interfaces": {
    "I2C1": { "speed": 400000 },
    "I2C3": { "speed": 100000 }
  },
  "tiles": [
    { "tile": "Display.RGBW", "bus": "I2C1", "instance": 0 },
    { "tile": "Sense.I.6P6",  "bus": "I2C3", "instance": 0 },
    { "tile": "Sense.T.C",    "bus": "I2C3", "instance": 0 }
  ]
}

SPI tile with software CS

{
  "core": "Core.ST.W5",
  "clock": "max",
  "pads": {
    "9": "SPI1.CLK", "6": "SPI1.MOSI", "7": "SPI1.MISO", "8": "SPI1.CS"
  },
  "interfaces": { "SPI1": { "mode": 0, "prescaler": 8 } },
  "tiles": [
    { "tile": "Drive.H", "bus": "SPI1", "instance": 0, "cs_pad": "8" }
  ]
}

PWM on two channels

{
  "core": "Core.ST.L4.2",
  "clock": "max",
  "pads": { "7": "TIM15.1", "8": "TIM2.1" },
  "interfaces": { "TIM2": { "freq": 2000 } }
}

ADC + UART logging

{
  "core": "Core.ST.L0.1",
  "clock": "high",
  "pads": { "6": "ADC1", "7": "USART2.TX", "2": "USART2.RX" },
  "interfaces": { "USART2": { "baud": 115200 } }
}

USB CDC + ROM-DFU bootloader

{
  "core": "Core.ST.L4.2",
  "clock": "max",
  "bootloader": "rom",
  "usb": { "enabled": true },
  "pads": { "6": "USB.DP", "7": "USB.DM" }
}