kicad_pcb (sexpr) format

This page is out of date with changes made for KiCad 6.0 but will eventually be updated
This file format was introduced with the launch of KiCad 4.0

File format syntax:

Based on the Specctra syntax. All tokens are lowercase. Strings such as board text and copper layer names can have upper case characters, but these will often be quoted. A special emphasis to readability considerations is made.

Coordinates of objects and sizes:

Coordinates are relative to the origin of their containing object. Values are given in millimeters. Exponential floating point values are not allowed and instead are presented as: "xxx.yyy" or "0.0x" or "0.x", or even "xy". This was done because values like 4e-2 are not as easy for a human to read.

Keywords:

Use only lowercase ASCII words (and trailing digits if needed). ASCII characters are ⇐ 127.

Identifiers and Strings:

Identifiers are variables used within the file such as layer names, net names, etc.
Strings are longer text sequences such as drawing labels.
They are handled the same, and will be referred to as strings henceforth.
From a purely syntactical perspective (and ignoring any limits imposed at a higher level by the user of the string), a string can contain embedded spaces and tabs, but may not contain an actual newline.
A string is to be encoded in UTF8 format, meaning that it may be ASCII or international characters sequences, since ASCII is a subset of UTF8. Note that this excludes LATIN characters >= 128.
To encode LATIN characters, a UTF8 sequence must be used.
A string may not contain an actual newline or carriage return, but it may use an escape sequence to encode a newline, such as \n.
If a string has any of the following conditions, then it must be quoted with a leading and trailing double quote character, otherwise it is acceptable to not quote the string:

  1. has one or more of the following 4 separator bytes: ASCII space, tab, '(', or ')'.

  2. has one or more of the following bytes: '%', '{', or '}'.

  3. has a length of zero bytes, and you need a place holder for the field, then use "".

  4. includes a byte of '-', and this byte is not in the first position of the string.

Examples:

  • If the field has embedded spaces, tabs, '(' or ')', then it must be quoted like these samples: "this is a sample", "con(14)", "(19".

  • If the field has an embedded #, then is must be quoted: "wire#123"

  • This string does not need to be quoted: -CDC, but this one does: "C-DC"

  • If your string needs to convey multiple lines, escape the new line character like this: "line 1\nline 2".

  • Here is a legal string with an embedded quote: leg"23

  • Here is the same string quoted, and because it is quoted the internal quote must be duplicated: "leg""23"

  • Here is a string quoted that does not need to be but is acceptable anyways: "R1"

Layer representation in files

Layer capacity:

  • Copper layers 16

  • Technical layers 13 ( 8 paired layers, 4 user layers and 1 layer for board edges )

Layer names in files

In files the layers have a name, not a number.

Copper layers: For copper layers the name can be set by the user.
A copper layer name is defined as <layer name set by user>.Cu
However, for pads and vias which are on all copper layers, the full set of copper layers is defined as *.Cu.

Paired technical layers: The name is fixed and built on the form.
B.<layer name> for a layer on the back side of the board.
F.<layer name> for a layer on the front side of the board.
The layer name is one of
Adhes Paste Paste SilkS Mask.
Or the translated name of these layers for non English users.
Like for Copper layers, *.<layer name> can be used to represent the 2 paired layers

Other layers: The name is <layer name>.User like:
Dwgs.User Cmts.User Eco1.User Eco2.User
Or the translated name of these layers for non English users.

Board outlines: the name is Edge.Cuts

Typical structure of the board file:

A board file includes different sections and list of board items:

  • The header line

  • The general section

  • The layers section (the mapping of layers)

  • The setup section

  • The list of nets

  • The list of net classes

  • The list of modules

  • The list of graphic items

  • The list of tracks

  • The list of zones

The order of lists is not critical, and some sections can be omitted. === Description of an item: The basic item syntax is an opening brace “(“ followed by a keyword with one or more parameters associated with the keyword separated by one or more spaces followed by a closing brace “)”. Items can be nested but the opening and closing braces must be symmetrical. An item is described by (<keyword> <parameter>)

Examples:

(via_drill 0.635)
(area 57.924999 28.924999 74.075001 42.075001)

