Ato

1. End-to-End Design Process

This is the canonical sequence for designing a board in atopile. Move quickly, keep the structure clean, and avoid spreading planning state across multiple rounds unless the design genuinely requires it.

Step 1: Draft The Architecture

Capture user intent as ato code immediately. Start with a clean high-level architecture and only stop to ask batched design questions when there are real unresolved decisions.

Focus on:

• What the system is supposed to do
• The main functional blocks
• The important interfaces and voltage domains
• Key constraints on size, cost, power, or manufacturing
• Any parts or protocols that are already fixed by the user

Tools: Use design_questions to batch multiple unresolved decisions at once. Use web_search if you need to research unfamiliar domains or components before locking the architecture.

Gate: a spec .ato file exists with module hierarchy, interface connections, requirements in docstrings, and formal constraints.

Step 2: Write The Spec

The spec IS the design file at a high level of abstraction. As you implement, you fill in real components and wiring. The file grows; the structure stays.

Key principles:

• Good naming — name modules by their role in the system, not implementation topology (see Section 1.1).
• Module boundaries should encapsulate common functionality to avoid duplication at the top level.
• Use high-level interfaces (ElectricPower, I2C, SPI, UART, ElectricLogic) instead of low-level electrical connections where possible.
• Custom interfaces are rare — before defining a new interface, check the stdlib first with stdlib_list / stdlib_get_item. If an existing stdlib interface or a simple composition/array of stdlib interfaces works, use that instead.
• Capture requirements in the module docstring under a Requirements: section on the module that owns them.
• Add formal constraints with assert for voltage, current, frequency bounds.
• Wire modules together at the interface level (~). Do NOT wire pins yet.

Step-by-step:

1. Break the request into subsystems. Each functional block becomes a module — power, MCU, sensors, comms, IO, etc.
2. Define interfaces at module boundaries. Use stdlib interfaces to declare how modules connect.
3. Capture requirements in docstrings. Add a Requirements: section to the docstring of the module that owns each requirement.
4. Add formal constraints with assert for voltage, current, frequency bounds.
5. Wire modules together at the interface level (~).
6. Create a checklist linking items to requirement IDs for tracking.

Example spec:

import ElectricPower
import I2C
import SPI
import ElectricLogic

module SensorBoard:
    """
    # Environmental Sensor Board

    Battery-powered sensor node with temperature, humidity, and
    pressure sensing, BLE comms, and USB-C charging.

    ## Requirements
    - R1: BLE connectivity — nRF52840 with BLE 5.0
    - R2: Environmental sensing — BME280 for temp/humidity/pressure
    - R3: USB-C charging — 5V USB-C input with charge IC
    - R4: Board size — 25mm x 30mm max

    ## Key Decisions
    - nRF52840 for BLE + low power
    - BME280 for temp/humidity/pressure

    """

    # ── Architecture ──────────────────────────────────────
    power = new PowerSupply
    mcu = new MCU
    sensors = new EnvironmentalSensor
    comms = new Radio

    # Interface-level wiring (no pins yet)
    power.rail_3v3 ~ mcu.power
    power.rail_3v3 ~ sensors.power
    mcu.i2c ~ sensors.i2c
    mcu.spi ~ comms.spi

    # ── Constraints ───────────────────────────────────────
    assert power.usb_in.voltage within 4.5V to 5.5V
    assert power.rail_3v3.voltage within 3.3V +/- 5%

module PowerSupply:
    """
    USB-C input, charge controller, LDO regulation.

    ## Requirements
    - R5: Battery charging — LiPo charge IC with thermal protection
    """

    usb_in = new ElectricPower
    battery = new ElectricPower
    rail_3v3 = new ElectricPower

module MCU:
    """nRF52840 with crystal, decoupling, and debug header."""
    power = new ElectricPower
    i2c = new I2C
    spi = new SPI

module EnvironmentalSensor:
    """BME280 environmental sensor."""
    power = new ElectricPower
    i2c = new I2C

module Radio:
    """BLE antenna matching and RF front end."""
    spi = new SPI

Key rules for this step:

• Module names are final — PowerSupply stays PowerSupply through implementation. Do NOT suffix with "Spec".
• Place requirements in the docstring of the module that owns them, not all on the top-level.
• Use docstrings for overview, requirements, and important decisions.
• Do not keep unresolved planning state in the design file longer than needed; use design_questions to batch open questions and then continue implementation.

