pcb/scripts/README.md

# Üretim, doğrulama ve routing akışı

## Gereksinimler

- KiCad 10.x ve `kicad-cli`.
- KiCad ile aynı sürümden `/usr/bin/python3` ve `pcbnew` modülü.
- Python paketleri: `pip install -r requirements.txt`.
- Yoğun sinyal routing aşaması için isteğe bağlı Freerouting 2.3.x.

`pcbnew` kullanan scriptler sistem Python'u ile çalıştırılmalıdır. Normal
Python ortamına yalnızca `pip install pcbnew` yapmak KiCad ABI uyumluluğunu
garanti etmez.

## Dosya üretim sırası

Repository kökünden:

```bash
python3 scripts/generate_footprints.py
python3 scripts/generate_kicad.py
python3 scripts/generate_design_tables.py
/usr/bin/python3 scripts/generate_pcb.py
```

Bu sıralama:

1. Özel footprintleri üretir.
2. `design_data.py` üzerinden şema hiyerarşisini ve BOM'u üretir.
3. Efinity C529 paket verisine karşı pin tablolarını doğrular ve üretir.
4. 8 katmanlı stackup, kurallar, zone'lar ve placement ile PCB'yi üretir.

`design_data.py` çalıştırıldığında dahili bağlantı assertion'ları da yürütülür:

```bash
python3 scripts/design_data.py
```

## Şema ve placement doğrulaması

```bash
kicad-cli sch erc --severity-all \
  -o outputs/erc_final_reset.rpt hardware/board.kicad_sch

kicad-cli pcb drc --severity-all \
  -o outputs/drc_final_placement.rpt hardware/board.kicad_pcb
```

Unrouted placement aşamasında unconnected-pad ve isolated-zone kayıtları
beklenir. Clearance, short, courtyard, solder-mask, edge ve footprint hataları
beklenmez.

## Routing sırası

### 1. BGA escape

```bash
/usr/bin/python3 scripts/preroute_bga.py \
  hardware/board.kicad_pcb hardware/board_prerouted.kicad_pcb
```

Ti375'in bağlı ball'larına kilitli 0.8 mm pitch dogbone/via escape ekler.

### 2. Güç katı

```bash
/usr/bin/python3 scripts/route_power_stage.py \
  hardware/board_prerouted.kicad_pcb \
  hardware/board_power_routed.kicad_pcb
```

Autorouter'dan önce aşağıdaki yüksek akım hatlarını deterministik ve kilitli
olarak route eder:

- TPS6287B15 giriş kapasitörü, SW, indüktör, çıkış kapasitörü ve remote-sense.
- TPS62867 1.8 V / 3.3 V giriş-SW-çıkış döngüleri ve plane via dizileri.
- Converter bölgesindeki SYS5 dağıtımı ve ana güç geçişleri.

SW node bakırı küçük tutulmalı; feedback/sense hatları SW ve indüktörden uzak,
Kelvin bağlantılı götürülmelidir. Autorouter bu kararları vermez.

Bu aşama stitching'den **önce** gelir. Tersi sırada plane stitching, buck
çıkışının geçmesi gereken koridora via bırakıp yüksek akım yolunu kesiyordu.

### 3. Yerel plane bağlantıları

```bash
/usr/bin/python3 scripts/stitch_plane_pads.py \
  hardware/board_power_routed.kicad_pcb \
  hardware/board_plane_stitched.kicad_pcb
```

Yalnızca altında gerçekten aynı nete ait dolu plane bulunan SMD güç/GND
padlerini kısa dogbone ile bağlar. Bu işlem yüksek akım buck loop routinginin
yerini tutmaz. RF/USB geçici keepoutlarına through-via koymaz; edge-launch J2
ground bağlantıları final RF ground zone/via-fence aşamasına bırakılır.

### 4. Yerel güç tamamlama

```bash
/usr/bin/python3 scripts/route_local_power.py \
  hardware/board_plane_stitched.kicad_pcb \
  hardware/board_power_local.kicad_pcb --clocks
```

`--clocks` clock sınıfını da burada, autorouter başlamadan kapatır; böylece
saat hatları sabit bakır olarak DSN'e girer ve router onları bozamaz.

