Root/README

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

Archive Download this file

Branches:
master



interactive