Tools: Use stdlib_list / stdlib_get_item to check available interfaces and components before defining custom ones. Use examples_search / examples_read_ato to find reference designs for similar systems.

Gate: architecture is coherent enough to implement. If there are multiple open design decisions, batch them with design_questions and continue once answers arrive.

Step 3: Resolve Open Decisions

Present the user with the current architecture and any real unresolved decisions:

• List the modules and their responsibilities.
• Show the interface connections between modules.
• Highlight any key decisions or trade-offs made.
• Call out any assumptions or areas where alternatives exist.

Use design_questions to batch unresolved decisions instead of trickling follow-up questions across multiple turns. Then incorporate the answers directly into the spec and continue implementation.

Gate: the key open questions are resolved or reasonable defaults have been chosen.

Step 4: Implement Detailed Design

Now fill in the spec with real components, wiring, and constraints. This step covers package search, part selection, and detailed wiring.

4a: Find existing packages

Search the atopile package registry before building from scratch.

Tools: packages_search → packages_install → package_ato_read to inspect public interface. Also check stdlib_list for built-in modules.

• Prefer reusing a well-tested package over writing a new driver module.

4b: Create local packages when none exist

When packages_search returns no match for a needed IC, connector, or module, create a local driver package instead of giving up or asking the user to find one.

Tools: parts_search → web_search (to compare families, inspect the vendor datasheet/design guide, validate topology, and find reference circuits) → parts_install(create_package=true) → project_read_file (to inspect the generated wrapper package) → project_edit_file (to refine that wrapper in place) → workspace_list_targets (to discover nested package targets).

Step-by-step recipe:

1. Find the part: Use parts_search to find the LCSC component (e.g., parts_search("LAN8742A")).
2. Research the part family when needed: Use web_search before locking the part if you need application notes, common reference circuits, family comparisons, or confirmation that the chosen topology is standard and robust.
3. Install as a local package: Use parts_install with the LCSC ID and create_package=true. This installs the raw part and generates the canonical reusable wrapper package under packages/.
4. Inspect the vendor docs with web search: Use web_search with the part number, vendor, and terms like datasheet, hardware design, application circuit, decoupling, pinout, or the specific pins/features you need.
5. Read the generated files: Inspect the generated wrapper under packages/<PartName>/<PartName>.ato and the installed raw part it imports to see available interfaces and exact pin names.
6. Refine the wrapper package if needed:
   • Treat packages/<PartName>/<PartName>.ato as the canonical wrapper module for that part.
   • Edit that generated package file in place rather than creating another wrapper layer.
   • Keep the raw installed part file unchanged.
   • Start with a basic reusable wrapper first. Expose the minimum standard interfaces needed to build the package and integrate it cleanly.
   • Keep the wrapper generic and reusable. Expose the chip's general capabilities, not one project's exact architecture.
   • Expose standard interfaces such as ElectricPower, I2C, SPI, UART, CAN, SWD, USB2_0, USB2_0_IF, ElectricLogic, or ElectricSignal.
   • Before writing any custom interface, check stdlib_list / stdlib_get_item for an existing stdlib interface and prefer stdlib arrays/composition over project-local aggregate interfaces.
   • Prefer capability-oriented names and boundaries such as uart, spi, adc_inputs, gpio, usb, swd, power, not design-specific roles like sbus, phase_current, weapon_pwm, or battlebot_interfaces.
   • It is fine to make slightly opinionated pin choices so key capabilities are wired out cleanly, but do not encode one specific end design into the wrapper shape.
   • Do not treat incomplete pin exposure as a blocker. Add more interfaces, alternate pin mappings, or richer capabilities later when integration proves they are needed.
   • Map the internal _package component pins to those interfaces.
   • Add decoupling capacitors and required passives.
   • Set voltage/current constraints from the datasheet.
   • If the wrapper needs new supporting physical parts while you are validating the package target in isolation, install them into that package project with parts_install(project_path="packages/<PartName>").
