kicad-file-format

KiCad ファイル形式リファレンス

KiCad 8.x の S 式ファイル形式の完全なリファレンスです。

KiCad はすべてのファイル形式で Lisp スタイルの S 式を使用します。ファイルは人が読み取れるテキスト形式です。

---

1. S 式の基本

構文

(keyword value)
(keyword (nested value))
(keyword
  (child1 value)
  (child2 value)
)

よく使われるパターン

• 座標：(at x y angle) または (xy x y)
• UUID：(uuid "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")
• 文字列："引用符で囲まれた文字列" または unquoted_identifier
• 数値：1.234（常に小数で、ファイル内に単位はありません）
• ブール値：yes / no

---

2. 回路図形式（.kicad_sch）

ファイル構造

(kicad_sch
  (version 20231120)
  (generator "eeschema")
  (generator_version "8.0")
  (uuid "project-uuid")
  (paper "A4")
  
  ; Title block
  (title_block
    (title "Project Title")
    (date "2024-01-01")
    (rev "1.0")
    (company "Company Name")
  )
  
  ; Library symbols (embedded copies)
  (lib_symbols
    (symbol "Device:R" ...)
  )
  
  ; Placed symbols (component instances)
  (symbol ...)
  (symbol ...)
  
  ; Wires and connections
  (wire ...)
  (bus ...)
  (junction ...)
  
  ; Labels and nets
  (label ...)
  (global_label ...)
  (hierarchical_label ...)
  
  ; Hierarchical sheets
  (sheet ...)
  
  ; Text and graphics
  (text ...)
  (polyline ...)
  (rectangle ...)
)

シンボルのインスタンス

(symbol
  (lib_id "Device:R")
  (at 100 50 0)              ; x, y, rotation (0, 90, 180, 270)
  (unit 1)                   ; Multi-unit symbols
  (exclude_from_sim no)
  (in_bom yes)
  (on_board yes)
  (dnp no)                   ; Do Not Populate
  (uuid "symbol-uuid")
  (property "Reference" "R1"
    (at 100 45 0)
    (effects (font (size 1.27 1.27)))
  )
  (property "Value" "10k"
    (at 100 55 0)
    (effects (font (size 1.27 1.27)))
  )
  (property "Footprint" "Resistor_SMD:R_0402_1005Metric"
    (at 100 50 0)
    (effects (font (size 1.27 1.27)) hide)
  )
  (property "LCSC" "C25744"
    (at 100 50 0)
    (effects (font (size 1.27 1.27)) hide)
  )
  (pin "1" (uuid "pin1-uuid"))
  (pin "2" (uuid "pin2-uuid"))
  (instances
    (project "project_name"
      (path "/root-uuid" (reference "R1") (unit 1))
    )
  )
)

配線

(wire
  (pts
    (xy 100 50)
    (xy 120 50)
  )
  (stroke (width 0) (type default))
  (uuid "wire-uuid")
)

ラベル（ローカルネット名）

(label "VCC"
  (at 100 50 0)
  (effects (font (size 1.27 1.27)))
  (uuid "label-uuid")
)

グローバルラベル（シート間のネット）

(global_label "USB_D+"
  (shape input)              ; input, output, bidirectional, tri_state, passive
  (at 150 60 0)
  (effects (font (size 1.27 1.27)))
  (uuid "global-uuid")
  (property "Intersheetrefs" "${INTERSHEET_REFS}"
    (at 150 60 0)
    (effects (font (size 1.27 1.27)) hide)
  )
)

電源シンボル

(symbol
  (lib_id "power:GND")
  (at 100 80 0)
  (unit 1)
  (exclude_from_sim yes)
  (in_bom no)
  (on_board yes)
  (uuid "power-uuid")
  (property "Reference" "#PWR01" ...)
  (property "Value" "GND" ...)
  (pin "1" (uuid "..."))
)

階層シート

(sheet
  (at 50 50)
  (size 30 20)
  (fields_autoplaced yes)
  (stroke (width 0.1524) (type solid))
  (fill (color 255 255 255 0))
  (uuid "sheet-uuid")
  (property "Sheetname" "Power Supply"
    (at 50 49 0)
    (effects (font (size 1.27 1.27)))
  )
  (property "Sheetfile" "power_supply.kicad_sch"
    (at 50 72 0)
    (effects (font (size 1.27 1.27)) hide)
  )
  (pin "VIN" input
    (at 50 55 180)
    (effects (font (size 1.27 1.27)))
    (uuid "sheet-pin-uuid")
  )
)

---

3. PCB 形式（.kicad_pcb）

ファイル構造

(kicad_pcb
  (version 20231014)
  (generator "pcbnew")
  (generator_version "8.0")
  (general
    (thickness 1.6)
    (legacy_teardrops no)
  )
  
  ; Page settings
  (paper "A4")
  (title_block ...)
  
  ; Layer definitions
  (layers
    (0 "F.Cu" signal)
    (31 "B.Cu" signal)
    (32 "B.Adhes" user "B.Adhesive")
    (33 "F.Adhes" user "F.Adhesive")
    (34 "B.Paste" user)
    (35 "F.Paste" user)
    (36 "B.SilkS" user "B.Silkscreen")
    (37 "F.SilkS" user "F.Silkscreen")
    (38 "B.Mask" user)
    (39 "F.Mask" user)
    (40 "Dwgs.User" user "User.Drawings")
    (41 "Cmts.User" user "User.Comments")
    (42 "Eco1.User" user "User.Eco1")
    (43 "Eco2.User" user "User.Eco2")
    (44 "Edge.Cuts" user)
    (45 "Margin" user)
    (46 "B.CrtYd" user "B.Courtyard")
    (47 "F.CrtYd" user "F.Courtyard")
    (48 "B.Fab" user)
    (49 "F.Fab" user)
  )
  
  ; Design rules setup
  (setup ...)
  
  ; Net definitions
  (net 0 "")
  (net 1 "GND")
  (net 2 "VCC")
  
  ; Footprints (component instances)
  (footprint ...)
  
  ; Traces
  (segment ...)
  
  ; Vias
  (via ...)
  
  ; Zones (copper pours)
  (zone ...)
  
  ; Graphics
  (gr_line ...)
  (gr_rect ...)
  (gr_circle ...)
  (gr_text ...)
)

