PCB 설계 (KiCad 8/9)
제조 가능하고 구문적으로 유효한 KiCad PCB 파일을 생성하고 .kicad_pcb s-expression 파일로 출력합니다. KiCad가 기본 프레임워크입니다. 파일 형식을 메모리에 의존하지 마십시오 — KiCad 개발자 문서와 함께 제공되는 검증기-클린 에셋을 진실의 원천으로 사용하십시오.
대상 방언: KiCad 9 ((version 20241229)). KiCad 8 (20240108)은 references/pcb-file-format.md#version-dialect-matrix에 나열된 차이점(특히 9에서 다시 변경된 레이어 순서)과 함께 지원됩니다. 방언을 혼합하지 마십시오: v8/v9 헤더 안의 v6/v7 시대 (tstamp ...) 또는 v6 (width ...) 그래픽은 파일 로드 실패의 가장 일반적인 원인입니다.
필수 사항
- 파일당 하나의 방언. 헤더
version,generator_version, 트랙 UUID, 스트로크 구문 및 풋프린트 필드는 모두 선언된 버전과 일치해야 합니다. - 보드는 조각이 아닌 완전한 파일입니다. KiCad에서 열리고 아래 구조적 검사기를 통과해야 합니다.
- 연결성은 기하학적입니다. 올바른 네트 번호가 있지만 패드나 다른 트랙에 닿지 않는 트랙은 여전히 배선되지 않은 것입니다.
- 무언의 전기적 추측 금지. 핀-네트 매핑, 극성, 풋프린트 선택 및 안전 간격은 가정으로 명시되거나 질문을 받아야 합니다.
- 검증된 제조 한계 없이 제조 적합성을 주장하지 마십시오. 제조 수치는 스택업 및 공급업체에 따라 다릅니다.
- 통과 보고서 없이 릴리스 주장 금지.
report/design-report.json이professional_claim: true를 나타낼 때만 보드가 릴리스 준비가 된 것입니다. 그렇지 않으면 실패한 게이트와 누락된 서명을 나열하십시오.
자동 설계 파이프라인 (새 보드에 권장)
이 파이프라인이 가능할 때 릴리스 보드를 수동으로 작성하지 마십시오. 파이프라인은 설계 사양을 실제 KiCad 라이브러리 풋프린트가 있는 보드로 변환하고, Freerouting으로 배선하며, KiCad DRC + DFM + 네트리스트 일치를 실행하고, 거버/드릴/위치/STEP/IPC-D-356을 내보내고 게이트 보고서를 작성합니다. profile.fab_outputs에 나열된 모든 출력은 하드 게이트입니다. 생성된 보드를 검토하거나 패치할 때만 수동 작성을 사용하십시오.
# 1. 의도 검증 (KiCad 불필요)
python3 scripts/design_spec.py validate specs/led-blinky.json
# 2. 완전 자동 설계. KiCad 9 pcbnew, Java 25 및 Freerouting 2.5.0이 있으면 로컬을 자동 선택하고, 그렇지 않으면 GitHub Actions에 위임합니다.
python3 scripts/design_pipeline.py all specs/led-blinky.json
# 전기적 진실의 원천은 회로도 또는 네트리스트입니다. 사양은 기계/규칙을 제공합니다.
python3 scripts/design_pipeline.py all specs/led-blinky.json --schematic design.kicad_sch
python3 scripts/design_pipeline.py all specs/led-blinky.json --netlist design.net
# 기존 보드: 재구축 없이 배선/확인/내보내기.
python3 scripts/design_pipeline.py all specs/led-blinky.json --board existing.kicad_pcb --skip-build
# 단계만 실행
python3 scripts/design_pipeline.py build specs/led-blinky.json -o build/led-blinky
python3 scripts/design_pipeline.py route build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json
python3 scripts/design_pipeline.py check build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json -o build/led-blinky/check
python3 scripts/design_pipeline.py fab build/led-blinky/led-blinky.kicad_pcb --spec specs/led-blinky.json -o build/led-blinky/fab
정식 입력. specs/<name>.json은 자동 경로의 진실의 원천입니다. schemas/design-spec.schema.json 및 specs/led-blinky.json을 모델로 사용하십시오. 자연어 요청의 경우 먼저 사양을 작성하고 assumptions[]에 가정을 명시한 다음 파이프라인을 실행하십시오. KiCad 회로도/네트리스트의 경우 네트리스트가 구성 요소/패드 네트에 대한 권위를 가지며, 사양 오버레이는 보드 크기, 스택업, 규칙, 배치 및 배선을 제공합니다.
보드 클래스 프로필. 프로필은 규칙 범위와 릴리스 게이트를 선택합니다:
| 프로필 | 자동화 | 필수 인간 서명 |
|---|---|---|
2layer-low-speed | 전체: 구축, 배치, 배선, DRC, DFM, fab | 없음 |
4layer-impedance / 6layer-impedance | 게이트됨: 스택업 + 임피던스 + 길이 일치 검사 | stackup, impedance |
rf-mixed-signal | 지원됨; RF 네트는 수동으로 재배선해야 함 | rf, emc, thermal |
flex-rigid | 지원됨 | mechanical, flex_bend, assembly |
high-voltage | 게이트됨; 간격/크리피지 검사 | safety, creepage |
professional_claim은 모든 하드 게이트가 통과 하고 모든 필수 서명이 signoff.completed에 나열된 경우에만 true입니다. RF, EMC, 열, 안전 및 플렉스 피로는 파이프라인이 인증할 수 없습니다. 과도하게 주장하는 대신 그렇게 말하십시오. signoff.reviewer에 검토자를 기록하십시오.
백엔드 선택: 로컬 또는 CI (자동). 전체 자동화에는 pcbnew (KiCad 9 Python), kicad-cli, Java 25 및 freerouting-2.5.0.jar (Freerouting 2.5.0은 Java 25용으로 빌드됨)이 필요합니다. --backend auto가 기본값입니다. 현재 환경을 프로브하고 요청된 모든 단계에 도구가 있으면 로컬에서 실행하고, 그렇지 않으면 .github/workflows/design.yml에 위임합니다. 해당 워크플로우는 공식 kicad/kicad:9.0 컨테이너에서 실행되고, JRE 25를 설치하고, Freerouting을 다운로드하고, 전체 파이프라인을 실행하고, design-output + design-report를 업로드합니다.
| 환경 | 프로브 결과 | 선택된 백엔드 |
|---|---|---|
| KiCad 9 + Java 25 + jar가 있는 실제 PC | 모든 단계 준비 | 로컬 |
KiCad 없는 Termux/컨테이너; gh 인증됨; 깨끗한 푸시된 저장소 | pcbnew/kicad-cli 누락 | CI |
| 로컬 도구 없음 및 사용 가능한 CI 없음 | 누락 | 로컬, 누락된 도구 목록과 함께 실패 |
python3 scripts/env_probe.py # 이 머신이 실행할 수 있는 것은?
python3 scripts/env_probe.py --json # 머신이 읽을 수 있는 프로브
python3 scripts/design_pipeline.py all specs/led-blinky.json # 자동
python3 scripts/design_pipeline.py all specs/led-blinky.json --backend local
python3 scripts/design_pipeline.py all specs/led-blinky.json --backend ci --ci-download build/ci
CI 디스패치는 보수적입니다. 더티 트리나 업스트림보다 앞선 브랜치를 거부합니다. Actions가 푸시된 리비전을 체크아웃하고 그렇지 않으면 잘못된 보드를 설계하기 때문입니다. 먼저 사양, 프로필, 스키마, 스크립트 및 워크플로우를 커밋하고 푸시하십시오. gh가 설치되고 인증되어야 합니다 (pkg install gh, gh auth login). 현재 저장소가 아닌 다른 저장소에 디스패치할 때만 --ci-repo owner/name을 사용하십시오. CI 실행은 기본적으로 감시되어 종료 코드가 professional_claim을 반영합니다. 디스패치 후 즉시 반환하려면 --no-ci-watch를 추가하십시오.
단계 명령(build, route, check, fab)은 CI가 커밋되지 않은 단계 파일을 볼 수 없기 때문에 로컬로 실행됩니다. 엔드 투 엔드 CI 실행에는 all --backend ci를 사용하십시오. GitHub Actions 내부에서 파이프라인은 항상 로컬로 유지되므로 CI 실행이 자신을 다시 디스패치하지 않습니다.
반복 규칙. 게이트가 실패하면 사양(배치, 너비, 간격, 스택업, 클래스 할당)을 변경하고 재생성하십시오. 생성된 보드를 편집한 다음 보고서가 적용된다고 주장하지 마십시오. 보고서는 정확히 해결된 사양(<name>.spec.json)을 기록합니다.
검색 소스 (추측하기 전에 사용)
| 리소스 | URL | 용도 |
|---|---|---|
| S-Expression 소개 (일반 구문) | https://dev-docs.kicad.org/en/file-formats/sexpr-intro/index.html | 구문, 인용, 좌표, 레이어, 풋프린트, 패드, 그래픽, 영역, 그룹 |
| 보드 파일 형식 | https://dev-docs.kicad.org/en/file-formats/sexpr-pcb/index.html | .kicad_pcb 최상위 섹션, 헤더, 레이어, 설정, 네트, 트랙, 영역 |
| 풋프린트 라이브러리 형식 | https://dev-docs.kicad.org/en/file-formats/sexpr-footprint/index.html | .kicad_mod 컨텍스트 및 풋프린트 필드 |
| KiCad 파일 형식 색인 | https://dev-docs.kicad.org/en/file-formats/index.html | 일치하는 회로도가 필요할 때 회로도/심볼 형식 |
| KiCad DRC 문서 | https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html#design-rule-checking | 실제 DRC가 확인하는 사항과 구성 가능한 규칙 |
| KiCad 사용자 정의 설계 규칙 | https://docs.kicad.org/9.0/en/pcbnew/pcbnew.html#custom-design-rules | .kicad_dru 구문 및 규칙 표현식 |
| JLCPCB 기능 | https://jlcpcb.com/capabilities/pcb-capabilities | 현재 제조 한계 (사용 전 확인) |
| IPC-2221 / IPC-2152 | https://www.ipc.org/ | 트레이스 폭/전류, 간격 및 크리피지 기본 사항 |
개발자 문서는 일부 애플리케이션보다 뒤쳐져 있습니다(여전히 v7 이전 (width ...) 그래픽 및 (tstamp ...) 트랙을 설명함). 문서와 대상 KiCad 버전의 실제 파일이 일치하지 않으면 실제 파일을 따르고 불일치를 기록하십시오.
로컬 참조 및 에셋
| 경로 | 내용 |
|---|---|
references/pcb-file-format.md | 버전 매트릭스, 섹션, 레이어 순서, 설정/스택업, 풋프린트, 패드, 트랙, 영역, 체크리스트 |
references/sexpr-primitives.md | 토큰 구문, 인용, 스트로크, 효과, UUID, 패드/그래픽/영역 기본 요소, 버전에 민감한 토큰 |
references/practical-rules.md | 스택업, 배치, 배선, 전류/폭, SI/PI/EMI, 임피던스, 열, 기계, DFM/DFA, 기본값 |
assets/minimal-2layer.kicad_pcb | 검증기-클린 빈 2레이어 보드 (시작점으로 복사) |
assets/example-led.kicad_pcb | 검증기-클린 배선 예제: THT 헤더, SMD 저항/LED, 비아, 코트야드, 장착 구멍 |
assets/example.kicad_dru | 사용자 정의 규칙 예제 (네트클래스 폭, 고전압 간격) |
schemas/design-spec.schema.json | 정식 자동 설계 사양 (보드, 규칙, 네트, 배치, 스택업, 게이트) |
profiles/*.json | 보드 클래스 규칙 범위 및 릴리스 게이트 |
specs/led-blinky.json | 자동 파이프라인용 참조 사양 |
scripts/design_spec.py | 종속성 없는 사양 검증기, 네트리스트 임포터, 임피던스/전류 계산, 게이트 보고서 |
scripts/pcb_build.py | 사양 → 실제 라이브러리 풋프린트를 사용한 KiCad 보드 (pcbnew) |
scripts/pcb_route.py | DSN 내보내기 → Freerouting → SES 가져오기 → 영역 채우기 |
scripts/pcb_check.py | 구조적, DRC, DFM, 네트리스트 일치 및 길이 일치 게이트 |
scripts/pcb_fab.py | 거버, 드릴, 위치, STEP, IPC-D-356 및 제조 README |
scripts/design_pipeline.py | 전체 자동 설계를 조정하고 릴리스 보고서를 작성합니다. --backend auto는 로컬 또는 CI를 선택합니다. |
scripts/env_probe.py | pcbnew, kicad-cli, Java 25, Freerouting, gh/git을 감지하고 로컬 vs CI를 권장합니다. |
scripts/ci_dispatch.py | .github/workflows/design.yml을 디스패치하고, 선택적으로 감시하고 아티팩트를 다운로드합니다. |
scripts/check_pcb.py | 종속성 없는 구조적/기하학적 사전 점검기 |
.github/workflows/design.yml | CI: KiCad 9 컨테이너에서 구축, 배선, DRC/DFM, fab 내보내기 및 보고서 |
전체 문서 페이지를 가져오기 전에 다음 검색어를 이러한 참조에서 사용하십시오: version, generator_version, layers, stackup, setup, net, footprint, property, attr, pad, stroke, segment, via, zone, keepout, filled_polygon, Edge.Cuts, embedded_fonts, remove_unused_layers, courtyard, impedance, differential, 3W, return path, DFM, trace width.
수동 / 검토 워크플로우
먼저 자동 파이프라인을 사용하십시오. 이 워크플로우는 생성된 보드를 검토하거나, 사양이 제약 조건을 표현할 수 없는 설계를 패치하거나, 파이프라인 도구를 사용할 수 없는 환경에서 작업할 때 사용합니다.
-
설계 의도 명확히 하기 (중요한 제약 조건에 대해 무언의 추측 금지).
- 보드 기능, 구성 요소, 커넥터, 전원/접지 네트, 대상 크기 및 기계적 제약 조건.
- 제조 가정: 레이어 수 (기본 2), 단위 (mm), 구리 두께, 스택업, 표면 마감, 조립 공정.
- 대상 KiCad 릴리스. 사용자가 달리 명시하지 않는 한 기본값은 KiCad 9입니다.
- 요구 사항이 불완전하게 지정된 경우, 응답에 가정을 명시적으로 설명하고 파일에 합리적인 기본값을 인코딩하십시오.
-
먼저 전기적 네트리스트 모델링.
- 항목이 참조하기 전에
(net 0 "")과 모든 명명된 네트를 정의하십시오. 순서를 안정적이고 고유하게 유지하십시오. - 모든 패드, 트랙, 비아 및 영역
net순서가 존재하는지 확인하십시오. 패드(net N "NAME")이름이 네트 테이블과 정확히 일치하는지 확인하십시오. - 일치하는 회로도가 있으면 풋프린트에
path/reference 링크가 필요합니다. 보드 전용 설계는 적절한 경우board_only로 표시되어야 합니다.
- 항목이 참조하기 전에
-
기계, 레이어 및 스택업 정의.
assets/minimal-2layer.kicad_pcb에서 시작하고 헤더/레이어/설정을 유효하게 유지하십시오.- 정식 이름과 올바른 순서로
layers섹션을 설정하십시오 (references/pcb-file-format.md의 표 참조,B.CrtYd/F.CrtYd는 순차적이지 않음). (general (thickness 1.6) (legacy_teardrops no)),(paper "A4")및 스택업이 중요하면 현실적인stackup을 설정하십시오.- 닫힌
Edge.Cuts경계(선/호 또는 하나의 rect/원/다각형)를 제공하십시오. 구리를 가장자리에서 멀리 유지하십시오.
-
풋프린트 배치.
- 완전한 임베디드 풋프린트 정의 사용:
layer,uuid,at,property필드 (Reference/Value),attr smd|through_hole, 패드, 실크스크린,F.CrtYd/B.CrtYd코트야드, 선택적으로F.Fab및 3D 모델. - 기능별 배치: 커넥터, 전원 입력 및 MCU를 먼저 배치; 관련 회로 그룹화; 아날로그/디지털/노이즈 도메인 분리.
- 각 IC 전원/접지 핀에 최소 루프 영역으로 디커플링 커패시터 배치; 데이터시트 또는 명시된 가정에 따른 값/패키지.
- 코트야드 및 조립 간격 준수; 참조를 읽을 수 있게 유지하고 극성 부품을 표시하십시오.
- 완전한 임베디드 풋프린트 정의 사용:
-
연결 배선.
segment는 트랙,via는 레이어 변경,arc는 곡선 트랙용. KiCad 8/9 트랙은(uuid ...)를 사용하고(tstamp ...)(v6/7은 여전히tstamp사용)를 사용하지 않습니다.- 전류/스택업 의도에 따라 항목별로
width설정; 신호보다 전원을 더 넓게. 네트 클래스는 프로젝트/설계 규칙 파일에 있으며.kicad_pcb에 없습니다. - 트랙을 짧고 직접적으로 유지하고 45° 굽힘을 선호하며 고속 경로에서 비아를 최소화하십시오.
- 리턴 경로 유지: 평면 분할을 가로질러 고속/민감 트레이스를 배선하지 마십시오. 누화에 취약한 병렬 실행에 ~3W 간격을 적용하십시오.
- 임피던스/차동 쌍은
references/practical-rules.md를 참조하십시오. - 고전압은 IPC-2221 크리피지와 제조 기능을 참조하십시오.
-
영역 및 평면.
- 접지/전원에 고형 구리 포옹 영역 사용, 신호 트레이스에 우선순위; 민감한 영역에서 열 패드/스포크 고려.
(zone (net N) ... (fill yes (arcs ...) (polygon ...) (filled_polygon ...))으로 채우기;priority와hatch를 적절히 설정하십시오.keepout은 제한된 영역에 사용하고 레이어, 명확한(polygon ...)및 정식 제약 조건을 설정하십시오.
-
검증.
- 구조적 무결성 검사: 누락/중복 UUID 확인, 음수/제자리 좌표 없음, 0-면적 영역 없음,
Edge.Cuts닫힘, 텍스트/치수 참조 일관성. - DRC 규칙에
check단계를 사용하십시오; 필요한 규칙 재정의가 있으면.kicad_dru에 추가하십시오. - 실패하면 사양을 변경하고 생성하십시오. 생성된
.kicad_pcb를 수동으로 편집하지 말고 게이트 통과를 주장하십시오.
- 구조적 무결성 검사: 누락/중복 UUID 확인, 음수/제자리 좌표 없음, 0-면적 영역 없음,
-
방언 전환.
sexpr-primitives.md/pcb-file-format.md의 지침에 따라(version ...)헤더를 변경하고 (20240108↔20241229), 모든 레이어 순서를 업데이트하고,stroke/effects/uuid구문을 조정하고, v6/v7 아티팩트를 제거하십시오.
사양 구조
사양은 하나의 JSON 파일입니다:
| 키 | 내용 | 필수 |
|---|---|---|
board.name | 프로젝트 이름 (파일 이름에도 사용됨) | 예 |
board.units | 좌표 단위: "mm" 또는 "mils" | 예 |
board.size_mm | 크기 [x, y] (mm) | 예 (units가 mm인 경우) |
board.size_mils | 크기 [x, y] (mils) | 예 (units가 mils인 경우) |
board.layers | 레이어 수 및 순서, 예: [ "F.Cu", "B.Cu" ] | 예 |
board.static_request | 변경되지 않아야 하는 사용자 제약 조건 문자열 | 아니요 |
board.defaults | 기본값: clearance, track_width, via_dia, via_drill, copper_weight, board_thickness | 아니요, 권장 |
rules | 간격, 트레이스 폭, 네트 클래스 맵, impedance/length_match 요구 사항 | 아니요 |
rules.clearance_mm | 모든 신호-신호 간격의 전역 기본값 | 아니요 |
rules.track_width_mm | 전역 기본 트레이스 폭 | 아니요 |
nets[N] | 명명된 네트: name, class, voltage, current_a, impedance_ohms, max_length_mm, differential | 예 (전역 GND가 있어야 함) |
nets[N].differential | 차동 쌍: pair, impedance_ohms, gap_mm | 아니요 |
placement[N] | 구성 요소: reference, footprint, value, at [x, y, rotation], side, locked, path | 예 |
stackup[N] | 레이어 스택: name, type (core/prepreg), thickness_mm, material, epsilon_r | 아니요 (기본 2-레이어 std) |
profile | 릴리스 게이트의 보드 클래스 (2layer-low-speed, 4layer-impedance, 6layer-impedance, rf-mixed-signal, flex-rigid, high-voltage) | 아니요 (기본 2layer-low-speed) |
assumptions[] | 가정을 기록하는 문자열 배열 | 아니요 (제어되지 않은 추측보다는 정직한 가정 필수) |
schema/design-spec.schema.json은 정식 스키마이며 자동 사양 생성/검증의 진실의 원천입니다.
행동 원칙
- 간격. 제조 기능의 가장자리 간격을 존중하십시오. 가장자리에서 구리/부품까지 >0.5mm (저가 2레이어) / >0.3mm (표준).
- 노출된 구리. 모든 노출된 구리를 적절한 솔더 마스크와 실크스크린으로 덮으십시오. 패드는 열리거나 마스크된 상태로 유지하고 적절한
solder_paste_margin을 설정하십시오. - 열 관리. 열이 있는 부품 주변에 방열판 없이 솔더 마스크를 열지 마십시오. 고전류 트레이스에 열 릴리프 스포크를 사용하십시오.
- 기계적 고정. 코트야드 유지, 석판화에 대한 그리드 참조 유지, 어셈블리 노트 포함.
- 접지. 단일 지점 또는 스타 접지를 사용하십시오. 반환 경로를 분할하지 마십시오. 감지 가능한 영역 주변에 가드 링/트레이스를 추가하십시오.
- 전력 무결성. 전력 평면에 디커플링 커패시터를 충분히 추가하십시오. 궤도 인덕턴스를 최소화하십시오.
- 신호 무결성. 종단, 길이 일치, 임피던스 제어를 적절히 사용하십시오. 고속 트레이스에 45도 굽힘을 선호하고 직각 굽힘을 피하십시오.
- 제조 가능성 (DFM). DFM 마진에 JLCPCB 기능을 참조하십시오. 권장 최소값: 트레이스/간격 0.15mm/0.15mm (표준), 0.1mm/0.1mm (고급).
- 일관성. 첫 번째 파일에서 마지막 파일까지 동일한 KiCad 방언을 고수하십시오. 스택업, 보드 크기 또는 지정되지 않은 가정을 변경하는 경우 명시적으로 기록하십시오.
- 설계 검토 후 검증. 보드가 자동 파이프라인 또는 수동/검토 워크플로우에 의해 생성된 후, 구문 유효성 검사를 실행하고, KiCad에서 열고,
scripts/check_pcb.py로 실행하고, 배선되지 않은 네트에 대한 DRC를 실행하고, 규칙 파일이 있는 경우 네트 일치를 확인하십시오.