kicad-schematic

KiCad 回路図エージェント

ピン位置を推測せず、計算したピン位置を使う Python スクリプトを作成して、ERC エラーのない KiCad 8/9 の回路図を生成します。既存の回路図の ERC エラーを修正し、KiCad 8 から 9 への移行にも対応します。

重要な原則

回路図が壊れる最大の原因は、ピン位置の推測です。 ラベルを IC ピンに接続するときは、シンボル定義のピン位置と座標変換式を使って、正確な座標を必ず計算してください。scripts/kicad_sch_helpers.py のヘルパーライブラリを使えば、自動的に計算できます。

Y 軸の落とし穴（最もよくあるバグ）

シンボルライブラリ（.kicad_sym）は Y 軸が上向き（数学の座標系）です。回路図（.kicad_sch）は Y 軸が下向き（画面の座標系）です。そのため、ライブラリ座標から回路図座標に変換するときは、Y 座標の符号を必ず反転する必要があります。これを忘れると、ラベルがピンから 10～50mm 離れた位置に配置され、大量の pin_not_connected エラーや label_dangling エラーが発生します。

変換式 — ライブラリ上の (px, py) にあるピンを、回転角 R で回路図上の (sx, sy) に配置する場合：

• 回転 0： 回路図上の位置 = (sx + px, sy - py)
• 回転 90： 回路図上の位置 = (sx + py, sy + px)
• 回転 180：回路図上の位置 = (sx - px, sy + py)
• 回転 270：回路図上の位置 = (sx - py, sy - px)

これらを手動で計算せず、必ずヘルパーライブラリの pin_abs() を使ってください。

アーキテクチャ

User describes circuit
        |
Read symbol libraries (.kicad_sym) to get pin positions
        |
Build pin position dictionaries for every multi-pin IC
        |
Write Python script using SchematicBuilder (from helper library)
  - Use connect_pin() for IC pins (computes positions automatically)
  - Use place_2pin_vertical() for passives (knows pin 1/2 positions)
        |
Generate .kicad_sch file
        |
Post-process with fix_subsymbol_names()
        |
Run ERC validation: kicad-cli sch erc --format json
        |
Parse errors -> fix script -> regenerate -> repeat (max 5 iterations)

手順

0. kicad-cli が利用可能であることを確認する

ERC 検証を実行する前に、システムの PATH に kicad-cli があることを確認してください。次を実行します。

which kicad-cli 2>/dev/null || where kicad-cli 2>/dev/null

見つからない場合は、ローカルの KiCad インストールを確認し、シンボリックリンクの作成を提案します。

macOS：

# Check if KiCad is installed as an app
KICAD_CLI="/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli"
if [ -f "$KICAD_CLI" ]; then
    echo "Found kicad-cli inside KiCad.app. Creating symlink..."
    sudo ln -sf "$KICAD_CLI" /usr/local/bin/kicad-cli
    echo "Done! kicad-cli is now available on PATH."
else
    echo "KiCad not found. Install from https://www.kicad.org/download/macos/"
fi

Linux：

# kicad-cli is typically installed alongside KiCad via package manager
# Check common locations
for p in /usr/bin/kicad-cli /usr/local/bin/kicad-cli /snap/kicad/current/bin/kicad-cli; do
    if [ -f "$p" ]; then
        echo "Found kicad-cli at $p"
        # If not on PATH, symlink it
        if ! command -v kicad-cli &>/dev/null; then
            sudo ln -sf "$p" /usr/local/bin/kicad-cli
        fi
        break
    fi
done
# If still not found:
# Ubuntu/Debian: sudo apt install kicad
# Fedora: sudo dnf install kicad
# Arch: sudo pacman -S kicad
# Or install from https://www.kicad.org/download/linux/

Windows：

# Check standard install path
$kicadCli = "C:\Program Files\KiCad\8.0\bin\kicad-cli.exe"
if (Test-Path $kicadCli) {
    Write-Host "Found kicad-cli. Add to PATH:"
    Write-Host '  [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";C:\Program Files\KiCad\8.0\bin", "User")'
} else {
    Write-Host "KiCad not found. Install from https://www.kicad.org/download/windows/"
}

