Root/README

1fped - Footprint editor
2=======================
3
4fped is an editor that allows the interactive creation of footprints of
5electronic components. Footprint definitions are stored in a text format
6that resembles a programming language.
7
8The language is constrained such that anything that can be expressed in
9the textual definition also has a straightforward equivalent operation
10that can be performed through the GUI.
11
12This README describes only the footprint definition language. A
13description of the GUI can be found here:
14
15http://downloads.qi-hardware.com/people/werner/fped/gui.html
16
17This work is distributed under the terms of the GNU GENERAL PUBLIC
18LICENSE, Version 2:
19
20  This program is free software; you can redistribute it and/or modify
21  it under the terms of the GNU General Public License as published by
22  the Free Software Foundation; either version 2 of the License, or
23  (at your option) any later version.
24
25For your convenience, a copy of the complete license has been included
26in the file COPYING.GPLv2.
27
28
29Building
30--------
31
32Prerequisites:
33
34- bash
35- flex
36- bison
37- fig2dev (transfig)
38- ImageMagick
39- Netpbm
40- Gtk+ 2.x development package (libgtk2.0-dev or similar)
41- Liberation Fonts (ttf-liberation or similar)
42
43Check out the repository:
44
45  git clone git://projects.qi-hardware.com/fped.git
46  cd fped
47
48Get updates:
49
50  git pull
51
52Compile:
53
54  make
55
56Run an example:
57
58  ./fped examples/qfn.fpd
59
60
61Motivation
62----------
63
64KiCad already includes a footprint ("module") editor, so why do we need
65a new one ? The issue with footprint generation for KiCad is that the
66built-in module editor is basically a drawing program that only captures
67the result of the module author's interpretation of a footprint drawing,
68but does not include the steps that led to this construction.
69
70Furthermore, accurate measuring of dimensions in the drawing can only be
71done manually in the module editor, which makes review difficult and
72time-consuming.
73
74In fped, the construction process is made explicit and each step can be
75expressed in terms of the parameters that appear in the vendor's
76drawing. Dimensions can be explicitly measured and the results can be
77included in the graphical output generated by fped.
78
79Directly using parameters and construction steps from the reference
80drawing reduces the risk of mistakes. Visualizing the construction
81process and verificative measurements helps efficient and accurate
82review.
83
84
85Footprint definition file format
86--------------------------------
87
88Footprint definitions are stored in text files. The program "fped" reads
89and (soon) writes such files, visualizes their content, and provides a
90graphical editor for them.
91
92The syntax is unique and draws from elements of a variety of languages
93commonly found on unix systems. One specialty is that there are no
94reserved words - the language keywords appear only at the beginning of
95a line and can thus be recognized as such without restricting their use
96for identifiers. This reduces the risk of creating incompatibilities
97with existing designs when introduction future language features.
98
99fped uses the C preprocessor for comments, conditional compilation,
100and - to a limited extent - also macros. Long lines can be split by
101ending them with a backslash. If multiple items need to be placed in a
102single line, e.g., in a macro, they can be separated with semicolons.
103
104The file has the following structure:
105
106frame definitions
107...
108package name
109setup
110objects
111...
112
113
114Geometry model
115--------------
116
117The geometry model consists of frames, vectors, and objects. The shape of
118objects is defined by a number of points. These points are produced by
119concatenating vectors.
120
121E.g., to draw a line from (1mm, 1mm) to (2mm, 2mm), one would make a
122vector from the origin to (1mm, 1mm) and one either from the origin or
123from the previous vector to (2mm, 2mm), and then make a line connecting
124the two points.
125
126
127Setup
128- - -
129
130The setup section defines settings that affect the entire footprint.
131It is optional and can contain a "unit" directive and an "allow"
132directive.
133
134
135Units
136- - -
137
138fped can calculate in mm and mil. Units are specified by following a
139number with "mm", "um", or "mil", separated by zero or more spaces or
140tabs.
141
142Examples:
143
1441mm
1452 mil
146
147Units can be mixed in calculations, e.g.,
148
149set a = 1mm+20mil
150set b = 10*1mm
151
152All values used as dimensions must be either mm or mil.
153
154The default unit can be set with one of the following directives:
155
156unit mm
157unit mil
158unit auto
159
160If the "unit" directive is omitted, fped defaults to millimeters.
161
162When saving a footprint definition, the default unit is set to the
163unit set in the GUI.
164
165
166Allow
167- - -
168
169fped normally disallows overlapping pads. This restriction can be
170relaxed with the "allow" directive.
171
172allow touch
173
174Allows pads touching but not having more than their border in common.
175
176allow overlap
177
178Do not check for overlaps at all.
179
180If the "allow" directive is omitted, fped defaults to allowing
181neither overlap nor touch.
182
183There is also the following experimental directive that can be used
184alone or without one of the overlap-checking directives:
185
186allow holes
187
188Allow multiple holes per pad.
189
190
191Vectors
192- - - -
193
194Vectors can be anonymous or they can be named for future reference:
195
196vec <base> ( <x-expr>, <y-expr> )
197<identifier>: vec <base> ( <x-expr>, <y-expr> )
198
199The base can be one of the following items:
200
201- @ is the origin of the frame containing the vector
202- . is the end of the previous vector in this frame
203- <identifier> is the name of a previous vector in the same frame
204
205The following example would draw the line described in the previous
206section:
207
208a: vec @(1mm, 1mm)
209b: vec .(1mm, 1mm)
210line a b
211
212
213Silk screen objects
214- - - - - - - - - -
215
216The output of fped is a footprint definition that contains pads and silk
217screen drawings (we may add more layers in the future). These items are
218called "objects". Their geometry is defined through points obtained with
219vectors.
220
221A line connects two points:
222
223line <point-a> <point-b> [<width>]
224
225The points can be specified with @, ., and an identifier, just like
226a vector base. The option width specifies the thickness of the silk
227screen line. If omitted, a hard-coded default of 15 mil is used.
228
229A rectangle has sides parallel to the x and y axis and is defined
230by two diagonally opposite corners:
231
232rect <point-a> <point-b> [<width>]
233
234A circle is defined by its center and a point on the circle:
235
236circ <center> <point> [<width>]
237
238This example draws a unit circle:
239
240vec @(1mm, 0mm)
241circ @ .
242
243An arc is like a circle, but the part of the circle drawn is determined
244by two points. The first point determines the radius and the starting
245angle. The second point only determines the end angle but its distance
246from the center is ignored.
247
248arc <center> <radius> <end> [<width>]
249
250The arc is drawn in a counter-clockwise direction. The following example
251draws an arc of the unit circle in the x > 0, y > 0 quadrant:
252
253from: vec @(1mm, 0mm)
254to: vec @(0mm, 1mm)
255arc @ from to
256
257
258Pads
259- -
260
261Pads are similar to rectangles, but they also have a name.
262
263pad "<name>" <point-a> <point-b> [<type>]
264
265Variables can be expanded in a pad's name by prefixing their name with
266a dollar sign. The ${name} syntax is also available.
267
268Example:
269
270vec @(1mm, 1mm)
271pad "1" @ .
272
273Pads normally affect the surface copper layer, the solder mask layer,
274and the solder paste layer. This can be modified with the optional
275type argument:
276
277Type Layers
278--------- -------------------------------------
279(default) copper, solder mask, and solder paste
280bare copper and solder mask
281trace copper without solder mask opening
282paste solder paste
283mask solder mask
284
285Typical uses:
286- "bare": connectors printed directly on the PCB
287- "trace": connections or antennas
288- "paste": sparse solder paste, e.g., for QFN center pads
289- "mask": non-standard mask openings, e.g., for solder mask defined
290  pads
291
292
293Rounded pads
294- - - - - -
295
296Rounded pads are like rectangular pads except that they end with a
297semi-circle at each of the smaller sides of the enclosing rectangle.
298If enclosed in a square, rounded pads form a circle.
299
300rpad "<name>" <point-a> <point-b> [<type>]
301
302
303Holes
304- - -
305
306Holes can be used for through-hole pins or for mechanical support.
307In the former case, the hole must be placed inside a pad. Only one
308hole per pad is allowed. Mechanical holes must be outside any pads.
309
310Through-hole pads are always present on both sides of the board, i.e.,
311when fped generates a KiCad module, the surface layers of a pad
312containing a hole are propagated to the opposite side of the board.
313
314Holes have the same shape as a rounded pad and their geometry is
315defined in the same way:
316
317hole <point-a> <point-b>
318
319
320Measurements
321- - - - - -
322
323*** This is obsolete - see the section on new-style mesurements at the end. ***
324
325Measurements show the distance between two points:
326
327meas <point-a> <point-b> <offset>
328
329The offset is the distance from the imaginary line connecting points A
330and B the measurement line is draw:
331
332- if the offset is 0mm, the line will connect A and B
333- if the offset is positive, the line would be on the left-hand side when
334  traveling from A to B
335- if the offset is negative , the line would be on the right-hand side when
336  traveling from A to B
337
338Example:
339
340a: vec @(-1mm, 1mm)
341b: vec @(1mm, 1mm)
342meas a b 0.2 mm
343
344
345Package name
346- - - - - -
347
348The package name is a non-empty string of printable ASCII characters,
349including spaces. If the "package" directive is omitted, fped defaults
350to using the name "_".
351
352package "<name>"
353
354Examples:
355
356package "48-SSOP"
357package "0603"
358
359Like in pad names, variables are expanded in package names. This allows
360the generation of multiple packages from a single definition.
361
362
363Frames
364- - -
365
366Frames are used to group things and to reuse them multiple times. Frames
367must be defined before they can be used:
368
369frame <name> {
370    ... items ...
371}
372
373Once defined, a frame is placed at a given location with
374
375frame <name> <point>
376
377The frame definitions must precede all other items in a footprint
378description. Frames cannot be defined inside other frames, but frames
379can invoke each other recursively.
380
381For example, this puts two unity squares, one centered at (0 mm, 0 mm),
382the other at (2 mm, 0 mm):
383
384frame unit_square {
385    a: vec @(-0.5mm, -0.5mm)
386    b: vec .(1mm, 1mm)
387    rect a b
388}
389
390frame unit_square @
391vec @(2mm, 0mm)
392frame unit_square .
393
394
395Names and variables
396-------------------
397
398fped uses several name spaces:
399
400- frame names occupy one global name space
401
402- vector names occupy name spaces delimited by the frame they're
403  contained in. A vector name is only visible inside the frame in which
404  it is defined.
405  
406- variable names occupy name spaces delimited by the frame they're
407  contained in. A variable lookup starts in the frame in which the
408  corresponding expression appears and propagates to outer frames
409  until the variable is found.
410
411- pads occupy one global name space (this is currently not enforced)
412
413Note that names cannot be redefined. E.g., this does not work:
414
415set a = 1
416set a = a+1
417
418The names spaces of frames, vectors, variables, and pads are separate
419from each other.
420
421
422Simple variables
423- - - - - - - -
424
425A variable with a single value is defined with the following
426assignment syntax:
427
428set <identifier> = <expression>
429
430Example:
431
432set a = b+2
433
434
435Loops
436- - -
437
438A loop is a variable with a range of values:
439
440loop <identifier> = <from>, <to>
441
442The variable assumes all the values i for <from> <= i <= <to>, in
443increments of one. E.g.,
444
445loop n = 1, 3
446
447and
448
449loop n = 1, 3.5
450
451both assign the values 1, 2, and 3 to the variable "n". The
452following loop would not execute at all:
453
454loop n = 1, 0
455
456This can be used to implement conditional execution. For example,
457the items in the following frame would be instantiated if the
458variable "enable" is set to 1 but not it is set to 0:
459
460frame ... {
461    loop dummy = 1, enable
462    ...
463}
464
465When a loop is executed, the objects contained in the body of the
466enclosing frame are generated for each value of the variable. If
467a frame contains multiple loops, all possible combinations of the
468values are generated.
469
470The following example draws three concentric circles around the
471origin, with radii 1, 2, and 3:
472
473loop x = 1, 3
474vec @(x*1mm, 0mm)
475circ @ .
476
477
478Tables
479- - -
480
481Tables combine values for multiple variables. Like loops, they are
482used to iteratively generate objects. A table begins with a row of
483variable names, followed by one or more rows with values. Rows are
484enclosed in curly braces and their elements are separated by commas.
485
486table
487    { <identifier>, ... }
488    { <expression>, ... }
489    ...
490
491Like loops, tables are iterated to generate objects. The following
492example is equivalent to the one in the previous section:
493
494table
495    { x }
496    { 1mm }
497    { 2mm }
498    { 3mm }
499vec @(x, 0mm)
500circ @ .
501
502Note that we can set the unit of the values directly in this case.
503
504Iteration is performed over rows. All variables of the table are set
505to the value in the respective row at the same time. For example, in
506
507table
508    { x, y }
509    { 1, 2 }
510    { 3, 4 }
511
512(x, y) assume the values (1, 2) and (3, 4).
513
514Tables can also be used to provide information that depends on
515other variables. The value of such a variable acts as a key, and a
516row is only selected if all the keys in that row match the
517respective variables. To mark a variable as being used as key, its
518name it prefixed with a question mark.
519
520Example:
521
522loop n = 1, 2, 3
523table
524    { ?n, name }
525    { 1, "one" }
526    { 2, "two" }
527    { 3, "three" }
528
529
530Expressions
531-----------
532
533Expressions can contain numeric constants (in non-exponential notation),
534variable names, the arithmetic operations +, -, *, /, unary -, and the
535functions sin(), cos(), sqrt(), and floor().
536
537Parentheses can be used to change precedence.
538
539The argument of sin and cos is a dimensionless number that specifies the
540angle in degrees. E.g., sin(90) yields 1.
541
542The argument of sqrt() can be dimensionless or have a dimension with an
543exponent that's a multiple of two. E.g., sqrt(2) and sqrt(2mm*3mm) are
544valid expressions, sqrt(2mm) isn't.
545
546The function floor() returns the next integer that is below or equal to
547the argument. If the argument has a dimension, that dimension is
548preserved. E.g., floor(-1.2) returns -2, floor(4.7mm) returns 4mm.
549
550
551GUI
552---
553
554Part of the GUI is described in
555http://downloads.qi-hardware.com/people/werner/fped/gui.html
556
557
558Keyboard shortcuts
559- - - - - - - - -
560
561Space reset user coordinates
562+, = zoom in (like mouse wheel forward)
563- zoom out (like mouse wheel backward)
564. cursor position to screen center (like middle click)
565* zoom and center to extents
566# zoom and center to currently active frame instance
567U undelete the previously deleted object
568/ Switch between variables, code, and packages display.
569
570
571Canvas
572- - -
573
574To create a new object, click on the corresponding tool icon, move the
575mouse to the base point of the new object, then drag to the object's
576second point.
577
578Frame references are created as follows:
579
580- select the frame you want to add
581- click on the frame icon. A black dot should appear on the icon.
582- select the frame on which you want to add the new reference.
583  The black dot should change to a green dot. If the current frame
584  is a child of the selected frame, the dot remains black.
585- click on the desired base location
586
587To change a point of an object, select the object, then drag the point
588to its new location. To edit the object's parameters, select it and
589make the changes in the input area at the bottom.
590
591To delete an object, select the delete tool and click on the object.
592Deleted objects can be undeleted by pressing "u". If any other changes
593have been made since deletion, fped may misbehave. If deleting a vector,
594all items that reference it are deleted as well.
595
596
597Experimental: new-style measurements
598------------------------------------
599
600New-style measurements can measure the distance between various pairs
601of points, not only between points in the same instance and the same
602frame. They operate on the set of points produced during instantiation.
603
604New-style measurements are placed in the root frame after all other
605items.
606
607Known issues:
608- they currently can't be edited through the GUI
609- tie-breaking heuristics don't always do what one expects
610
611Syntax:
612
613<type> [<label>] <from> <op> <to> [<offset>]
614
615Types:
616- meas: measure diagonally
617- measx: measure along the X axis
618- measy: measure along the y axis
619
620Note that the type also affects the selection of the points. E.g.,
621measx will select maximum x values.
622
623Operators:
624- A -> B: smallest value of A and smallest B greater than A
625- A <- B: like A -> B, but normal (for offset and text) is inverted
626- A >> B: smallest value of A and greatest value of B
627- A << B: like A -> B, but normal (for offset and text) is inverted
628
629Operands are qualified vector names. Vectors in the root frame are
630referenced by their name. Vectors in other frames are prefixed with
631the name of the frame followed by a dot.
632
633Example:
634
635measx pad.sw -> pad.se 1mm
636
637The optional label is printed directly before the distance. Example:
638
639a: vec @(0mm, 0mm)
640b: vec @(1mm, 0mm)
641measx "width = " a >> b 0mm
642
643would print "width = 1mm"
644
645
646Additional qualifiers
647- - - - - - - - - - -
648
649When using frames as reusable building blocks, similar to functions or
650macros in many programming languages, one may need finer control over
651the points that are selected for measurements.
652
653For example, let us consider a frame "square" that draws a square
654centered at the frame's origin and with a side length given by the
655variable "size". This variable be set in the frame referencing
656"square".
657
658    frame square {
659    a: vec @(-size/2, -size/2)
660    b: vec @(size/2, size/2)
661    rect a b
662    }
663
664    frame small {
665    set size = 2mm
666    frame square @
667    }
668
669    frame big {
670    set size = 5mm
671    frame square @
672    }
673
674    frame small @
675    vec @(5mm, 0mm)
676    frame big .
677
678If we want to measure the size of each square, we could use
679
680measx square.a -> square.b
681
682Unfortunately, this only measures the small square. To reach the
683big frame, we need to tell fped to use only those points in "square"
684that have been placed when "square" was invoked from the big frame.
685
686This is accomplished by prefixing the points in question with the
687name(s) of the frames that need to be visited. The frame names are
688separated by slashes (/).
689
690measx big/square.a -> square.b
691
692For clarity, it's better to qualify both points, e.g.,
693
694measx big/square.a -> big/square.b
695
696If multiple frame names are given, they must be in the order in
697which they are invoked.
698
699
700Experimental: debugging directives
701----------------------------------
702
703For debugging and regression tests, fped supports the following commands,
704most of which mimick the effect of GUI operations:
705
706%del <qualified-identifier>
707%move <identifier> [<number>] <identifier>
708%frame <identifier> <qualified-base>
709%print <expression>
710%iprint <expression>
711%meas <identifier>
712%dump
713%exit
714%tsort { -<id> | +<id> | <id-before> <id-after> [<number>] ... }
715
716%del removes the specified item. This can be a vector, an object, or
717a frame. If the vector or object is in a different frame than the
718current, its name is qualified with the frame name, e.g., "foo.obj".
719
720For this purpose, also objects can be labeled. Object labels behave like
721vector labels and share the same name space. They are not normally
722accessible in the GUI. (You can see them in the code view.)
723
724%move take as its first argument the name of the vector or object to
725manipulate. %move sets an anchor point to the vector named as its last
726argument. The anchor point is identified by index as follows:
727
728anchor index vec/frame line/rect/pad arc measurement
729-------------- --------- ------------- ------------ -----------
7300 (or omitted) base first point center low point
7311 - second point end of arc high point
7322 - - start of arc -
733
734%frame creates a frame reference. Unlike "frame", the destination frame
735can be different from the current frame. E.g., "%frame foo bar.a" would
736add a reference to frame "foo" in frame "bar", rooted at vector "a". The
737parent frame's origin can be references as "@".
738
739%dump writes the footprint definition in the fped language to standard
740output. %exit immediately exits fped, without invoking the GUI.
741
742%print and %iprint evaluate the expression and print the result to
743standard output. The difference between them is that %print runs only
744once and without explicit instantiation, while %iprint is treated as
745a regular object and is executed as many times as instantiation
746demands.
747
748For example, after loop x = 1, 3 we would obtain just 1 with %print
749while %iprint would display, 1, 2, and 3.
750
751%meas performs an instantiation and prints the value of the labeled
752measurement.
753
754%tsort is used to test-drive the topological sort algorithm. The items
755in the curly braces are declarations of nodes with (-<id>) or without
756(+<id>) decay or edges in the partial order. The optional number is
757the edge's priority. See tsort.c for details, test/tsort for examples.
758

Archive Download this file

Branches:
master



interactive