Plane ve plane stitching'in ulaşamadığı güç bağlantılarını tamamlar: adasının
hemen dışında kalan pad'ler, plane'i olmayan küçük raylar (`FTDI_1V8`,
`IMU_VREGD`, anten bias hatları) ve her LDO'nun etrafındaki yerel giriş/çıkış
döngüleri. Gerçek connectivity grafiği üzerinde çalışır: ayrık kalan her grup
için ya kendi plane'ine via indirir ya da en yakın gruba 45 derecelik yol
çeker. Bütün sonuçlar kilitlidir.

İki fazlıdır. Önce bütün raylar için yalnızca plane inişi ve kısa doğrudan
yollar denenir; ikinci fazda kalanlar ara nokta üzerinden dolaşabilir. Bu ayrım
olmadan listedeki ilk ray, sonraki bir rayın kısa bağlantı için ihtiyaç duyduğu
boşluğu uzun yollarla harcar.

Bir grubu kendi plane'ine indirmek, o adada başka grup yoksa grup sayısını
düşürmez. Bu yüzden ilerleme, `reach_plane`'in döndürdüğü değere değil grup
sayısının gerçekten azalmasına bakılarak ölçülür ve zaten plane'e bağlı gruplar
atlanır. Aksi halde aynı pad çevresinde her turda 0.4 mm daha dışarıda yeni bir
via açılır ve ray tek bir pad'in etrafında onlarca gereksiz via'dan oluşan bir
"via cloud" ile biter.

Bu aşama güç raylarını autorouter'a bırakmamanın karşılığıdır. Freerouting
DSN'de plane göremez; `GND` ve `VCC3V3` gibi rayları ona verseydik yüzlerce
pad'i plane yerine trace ile birbirine bağlamaya çalışırdı.

### 5. Freerouting için sınıf bazlı DSN

```bash
/usr/bin/python3 scripts/export_routing_stage.py \
  hardware/board_power_local.kicad_pcb outputs/signal_stage.dsn \
  --classes "Default;BGA_ESCAPE;CLOCK" \
  --extra-nets "ANT_BIAS_SW;EXT5_PROT;FTDI_1V8;FTDI_VPHY;FTDI_VPLL;USB5_PROT;VBUS_RAW" \
  --fixed-copper keepout
```

`--extra-nets`, POWER sınıfında olduğu için sınıf filtresine takılan ama
plane'i de bulunmayan rayları listeler; yerel tamamlama bunlardan artakalan
bağlantıları autorouter'a devreder.

Route edilmeyen netlerin bakırı `--fixed-copper keepout` ile her parça için bir
rule area olarak aktarılır: router o bakırı görmez, yalnızca etrafından dolaşır.
`--fixed-copper wire` alternatifi bakırı kendi netinde `(type fix)` wire olarak
yazar ve netleri network bölümünde pinsiz tanımlar; daha az alan üretir ama bu
kartta pass başına yaklaşık dört kat yavaş çalışır.

Buradaki alan sayısı doğrudan yerel güç aşamasının ne kadar bakır bıraktığına
bağlıdır: via cloud'lar temizlendikten sonra 4146 keepout 2541'e düştü.

Bu aşamanın autorouter'ı hâlâ **Freerouting 2.3.0**'dır (aşağıda). KiCad 10 DSN
clearance değerlerini doğru ölçekte okur; `-mt 1` ile çalıştırılır (çok-thread
optimizasyon clearance ihlali üretebiliyor).

`hardware/power_routes.json` ve `hardware/critical_routes.json` el çizimi
geometriyi veri olarak tutar (bkz. `hardware/routes_schema.md`); tek seferlik
üretim: `/usr/bin/python3 scripts/_extract_fixed_routes.py`.

> Bu repoda bir zamanlar `router/` altında bağımsız bir C++ autorouter +
> Qt GUI (`pcbrouter`) vardı. Yoğun 8 katmanlı sinyal aşamasında Freerouting
> kadar tamamlamadığı için kartın routing akışında hiç kullanılmadı ve
> 2026-09-01'de repodan çıkarıldı (`../pcbrouter-cpp-20260901.tar.gz` olarak
> arşivlendi). Sinyal aşaması Freerouting 2.3.0, kalan bağlantılar
> `close_remaining.py` ile kapatılır.

```bash
.tools/freerouting-2.3.0/app/freerouting-2.3.0-linux-x64/bin/freerouting \
  -de outputs/signal_stage.dsn -do outputs/signal_stage_pass4.ses \
  -mp 4 -mt 1 -us Greedy -is prioritized
```