確認できた内容をユーザーに伝え、シンボリックリンクを作成する前に確認を求めてください。kicad-cli が本当にインストールされていない場合は、使用 OS 向けのダウンロードリンクを案内して終了してください。ERC 検証には kicad-cli が必要です。

1. 回路を把握する

コードを書く前に、次の情報を集めてください。

• 部品番号を含む部品リスト
• 電源構成（電圧レール、レギュレーター）
• 信号の接続（どのピン同士を接続するか）
• 必要なシンボルライブラリ（標準 KiCad ライブラリ、およびカスタム .kicad_sym ファイル）

2. シンボルライブラリを読む（必須）

すべての IC と複数ピンを持つ部品について、.kicad_sym の定義を読み、正確なピン名、番号、位置、タイプを確認してください。このデータがなければ、ピンを正しく接続できません。

from kicad_sch_helpers import SymbolLibrary

lib = SymbolLibrary()
lib.load_from_kicad_sym("path/to/library.kicad_sym")

# Now you know exact pin positions
ad9363 = lib.get("AD9363ABCZ")
for pin in ad9363.pins:
    print(f"{pin.name} ({pin.number}): at ({pin.x}, {pin.y}), type={pin.pin_type}")

手動またはインラインで実装する場合は、ライブラリからピン辞書を作成してください。

# Extract from .kicad_sym file — these are LIBRARY coordinates (Y-up)
AD_PINS = {
    'TX1A_P': (-17.78, 25.40),
    'TX1A_N': (-17.78, 22.86),
    'SPI_CLK': (-17.78, -10.16),
    # ... all pins
}

# SOT-23-5 packages (common for LDOs like AP2112K, ME6211):
SOT5_PINS = {
    'VIN':  (-7.62,  2.54),   # Pin 1 - top left
    'GND':  ( 0.00, -7.62),   # Pin 2 - bottom center
    'EN':   (-7.62, -2.54),   # Pin 3 - bottom left
    'NC':   ( 7.62, -2.54),   # Pin 4 - bottom right  <- NOT VOUT!
    'VOUT': ( 7.62,  2.54),   # Pin 5 - top right     <- THIS is VOUT!
}

警告 — SOT-23-5 のピンの落とし穴： VOUT は (7.62, +2.54) に、NC は (7.62, -2.54) にあります。この 2 つのピンの間隔はわずか 5.08mm です。取り違えると、LDO の出力がどこにも接続されません。必ず実際のライブラリファイルで確認してください。

3. ジェネレータースクリプトを作成する

回路図の構築にはすべて SchematicBuilder を使ってください。重要なメソッドは connect_pin() です。ピンの正確な位置を自動的に計算します。

from kicad_sch_helpers import SchematicBuilder, SymbolLibrary, snap

lib = SymbolLibrary()
lib.load_from_kicad_sym("custom_symbols.kicad_sym")

sch = SchematicBuilder(symbol_lib=lib, project_name="my_project")
sch.set_lib_symbols(lib_symbols_content)  # Raw S-expression for embedded symbols

# Place an IC
sch.place("CubeSat_SDR:AD9363ABCZ", "U1", "AD9363ABCZ",
          x=320, y=200, footprint="CubeSat_SDR:AD9363_BGA144")

# Connect pins by NAME — coordinates computed automatically
sch.connect_pin("U1", "TX1A_P", "TX1A_P", wire_dx=-5.08)
sch.connect_pin("U1", "SPI_CLK", "SPI_CLK", wire_dy=-5.08)
sch.connect_pin("U1", "GND", "GND", wire_dy=5.08)

# For unused pins, add no-connect flags
sch.connect_pin_noconnect("U1", "AUXDAC1")

# For 2-pin passives, use convenience helpers
from kicad_sch_helpers import place_2pin_vertical
place_2pin_vertical(sch, "Device:C", "C1", "100nF",
                    x=snap(230), y=snap(155),
                    top_net="VCC_3V3", bottom_net="GND",
                    footprint="Capacitor_SMD:C_0402_1005Metric")

