1. Uçtan Uca Tasarım Süreci

Bu, atopile'de bir board tasarlamak için kanonik dizidir. Hızlı ilerleyin, yapıyı temiz tutun ve planlama durumunu birden fazla tur üzerine yaymaktan kaçının (tasarım bunu gerçekten gerektirmedikçe).

Adım 1: Mimariye Taslak Çizin

Kullanıcı niyetini hemen ato koduna dönüştürün. Temiz, yüksek seviyeli bir mimarinin başlayın ve yalnızca çözülmemiş gerçek kararlar olduğunda toplu tasarım sorularını sorun.

Odaklanın:

Sistemin ne yapması gerektiği
Ana fonksiyonel bloklar
Önemli arayüzler ve gerilim domains
Boyut, maliyet, güç veya üretim üzerinde anahtar kısıtlamalar
Kullanıcı tarafından zaten sabitlenmiş parçalar veya protokoller

Araçlar: Birden çok çözülmemiş kararı bir kere toplamak için design_questions kullanın. Tanımadığınız domains veya bileşenleri araştırmanız gerekirse mimariyi kilitlemeden önce web_search kullanın.

Kapı: spec .ato dosyası var, module hiyerarşisi, arayüz bağlantıları, docstrings içinde gereksinimler ve formal kısıtlamalar.

Adım 2: Spec'i Yazın

Spec, yüksek abstraksiyon seviyesinde tasarım dosyasıdır. Uygularken gerçek bileşenleri ve kablolama doldurursunuz. Dosya büyür; yapı aynı kalır.

Ana ilkeler:

İyi adlandırma — modules'ı sistem içindeki rollerine göre adlandırın, implementasyon topolojisine göre değil (bkz. Bölüm 1.1).
Module sınırları üst seviyede duplication'ı önlemek için ortak işlevselliği kapsüllemeliydir.
Yüksek seviyeli arayüzler kullanın (ElectricPower, I2C, SPI, UART, ElectricLogic) mümkün olduğunda düşük seviyeli elektriksel bağlantılar yerine.
Özel arayüzler nadirdir — yeni bir interface tanımlamadan önce stdlib'i stdlib_list / stdlib_get_item ile kontrol edin. Var olan stdlib arayüzü veya basit stdlib arayüzleri composition/array'i çalışırsa, bunun yerine onu kullanın.
Gereksinimler sahibi module'nin docstring'inde Requirements: bölümü altında yakalanmalıdır.
Formal kısıtlamalar ekleyin assert ile gerilim, akım, frekans sınırları için.
Module'leri arayüz seviyesinde (~) birbirine bağlayın. Pin'ları henüz bağlamayın.

Adım adım:

İsteği subsistems'e bölün. Her fonksiyonel blok bir module olur — güç, MCU, sensörler, iletişim, IO, vb.
Module sınırlarında arayüzleri tanımlayın. Module'lerin nasıl bağlandığını bildirmek için stdlib arayüzlerini kullanın.
Gereksinimler docstring'lerde yakalanmalıdır. Sahibi module'nin docstring'ine Requirements: bölümü ekleyin.
Formal kısıtlamalar ekleyin assert ile gerilim, akım, frekans sınırları için.
Module'leri arayüz seviyesinde (~) birbirine bağlayın.
Bir kontrol listesi oluşturun, öğeleri requirement ID'lerine bağlayın.

Örnek spec:

import ElectricPower
import I2C
import SPI
import ElectricLogic

module SensorBoard:
    """
    # Environmental Sensor Board

    Pil güçlü sensör nodu, sıcaklık, nem ve
    basınç ölçümü, BLE iletişim ve USB-C şarjı.

    ## Requirements
    - R1: BLE bağlantısı — BLE 5.0 ile nRF52840
    - R2: Çevresel ölçüm — sıcaklık/nem/basınç için BME280
    - R3: USB-C şarjı — 5V USB-C girişi ve charge IC
    - R4: Board boyutu — 25mm x 30mm max

    ## Anahtar Kararlar
    - BLE + düşük güç için nRF52840
    - sıcaklık/nem/basınç için BME280

    """

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

    # Arayüz seviyesi kablolama (henüz pin değil)
    power.rail_3v3 ~ mcu.power
    power.rail_3v3 ~ sensors.power
    mcu.i2c ~ sensors.i2c
    mcu.spi ~ comms.spi

    # ── Kısıtlamalar ───────────────────────────────────────
    assert power.usb_in.voltage within 4.5V to 5.5V
    assert power.rail_3v3.voltage within 3.3V +/- 5%