via_drill or area are keywords, followed by one or four values.

(fp_line (start -3.81 0) (end -3.302 0) (layer F.SilkS) (width 0.2032))

fp_line is a keyword, followed by parameters, which are 4 item descriptions.

The header line

(kicad_pcb (version 3) (host pcbnew "(2013-02-20 BZR 3963)-testing")

The general section

(general
  (links 2)
  (no_connects 0)
  (area 57.924999 28.924999 74.075001 42.075001)
  (thickness 1.6)
  (drawings 5)
  (tracks 5)
  (zones 0)
  (modules 2)
  (nets 3)
)
(page A4)

The layers section (the mapping of layers)

(layers
  (15 top_side.Cu signal)
  (2 Inner2.Cu signal)
  (1 Inner1.Cu signal)
  (0 bottom_side.Cu signal)
  (16 B.Adhes user)
  (17 F.Adhes user)
  (18 B.Paste user)
  (19 F.Paste user)
  (20 B.SilkS user)
  (21 F.SilkS user)
  (22 B.Mask user)
  (23 F.Mask user)
  (24 Dwgs.User user)
  (25 Cmts.User user)
  (26 Eco1.User user)
  (27 Eco2.User user)
  (28 Edge.Cuts user)
)

This is an important section, because it defines the active layers, the layer types and attributes, the copper layer names (set by the user) and the numerical identifier used to associate the user defined layer names with the Pcbnew internal layer definition. All subsequent layer references are by name only.

The setup section

(setup
  (last_trace_width 0.254)
  (trace_clearance 0.254)
  (zone_clearance 0.2)
  (zone_45_only no)
  (trace_min 0.254)
  (segment_width 0.2)
  (edge_width 0.15)
  (via_size 0.889)
  (via_drill 0.635)
  (via_min_size 0.889)
  (via_min_drill 0.508)
  (uvia_size 0.508)
  (uvia_drill 0.127)
  (uvias_allowed no)
  (uvia_min_size 0.508)
  (uvia_min_drill 0.127)
  (pcb_text_width 0.3)
  (pcb_text_size 1.5 1.5)
  (mod_edge_width 0.15)
  (mod_text_size 1.5 1.5)
  (mod_text_width 0.15)
  (pad_size 0.0005 0.0005)
  (pad_drill 0)
  (pad_to_mask_clearance 0.2)
  (aux_axis_origin 0 0)
  (visible_elements 7FFFFFFF)
  (pcbplotparams
    (layerselection 3178497)
    (usegerberextensions true)
    (excludeedgelayer true)
    (linewidth 50000)
    (plotframeref false)
    (viasonmask false)
    (mode 1)
    (useauxorigin false)
    (hpglpennumber 1)
    (hpglpenspeed 20)
    (hpglpendiameter 15)
    (hpglpenoverlay 2)
    (psnegative false)
    (psa4output false)
    (plotreference true)
    (plotvalue true)
    (plotothertext true)
    (plotinvisibletext false)
    (padsonsilk false)
    (subtractmaskfromsilk false)
    (outputformat 1)
    (mirror false)
    (drillshape 1)
    (scaleselection 1)
    (outputdirectory ""))
)

This section stores the current settings (default item sizes) and options in use for this board

The list of nets

(net 0 "")
(net 1 /SIGNAL)
(net 2 GND)

This section includes the list of nets read from the schematic netlist. Each net has a net number and a name if in the schematic the net has a label.

The list of net classes

(net_class Default "Ceci est la Netclass par défaut"
  (clearance 0.254)
  (trace_width 0.254)
  (via_dia 0.889)
  (via_drill 0.635)
  (uvia_dia 0.508)
  (uvia_drill 0.127)
  (add_net "")
  (add_net /SIGNAL)
)
(net_class POWER ""
  (clearance 0.254)
  (trace_width 0.5)
  (via_dia 1.2)
  (via_drill 0.635)
  (uvia_dia 0.508)
  (uvia_drill 0.127)
  (add_net GND)
)

This section stores the net classes setup. Each netclass has a set of track and via and size and clearance settings and the name of net or nets assigned to the net class.

The list of modules

(module R3 (layer top_side.Cu) (tedit 4E4C0E65) (tstamp 5127A136)
  (at 66.04 33.3502)
  (descr "Resitance 3 pas")
  (tags R)
  (path /5127A011)
  (autoplace_cost180 10)
  (fp_text reference R1 (at 0 0.127) (layer F.SilkS) hide
    (effects (font (size 1.397 1.27) (thickness 0.2032)))
  )
  (fp_text value 330K (at 0 0.127) (layer F.SilkS)
    (effects (font (size 1.397 1.27) (thickness 0.2032)))
  )
  (fp_line (start -3.81 0) (end -3.302 0) (layer F.SilkS) (width 0.2032))
  (fp_line (start 3.81 0) (end 3.302 0) (layer F.SilkS) (width 0.2032))
  (fp_line (start 3.302 0) (end 3.302 -1.016) (layer F.SilkS) (width 0.2032))
  (fp_line (start 3.302 -1.016) (end -3.302 -1.016) (layer F.SilkS) (width 0.2032))
  (fp_line (start -3.302 -1.016) (end -3.302 1.016) (layer F.SilkS) (width 0.2032))
  (fp_line (start -3.302 1.016) (end 3.302 1.016) (layer F.SilkS) (width 0.2032))
  (fp_line (start 3.302 1.016) (end 3.302 0) (layer F.SilkS) (width 0.2032))
  (fp_line (start -3.302 -0.508) (end -2.794 -1.016) (layer F.SilkS) (width 0.2032))
  (pad 1 thru_hole circle (at -3.81 0) (size 1.397 1.397) (drill 0.812799)
    (layers *.Cu *.Mask F.SilkS)
    (net 1 /SIGNAL)
  )
  (pad 2 thru_hole circle (at 3.81 0) (size 1.397 1.397) (drill 0.812799)
    (layers *.Cu *.Mask F.SilkS)
    (net 2 GND)
  )
  (model discret/resistor.wrl
    (at (xyz 0 0 0))
    (scale (xyz 0.3 0.3 0.3))
    (rotate (xyz 0 0 0))
  )
)

This is the description of all modules (footprints) on the board. === The list of graphic items

(gr_text TEST (at 62 31) (layer top_side.Cu)
  (effects (font (size 1.5 1.5) (thickness 0.3)))
)
(gr_line (start 58 42) (end 58 29) (angle 90) (layer Edge.Cuts) (width 0.15))
(gr_line (start 74 42) (end 58 42) (angle 90) (layer Edge.Cuts) (width 0.15))
(gr_line (start 74 29) (end 74 42) (angle 90) (layer Edge.Cuts) (width 0.15))
(gr_line (start 58 29) (end 74 29) (angle 90) (layer Edge.Cuts) (width 0.15))

This is the list of “graphical” items on the board. Graphical items are text, lines, arcs, circles on copper and non copper layers, excluding tracks and vias. Only text is allowed on copper layers.

The list of tracks

(segment (start 61.0616 36.8808) (end 61.0616 34.5186) (width 0.254) (layer bottom_side.Cu) (net 1))
(segment (start 61.0616 34.5186) (end 62.23 33.3502) (width 0.254) (layer bottom_side.Cu) (net 1) (tstamp 5127A159))
(segment (start 69.85 33.3502) (end 70.993 33.3502) (width 0.5) (layer bottom_side.Cu) (net 2))
(segment (start 71.2216 33.5788) (end 71.2216 36.8808) (width 0.5) (layer bottom_side.Cu) (net 2) (tstamp 5127A156))
(segment (start 70.993 33.3502) (end 71.2216 33.5788) (width 0.5) (layer bottom_side.Cu) (net 2) (tstamp 5127A155))

This is the list of tracks and vias (obviously, only on copper layers) on the board.

The list of zones

  (zone (net 2) (net_name GND) (layer bottom_side.Cu) (tstamp 5127A1B2) (hatch edge 0.508)
    (connect_pads (clearance 0.2))
    (min_thickness 0.1778)
    (fill (arc_segments 16) (thermal_gap 0.254) (thermal_bridge_width 0.4064))
    (polygon
      (pts
        (xy 59 30) (xy 73 30) (xy 73 41) (xy 59 41)
      )
    )
  )
)