インラインのピン辞書を使う場合（SymbolLibrary を使わない場合）は、pin_abs() を使ってください。

from kicad_sch_helpers import pin_abs, snap

GRID = 1.27

def wl(sch, sx, sy, pin_name, pins_dict, net, dx=0, dy=0, rot=0, label_angle=0):
    """Wire + Label: connect an IC pin to a net label."""
    px, py = pin_abs(sx, sy, pins_dict[pin_name][0], pins_dict[pin_name][1], rot)
    ex, ey = snap(px + dx), snap(py + dy)
    if dx != 0 or dy != 0:
        sch.w(px, py, ex, ey)
    sch.label(net, ex, ey, label_angle)

# Usage:
wl(sch, 320, 200, 'TX1A_P', AD_PINS, "TX1A_P", dx=-7.62)

4. lib_symbols セクションを処理する

参照するすべてのシンボルを、回路図の lib_symbols に埋め込む必要があります。重要なルールは次の 3 つです。

1. 親シンボルには、完全な lib_id を使います。(symbol "Device:R" ...)
2. サブシンボルには、ライブラリのプレフィックスを付けてはいけません。(symbol "R_0_1" ...) とし、(symbol "Device:R_0_1" ...) にはしません。
3. 間違いを検出できるよう、必ず fix_subsymbol_names() で後処理します。

後処理として fix_subsymbol_names() を使ってください。

from kicad_sch_helpers import fix_subsymbol_names

content = sch.build(title="My Schematic")
content = fix_subsymbol_names(content)

正規表現ベースの修正処理は、ネストされたサブシンボルの階層の深さや、ライブラリのプレフィックス形式に関係なく対応します。

5. グリッドにスナップする（警告の 90% を防止）

回路図のすべての座標は、1.27mm の倍数でなければなりません。snap() を使ってください。

from kicad_sch_helpers import snap

# snap() rounds to nearest 1.27mm grid point
x = snap(123.45)  # -> 124.46 (nearest multiple of 1.27)

snap() を部品の位置、配線の端点、ラベルの位置、非接続位置、PWR_FLAG の位置に適用してください。connect_pin() と pin_abs() はこれを自動で行います。

6. PWR_FLAG シンボルを追加する

電圧レギュレーター（電源シンボルではありません）から供給されるすべての電源ネットに PWR_FLAG を追加し、「power_pin_not_driven」エラーを防ぎます。

# Define PWR_FLAG in lib_symbols (see references/kicad_sexpression_format.md)
# Then place on each power net:
sch.place_pwr_flag(x=70, y=78, net_name="VCC_3V3A")

経験則： power_out ではなく、出力ピンのタイプが passive であるコンポーネントによって駆動されるネットには、PWR_FLAG が必要です。これにはほとんどの LDO レギュレーターが含まれます。

専用の GND 電源シンボルで駆動されていない GND ネットにも、PWR_FLAG を配置します。

7. 未接続フラグ

すべての IC の未使用ピンには、必ず未接続フラグを付けてください。未接続フラグがないと、pin_not_connected エラーが発生します。

# Using SchematicBuilder:
sch.connect_pin_noconnect("U1", "AUXDAC1")

# Or manually with pin_abs:
px, py = pin_abs(sx, sy, pin_x, pin_y, rotation)
sch.nc(px, py)

8. kicad-cli で検証する

from kicad_sch_helpers import run_erc

result = run_erc("output/schematic.kicad_sch")
print(f"Errors: {result['errors']}, Warnings: {result['warnings']}")

if result['errors'] > 0:
    for detail in result['details']:
        if detail.get('severity') == 'error':
            print(f"  {detail['type']}: {detail.get('description', '')}")

9. 自動修正ループ

複雑な回路図では、次の検証ループを使用します。

from kicad_sch_helpers import validate_and_fix_loop

