board-design

Board Design

For atopile syntax and patterns, see the ato-language skill. For build workflow, see build-and-test. For creating new shared packages, see creating-packages.

A board is a composition: you instantiate packages (MCU, regulators, connectors, application ICs) and wire them together at the board level. The board module's body should read like a block diagram — major blocks first, then the connections between them.

File Structure

<board-name>/
    <board-name>.ato         # Main board module
    ato.yaml                 # Build manifest
    layouts/                 # KiCad layout files (created by ato build)
    parts/                   # Board-specific parts (from ato create part)

ato.yaml template

requires-atopile: ^0.15.7
paths:
  src: ./
  layout: ./layouts
builds:
  <board-name>:
    entry: <board-name>.ato:<BoardModule>
    hide_designators: true
dependencies:
  # Local packages:
  - type: file
    identifier: <namespace>/<package-name>
    path: ../packages/<package-name>
  # Registry packages:
  - type: registry
    identifier: atopile/<package-name>
    release: <version>

Board module template

#pragma experiment("BRIDGE_CONNECT")
#pragma experiment("TRAITS")

import Resistor
import Capacitor

from "<namespace>/<mcu-package>/<mcu-package>.ato" import MyMCU
from "atopile/usb-connectors/usb-connectors.ato" import USBCConn

module MyBoard:
    """One-line description of what this board does."""

    # --- Major blocks ---
    mcu = new MyMCU
    usb = new USBCConn

    # --- Power ---
    # power_in ~> regulator ~> power_3v3
    # power_3v3 ~ mcu.power

    # --- Communication / control ---
    # usb.usb2 ~ mcu.usb
    # app_ic.i2c ~ mcu.i2c[0]

    # --- Ground domains tied together ---
    # power_hv.lv ~ power_3v3.lv

Composition Methodology

1. Instantiate the major blocks first — MCU, power source/regulators, connectors, application ICs. Give them clear names.
2. Establish power rails — identify each voltage rail, route the input source through regulators to each rail (power_in ~> regulator ~> power_3v3), and connect every block's power interface to the right rail.
3. Wire the standard MCU peripherals consistently — pick the same peripheral assignment convention across boards (e.g. always mcu.i2c[0] for the primary on-board I2C bus, a fixed UART for debug). Document which MCU pins each peripheral consumes so you don't double-assign a pin that's already used by a peripheral.
4. Connect application buses — wire each application IC's communication interface to an MCU peripheral (app_ic.i2c ~ mcu.i2c[0], app_ic.spi ~ mcu.spi[0]). For single control lines use a GPIO: connect .line for the signal and set .reference to the rail that defines its logic level.
5. Use bridge syntax for inline series elements — ~> for things like current-sense modules in a power path (requires BRIDGE_CONNECT).
6. Tie ground domains together explicitly at the board level — don't rely on implicit shared ground.