Planning

my-project/
├── ato.yaml                        # Project-level builds defined here
├── main.ato                        # Top-level design — imports packages, not raw parts
├── packages/
│   ├── stm32g474/
│   │   └── stm32g474.ato           # Wrapper: raw pins → standard interfaces
│   ├── drv8317/
│   │   └── drv8317.ato
│   └── tcan3414/
│       └── tcan3414.ato
├── parts/                          # All raw parts (ICs + connectors)
│   ├── STMicroelectronics_STM32G474CBT6/
│   ├── TEXAS_INSTRUMENTS_DRV8317HREER/
│   ├── Changzhou_Amass_Elec_XT30U_M/
│   └── ...
└── layouts/

requires-atopile: ^0.14.0

paths:
  src: ./
  layout: ./layouts

builds:
  default:
    entry: main.ato:DualBLDCController

  # Package builds — for independent testing
  stm32g474:
    entry: packages/stm32g474/stm32g474.ato:STM32G474
    hide_designators: true
  drv8317:
    entry: packages/drv8317/drv8317.ato:DRV8317
    hide_designators: true

#pragma experiment("BRIDGE_CONNECT")

import ElectricPower
import CAN
import ElectricLogic
import Capacitor

from "parts/STMicroelectronics_STM32G474CBT6/STMicroelectronics_STM32G474CBT6.ato" import STMicroelectronics_STM32G474CBT6_package

module STM32G474:
    """STM32G474 MCU with decoupling and standard interfaces.

    Exposes:
    - power: 3.3V rail
    - can: CAN FD interface (PA11/PA12)
    - pwm_a: 3x PWM for motor A (TIM1: PA8/PA9/PA10)
    - pwm_b: 3x PWM for motor B (TIM8: PB13/PB14/PB15)
    """

    # ── External interfaces ──
    power = new ElectricPower
    can = new CAN
    pwm_a = new ElectricLogic[3]
    pwm_b = new ElectricLogic[3]

    # ── Package ──
    package = new STMicroelectronics_STM32G474CBT6_package

    # ── Power ──
    power.hv ~ package.VDD
    power.hv ~ package.VDDA
    power.lv ~ package.VSS
    power.lv ~ package.VSSA
    assert power.voltage within 3.3V +/- 10%

    # ── Decoupling ──
    decoupling = new Capacitor[3]
    for cap in decoupling:
        cap.capacitance = 100nF +/- 10%
        cap.package = "C0402"
        power ~> cap ~> power.lv

    # ── CAN ──
    can.tx.line ~ package.PA11
    can.rx.line ~ package.PA12
    can.tx.reference ~ power
    can.rx.reference ~ power

    # ── PWM ──
    pwm_a[0].line ~ package.PA8
    pwm_a[1].line ~ package.PA9
    pwm_a[2].line ~ package.PA10
    pwm_b[0].line ~ package.PB13
    pwm_b[1].line ~ package.PB14
    pwm_b[2].line ~ package.PB15

#pragma experiment("BRIDGE_CONNECT")

import ElectricPower

from "packages/stm32g474/stm32g474.ato" import STM32G474
from "packages/drv8317/drv8317.ato" import DRV8317
from "packages/tcan3414/tcan3414.ato" import TCAN3414
from "parts/Changzhou_Amass_Elec_XT30U_M/Changzhou_Amass_Elec_XT30U_M.ato" import Changzhou_Amass_Elec_XT30U_M_package

module DualBLDCController:
    """Dual BLDC motor controller for robot drivetrain."""

    mcu = new STM32G474
    motor_a = new DRV8317
    motor_b = new DRV8317
    can_phy = new TCAN3414

    power = new ElectricPower
    power ~ mcu.power
    power ~ motor_a.motor_supply
    power ~ motor_b.motor_supply

    mcu.can ~ can_phy.can
    mcu.pwm_a ~ motor_a.pwm
    mcu.pwm_b ~ motor_b.pwm

module PowerStage:
    """Three-phase MOSFET bridge sized for continuous motor current.

    Requirements:
    - R1: 20A continuous — FET stage rated for 20A with thermal margin
    """

#pragma experiment("BRIDGE_CONNECT")

import ElectricPower
import CAN
import ElectricLogic

module BLDCController:
    """
    # BLDC Motor Controller

    Dual-motor BLDC controller using STM32G474 and two DRV8317 drivers.

    ## Key Decisions
    - STM32G474 MCU — motor control timers + CAN FD
    - DRV8317 gate driver — 3-phase, integrated LDO

    ## Requirements
    - R1: MCU platform — Uses STM32G474
    - R2: 5-18V input — Operating voltage range
    - R3: Dual motor — 2x DRV8317 in 3-PWM mode

    ## Open Questions
    - Current sensing: phase shunt vs low-side?
    """

    # ── Architecture ──
    power = new PowerSupply
    control = new MCU
    motor_a = new MotorDrive
    motor_b = new MotorDrive
    comms = new CANTransceiver

    power.rail_3v3 ~ control.power
    power.motor_supply ~ motor_a.supply
    power.motor_supply ~ motor_b.supply
    control.pwm_a ~ motor_a.pwm
    control.pwm_b ~ motor_b.pwm
    control.can ~ comms.can

    assert power.vin.voltage within 5V to 18V

module PowerSupply:
    """Power input and regulation."""
    vin = new ElectricPower
    rail_3v3 = new ElectricPower
    motor_supply = new ElectricPower

module MCU:
    """STM32G474 with timers and comms peripherals."""
    power = new ElectricPower
    can = new CAN
    pwm_a = new ElectricLogic[3]
    pwm_b = new ElectricLogic[3]

module MotorDrive:
    """DRV8317 3-phase gate driver."""
    supply = new ElectricPower
    pwm = new ElectricLogic[3]

module CANTransceiver:
    """CAN FD transceiver with UAVCAN connector.

    Requirements:
    - R4: CAN FD transceiver with UAVCAN connector
    """
    can = new CAN

checklist_create({
  items: [
    {id: "spec", description: "Write spec and project structure", criteria: "main.ato with architecture and project-level ato.yaml"},
    {id: "questions", description: "Gather design decisions", criteria: "design_questions called with all open questions"},
    {id: "pkg-mcu", description: "Create MCU wrapper package", criteria: "packages/stm32g474/stm32g474.ato with standard interfaces"},
    {id: "pkg-driver", description: "Create gate driver wrapper package", criteria: "packages/drv8317/drv8317.ato with standard interfaces"},
    {id: "integrate", description: "Wire up top-level design", criteria: "main.ato connects packages through interfaces"},
    {id: "build", description: "Build and verify", criteria: "Build passes or issues clearly identified"},
  ]
})