Root/README

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

Archive Download this file

Branches:
master



interactive