7. Discover targets: Run workspace_list_targets after package creation to inspect and build the package targets that were exposed automatically.
8. Import and use the local package in your top-level design directly from packages/<PartName>/<PartName>.ato.
9. Delegate package work when helpful: If the package project exists and can be built independently, use package_agent_spawn(project_path="packages/<PartName>", goal=..., comments=...) so a package specialist can refine that wrapper while you continue top-level integration.

Example: refining a generated local I2C mux wrapper

The generated package file under packages/<PartName>/<PartName>.ato is the wrapper you should refine. The raw part component it imports is not the place to edit behavior.

#pragma experiment("BRIDGE_CONNECT")

import ElectricPower
import ElectricLogic
import I2C
import Capacitor
import Resistor

from "parts/Texas_Instruments_TCA9548APWR/Texas_Instruments_TCA9548APWR.ato" import Texas_Instruments_TCA9548APWR_package

module TI_TCA9548A:
    # Public interfaces
    power = new ElectricPower
    assert power.voltage within 1.65V to 5.5V

    i2c = new I2C
    reset = new ElectricLogic

    # Instantiate the auto-generated package component
    package = new Texas_Instruments_TCA9548APWR_package

    # Power connections
    power.hv ~ package.VCC
    power.lv ~ package.GND

    # I2C — connect via .line and .reference
    i2c.sda.line ~ package.SDA
    i2c.scl.line ~ package.SCL
    i2c.sda.reference ~ power
    i2c.scl.reference ~ power

    # Decoupling — use bridge connect (~>) for series path
    decoup_100n = new Capacitor
    decoup_100n.capacitance = 100nF +/- 20%
    decoup_100n.package = "0402"
    power.hv ~> decoup_100n ~> power.lv

    decoup_2u2 = new Capacitor
    decoup_2u2.capacitance = 2.2uF +/- 20%
    decoup_2u2.package = "0402"
    power.hv ~> decoup_2u2 ~> power.lv

    # Reset with pullup
    reset.line ~ package.nRESET
    reset.reference ~ power
    reset_pullup = new Resistor
    reset_pullup.resistance = 10kohm +/- 1%
    reset_pullup.package = "0402"
    reset.line ~> reset_pullup ~> reset.reference.hv

Key rules:

• Always parts_install first — never reference a part that hasn't been installed.
• Prefer parts_install(create_package=true) for ICs and other reusable wrapped parts.
• When validating a package as its own project, use parts_install(project_path="packages/<name>") for any new supporting parts the package itself imports.
• Use package_create_local only when you need an empty local package scaffold without installing a physical part.
• Always read the generated package and raw part .ato files to see the exact signal names (e.g., package.VCC, package.SDA). Do NOT guess pin names.
• Always use web_search to inspect the vendor datasheet and hardware design notes to get correct pin mapping, constraints, and recommended decoupling.
• The generated package file under packages/ is the canonical wrapper for that part. Refine it in place.
• The raw installed file is a component — never edit it.
• Build a basic reusable wrapper first. Expose the minimum standard interfaces needed to validate the package and integrate it, then come back and add more pin mappings or interfaces later if integration requires them.
• Once a package project exists, prefer delegating isolated wrapper build-out through package_agent_spawn instead of doing all package work serially in the main agent.
• Instantiate the raw component inside the wrapper as package = new <ComponentName>.
• main.ato should import wrapper packages directly from packages/<name>/<name>.ato, not through an extra aggregator wrapper file.
• Connect interfaces via .line and .reference (e.g., i2c.sda.line ~ package.SDA; i2c.sda.reference ~ power).
• Use bridge connect ~> for decoupling caps in series (e.g., power.hv ~> cap ~> power.lv).
• Use .capacitance for Capacitor values, .resistance for Resistor values (NOT .value).
• Add #pragma experiment("BRIDGE_CONNECT") if using ~>.
• Keep IC-specific pin wiring inside the driver module; expose only abstract interfaces.
• Do NOT skip this step and tell the user to create the package themselves. This is core agent capability.

4c: Part selection

Choose components using generics + constraints wherever possible.

Tools: parts_search / parts_install for specific ICs/connectors. web_search for vendor datasheets, hardware design guides, application notes, and alternative parts.