def my_fixer(erc_result, iteration):
    """Analyze ERC errors and apply fixes. Return True if fixes applied."""
    error_types = erc_result.get('error_types', {})

    if 'pin_not_connected' in error_types:
        # Read the schematic, find unconnected pins, add connections
        # ... fix logic ...
        return True

    if 'label_dangling' in error_types:
        # Move labels to correct pin positions
        # ... fix logic ...
        return True

    return False  # No fixable errors found

final = validate_and_fix_loop("output/schematic.kicad_sch", my_fixer)

既存の回路図で ERC エラーを修正する

ユーザーが ERC エラーのある既存の .kicad_sch を持っている場合（新しい回路図を生成するのではない場合）は、このワークフローを使用します。

ステップ 1：JSON 出力で ERC を実行する

必ず --format json -o file.json --severity-all を使用してください。kicad-cli の出力を stdout にパイプしてはいけません。JSON は -o で指定されたファイルに書き込まれます。

macOS では、標準ライブラリを見つけられるように kicad-cli に環境変数を設定する必要があります。

KICAD9_SYMBOL_DIR="/Applications/KiCad/KiCad.app/Contents/SharedSupport/symbols" \
KICAD9_FOOTPRINT_DIR="/Applications/KiCad/KiCad.app/Contents/SharedSupport/footprints" \
/Applications/KiCad/KiCad.app/Contents/MacOS/kicad-cli sch erc \
  --format json --severity-all -o /tmp/erc_result.json schematic.kicad_sch

または、ヘルパーを使用します。

from kicad_sch_helpers import run_erc
result = run_erc("schematic.kicad_sch", env_vars={
    "KICAD9_SYMBOL_DIR": "/Applications/KiCad/KiCad.app/Contents/SharedSupport/symbols",
    "KICAD9_FOOTPRINT_DIR": "/Applications/KiCad/KiCad.app/Contents/SharedSupport/footprints",
})

ステップ 2：違反を解析して分類する

import json
with open("/tmp/erc_result.json") as f:
    report = json.load(f)

violations = []
for sheet in report.get("sheets", []):
    violations.extend(sheet.get("violations", []))

# Categorize by severity and type
errors = [v for v in violations if v.get("severity") == "error"]
warnings = [v for v in violations if v.get("severity") == "warning"]
by_type = {}
for v in violations:
    t = v.get("type", "unknown")
    by_type.setdefault(t, []).append(v)

print(f"Errors: {len(errors)}, Warnings: {len(warnings)}")
for t, items in sorted(by_type.items()):
    print(f"  {t}: {len(items)}")

注： JSON 形式では、違反はトップレベルではなく sheets[].violations[] の下にネストされています。

ステップ 3：対象を絞った Python 修正スクリプトを作成する

.kicad_sch ファイルを手動で編集してはいけません。 必ず Python スクリプトを作成してください。S 式の形式は空白と括弧の対応に敏感です。

主なユーティリティ関数（すべて scripts/kicad_sch_helpers.py にあります）：

from kicad_sch_helpers import (
    find_block,                    # Find balanced parenthesized block
    remove_block_with_whitespace,  # Clean removal preserving formatting
    extract_embedded_symbol,       # Extract from lib_symbols section
    convert_embedded_to_library,   # Embedded → standalone library format
    find_by_uuid,                  # Locate element by UUID
    remove_by_uuid,                # Remove element by UUID
    replace_lib_id,                # Bulk lib_id replacement
    replace_footprint,             # Bulk footprint replacement
    fix_annotation_suffixes,       # Add numeric suffixes to bare refs
    create_pwr_flag_block,         # Generate PWR_FLAG s-expression
)

ステップ 4：よくある修正パターン

UUID でシンボルを削除する：

content = remove_by_uuid(content, "uuid-string", "symbol")

すべてのインスタンスで lib_id を置き換える：

content = replace_lib_id(content, "Connector:Conn_01x04", "CubeSat_SDR:Conn_01x04")

power_pin_not_driven を修正するために PWR_FLAG を追加する：