フットプリント

(footprint "Package_SO:SOIC-8_3.9x4.9mm_P1.27mm"
  (layer "F.Cu")
  (uuid "footprint-uuid")
  (at 100 50 0)              ; x, y, rotation
  (descr "SOIC-8 package")
  (property "Reference" "U1"
    (at 0 -3.5 0)
    (layer "F.SilkS")
    (uuid "ref-uuid")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (property "Value" "ESP32-S3"
    (at 0 3.5 0)
    (layer "F.Fab")
    (uuid "val-uuid")
    (effects (font (size 1 1) (thickness 0.15)))
  )
  (property "Footprint" "Package_SO:SOIC-8..."
    (at 0 0 0)
    (layer "F.Fab")
    (hide yes)
    (uuid "fp-uuid")
  )
  
  ; Pads
  (pad "1" smd rect
    (at -1.905 -2.475)
    (size 0.6 1.5)
    (layers "F.Cu" "F.Paste" "F.Mask")
    (net 1 "GND")
    (uuid "pad-uuid")
  )
  (pad "2" thru_hole circle
    (at 0 0)
    (size 1.7 1.7)
    (drill 1.0)
    (layers "*.Cu" "*.Mask")
    (net 2 "VCC")
    (uuid "pad-uuid")
  )
  
  ; Silkscreen graphics
  (fp_line
    (start -2.5 -2.5)
    (end 2.5 -2.5)
    (stroke (width 0.12) (type solid))
    (layer "F.SilkS")
    (uuid "line-uuid")
  )
)

配線（セグメント）

(segment
  (start 100 50)
  (end 120 50)
  (width 0.25)
  (layer "F.Cu")
  (net 1)
  (uuid "segment-uuid")
)

円弧状の配線

(arc
  (start 100 50)
  (mid 105 45)
  (end 110 50)
  (width 0.25)
  (layer "F.Cu")
  (net 1)
  (uuid "arc-uuid")
)

ビア

(via
  (at 110 60)
  (size 0.8)
  (drill 0.4)
  (layers "F.Cu" "B.Cu")
  (net 1)
  (uuid "via-uuid")
)

ゾーン（銅箔ベタ）

(zone
  (net 1)
  (net_name "GND")
  (layer "F.Cu")
  (uuid "zone-uuid")
  (hatch edge 0.5)
  (connect_pads
    (clearance 0.25)
  )
  (min_thickness 0.25)
  (filled_areas_thickness no)
  (fill yes
    (thermal_gap 0.5)
    (thermal_bridge_width 0.5)
  )
  (polygon
    (pts
      (xy 0 0)
      (xy 100 0)
      (xy 100 100)
      (xy 0 100)
    )
  )
  (filled_polygon
    (layer "F.Cu")
    (pts ...)
  )
)

基板外形

(gr_rect
  (start 0 0)
  (end 100 100)
  (stroke (width 0.1) (type default))
  (fill none)
  (layer "Edge.Cuts")
  (uuid "outline-uuid")
)

---

4. よく使われる操作

回路図へのコンポーネントの追加

1. まだ存在しない場合は、(lib_symbols ...) にシンボルを追加します
2. 次の項目を含む (symbol ...) ブロックを追加します：
   • 一意の UUID
   • 位置 (at x y rotation)
   • リファレンスプロパティ
   • 値プロパティ
   • フットプリントプロパティ
   • ピンのマッピング

PCB への配線の追加

1. 接続に使うネット番号を確認します
2. 次の項目を含む (segment ...) ブロックを追加します：
   • 始点と終点の座標
   • 幅
   • レイヤー
   • ネット番号
   • 一意の UUID

ネットの作成

1. PCB ファイルに (net N "NetName") を追加します
2. パッドとセグメントでネット番号を参照します

---

5. 単位と座標

コンテキスト	単位
回路図	ミル（1/1000 インチ）。ファイル内では mm として保存されます
PCB	ミリメートル
角度	度（一般的には 0、90、180、270）

座標は原点 (0,0) からの絶対値です。

---

6. UUID の生成

すべての要素に一意の UUID が必要です。形式：xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

uuidgen コマンドまたはプログラミング言語の UUID ライブラリで生成します。

---

7. 解析のヒント

S 式の読み取り

# Simple recursive descent parser concept
def parse_sexpr(text):
    tokens = tokenize(text)
    return parse_list(tokens)

def parse_list(tokens):
    result = []
    while tokens and tokens[0] != ')':
        if tokens[0] == '(':
            tokens.pop(0)
            result.append(parse_list(tokens))
        else:
            result.append(tokens.pop(0))
    if tokens:
        tokens.pop(0)  # Remove closing ')'
    return result

S 式の書き込み

• インデントを統一します（2 スペース）
• 編集時は既存の UUID を保持します
• KiCad が想定する要素の順序を維持します
• スペースを含む文字列には適切な引用符を使用します

---

8. ファイルの検証

編集後：

1. KiCad で開いて解析結果を確認します
2. kicad-cli で ERC/DRC を実行します
3. 不明なトークンに関する警告がないか確認します

---

重要： プログラムで編集する前に、必ずファイルをバックアップしてください。KiCad は保存時にフィールドを追加または削除することがあります。