• Use stdlib generics (Resistor, Capacitor, Inductor, Diode, LED, Fuse) with value + package constraints for auto-picking. Prefer generics over locked parts.
• Use parts_search only when a specific part is needed (IC, connector, specialized component).
• Use web_search before locking a part when you need to compare candidate families, confirm the recommended implementation pattern, or find a solid reference circuit/application note.
• Use parts_install for parts that need explicit LCSC IDs, and prefer create_package=true when the part should become a reusable local wrapper.
• Use web_search after selecting a concrete part to inspect the vendor datasheet, exact pins, limits, and supporting circuitry.
• Lock only high-risk parts (MCU, PMIC, RF, connectors). Leave commodity passives auto-picked.
• Before inventing a project-local interface, check whether the wrapper boundary can be represented as:
  • a stdlib interface (SPI, UART, SWD, USB2_0_IF, etc.)
  • an array of stdlib signals/interfaces (new ElectricLogic[3], new ElectricPower[3], new ElectricSignal[3])
  • a few named stdlib fields directly on the module
• Only define a custom interface when it represents a real reusable protocol/boundary that stdlib or simple composition does not already cover.
• Keep package wrappers generic. Design-specific grouping and role naming belong in main.ato or project modules above the package layer.

4d: Detailed wiring and constraints

Wire connectivity, add constraints and equations, complete the design.

• Wire modules through interfaces using ~ (or ~> for bridge/series paths).
• Add parameter constraints (assert ... within ...) for all key electrical properties.
• Add decoupling, pullups, and protection per Section 4 patterns.

Gate: design is complete — all modules wired, all constraints declared, all interfaces connected. Every component is either a constrained generic or an explicitly selected part.

Step 5: Build

Run builds and fix issues iteratively until everything passes. Build submodules first (if applicable) — it is much easier to get small chunks working before running the full build.

5a: Build + fix loop

Tools: workspace_list_targets → build_run → build_logs_search (filter by log_levels/stage) → design_diagnostics for silent failures. Use report_variables to inspect constraint state and report_bom to verify part selection.

• Run workspace_list_targets first after creating/installing local packages so you know which package targets already exist automatically.
• Split the design into sensible submodules and build those smaller targets first. This is the default validation loop.
• Build wrapper/package targets first, and do so in parallel where practical, so you get feedback much faster than waiting on repeated full-design builds.
• If a wrapper is only partially exposed, still build the basic wrapper and keep moving. Extend the wrapper later during integration instead of marking the work blocked just because more interfaces may be needed.
• Fix submodule/package failures before running the top-level design.
• Do not add manual top-level ato.yaml entries just to build generated local package wrappers if workspace_list_targets already exposes those targets.
• Use the full top-level build after submodules are green; it should then be mainly an integration check rather than the first place issues appear.
• Check build_logs_search for errors/warnings.
• Use design_diagnostics for silent failures.
• Fix issues using Section 5 troubleshooting.
• Repeat until build passes cleanly.

Step 6: Summary

Tools: Use report_bom for parts list and report_variables for constraint summary when preparing the summary.

When the build finishes, give the user a summary:

• What was built — list the modules, key components, and interfaces.
• Blockers or issues — note any problems encountered and how they were resolved (or if they remain).
• Suggestions for next steps — what the user might want to do next (e.g., review placement, order boards, add features, run DRC).

Gate: user has received a clear summary and knows the state of the design.

1.1 Module Naming

Name modules the way you'd label blocks on a system block diagram — by their role in the system, not their implementation topology. Avoid generic suffixes like Subsystem, Unit, Block, or Section.

Good names:

• PowerSupply — input protection, regulation, and distribution
• PowerInput — connector, reverse polarity protection, and bulk decoupling
• BatteryCharger — charge IC, sense resistors, and status output
• BMS — cell balancing, protection, and fuel gauge
• GateDriver — bootstrap, dead-time, and level shifting for a FET bridge
• MotorDrive — integrated driver with current limit and fault output
• CurrentSense — shunt and sense amplifier
• CANTransceiver — transceiver, termination, and ESD (don't use CAN — it shadows the stdlib interface)
• USBPort — connector, ESD, and pull-ups (don't use USB — too generic, may shadow stdlib types)
• EthernetPHY — PHY, magnetics, and RJ45
• Radio — RF front end, antenna match, and balun
• IMU — accelerometer/gyro with decoupling
• ADCInput — anti-alias filter, reference, and input scaling
• LevelShift — voltage translation between power domains
• InputFilter — common-mode choke and filter caps
• Clock — crystal or oscillator with load caps
• Debug — SWD/JTAG connector and pull-ups
• Indicators — status LEDs with current-limiting resistors
• Protection — ESD, TVS, or overvoltage clamping on an interface

IC wrapper packages use the part name directly: STM32G474, DRV8317, TCAN3414.

Inside a module, names get more specific — a PowerSupply module might contain a BuckConverter and an LDO. The name should match the level of abstraction: system-level blocks use system-level names.

When in doubt, ask: "what would this block be labelled on a system block diagram?"

1.2 Architecture Decomposition

For non-trivial designs, split early and keep one primary module per file.

Complexity triggers that force splitting:

• More than 40 connect statements in one module
• More than 12 direct package-pin connections in one module
• More than 10 child instances in one module
• Mixed concerns (power conversion + MCU + comms + connectors in one module)
• Duplicated wiring clusters that could be a reusable child module

Example file layout:

main.ato                    # integration module only
ato.yaml                    # project-level builds
packages/
  stm32g474/
    stm32g474.ato           # reusable wrapper package
power/
  buck_5v.ato               # project-specific power stage
  buck_3v3.ato              # project-specific regulator stage
control/
  motor_control.ato         # project-specific control module
io/
  connectors.ato            # project-specific adapters/connectors

Keep main.ato at the project root. Put reusable IC wrappers under packages/. Put project-specific implementation modules in sibling folders only when they help keep the design clean.

1.3 Design for Test

Imagine the board comes back from the factory, gets plugged in, and it's your job to bring it up — automatically, at scale. Design with that scenario in mind from the start.

Think about the bringup flow

Before wiring, walk through the commissioning sequence in your head:

1. Power on — how does it get power? USB? Bench supply? Battery? What's the first thing that should happen?
2. Programming — how does firmware get loaded? SWD/JTAG header? USB bootloader? Is the debug connector accessible?
3. Configuration — does the device need provisioning (keys, calibration, IDs)? What interface is used?
4. Verification — how do you confirm each subsystem works? What can you measure?
5. Final state — what does "pass" look like? An LED? A USB enumeration? A message on a bus?

Include the connectors, headers, and test points needed for this flow in your design. A debug header that gets cut to save $0.10 will cost hours during bringup.

Self-measurement of critical rails

Every power rail that matters should be observable — ideally by the MCU itself, not just a multimeter:

• ADC sense dividers on critical voltage rails (battery, main supply, regulated outputs) so firmware can read and report rail health.
• Current sense on high-power paths (motor drives, charging) for monitoring and fault detection.
• Test points on rails that can't be ADC-measured, so they're accessible with a probe during bringup.

# Example: ADC-measurable voltage rail
adc_sense = new ResistorVoltageDivider
power_12v.hv ~> adc_sense ~> power_12v.lv
adc_sense.output ~ mcu.adc[0]
assert adc_sense.ratio within 0.2 to 0.3   # scale 12V into MCU ADC range

Practical checklist

When designing, ask yourself:

• Programming: Is there a debug header (SWD/JTAG) or USB bootloader path? Is it accessible after assembly?
• Power rails: Can the MCU read the key voltage rails via ADC? Are there test points on rails it can't read?
• Communication buses: Is there a way to verify each bus is alive? (e.g., I2C scan, SPI loopback, UART console)
• Indicators: Are there status LEDs that show power-good, heartbeat, or error states?
• Isolation: Can subsystems be tested independently? (e.g., can you power the MCU without the motor driver?)
• Test points: Are critical signals (clocks, resets, key nets) accessible for probing?
• Connectors: Are debug/programming connectors placed where they won't be blocked by enclosures or other boards?

2. Language Reference

ato is a declarative language for defining electronics. Every statement constructs graph nodes and edges or declares constraints — there is no runtime execution order. This section covers the language by concept with practical examples.

2.1 Blocks

Three block kinds exist: module, component, and interface.

module PowerSupply:
    """Regulate 5V input down to 3.3V."""
    pass

component MyChip:
    pin VCC
    pin GND

interface MyBus:
    signal data
    signal clock

• Use module for reusable hardware building blocks with components and equations.
• Use interface for reusable connectable bus/signal/power abstractions.
• Use component for physical parts with pin mappings (usually auto-generated — you rarely write these by hand).

Inheritance specializes a block:

module USB2_0TypeCVerticalConnector from USBTypeCConnector_driver:
    connector -> VerticalUSBTypeCConnector_model

Rules:

• Nested block definitions are NOT allowed — all blocks must be at file top-level.
• Duplicate symbol names in the same scope are errors.
• Use docstrings (triple-quoted strings) as the first statement for module documentation.

2.2 Instances

Create instances with new. Bare type assignment is invalid.

# Good
r = new Resistor
caps = new Capacitor[4]

# Bad — will error
r = Resistor

Arrays create indexed sequences:

leds = new LED[8]
leds[0].lcsc_id = "C2286"
leds[3].lcsc_id = "C2297"

Templated construction (requires MODULE_TEMPLATING pragma):

#pragma experiment("MODULE_TEMPLATING")

addressor = new Addressor<address_bits=3>

2.3 Fields and Access

Access fields with dotted paths and array indexing:

power                          # local field
power.hv                       # sub-field
i2c.sda.line                   # nested access
gpio[0].line                   # indexed access
microcontroller.uart[0].tx     # deep path

Declare typed parameters with unit annotation:

v_in: V
v_out: V
max_current: A
ratio: dimensionless

Declared parameters can then be used in equations and constraints.

2.4 Connections

Direct connect: ~

Use for net-level or interface-level equivalence. This is the primary connection operator.

power_3v3 ~ sensor.power       # interface-level
i2c_bus ~ sensor.i2c            # bus-level
gpio.line ~ package.PA0         # signal-level

When you connect interfaces, all matching sub-fields connect recursively.

Bridge connect: ~> (requires BRIDGE_CONNECT pragma)

Use for series/inline topology through bridgeable elements:

#pragma experiment("BRIDGE_CONNECT")

power_in ~> fuse ~> ldo ~> power_out      # power path
power.hv ~> cap ~> power.lv               # decoupling
data_in ~> led_strip ~> data_out           # daisy chain

Bridge connect traverses can_bridge trait paths (in/out). Only use when the module is physically in series.

Rules:

• Do NOT mix directions in one statement: a ~> b <~ c is invalid.
• Both ~> and <~ exist but keep chains in one direction.

2.5 Constraints

Use assert to declare constraints over parameter domains.

within — for bounds and ranges (preferred for values)

assert power.voltage within 3.3V +/- 5%
assert power.voltage within 1.8V to 5.5V
assert i2c.frequency within 100kHz to 400kHz

is — for expression identity between parameters

assert addressor.address is i2c.address
assert v_out is v_in * r_bottom.resistance / r_total
assert r_total is r_top.resistance + r_bottom.resistance

Comparison operators

assert power.voltage >= 3.0V
assert max_current <= 500mA
assert inductor.max_current >= peak_current

Rules:

• Use within for literal/range bounds. Use is for relating expressions/parameters.
• Avoid assert x is 3.3V (deprecated) — use assert x within 3.3V +/- 0% instead.
• Only one comparison per assert — assert 1V < x < 5V is NOT supported. Split into two asserts.
• Supported operators: >, >=, <, <=, within, is.

2.6 Quantities and Units

Singleton

3.3V
10kohm
100nF
2.4MHz
1A

Bounded range

1.8V to 5.5V
100kHz to 400kHz
0.5mA to 3mA

Bilateral tolerance (absolute)

10kohm +/- 1kohm
3.3V +/- 0.2V

Bilateral tolerance (relative)

10kohm +/- 5%
3.3V +/- 5%

Unitless values

ratio: dimensionless
ratio = 0.5
assert ratio within 0.1 to 0.9

Arithmetic

Supported operators: +, -, *, /, **, parentheses ().

assert resistor.resistance is (power.voltage - led.forward_voltage) / current
assert peak_current is (i_out / (efficiency * (1 - duty))) + ((v_in * duty) / (2 * f_sw * l))

Rules:

• Both sides of a range/tolerance must have commensurable units (3.3V to 5A is invalid).
• | and & operators parse but are rejected semantically — never use them.
• Common unit symbols: V, A, ohm/kohm/Mohm, F/uF/nF/pF, Hz/kHz/MHz, W, H/uH, mm. SI prefixes (m, u, n, k, M) are supported.

2.7 Imports

Bare import — stdlib only

import ElectricPower
import I2C
import Resistor
import Capacitor

Bare import X must resolve to a stdlib-allowlisted type or trait. If not allowlisted, you get a DslImportError.

Path import — packages and local files

from "atopile/ti-tlv75901/ti-tlv75901.ato" import TI_TLV75901
from "packages/stm32g474/stm32g474.ato" import STM32G474
from "parts/Texas_Instruments_TCA9548APWR/Texas_Instruments_TCA9548APWR.ato" import Texas_Instruments_TCA9548APWR_package
from "./power/buck_5v.ato" import Buck5V

Rules:

• One import per line (multi-import import A, B is deprecated).
• Use path imports for anything not in the stdlib allowlist.
• main.ato should import reusable local wrappers directly from packages/<name>/<name>.ato.
• Use ./relative/path.ato for truly local sibling files, not for canonical wrapper packages under packages/.

2.8 Traits

Traits attach metadata and behavior to blocks. Use them only for traits that are actually supported by the language/runtime.

#pragma experiment("TRAITS")
import can_bridge_by_name

module MyModule:
    """
    Requirements:
    - R1: Supply voltage — 3.3V regulated
    """

    # Bridge trait for series-path modules
    trait can_bridge_by_name<input_name="power_in", output_name="power_out">

    # Targeted trait on a specific field
    trait some_field has_part_removed

Common traits:

2.9 Assignments and Overrides

Parameter assignment

r.resistance = 10kohm +/- 5%
cap.capacitance = 100nF +/- 20%
ldo.v_out = 3.3V +/- 3%

Special override fields

These field names map to trait behavior:

r.package = "0402"              # footprint/package constraint
led.lcsc_id = "C2286"           # lock to specific LCSC part
ic.manufacturer = "Texas Instruments"
ic.mpn = "TLV75901PDDR"
i2c.required = True             # mark interface as required
net.override_net_name = "VCC"   # force net name
net.suggest_net_name = "SDA"    # suggest net name
param.default = 0x20            # default value (overridable)

Defaults

Package/module authors set defaults; integrators override with explicit constraints:

# In the package module:
i2c.address.default = 0x20

# In the integration module:
assert sensor.i2c.address within 0x21 to 0x21

2.10 For Loops

Requires FOR_LOOP pragma. Used for repetitive constraint/wiring patterns, not logic branching.

#pragma experiment("FOR_LOOP")

# Iterate over a sequence
for cap in decoupling_caps:
    cap.capacitance = 100nF +/- 20%
    cap.package = "0402"

# Iterate with slice
for cap in decoupling_caps[1:]:
    cap.package = "0603"

# Iterate over explicit list of references
for rail in [power_core, power_io, power_analog]:
    assert rail.voltage within 3.3V +/- 10%

Restricted — NOT allowed in loop body:

• import statements
• new assignments (create arrays outside the loop, constrain inside)
• pin / signal declarations
• trait statements
• Nested for loops

# Good: create array outside, constrain inside
resistors = new Resistor[8]
for r in resistors:
    r.resistance = 1kohm +/- 20%
    r.package = "0402"

# Bad: creating instances inside loop
for r in resistors:
    x = new Resistor    # NOT ALLOWED

2.11 Pragmas

Feature gates for experimental constructs. Place at top of file, only include what you use.

#pragma experiment("BRIDGE_CONNECT")       # enables ~> and <~
#pragma experiment("FOR_LOOP")             # enables for loops
#pragma experiment("TRAITS")               # enables trait statements
#pragma experiment("MODULE_TEMPLATING")    # enables new Type<k=v>

Unknown experiment names are errors.

2.12 Retype

-> performs deferred specialization of an existing field to a more specific type:

module USB2_0TypeCVerticalConnector from USBTypeCConnector_driver:
    connector -> VerticalUSBTypeCConnector_model

Use sparingly — only for clear specialization points like swapping a connector variant. Do not use as a general-purpose assignment.

2.13 Pin and Signal Declarations

Used inside component and interface blocks:

component MyChip:
    pin VCC
    pin GND
    pin 1
    pin "A0"

interface MyBus:
    signal data
    signal clock

In practice, you rarely write pin declarations by hand — they come from auto-generated part files.

2.14 Not Supported

ato is declarative. Do NOT generate or suggest:

• if / elif / else / while / match
• Function definitions, lambdas, classes
• try / except / finally
• List comprehensions, dict literals
• Decorators

If a user asks for conditional behavior, express it as constraints and module alternatives.

3. Stdlib Reference

3.1 Interfaces

Electrical

Untyped electrical connection point. Use when you only need net continuity with no reference semantics.

ElectricPower

Two-rail power interface.

Legacy aliases vcc and gnd exist — prefer hv/lv.

power = new ElectricPower
assert power.voltage within 3.3V +/- 5%

ElectricSignal

Single signal line with explicit reference power rail. Use for analog or general signals.

ElectricLogic

Logic signal (line + reference). Use for GPIOs, digital control, interrupts, reset, enable.

ElectricLogic vs ElectricSignal: Use ElectricLogic for digital. Use ElectricSignal for analog/general.

Important: Always connect the .reference when crossing module boundaries:

gpio.reference ~ power
i2c.sda.reference ~ power

Missing reference wiring is a common source of bugs.

I2C

Two-wire bus with address and frequency.

i2c = new I2C
i2c.scl.reference ~ power
i2c.sda.reference ~ power
assert i2c.frequency within 100kHz to 400kHz

SPI

3-wire data+clock bus (CS managed separately).

MultiSPI

Multi-lane SPI/QSPI style interface.

UART_Base and UART

UART_Base — minimal TX/RX. UART — full with flow control (RTS/CTS). UART includes base_uart sub-field.

I2S

Audio serial bus.

DifferentialPair

Paired differential signals with impedance parameter.

USB2_0_IF and USB2_0

USB2_0_IF contains differential data pair (d) and bus power (buspower). USB2_0 wraps usb_if and is easier for top-level module interfaces.

Other interfaces

SWD, JTAG, Ethernet, XtalIF — available for import, commonly used in package modules.

3.2 Components

Resistor

Auto-pickable passive. Key fields:

r = new Resistor
r.resistance = 10kohm +/- 5%
r.package = "0402"

Two unnamed pins accessed via bridge connect or r.unnamed[0] / r.unnamed[1].

Capacitor

cap = new Capacitor
cap.capacitance = 100nF +/- 20%
cap.package = "0402"

Inductor

ind = new Inductor
ind.inductance = 10uH +/- 20%
ind.max_current = 1A

Diode

Key fields: anode, cathode, forward_voltage, max_current.

LED

Extends Diode behavior. Key fields: diode.forward_voltage, diode.max_current.

led = new LED
led.lcsc_id = "C2286"        # lock to specific LED

Fuse

Series protection element with bridge capability.

ResistorVoltageDivider

Pre-built voltage divider module with r_top, r_bottom, and ratio equations.

MountingHole

Standalone mounting hole for mechanical attachment.

TestPoint

Test point for debugging and measurement.

NetTie

Net tie for connecting separate nets on the PCB.

3.3 Traits

Traits require #pragma experiment("TRAITS") and must be imported.

Requirements in docstrings

Document design requirements in the owning module's docstring.

module PowerSupply:
    """
    Requirements:
    - R1: Supply voltage — 3.3V regulated from USB
    """

can_bridge_by_name

Enable bridge connect (~>) through a module by naming its input and output fields.

import can_bridge_by_name
trait can_bridge_by_name<input_name="power_in", output_name="power_out">

has_part_removed

Suppress part picking. Used for non-BOM placeholders or integration stubs.

trait some_field has_part_removed

has_single_electric_reference

Declare that an interface shares a single reference rail. Used internally by stdlib interfaces.

Assignment-based trait shortcuts

These field assignments map to traits without needing explicit trait syntax:

• x.package = "0402" — package/footprint requirement
• x.lcsc_id = "C12345" — lock to LCSC part
• x.manufacturer = "TI" — manufacturer constraint
• x.mpn = "TLV75901PDDR" — manufacturer part number
• x.required = True — mark as externally required
• x.override_net_name = "VCC" — force net name
• x.suggest_net_name = "SDA" — suggest net name
• x.default = 0x20 — set default (overridable by downstream

…(truncated)