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")
• 字符串："quoted string" 或 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. 单位和坐标

上下文	单位
原理图	mil（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 可能会在保存时添加或删除字段。