module PowerSupply:
    """
    USB-C girişi, charge controller, LDO regülasyonu.

    ## Requirements
    - R5: Pil şarjı — termal koruma ile LiPo charge IC
    """

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

module MCU:
    """nRF52840 kristal, decoupling ve debug header ile."""
    power = new ElectricPower
    i2c = new I2C
    spi = new SPI

module EnvironmentalSensor:
    """BME280 çevresel sensörü."""
    power = new ElectricPower
    i2c = new I2C

module Radio:
    """BLE anten uyumu ve RF front end."""
    spi = new SPI

Bu adım için anahtar kurallar:

Module isimleri finaldir — PowerSupply implementasyonun tamamında PowerSupply kalır. "Spec" ile soneklemek MAY.
Gereksinimler tüm üst seviye değil, sahibi module'nin docstring'ine yerleştirilmelidir.
Docstring'leri özet, gereksinimler ve önemli kararlar için kullanın.
Çözülmemiş planlama durumunu tasarım dosyasında gerekli olmaktan daha uzun tutmayın; design_questions ile açık soruları topla ve cevaplar geldikten sonra implementasyonu devam ettir.

Araçlar: stdlib_list / stdlib_get_item özel tanımlamadan önce mevcut arayüzleri ve bileşenleri kontrol edin. Benzer sistemler için referans tasarımlar bulmak için examples_search / examples_read_ato kullanın.

Kapı: mimari implementasyon için yeterince tutarlıdır. Birden çok açık tasarım kararı varsa, bunları design_questions ile toplayın ve cevaplar geldikten sonra devam edin.

Adım 3: Açık Kararları Çözün

Kullanıcıya mevcut mimayi ve çözülmemiş gerçek kararları sunun:

Module'leri ve sorumlulukları listeleyin.
Module'ler arasında arayüz bağlantılarını gösterin.
Yapılan anahtar kararları veya trade-off'ları vurgulayın.
Varsayımları veya alternatif seçeneklerin olduğu alanları çıkarın.

Birden çok tur üzerinde takip soruları akıtmak yerine, çözülmemiş kararları toplamak için design_questions kullanın. Ardından cevapları doğrudan spec'e dahil edin ve implementasyonu devam ettirin.

Kapı: anahtar açık sorular çözüldü veya makul varsayılanlar seçildi.

Adım 4: Detaylı Tasarımı Uygulayın

Şimdi spec'i gerçek bileşenler, kablolama ve kısıtlamalar ile doldurun. Bu adım paket araması, parça seçimi ve detaylı kablolama kapsar.

4a: Mevcut paketleri bulun

Sıfırdan inşa etmeden önce atopile paket registry'sinde arayın.

Araçlar: packages_search → packages_install → package_ato_read genel arayüzü incelemek için. Ayrıca yerleşik modules için stdlib_list kontrol edin.

Yeni bir driver module yazmaktan çok iyi test edilmiş bir paketi yeniden kullanmayı tercih edin.

4b: Yok olduğunda yerel paketler oluşturun

packages_search gerekli IC, konnektör veya module için eşleşme döndürmediğinde, yerel driver paketi oluşturun yerine pes edin veya kullanıcıdan bir bulmasını isteyin.