Description of a module (footprint)

Here is an example:

  (module R3 (layer top_side.Cu) (tedit 4E4C0E65) (tstamp 5127A136)
    (at 66.04 33.3502)
    (descr "Resitance 3 pas")
    (tags R)
    (path /5127A011)
    (autoplace_cost180 10)
    (fp_text reference R1 (at 0 0.127) (layer F.SilkS) hide
      (effects (font (size 1.397 1.27) (thickness 0.2032)))
    )
    (fp_text value 330K (at 0 0.127) (layer F.SilkS)
      (effects (font (size 1.397 1.27) (thickness 0.2032)))
    )
    (fp_line (start -3.81 0) (end -3.302 0) (layer F.SilkS) (width 0.2032))
    (fp_line (start 3.81 0) (end 3.302 0) (layer F.SilkS) (width 0.2032))
    (fp_line (start 3.302 0) (end 3.302 -1.016) (layer F.SilkS) (width 0.2032))
    (fp_line (start 3.302 -1.016) (end -3.302 -1.016) (layer F.SilkS) (width 0.2032))
    (fp_line (start -3.302 -1.016) (end -3.302 1.016) (layer F.SilkS) (width 0.2032))
    (fp_line (start -3.302 1.016) (end 3.302 1.016) (layer F.SilkS) (width 0.2032))
    (fp_line (start 3.302 1.016) (end 3.302 0) (layer F.SilkS) (width 0.2032))
    (fp_line (start -3.302 -0.508) (end -2.794 -1.016) (layer F.SilkS) (width 0.2032))
    (pad 1 thru_hole circle (at -3.81 0) (size 1.397 1.397) (drill 0.812799)
      (layers *.Cu *.Mask F.SilkS)
      (net 1 /SIGNAL)
    )
    (pad 2 thru_hole circle (at 3.81 0) (size 1.397 1.397) (drill 0.812799)
      (layers *.Cu *.Mask F.SilkS)
      (net 2 GND)
    )
    (model discret/resistor.wrl
      (at (xyz 0 0 0))
      (scale (xyz 0.3 0.3 0.3))
      (rotate (xyz 0 0 0))
    )
  )