Bu tasarımda Freerouting'in 20-25 bağlantıda plato yapması beklenen durumdur;
onu sıfıra ulaşana kadar açık bırakmak session'ın hiç yazılmamasına yol açar.
`-mp 4` global yoğun rotayı sınırlar ve kalan bağlantılar varken de geçerli SES
yazar. İnce BGA/FTDI çıkışları, mevcut dogbone ve track uçlarını anchor olarak
kullanan KiCad-side finisher tarafından sonraki adımda tamamlanır. Böylece SES
kaydı için sıfır unrouted önkoşulu yoktur; sıfır bağlantı ve sıfır DRC yalnızca
son KiCad kontrolünün kabul ölçütüdür.

RF, USB ve güç converter loopları otomatik sonuca bırakılmaz. Bu netler DSN'de
hiç yoktur; yerlerini `generate_pcb.py` içindeki `TEMP_` rule area'ları tutar.
`TEMP_*_BELOW` alanları RF ve USB altındaki referans/routing katmanlarını,
`TEMP_RF_LINE` ve `TEMP_USB_*` koridorları ise `finalize_routing.py`'nin
kuracağı geometrinin F.Cu izini korur. CLOCK sınıfı kendi genişlik/clearance
kurallarıyla route edilir ve finalde ayrıca incelenir.

### 6. Kritik hatları kur ve session'ı sonlandır

```bash
/usr/bin/python3 scripts/finalize_routing.py \
  outputs/signal_stage_pass4.ses \
  --base hardware/board_power_local.kicad_pcb \
  --output hardware/board_routed.kicad_pcb \
  --finish-nets auto
```

Bu işlem Freerouter'ın RF ve USB üzerindeki copperını kaldırır, geçici rule
area'ları siler, denetlenmiş RF/USB geometrisini ekler ve RF GND via fence'i
kurar. Ardından koridorlar boşaldığı için `stitch_plane_pads` ve
`route_local_power` bir kez daha çalıştırılır; bu, RF/USB bölgesindeki güç
pad'lerinin plane'e ulaşabildiği tek andır. Kalan CLOCK, BGA_ESCAPE, Default ve
yalnız düşük-akım yerel POWER netleri `finish_signal_routes.py` ile kapatılır;
5-V giriş yolları ile ana FPGA rayları dar fallback route'a kesinlikle verilmez.
Son olarak dangling copper temizlenir, plane'lerde island temizliği açılır ve
zone'lar doldurulur.

### 7. Kalan bağlantıları kapat

```bash
/usr/bin/python3 scripts/close_remaining.py \
  hardware/board_routed.kicad_pcb --deadline 60 --ripup-depth 2
```

Freerouting ve yerel tamamlama adımlarından sonra kalan her açık bağlantıyı tek
bir çok katmanlı maze router ile kapatır. Bu adımın yerini aldığı eski
artık-bağlantı scriptlerinin sabit bir şekli vardı: A pad'inin yanına via, tek
bir katmanda A*, B pad'inin yanına via. Bu şekil, dört dogbone noktası da dolu
olan bir 0.8 mm BGA balını kaçıramaz ve sinyal hatlarının adalara böldüğü bir
güç pour'unu köprüleyemez. Bu kartta kalan başarısızlıklar tam olarak bunlardı,
bu yüzden o scriptler kaldırıldı.

`close_remaining.py`:

- Beş route edilebilir katmanın hepsinde `(x, y, katman)` üzerinde 0.1 mm
  adımla arar; via'nın yasal olarak sığdığı her yerde katman değiştirir.
- Başlangıç ve hedef, birleştirilen iki grubun **bütün** bakırıdır (pad, track,
  via); tek bir pad değil.
- Clearance'ı gerçek pad/track/via geometrisinden, gerçek net-class
  değerleriyle hesaplar.
- Bakırı U1 courtyard'ı içinde 0.10 mm'ye daraltır (iki 0.8 mm land arasından
  geçen tek genişlik), dışarıda net-class genişliğini kullanır.
- Yabancı bir güç pour'unun içine girmez; böylece yeni bir hat bir güç adasını
  ikiye bölemez.
- Sığmayan bir bağlantı için autorouter bakırını **geri alınabilir şekilde**
  söker: hattı geçirir, yerinden ettiği netleri tekrar route eder, biri geri
  konamazsa her şeyi eski haline döndürür. Rip-up kartı asla bulduğundan daha
  kötü bırakmaz.

Eklenen her şey kilitlidir. Sonrasında zone'lar doldurulur ve dangling bakır
temizlenir.