pwr_block = create_pwr_flag_block(
    x=34.29, y=77.47, ref_num=7,
    project_name="my_project",
    root_uuid="5fb33c66-7637-43ae-9eef-34b4f23f6cfb"
)
# Insert before the final closing paren
last_close = content.rstrip().rfind(')')
content = content[:last_close] + '\n' + pwr_block + '\n' + content[last_close:]

.kicad_pro で警告を抑制する：

import json
with open("project.kicad_pro") as f:
    pro = json.load(f)
pro["erc"]["rule_severities"]["lib_symbol_mismatch"] = "ignore"
with open("project.kicad_pro", "w") as f:
    json.dump(pro, f, indent=2)
    f.write('\n')

ステップ 5：反復的な修正・検証ループ

修正を適用するたびに、必ず ERC を実行してください。修正によって新しい問題が明らかになる場合があります。

1. ERC を実行 → 結果を解析 → 分類
2. 優先度の高いエラーから修正する（参考資料のエラー優先度を参照）
3. ERC を再実行 → エラー数が減ったことを確認する
4. エラーが 0 件になるまで繰り返す（妥当な理由があれば警告は抑制できます）

修正スクリプトを実行する前に、回路図をバックアップしてください。 shutil.copy2() を使用します。

---

KiCad 8 から 9 への移行

KiCad 9 で KiCad 8 の回路図を検証する場合、次のカテゴリの問題が発生することを想定してください。

シンボル名の変更（lib_symbol_issues）

KiCad 8 の名前	KiCad 9 の名前	備考
Connector:Conn_01x04	Connector:Conn_01x04_Pin	1 列コネクターはすべて名前が変更されています
Connector:Conn_01x06	Connector:Conn_01x06_Pin	同じパターンです
Connector:Conn_02x20	Connector:Conn_02x20_Pin	2 列コネクターもすべて対象です
Connector:SMA	削除済み	カスタムライブラリまたは Connector:Coaxial を使用します
Connector:TestPoint	Connector:TestPoint（移動）	ピン配置が異なる場合があります
Regulator_Linear:AMS1117	ピンが 4 本（ADJ が追加）	3 ピンの回路図とは一致しません

修正方法： KiCad 8 のシンボルバージョンを含むプロジェクトレベルのカスタムライブラリを作成します。lib_id をカスタムライブラリを指すように変更します。KiCad 9 のバージョンに更新しようとしてはいけません。ピン位置が異なり、配線接続が壊れるためです。

ピン位置の変更（lib_symbol_mismatch）

重要：埋め込み済みの Device:C/R/L シンボルを KiCad 9 のバージョンに置き換えてはいけません。

KiCad 9 では受動部品のピン位置が変更されました。

• KiCad 8：Device:C のピンは (0, ±2.54)
• KiCad 9：Device:C のピンは (0, ±3.81)

埋め込みシンボルを置き換えると、すべてのコンデンサー、抵抗器、インダクターに接続されているすべての配線が壊れます。代わりに、.kicad_pro で lib_symbol_mismatch を抑制してください。埋め込み済みの KiCad 8 シンボルは問題なく動作します。

フットプリント名の変更（footprint_link_issues）

KiCad 8 のフットプリント	KiCad 9 のフットプリント
SW_Push_1P1T_NO_6x3.5mm	SW_Push_1P1T_NO_CK_PTS125Sx43SMTR
SMA_Amphenol_901-143_Vertical	SMA_Amphenol_901-144_Vertical

一括更新には replace_footprint() を使用します。

アノテーション要件

KiCad 9 では、すべてのリファレンスデジグネータを数字で終わらせる必要があります。 C_RX1B_N や J_PWR のようなリファレンスは、GUI で「Item not annotated」エラーの原因になります（ただし、CLI ERC では発生しません）。

from kicad_sch_helpers import fix_annotation_suffixes
content = fix_annotation_suffixes(content)  # Adds "1" suffix to bare refs

移行ワークフロー