Araçlar: parts_search → web_search (aileleri karşılaştırmak, vendor datasheet/design guide incelemek, topolojiyi doğrulamak ve referans devreleri bulmak için) → parts_install(create_package=true) → project_read_file (oluşturulan wrapper paketi incelemek için) → project_edit_file (wrapper'ı yerinde iyileştirmek için) → workspace_list_targets (iç içe paket targetleri keşfetmek için).

Adım adım tarif:

Parçayı bulun: LCSC bileşenini bulmak için parts_search kullanın (örn. parts_search("LAN8742A")).
Parça ailesini araştırın gerektiğinde: Uygulama notları, ortak referans devreler, aile karşılaştırmaları veya seçilen topolojinin standart ve sağlam olduğunun doğrulanması için parçayı kilitlemeden önce web_search kullanın.
Yerel paket olarak kurun: LCSC ID ile parts_install ve create_package=true kullanın. Bu raw parçayı kurar ve packages/ altında kanonik yeniden kullanılabilir wrapper paketi oluşturur.
Vendor docsunu web search ile inceleyin: Parça numarası, vendor ve datasheet, hardware design, application circuit, decoupling, pinout gibi terimler veya ihtiyaç duyduğunuz belirli pin'ler/özellikler ile web_search kullanın.
Oluşturulan dosyaları okuyun: packages/<PartName>/<PartName>.ato altındaki oluşturulan wrapper'ı ve ithal ettiği kurulu raw parçayı inceleyin, mevcut arayüzleri ve tam pin isimlerini görmek için.
Wrapper paketi iyileştirin gerekirse:
- packages/<PartName>/<PartName>.ato'yu o parça için kanonik wrapper module olarak düşünün.
- Başka bir wrapper katmanı oluşturmak yerine oluşturulan paket dosyasını yerinde düzenleyin.
- Raw kurulu parça dosyasını değiştirilmez tutun.
- Temel yeniden kullanılabilir wrapper ile başlayın. Paketi temiz bir şekilde inşa etmek ve entegre etmek için gereken minimum standart arayüzleri ortaya çıkarın.
- Wrapper'ı genel ve yeniden kullanılabilir tutun. Chip'in genel yetkinliklerini ortaya çıkarın, bir projenin tam mimarisini değil.
- ElectricPower, I2C, SPI, UART, CAN, SWD, USB2_0, USB2_0_IF, ElectricLogic, veya ElectricSignal gibi standart arayüzleri ortaya çıkarın.
- Herhangi bir özel interface yazmadan önce, stdlib_list / stdlib_get_item ile mevcut stdlib arayüzünü kontrol edin ve proje-yerel aggregate arayüzlerden stdlib arrays/composition'ı tercih edin.
- sbus, phase_current, weapon_pwm, veya battlebot_interfaces gibi tasarıma özgü roller yerine uart, spi, adc_inputs, gpio, usb, swd, power gibi capability-odaklı isimler ve sınırları tercih edin.
- Anahtar yetkinliklerin temiz bir şekilde kablolansa da eksik pin maruziyeti bloker olarak işlem görmemelidir. Entegrasyon daha fazla arayüz, alternatif pin eşlemeleri veya daha zengin yetkinliklere ihtiyaç olduğunu kanıtladığında daha sonra ekleyin.
- Dahili _package bileşen pin'lerini bu arayüzlere eşleyin.
- Decoupling kapasitörleri ve gerekli pasifleri ekleyin.
- Datasheet'ten gerilim/akım kısıtlamaları belirleyin.
- Wrapper'ı paketi izole olarak doğrularken yeni destekleyici fiziksel parçalara ihtiyacı varsa, bunları parts_install(project_path="packages/<PartName>") ile o paket projesine kurun.
Target'leri keşfedin: Paket oluşturulduktan sonra workspace_list_targets çalıştırın, otomatik olarak ortaya çıkarılan paket target'lerini incelemek için.
İçeri aktarın ve kullanın yerel paketi packages/<PartName>/<PartName>.ato adresinden doğrudan üst seviye tasarımda.
Paket çalışmasını delegate edin gerekirse: Paket projesi varsa ve bağımsız olarak inşa edilebiliyorsa, bir paket uzmanı wrapper'ı iyileştirirken siz üst seviye entegrasyon üzerinde devam etmek için package_agent_spawn(project_path="packages/<PartName>", goal=..., comments=...) kullanın.

Örnek: oluşturulan yerel I2C mux wrapper'ı iyileştirme

packages/<PartName>/<PartName>.ato altındaki oluşturulan paket dosyası, iyileştirmeniz gereken wrapper'dır. İthal ettiği raw parça bileşeni davranışı düzenlemek için bir yer değildir.

#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:
    # Genel arayüzler
    power = new ElectricPower
    assert power.voltage within 1.65V to 5.5V

    i2c = new I2C
    reset = new ElectricLogic

    # Otomatik oluşturulan paket bileşenini örnekleştirin
    package = new Texas_Instruments_TCA9548APWR_package

    # Güç bağlantıları
    power.hv ~ package.VCC
    power.lv ~ package.GND

    # I2C — .line ve .reference aracılığıyla bağlayın
    i2c.sda.line ~ package.SDA
    i2c.scl.line ~ package.SCL
    i2c.sda.reference ~ power
    i2c.scl.reference ~ power

    # Decoupling — seri yol için bridge connect (~>) kullanın
    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

    # Pullup ile Reset
    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

Anahtar kurallar:

Her zaman ilk parts_install — kurulmamış bir parçaya hiçbir zaman başvurmayın.
IC'ler ve diğer yeniden kullanılabilir sarılı parçalar için parts_install(create_package=true) tercih edin.
Bir paketi kendi projesi olarak doğrularken, paket kendisi tarafından ithal edilen yeni destekleyici parçalar için parts_install(project_path="packages/<name>") kullanın.
Tam bir paket iskeleti olmadan yerel paket gerektiğinde package_create_local kullanın.
Her zaman oluşturulan paketi ve raw parça .ato dosyalarını okuyun tam sinyal isimlerini görmek için (örn. package.VCC, package.SDA). Pin isimlerini ASLA tahmin etmeyin.
Doğru pin eşlemesi, kısıtlamalar ve önerilen decoupling almak için her zaman vendor datasheet'ini ve hardware design notlarını incelemek için web_search kullanın.
packages/ altındaki oluşturulan paket dosyası o parça için kanonik wrapper'dır. Yerinde iyileştirin.
Raw kurulu dosya bir component — asla düzenlemeyim.
Temel yeniden kullanılabilir wrapper inşa edin. Paketi doğrulamak ve entegre etmek için gereken minimum standart arayüzleri ortaya çıkarın, sonra entegrasyon daha fazla pin eşlemeleri veya arayüzlere ihtiyaç olduğunu kanıtlarsa daha sonra geri dönün ve daha fazla ekleyin.
Paket projesi var olduğunda, tüm paket çalışmalarını seri olarak yapmak yerine package_agent_spawn aracılığıyla izole wrapper inşaasını delegate etmeyi tercih edin.
Raw bileşeni wrapper içine package = new <ComponentName> olarak örnekleştirin.
main.ato extra aggregator wrapper dosyasından değil, doğrudan packages/<name>/<name>.ato adresinden wrapper paketlerini içeri aktarmalıdır.
.line ve .reference aracılığıyla arayüzleri bağlayın (örn. i2c.sda.line ~ package.SDA; i2c.sda.reference ~ power).
Seri decoupling caps için bridge connect ~> kullanın (örn. power.hv ~> cap ~> power.lv).
Capacitor değerleri için .capacitance, Resistor değerleri için .resistance kullanın (.value DEĞIL).
~> kullanıyorsanız #pragma experiment("BRIDGE_CONNECT") ekleyin.
IC'ye özel pin kablolama'yı module içinde tutun; yalnızca soyut arayüzleri ortaya çıkarın.
Kullanıcı'ya paket'i kendisi oluşturmasını söylemek için bu adımı atlamayın ve siz de atlamayın. Bu core agent yetkinliğidir.

4c: Parça seçimi

Mümkün olduğunda generics + kısıtlamalar kullanarak bileşenleri seçin.

Araçlar: Belirli IC'ler/konektörler için parts_search / parts_install. Vendor datasheetleri, hardware design rehberleri, uygulama notları ve alternatif parçalar için web_search.

Otomatik seçim için stdlib generics (Resistor, Capacitor, Inductor, Diode, LED, Fuse) değer + paket kısıtlamaları ile kullanın. Kilitli parçalar yerine generics'leri tercih edin.
parts_search'ü yalnızca belirli bir parça gerektiğinde (IC, konnektör, özel bileşen) kullanın.
Aday aileleri karşılaştırmanız, önerilen implementasyon modelini onaylamanız veya katı bir referans devre/uygulama notu bulmanız gerektiğinde bir parçayı kilitlemeden önce web_search kullanın.
Açık LCSC ID'leri gerektiren parçalar için parts_install ve wrapper paketi olması gerektiğinde create_package=true tercih edin.
Seçilen somut parçayı incelemek için vendor datasheet'ini, tam pin'leri, sınırları ve destekleyici devrelerinizi incelemek için web_search kullanın.
Yalnızca yüksek riskli parçaları (MCU, PMIC, RF, konektörler) kilitleyin. Emtia pasifleri otomatik seçime bırakın.
Proje-yerel interface icad etmeden önce, wrapper sınırının şu şekilde temsil edilip edilemeyeceğini kontrol edin:
- stdlib arayüzü (SPI, UART, SWD, USB2_0_IF, vb.)
- stdlib sinyalleri/arayüzleri dizi (new ElectricLogic[3], new ElectricPower[3], new ElectricSignal[3])
- module üzerinde doğrudan birkaç named stdlib alanı
Yalnızca stdlib veya basit composition'ın zaten kapsadığı gerçek yeniden kullanılabilir bir protokol/sınırı temsil ettiğinde özel arayüz tanımlayın.
Paket wrapper'larını genel tutun. Tasarıma özgü gruplama ve rol adlandırması main.ato veya paket katmanının üzerindeki proje module'lerine aittir.

4d: Detaylı kablolama ve kısıtlamalar

Bağlantı, kısıtlamalar ve denklemler ekleyin, tasarımı tamamlayın.

Module'leri ~ kullanarak arayüzler aracılığıyla bağlayın (veya bridge/seri yollar için ~>).
Tüm anahtar elektriksel özellikler için parametre kısıtlamaları (assert ... within ...) ekleyin.
Bölüm 4 desenlerine göre decoupling, pullup'lar ve koruma ekleyin.

Kapı: tasarım tamamlandı — tüm module'ler kablolama, tüm kısıtlamalar beyan edildi, tüm arayüzler bağlı. Her bileşen kısıtlı generic veya açıkça seçilmiş parçadır.

Adım 5: İnşa Edin

Her şey geçene kadar iteratif olarak inşa ve sorunları düzeltin. Önce submodule'leri inşa edin (varsa) — tam inşaadan önce küçük parçaları çalıştırmak çok daha kolaydır.

5a: İnşa + düzeltme döngüsü

Araçlar: workspace_list_targets → build_run → build_logs_search (log_levels/stage tarafından filtre) → sessiz hatalar için design_diagnostics. Kısıt durumunu incelemek ve parça seçimini doğrulamak için report_variables ve report_bom kullanın.

Yerel paketler oluşturduktan/kurduktan sonra ilk workspace_list_targets çalıştırın, böylece hangi paket target'lerinin zaten otomatik olarak var olduğunu bilirsiniz.
Tasarımı makul submodule'lere bölün ve bunları daha küçük target'leri daha önce inşa edin. Bu default doğrulama döngüsüdür.
Tekrarlanan tam tasarım inşalarından çok daha hızlı geri bildirim alabilmeniz için wrapper/paket target'lerini paralel olarak da inşa edin.
Wrapper yalnızca kısmen ortaya çıkarılmışsa, yine de temel wrapper'ı inşa edin ve devam edin. Daha fazla arayüze ihtiyaç olabileceği için çalışmayı bloke işaretlemek yerine, entegrasyon sırasında wrapper'ı daha sonra genişletin.
Alt module/paket başarısızlıklarını üst seviye tasarımı çalıştırmadan önce düzeltin.
Oluşturulan yerel paket wrapper'larını inşa etmek için el ile üst seviye ato.yaml girişleri eklemeyin, eğer workspace_list_targets zaten bu target'leri ortaya çıkarıyorsa.
Alt module'ler yeşil olduktan sonra tam üst seviye inşasını kullanın; bu daha sonra ilk hata bulunduğu yer yerine esas olarak entegrasyon kontrolü olmalıdır.
Hatalar/uyarılar için build_logs_search kontrol edin.
Sessiz hatalar için design_diagnostics kullanın.
Bölüm 5 troubleshooting'i kullanarak sorunları düzeltin.
Inşa temiz bir şekilde geçene kadar tekrarlayın.

Adım 6: Özet

Araçlar: Özet hazırlarken parts listesi için report_bom ve kısıt özeti için report_variables kullanın.

Inşa bittiğinde, kullanıcıya özet verin:

Ne inşa edildi — module'leri, anahtar bileşenleri ve arayüzleri listeleyin.
Blocker'lar veya sorunlar — karşılaşılan sorunları ve nasıl çözüldüğünü (veya kalıp kalıyorsa) belirtin.
Sonraki adımlar için öneriler — kullanıcının sonra ne yapmak isteyebileceği (örn. yerleşimi gözden geçirme, board sipariş etme, özellikler ekleme, DRC çalıştırma).

Kapı: kullanıcı net bir özet aldı ve tasarımın durumunu biliyor.

1.1 Module Adlandırması

Module'leri sistem blok diyagramında labelleştireceğiniz şekilde adlandırın — sistem içindeki rolüne göre, implementasyon topolojisine göre değil. Subsystem, Unit, Block, veya Section gibi genel sonekleri kaçının.

İyi isimler:

PowerSupply — giriş koruması, regülasyon ve dağıtım
PowerInput — konnektör, ters polarite koruması ve bulk decoupling
BatteryCharger — charge IC, sense resistors ve durum çıkışı
BMS — hücre balanslaması, koruma ve fuel gauge
GateDriver — bootstrap, dead-time ve FET köprüsü için level shifting
MotorDrive — akım sınırı ve fault çıkışı ile entegre driver
CurrentSense — shunt ve sense amplifier

ato

Bu skill hakkında