A module has:

  • a reference

  • a layer (Front or Back layer)

  • a last edition time stamp (for user info)

  • a time stamp from the schematic

  • a position.

Its description includes:

  • Text (at least reference and value)

  • Graphic outlines

  • Pads (with pad type, pad layers, pad size and position, net)

  • A link to a 3D model, if exists, for the 3D viewer.

Board Example:

(kicad_pcb (version 3) (host pcbnew "(2013-02-20 BZR 3963)-testing")

  (general
    (links 2)
    (no_connects 0)
    (area 57.924999 28.924999 74.075001 42.075001)
    (thickness 1.6)
    (drawings 5)
    (tracks 5)
    (zones 0)
    (modules 2)
    (nets 3)
  )

  (page A4)
  (layers
    (15 top_side.Cu signal)
    (2 Inner2.Cu signal)
    (1 Inner1.Cu signal)
    (0 bottom_side.Cu signal)
    (16 B.Adhes user)
    (17 F.Adhes user)
    (18 B.Paste user)
    (19 F.Paste user)
    (20 B.SilkS user)
    (21 F.SilkS user)
    (22 B.Mask user)
    (23 F.Mask user)
    (24 Dwgs.User user)
    (25 Cmts.User user)
    (26 Eco1.User user)
    (27 Eco2.User user)
    (28 Edge.Cuts user)
  )

  (setup
    (last_trace_width 0.254)
    (trace_clearance 0.254)
    (zone_clearance 0.2)
    (zone_45_only no)
    (trace_min 0.254)
    (segment_width 0.2)
    (edge_width 0.15)
    (via_size 0.889)
    (via_drill 0.635)
    (via_min_size 0.889)
    (via_min_drill 0.508)
    (uvia_size 0.508)
    (uvia_drill 0.127)
    (uvias_allowed no)
    (uvia_min_size 0.508)
    (uvia_min_drill 0.127)
    (pcb_text_width 0.3)
    (pcb_text_size 1.5 1.5)
    (mod_edge_width 0.15)
    (mod_text_size 1.5 1.5)
    (mod_text_width 0.15)
    (pad_size 0.0005 0.0005)
    (pad_drill 0)
    (pad_to_mask_clearance 0.2)
    (aux_axis_origin 0 0)
    (visible_elements 7FFFFFFF)
    (pcbplotparams
      (layerselection 3178497)
      (usegerberextensions true)
      (excludeedgelayer true)
      (linewidth 50000)
      (plotframeref false)
      (viasonmask false)
      (mode 1)
      (useauxorigin false)
      (hpglpennumber 1)
      (hpglpenspeed 20)
      (hpglpendiameter 15)
      (hpglpenoverlay 2)
      (psnegative false)
      (psa4output false)
      (plotreference true)
      (plotvalue true)
      (plotothertext true)
      (plotinvisibletext false)
      (padsonsilk false)
      (subtractmaskfromsilk false)
      (outputformat 1)
      (mirror false)
      (drillshape 1)
      (scaleselection 1)
      (outputdirectory ""))
  )

  (net 0 "")
  (net 1 /SIGNAL)
  (net 2 GND)

  (net_class Default "Ceci est la Netclass par défaut"
    (clearance 0.254)
    (trace_width 0.254)
    (via_dia 0.889)
    (via_drill 0.635)
    (uvia_dia 0.508)
    (uvia_drill 0.127)
    (add_net "")
    (add_net /SIGNAL)
  )

  (net_class POWER ""
    (clearance 0.254)
    (trace_width 0.5)
    (via_dia 1.2)
    (via_drill 0.635)
    (uvia_dia 0.508)
    (uvia_drill 0.127)
    (add_net GND)
  )

  (module R3 (layer top_side.Cu) (tedit 4E4C0E65) (tstamp 5127A136)
    (at 66.04 33.3502)
    (descr "Resitance 3 pas")
    (tags R)
    (path /5127A011)
    (autoplace_cost180 10)
    (fp_text reference R1 (at 0 0.127) (layer F.SilkS) hide
      (effects (font (size 1.397 1.27) (thickness 0.2032)))
    )
    (fp_text value 330K (at 0 0.127) (layer F.SilkS)
      (effects (font (size 1.397 1.27) (thickness 0.2032)))
    )
    (fp_line (start -3.81 0) (end -3.302 0) (layer F.SilkS) (width 0.2032))
    (fp_line (start 3.81 0) (end 3.302 0) (layer F.SilkS) (width 0.2032))
    (fp_line (start 3.302 0) (end 3.302 -1.016) (layer F.SilkS) (width 0.2032))
    (fp_line (start 3.302 -1.016) (end -3.302 -1.016) (layer F.SilkS) (width 0.2032))
    (fp_line (start -3.302 -1.016) (end -3.302 1.016) (layer F.SilkS) (width 0.2032))
    (fp_line (start -3.302 1.016) (end 3.302 1.016) (layer F.SilkS) (width 0.2032))
    (fp_line (start 3.302 1.016) (end 3.302 0) (layer F.SilkS) (width 0.2032))
    (fp_line (start -3.302 -0.508) (end -2.794 -1.016) (layer F.SilkS) (width 0.2032))
    (pad 1 thru_hole circle (at -3.81 0) (size 1.397 1.397) (drill 0.812799)
      (layers *.Cu *.Mask F.SilkS)
      (net 1 /SIGNAL)
    )
    (pad 2 thru_hole circle (at 3.81 0) (size 1.397 1.397) (drill 0.812799)
      (layers *.Cu *.Mask F.SilkS)
      (net 2 GND)
    )
    (model discret/resistor.wrl
      (at (xyz 0 0 0))
      (scale (xyz 0.3 0.3 0.3))
      (rotate (xyz 0 0 0))
    )
  )

  (module CP4 (layer top_side.Cu) (tedit 5127A26C) (tstamp 5127A146)
    (at 66.1416 36.8808)
    (descr "Condensateur polarise")
    (tags CP)
    (path /50FD6D39)
    (fp_text reference C1 (at 0.508 0) (layer F.SilkS)
      (effects (font (size 1.27 1.397) (thickness 0.254)))
    )
    (fp_text value 10uF (at 0.8584 2.1192) (layer F.SilkS) hide
      (effects (font (size 1.27 1.143) (thickness 0.254)))
    )
    (fp_line (start 5.08 0) (end 4.064 0) (layer F.SilkS) (width 0.3048))
    (fp_line (start 4.064 0) (end 4.064 1.016) (layer F.SilkS) (width 0.3048))
    (fp_line (start 4.064 1.016) (end -3.556 1.016) (layer F.SilkS) (width 0.3048))
    (fp_line (start -3.556 1.016) (end -3.556 -1.016) (layer F.SilkS) (width 0.3048))
    (fp_line (start -3.556 -1.016) (end 4.064 -1.016) (layer F.SilkS) (width 0.3048))
    (fp_line (start 4.064 -1.016) (end 4.064 0) (layer F.SilkS) (width 0.3048))
    (fp_line (start -5.08 0) (end -4.064 0) (layer F.SilkS) (width 0.3048))
    (fp_line (start -3.556 0.508) (end -4.064 0.508) (layer F.SilkS) (width 0.3048))
    (fp_line (start -4.064 0.508) (end -4.064 -0.508) (layer F.SilkS) (width 0.3048))
    (fp_line (start -4.064 -0.508) (end -3.556 -0.508) (layer F.SilkS) (width 0.3048))
    (pad 1 thru_hole rect (at -5.08 0) (size 1.397 1.397) (drill 0.812799)
      (layers *.Cu *.Mask F.SilkS)
      (net 1 /SIGNAL)
    )
    (pad 2 thru_hole circle (at 5.08 0) (size 1.397 1.397) (drill 0.812799)
      (layers *.Cu *.Mask F.SilkS)
      (net 2 GND)
    )
    (model discret/c_pol.wrl
      (at (xyz 0 0 0))
      (scale (xyz 0.4 0.4 0.4))
      (rotate (xyz 0 0 0))
    )
  )

  (gr_text TEST (at 62 31) (layer top_side.Cu)
    (effects (font (size 1.5 1.5) (thickness 0.3)))
  )
  (gr_line (start 58 42) (end 58 29) (angle 90) (layer Edge.Cuts) (width 0.15))
  (gr_line (start 74 42) (end 58 42) (angle 90) (layer Edge.Cuts) (width 0.15))
  (gr_line (start 74 29) (end 74 42) (angle 90) (layer Edge.Cuts) (width 0.15))
  (gr_line (start 58 29) (end 74 29) (angle 90) (layer Edge.Cuts) (width 0.15))

  (segment (start 61.0616 36.8808) (end 61.0616 34.5186) (width 0.254) (layer bottom_side.Cu) (net 1))
  (segment (start 61.0616 34.5186) (end 62.23 33.3502) (width 0.254) (layer bottom_side.Cu) (net 1) (tstamp 5127A159))
  (segment (start 69.85 33.3502) (end 70.993 33.3502) (width 0.5) (layer bottom_side.Cu) (net 2))
  (segment (start 71.2216 33.5788) (end 71.2216 36.8808) (width 0.5) (layer bottom_side.Cu) (net 2) (tstamp 5127A156))
  (segment (start 70.993 33.3502) (end 71.2216 33.5788) (width 0.5) (layer bottom_side.Cu) (net 2) (tstamp 5127A155))

  (zone (net 2) (net_name GND) (layer bottom_side.Cu) (tstamp 5127A1B2) (hatch edge 0.508)
    (connect_pads (clearance 0.2))
    (min_thickness 0.1778)
    (fill (arc_segments 16) (thermal_gap 0.254) (thermal_bridge_width 0.4064))
    (polygon
      (pts
        (xy 59 30) (xy 73 30) (xy 73 41) (xy 59 41)
      )
    )
  )
)

Last Modified