1. ERC を実行 → 違反を分類
2. KiCad 8 のシンボルバージョンを使用したカスタムライブラリを作成（埋め込みの lib_symbols から抽出）
3. 標準ライブラリからカスタムライブラリへ lib_ids を更新
4. 名前が変更されたフットプリントを更新
5. アノテーションの接尾辞を修正
6. 新たに発生した power_pin_not_driven エラーに対して PWR_FLAG を追加
7. .kicad_pro で lib_symbol_mismatch を抑制（埋め込みシンボルは引き続き動作するため安全です）
8. 意図的な二重命名がある場合は multiple_net_names を抑制
9. ERC を再度実行 → エラーが 0 件であることを確認

---

カスタムライブラリの管理

KiCad の標準ライブラリがバージョン間で変更された場合は、互換性を維持するためにプロジェクトレベルのライブラリを作成します。

プロジェクトライブラリテーブルの作成

プロジェクトルートの sym-lib-table：

(sym_lib_table
  (version 7)
  (lib (name "CubeSat_SDR")(type "KiCad")(uri "${KIPRJMOD}/libraries/cubesat_sdr.kicad_sym")(options "")(descr "Project custom symbols"))
)

プロジェクトルートの fp-lib-table：

(fp_lib_table
  (version 7)
  (lib (name "CubeSat_SDR")(type "KiCad")(uri "${KIPRJMOD}/libraries/cubesat_sdr.pretty")(options "")(descr "Project custom footprints"))
)

移植性の高いパスには ${KIPRJMOD} を使用します。これはプロジェクトディレクトリに解決されます。

埋め込みシンボルのライブラリへの抽出

標準ライブラリのシンボルからカスタムシンボルへ移行する場合：

from kicad_sch_helpers import extract_embedded_symbol, convert_embedded_to_library

# Read schematic
with open("schematic.kicad_sch") as f:
    sch = f.read()

# Extract a symbol from the embedded lib_symbols section
block = extract_embedded_symbol(sch, "Connector:Conn_01x04")

# Convert from embedded format (prefix:Name) to library format (Name)
lib_block = convert_embedded_to_library(block, "Connector", "Conn_01x04")

# Append to custom library file (before the final closing paren)
with open("libraries/custom.kicad_sym") as f:
    lib = f.read()
close_pos = lib.rstrip().rfind(')')
lib = lib[:close_pos] + '\t' + lib_block + '\n' + lib[close_pos:]
with open("libraries/custom.kicad_sym", "w") as f:
    f.write(lib)

埋め込み形式とライブラリ形式

.kicad_sch の埋め込み lib_symbols では、トップレベルは (symbol "Library:Name" ...) で、サブシンボルには (symbol "Name_0_1" ...) を使用します。

.kicad_sym のライブラリファイルでは、トップレベルは (symbol "Name" ...) で、サブシンボルには (symbol "Name_0_1" ...) を使用します。

違いは、トップレベルの名前からライブラリの接頭辞がなくなることだけです。

---

よくあるパターン

デカップリングコンデンサアレイ

for i, (ref, val) in enumerate(zip(refs, values)):
    place_2pin_vertical(sch, "Device:C", ref, val,
                        x=snap(start_x + i * 8), y=snap(cap_y),
                        top_net=power_net, bottom_net="GND",
                        footprint=f"Capacitor_SMD:{fp}")

2 ピンの受動部品（R、C、L）

KiCad 標準の 2 ピン受動部品シンボルは、次のようになっています。

• ライブラリ上でピン 1 は (0, 2.54) にあります — 縦向きの場合は上
• ライブラリ上でピン 2 は (0, -2.54) にあります — 縦向きの場合は下

回路図上の回転が 0 で、位置が (sx, sy) の場合：

• 回路図上のピン 1 の位置：(sx, sy - 2.54)
• 回路図上のピン 2 の位置：(sx, sy + 2.54)

place_2pin_vertical(sch, "Device:C", "C1", "100nF",
                    x=snap(100), y=snap(150),
                    top_net="VCC_3V3", bottom_net="GND",
                    footprint="Capacitor_SMD:C_0402_1005Metric")

多ピン IC の接続

# Always use connect_pin — never compute positions manually
signal_map = {
    "TX1A_P": "TX1A_P",
    "TX1A_N": "TX1A_N",
    "SPI_CLK": "SPI_CLK",
    # ... all signal pins
}
for pin_name, net_name in signal_map.items():
    sch.connect_pin("U1", pin_name, net_name, wire_dx=-7.62)

