Structure of PCB "Element" files -------------------------------- S. Salewski, 23-MAR-2009 This is a short summary of the (ASCII) file format which is used by the free, open source program PCB to store footprint or "land pattern" files -- sometimes called "Elements" in PCB. This text describes only the new file format understood by recent PCB versions -- for the old M4 (oldlib) format consult the references which are given at the end of this document. This documentation uses 0.01 mil (1 mil = 0.001 inch) base units for coordinates and dimensions (older file formats have used 1 mil units). All coordinates are relative to the element mark (reference point), and symbolic (string) flags are used. (In old days PCB used absolute positions and hexadecimal flags.) Latest versions of the PCB program may allow to specify a unit like mm, mil or nm for each coordinate or dimension -- here we are using only default 0.01 mil units. In this new file format a PCB Element has a header, which is enclosed in square brackets and specifies some general parameters, and a body enclosed in parenthesis (round brackets). The body contains the primitives, which build the shape of the footprint: Pins and pads for the electric part, and lines and arcs drawn on the silk layer for visual appearance. Additional data like author or links to documentation can be included in the form of comment lines beginning with a # character or by attributes in the element body. Each PCB element is stored in a single file -- filename should end with .fp to indicate that it is a PCB footprint. PCB elements uses a coordinate system with positive x direction to the right and positive y direction downwards. Angles are measured counterclockwise with 0 degree pointing to the left (negative x direction). An element file may look like this: # author: S. Salewski Element["" "Capacitor" "" "" 0 0 -25590 -14874 0 100 ""] ( Pin[-19685 0 6299 2000 8299 3150 "1" "1" "square"] Pin[19685 0 6299 2000 8299 3150 "2" "2" ""] ElementLine[-24016 -7874 -25590 -6300 1000] Attribute("description" "Rectangular Capacitor") Attribute("use-license" "unlimited") Attribute("dist-license" "GPL") Attribute("documentation" "http://www...") ) The element header holds general top-level information pertinent to the footprint as a whole. Element[SFlags Desc Name Value MX MY TX TY TDir TScale TSFlags] Name Type Values Description --------------------------------------- SFlags String "" Symbolic flags Desc String "" Description Name String "" (File)-Name, reference designator in PCB Value String "" Value, in PCB something like "100nF" MX, MY Integer 0 Mark, initial position on PCB board TX, TY Integer ? Initial position of Desc, Name and Value TDir Integer 0 Text orientation, 0 is horizontal TScale Integer 100 Text size, 100 means 100% of default size (40 mil) TSFlags String "" Text flags Desc, Name and Value are overwritten by gsch2pcb or PCB. These fields may be left empty -- initial value of desc may be a short description, initial value of name may be the (file)-name. Note that parameters are separated by whitespace and strings must be enclosed in double quotes. TDir can be 0 for horizontal text, 1 for 90 degree counterclockwise rotated text, 2 for upside down, and 3 for rotation 90 degree clockwise (=270 degree counterclockwise). Origin of horizontal text (TDir = 0) is upper left corner. It seems that SFlags and TSFlags should always be an empty string "". A Pad macro held inside the body of an element generates a single rectangular shaped copper area serving as a land pattern for a SMT device. Pad[X1 Y1 X2 Y2 Thickness Clearance Mask Name Number SFlags] Name Type Values Description --------------------------------------- Xi, Yi Integer ? Start (i=1) and end (i=2) of line segment Thickness Integer ? Short edge of rectangular pad Clearance Integer ? (Half) separation to surrounding copper Mask Integer ? Thickness of solder mask relief Name String ? (Arbitrary) name of this pad Number String ? Number of the pad, used to attach nets SFlags String ? Symbolic flags You can think of a rectangular copper pad as a line segment drawn with a pen with quadratic shape: You start at (X1,Y1) and move the pen on a straight line to (X2,Y2) always with the center of the pen on this line and with one edge of the pen parallel to this line. (This is true if SFlags contain "square", otherwise a round pen is used, resulting in a pad with the same thickness but round caps. The mask is drawn in the same way, it erases the solder mask giving a relief -- an area which is not covered with the mask. Thickness of mask should be larger than thickness of pad to allow some misalignment of the mask without covering the copper pad. Clearance defines the separation of the pad to any surrounding copper. There is a factor of two involved: separation = clearance/2 Important SFlags for pads: square: pad is rectangular. If not set: Pad is drawn with round pen onsolder: pad is placed on opposite side of the board edge2: second point of pad is closer to the edge of element ??? The edge2 flag was used as a hint to position visible pad numbers -- recent PCB versions are smart enough to choose good positions, so there seems to be no effect of the edge2 flag. Separate multiple SFlags with a comma without any whitespace! A Pin statement defines a single through hole with surrounding metal pad, it is used for soldering through hole parts or to specify mounting holes. Pin[X Y Thickness Clearance Mask Drill Name Number SFlags] Name Type Values Description --------------------------------------- X, Y Integer ? Position (Center) Thickness Integer ? Diameter of copper annulus (pad) Clearance Integer ? (Half) separation to surrounding copper Mask Integer ? Diameter of solder mask relief (opening) Drill Integer ? Diameter of the hole Name String ? (Arbitrary) name of this pin Number String ? Number of the pin, used to attach nets SFlags String ? Symbolic flags Important SFlags for pins: square: pin is square shaped octagon: pin shape is an octagon hole: unplated hole, no copper annulus egde2: pin is closer to a horizontal edge and thus pinout text is vertical ??? The edge2 flag was used as a hint to position visible pad numbers -- recent PCB versions are smart enough to choose good positions, so there seems to be no effect of the edge2 flag. Separate multiple SFlags with a comma without any whitespace! The ElementLine macro draws line segments on the silk screen layer and is used to draw element outlines, marks and other graphics. ElementLine[X1 Y1 X2 Y2 Thickness] Name Type Values Description --------------------------------------- Xi, Yi Integer ? Start (i=1) and end (i=2) of line segment Thickness Integer ? Thickness of line segment The ElementArc is used to draw a circle, oval or arc on the silkscreen layer. ElementArc[X Y Width Height StartAngle DeltaAngle Thickness] Name Type Values Description --------------------------------------- X, Y Integer ? Coordinate of arc's center point Width Integer ? Radius in x (horizontal) direction Height Integer ? Radius in y (vertical) direction StartAngle Integer 0..360 Start angle of arc, 0 is negative x direction DeltaAngle Integer -360..360 Sweep of the arc, negative angles sweep clockwise Thickness Integer ? Line thickness Attributes can be used to include textual information. Attribute(name content) Name Type Values Description --------------------------------------- name String ? "author", "license", "documentation"... content String ? "GPL", "", "http://www..." For more detailed documentation of PCB elements see: http://www.gpleda.org/ http://pcb.sourceforge.net/ http://www.brorson.com/gEDA/land_patterns_20070818.pdf http://geda.seul.org/wiki/geda:pcb_tips