#### Bu adımın gerektirdiği iki kural değişikliği

**1. `Ti375 escape field copper clearance` (yeni, `board.kicad_dru`).**
0.8 mm ball pitch, iki komşu 0.45 mm dogbone via arasında 0.35 mm'lik bir
kanal bırakır. 0.10 mm'lik bir hat bu kanala escape alanının 0.10 mm bakır
minimumunda sığar, CLOCK sınıfının 0.15 mm'sinde sığmaz (0.10 + 2x0.15 = 0.40
> 0.35). Bu yüzden `HARD_TCK` ve `MAX_SCLK` paketten hiç çıkarılamıyordu. Yeni
kural, **her iki nesne de** U1 courtyard'ının içindeyken clearance'ı bu alanın
geri kalanının zaten kullandığı 0.10 mm'ye indirir. Clock trunk, U1
courtyard'ından çıkar çıkmaz 0.15 mm'sine geri döner.

**2. `RF_NO_DIGITAL` artık RF hattının koridoru kadar.**
Alan (152, 36)-(174.5, **49.5**) dikdörtgeniydi; RF bakırı ise y <= 42.6'da
kalıyor. Yani alan, RF hattının 7 mm güneyine kadar uzanıyor ve MAX2771'in
bütün dijital pin sıralarını (y = 44.5 .. 47.4) içine alıyordu. Sonuç: U21'in
her dijital çıkışı yalnız F.Cu'dan kaçmak zorundaydı ve sığmıyordu. Alan
(152, 36)-(174.5, **43.7**) yapıldı; bu, `generate_pcb.py`'nin `TEMP_RF_LINE`
olarak zaten ayırdığı koridorun aynısıdır ve RF bakırını 1.1 mm açıkla geçer.
RF dönüş yolu zaten bu alan tarafından değil, üzerinde hiç route edilmeyen
L2/L7 GND plane'leri tarafından garanti edilir.

### 8. Final kontroller

```bash
kicad-cli pcb drc --severity-all --schematic-parity --refill-zones \
  --save-board -o outputs/drc_final_routed.rpt \
  hardware/board_routed.kicad_pcb

/usr/bin/python3 scripts/report_routing.py hardware/board_routed.kicad_pcb
```

DRC "yanlış olan var mı" sorusunu, `report_routing.py` ise "eksik olan var mı
ve bakır kurallarına uyuyor mu" sorusunu yanıtlar: hâlâ birden fazla parçaya
bölünmüş netleri, net-class başına gerçekten kullanılan hat genişliğini
(Specctra gidiş-dönüşünde sessizce değişebilen değer) ve katman dağılımını
listeler.

Final kartta unconnected item, short, clearance, isolated copper veya
schematic-parity hatası kabul edilmez. RF uzunlukları, USB eşleşmesi, güç
loopları, return path ve test-point erişimi görsel olarak da incelenmelidir.

## Script özeti

| Script | Görev |
|---|---|
| `design_data.py` | Tek kaynak komponent/net verisi ve bağlantı assertion'ları |
| `generate_footprints.py` | Üretici land-patternlerinden özel footprint üretimi |
| `generate_kicad.py` | Şema, sembol ve BOM üretimi |
| `generate_design_tables.py` | Ti375 pinout/constraint ve MAX2771 tablo üretimi |
| `generate_pcb.py` | Stackup, rule, zone ve deterministic placement üretimi |
| `preroute_bga.py` | Kilitli Ti375 dogbone escape |
| `stitch_plane_pads.py` | Yerel pad-to-plane bağlantıları |
| `route_power_stage.py` | Buck yüksek-akım döngüleri ve plane girişleri |
| `route_local_power.py` | Plane'e ulaşamayan güç bağlantılarının deterministik tamamlanması |
| `export_routing_stage.py` | Seçili net-class için DSN üretimi |
| `prepare_freerouting_dsn.py` | Yalnız doğrulanmış farklı router build'leri için opsiyonel DSN clearance ölçekleme |
| `finalize_routing.py` | SES importu ve denetlenmiş RF/USB geometrisi |
| `finish_signal_routes.py` | Global router'ın bıraktığı yerel bağlantıları gerçek KiCad obstacle modeliyle tamamlar |
| `close_remaining.py` | Kalan bütün açık bağlantıları çok katmanlı maze + geri alınabilir rip-up ile kapatır |
| `report_routing.py` | Routed kartta eksik bağlantı, hat genişliği ve katman dağılımı raporu |