# Power pins
for pin_name in ["VDDD1P3", "VDDA1P3", "VDDD1P8"]:
    sch.connect_pin("U1", pin_name, f"VCC_{pin_name}", wire_dy=5.08)

# Unused pins — EVERY unused pin needs this
for pin_name in ["AUXDAC1", "AUXDAC2", "AUXADC", "TEMP_SENS"]:
    sch.connect_pin_noconnect("U1", pin_name)

PWR_FLAG を使用した電源レギュレーター

sch.place("CubeSat_SDR:AP2112K", "U4", "AP2112K-3.3",
          x=snap(100), y=snap(180),
          footprint="Package_TO_SOT_SMD:SOT-23-5")
wl(sch, 100, 180, 'VIN',  SOT5_PINS, "VCC_5V",  dx=-7.62)
wl(sch, 100, 180, 'EN',   SOT5_PINS, "VCC_5V",  dx=-7.62)
wl(sch, 100, 180, 'GND',  SOT5_PINS, "GND",     dy=5.08)
wl(sch, 100, 180, 'VOUT', SOT5_PINS, "VCC_3V3", dx=7.62)
# NC pin — no-connect flag, NOT a label
nc_x, nc_y = pin_abs(100, 180, *SOT5_PINS['NC'])
sch.nc(nc_x, nc_y)
# PWR_FLAG on output net
sch.place_pwr_flag(x=snap(115), y=snap(178), net_name="VCC_3V3")

得られた教訓（実証済み）

実際の119コンポーネントのCubeSat SDR回路図のデバッグから得られた教訓です。

1. ピンの位置を推測しないでください。 1.27mm（グリッド1単位）ずれただけでもERCエラーが発生します。必ず .kicad_sym ファイルを読み込み、計算した位置を使用してください。

2. Y軸の反転は、バグの最大の原因です。 ライブラリのY軸は上向き、回路図のY軸は下向きなので、Yを反転する必要があります。ライブラリ座標 (0, 25.4) にあるピンは、回路図では (sx, sy - 25.4) です。 (sx, sy + 25.4) ではありません。これを間違えると、ラベルがピンから50mm離れた位置に配置されます。

3. SOT-23-5のVOUTとNCの取り違えは、気づかないままLDO回路を壊します。 VOUT=(7.62, 2.54)、NC=(7.62, -2.54)です。違いはYの符号だけです。Y軸を反転すると、回路図ではVOUTがNCより上になります。必ずライブラリと照合してください。

4. サブシンボルの命名を間違えると、KiCadで問題が発生しても通知されません。 (symbol "Device:R_0_1" ...) のように記述すると、KiCadでファイルを開けても、すべてのシンボルが壊れて表示されることがあります。必ず fix_subsymbol_names() を実行してください。

5. PWR_FLAGは想像以上に必要です。 パッシブ型の出力ピンを持つレギュレーターで駆動するネットには、必ずPWR_FLAGが必要です。GNDにも追加してください。PWR_FLAGがないと、そのネット上のすべてのコンポーネントでpower_pin_not_drivenエラーが発生します。

6. グリッドへのスナップで、何百もの警告を防げます。 グリッドから外れたコンポーネントが1つあるだけで、接続されているすべての配線とラベルにグリッド外れの警告が連鎖します。最初からすべてをスナップしてください。

7. すべてのピンを確認してください。 ピンの一覧を順に確認します。各ピンは、配線とラベルで接続するか、電源シンボルに接続するか、no_connectでフラグを付ける必要があります。ピンが1つでも欠けていると、エラーが発生します。

8. 括弧の対応を確認してください。 KiCadのS式では、括弧が完全に対応している必要があります。生成の最後に確認処理を追加してください。

   depth = sum(1 if c == '(' else -1 if c == ')' else 0 for c in content)
   assert depth == 0, f"Parenthesis imbalance: depth={depth}"
   

9. 埋め込み済みのDevice:C/R/LをKiCad 9のバージョンに置き換えないでください。 KiCad 9では、パッシブピンの位置が±2.54から±3.81に変更されています。埋め込みシンボルを置き換えると、すべての配線接続が壊れます。代わりに lib_symbol_mismatch を抑制してください。

10. kicad-cliのJSON出力先はstdoutではなくファイルです。 必ず -o /tmp/result.json を使用してください。pythonにパイプで渡すと、stdinは空になります。JSONは最上位ではなく、sheets[].violations[] の下にネストされています。

11. CLIのERCではアノテーションを確認しません。 GUIでは、数字で終わらないリファレンス（例：C_RX1B_N）に対して「Item not annotated」と警告されますが、CLIのERCでは通知されずに通過します。移行時には必ず fix_annotation_suffixes() を実行してください。

12. macOSのkicad-cliでは環境変数が必要です。 KICAD9_SYMBOL_DIR と KICAD9_FOOTPRINT_DIR がないと、kicad-cliはグローバルライブラリを見つけられず、誤った lib_symbol_issues 警告が発生します。

13. macOSでは grep -P を使わないでください。 PCREモードはサポートされていません。回路図ファイルのパターンマッチングには、すべてPythonの正規表現を使用してください。

14. カスタムシンボルにはプロジェクトレベルのライブラリテーブルを作成してください。 移植可能なパスには ${KIPRJMOD} を使用します。ライブラリに登録するには埋め込みシンボルを抽出してください。一から書き直さないでください。

15. 修正スクリプトを実行する前にバックアップしてください。 括弧の対応が崩れると、回路図を読み込めなくなります。変更を加える前に shutil.copy2() を使用してください。

16. ERCエラーは抑制せず、警告だけを抑制してください。 KiCad 8から9への移行では、lib_symbol_mismatch（警告）の抑制は安全です。pin_not_connected や power_pin_not_driven のような実際のエラーは、決して抑制しないでください。

参照ファイル

• scripts/kicad_sch_helpers.py — Pythonヘルパーライブラリ（必ず使用してください）
• references/kicad_sexpression_format.md — KiCadのS式形式の仕様、座標系、一般的なERCエラーと修正方法

座標系、サブシンボルの命名規則、PWR_FLAGの要件を理解するため、回路図を生成する前に references/kicad_sexpression_format.md を読んでください。

納品前チェックリスト

新しい回路図の生成

1. すべての座標が snap() によって 1.27mm グリッドにスナップされています
2. すべての IC ピンが connect_pin() / wl() で接続されているか、connect_pin_noconnect() / nc() で未接続として指定されています
3. サブシンボル名が fix_subsymbol_names() で修正されています
4. すべての電圧レギュレーター出力ネットおよび GND に PWR_FLAG が設定されています
5. ERC 検証が実行されています（エラー 0 件が目標、警告は許容されます）
6. 括弧の対応が確認されています（ファイル末尾で深さが 0）
7. ピン位置が推測ではなく .kicad_sym ライブラリで確認されています
8. すべての LDO について、SOT-23-5 の VOUT と NC の位置が二重に確認されています

既存の回路図の修正／KiCad 9 への移行

9. すべてのリファレンスデジグネーターの末尾が数字になっています（fix_annotation_suffixes()）
10. 名前が変更されたシンボルや不足しているシンボルは、プロジェクトレベルのカスタムライブラリで処理されています
11. 埋め込みの Device:C/R/L シンボルは置き換えられていません（代わりに lib_symbol_mismatch を抑制しています）
12. 名前が変更されたフットプリントが更新されています（replace_footprint()）
13. 外部電源（バレルジャック、USB VBUS）を含むすべての電源入力ネットに PWR_FLAG が追加されています
14. 修正スクリプトを実行する前に回路図がバックアップされています
15. macOS 上の kicad-cli 用に環境変数が設定されています（KICAD9_SYMBOL_DIR、KICAD9_FOOTPRINT_DIR）
16. すべての警告タイプを検出するため、--severity-all を指定して ERC が実行されています