Root/README

Source at commit 190bcaf982869388b508a0a4c97cff62fbb73038 created 9 years 6 months ago.
By werner, Added a topological sort algorithm, for use when dumping.
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://people.openmoko.org/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  svn co http://svn.openmoko.org/trunk/eda/fped
46  cd fped
47
48Get updates:
49
50  svn update
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
109unit
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
127Units
128- - -
129
130fped can calculate in mm and mil. Units are specified by following a
131number with "mm" or "mil", separated by zero or more spaces or tabs.
132
133Examples:
134
1351mm
1362 mil
137
138Units can be mixed in calculations, e.g.,
139
140set a = 1mm+20mil
141set b = 10*1mm
142
143All values used as dimensions must be either mm or mil.
144
145The default unit can be set with one of the following directives:
146
147unit mm
148unit mil
149unit auto
150
151When saving a footprint definition, the default unit is set to the
152unit set in the GUI.
153
154
155Vectors
156- - - -
157
158Vectors can be anonymous or they can be named for future reference:
159
160vec <base> ( <x-expr>, <y-expr> )
161<identifier>: vec <base> ( <x-expr>, <y-expr> )
162
163The base can be one of the following items:
164
165- @ is the origin of the frame containing the vector
166- . is the end of the previous vector in this frame
167- <identifier> is the name of a previous vector in the same frame
168
169The following example would draw the line described in the previous
170section:
171
172a: vec @(1mm, 1mm)
173b: vec .(1mm, 1mm)
174line a b
175
176
177Silk screen objects
178- - - - - - - - - -
179
180The output of fped is a footprint definition that contains pads and silk
181screen drawings (we may add more layers in the future). These items are
182called "objects". Their geometry is defined through points obtained with
183vectors.
184
185A line connects two points:
186
187line <point-a> <point-b> [<width>]
188
189The points can be specified with @, ., and an identifier, just like
190a vector base. The option width specifies the thickness of the silk
191screen line. If omitted, a hard-coded default of 15 mil is used.
192
193A rectangle has sides parallel to the x and y axis and is defined
194by two diagonally opposite corners:
195
196rect <point-a> <point-b> [<width>]
197
198A circle is defined by its center and a point on the circle:
199
200circ <center> <point> [<width>]
201
202This example draws a unit circle:
203
204vec @(1mm, 0mm)
205circ @ .
206
207An arc is like a circle, but the part of the circle drawn is determined
208by two points. The first point determines the radius and the starting
209angle. The second point only determines the end angle but its distance
210from the center is ignored.
211
212arc <center> <radius> <end> [<width>]
213
214The arc is drawn in a counter-clockwise direction. The following example
215draws an arc of the unit circle in the x > 0, y > 0 quadrant:
216
217from: vec @(1mm, 0mm)
218to: vec @(0mm, 1mm)
219arc @ from to
220
221
222Pads
223- -
224
225Pads are similar to rectangles, but they also have a name.
226
227pad "<name>" <point-a> <point-b> [<type>]
228
229Variables can be expanded in a pad's name by prefixing their name with
230a dollar sign. The ${name} syntax is also available.
231
232Example:
233
234vec @(1mm, 1mm)
235pad "1" @ .
236
237Pads normally affect the surface copper layer, the solder mask layer,
238and the solder paste layer. This can be modified with the optional
239type argument:
240
241Type Layers
242--------- -------------------------------------
243(default) copper, solder mask, and solder paste
244bare copper and solder mask
245paste solder paste
246mask solder mask
247
248
249Rounded pads
250- - - - - -
251
252Rounded pads are like rectangular pads except that they end with a
253semi-circle at each of the smaller sides of the enclosing rectangle.
254If enclosed in a square, rounded pads form a circle.
255
256rpad "<name>" <point-a> <point-b> [<type>]
257
258
259Holes
260- - -
261
262Holes can be used for through-hole pins or for mechanical support.
263In the former case, the hole must be placed inside a pad. Only one
264hole per pad is allowed. Mechanical holes must be outside any pads.
265
266Through-hole pads are always present on both sides of the board, i.e.,
267when fped generates a KiCad module, the surface layers of a pad
268containing a hole are propagated to the opposite side of the board.
269
270Holes have the same shape as a rounded pad and their geometry is
271defined in the same way:
272
273hole <point-a> <point-b>
274
275
276Measurements
277- - - - - -
278
279*** This is obsolete - see the section on new-style mesurements at the end. ***
280
281Measurements show the distance between two points:
282
283meas <point-a> <point-b> <offset>
284
285The offset is the distance from the imaginary line connecting points A
286and B the measurement line is draw:
287
288- if the offset is 0mm, the line will connect A and B
289- if the offset is positive, the line would be on the left-hand side when
290  traveling from A to B
291- if the offset is negative , the line would be on the right-hand side when
292  traveling from A to B
293
294Example:
295
296a: vec @(-1mm, 1mm)
297b: vec @(1mm, 1mm)
298meas a b 0.2 mm
299
300
301Package name
302- - - - - -
303
304The package name is a string of printable ASCII characters, including
305spaces.
306
307package "<name>"
308
309Examples:
310
311package "48-SSOP"
312package "0603"
313
314Like in pad names, variables are expanded in package names. This allows
315the generation of multiple packages from a single definition.
316
317
318Frames
319- - -
320
321Frames are used to group things and to reuse them multiple times. Frames
322must be defined before they can be used:
323
324frame <name> {
325    ... items ...
326}
327
328Once defined, a frame is placed at a given location with
329
330frame <name> <point>
331
332The frame definitions must precede all other items in a footprint
333description. Frames cannot be defined inside other frames, but frames
334can invoke each other recursively.
335
336For example, this puts two unity squares, one centered at (0 mm, 0 mm),
337the other at (2 mm, 0 mm):
338
339frame unit_square {
340    a: vec @(-0.5mm, -0.5mm)
341    b: vec .(1mm, 1mm)
342    rect a b
343}
344
345frame unit_square @
346vec @(2mm, 0mm)
347frame unit_square .
348
349
350Names and variables
351-------------------
352
353fped uses several name spaces:
354
355- frame names occupy one global name space
356
357- vector names occupy name spaces delimited by the frame they're
358  contained in. A vector name is only visible inside the frame in which
359  it is defined.
360  
361- variable names occupy name spaces delimited by the frame they're
362  contained in. A variable lookup starts in the frame in which the
363  corresponding expression appears and propagates to outer frames
364  until the variable is found.
365
366- pads occupy one global name space (this is currently not enforced)
367
368Note that names cannot be redefined. E.g., this does not work:
369
370set a = 1
371set a = a+1
372
373The names spaces of frames, vectors, variables, and pads are separate
374from each other.
375
376
377Simple variables
378- - - - - - - -
379
380A variable with a single value is defined with the following
381assignment syntax:
382
383set <identifier> = <expression>
384
385Example:
386
387set a = b+2
388
389
390Loops
391- - -
392
393A loop is a variable with a range of values:
394
395loop <identifier> = <from>, <to>
396
397The variable assumes all the values i for <from> <= i <= <to>, in
398increments of one. E.g.,
399
400loop n = 1, 3
401
402and
403
404loop n = 1, 3.5
405
406both assign the values 1, 2, and 3 to the variable "n". The
407following loop would not execute at all:
408
409loop n = 1, 0
410
411This can be used to implement conditional execution. For example,
412the items in the following frame would be instantiated if the
413variable "enable" is set to 1 but not it is set to 0:
414
415frame ... {
416    loop dummy = 1, enable
417    ...
418}
419
420When a loop is executed, the objects contained in the body of the
421enclosing frame are generated for each value of the variable. If
422a frame contains multiple loops, all possible combinations of the
423values are generated.
424
425The following example draws three concentric circles around the
426origin, with radii 1, 2, and 3:
427
428loop x = 1, 3
429vec @(x*1mm, 0mm)
430circ @ .
431
432
433Tables
434- - -
435
436Tables combine values for multiple variables. Like loops, they are
437used to iteratively generate objects. A table begins with a row of
438variable names, followed by one or more rows with values. Rows are
439enclosed in curly braces and their elements are separated by commas.
440
441table
442    { <identifier>, ... }
443    { <expression>, ... }
444    ...
445
446Like loops, tables are iterated to generate objects. The following
447example is equivalent to the one in the previous section:
448
449table
450    { x }
451    { 1mm }
452    { 2mm }
453    { 3mm }
454vec @(x, 0mm)
455circ @ .
456
457Note that we can set the unit of the values directly in this case.
458
459Iteration is performed over rows. All variables of the table are set
460to the value in the respective row at the same time. For example, in
461
462table
463    { x, y }
464    { 1, 2 }
465    { 3, 4 }
466
467(x, y) assume the values (1, 2) and (3, 4).
468
469
470Expressions
471-----------
472
473Expressions can contain numeric constants (in non-exponential notation),
474variable names, the arithmetic operations +, -, *, /, unary -, and the
475functions sin(), cos(), and sqrt().
476
477Parentheses can be used to change precedence.
478
479The argument of sin and cos is a dimensionless number that specifies the
480angle in degrees. E.g., sin(90) yields 1.
481
482The argument of sqrt() can be dimensionless or have a dimension with an
483exponent that's a multiple of two. E.g., sqrt(2) and sqrt(2mm*3mm) are
484valid expressions, sqrt(2mm) isn't.
485
486
487GUI
488---
489
490Part of the GUI is described in
491http://people.openmoko.org/werner/fped/gui.html
492
493
494Keyboard shortcuts
495- - - - - - - - -
496
497Space reset user coordinates
498+, = zoom in (like mouse wheel forward)
499- zoom out (like mouse wheel backward)
500. cursor position to screen center (like middle click)
501* zoom and center to extents
502# zoom and center to currently active frame instance
503U undelete the previously deleted object
504/ Switch between variable and item display.
505
506
507Canvas
508- - -
509
510To create a new object, click on the corresponding tool icon, move the
511mouse to the base point of the new object, then drag to the object's
512second point.
513
514Frame references are created as follows:
515
516- select the frame you want to add
517- click on the frame icon. A black dot should appear on the icon.
518- select the frame on which you want to add the new reference.
519  The black dot should change to a green dot. If the current frame
520  is a child of the selected frame, the dot remains black.
521- click on the desired base location
522
523To change a point of an object, select the object, then drag the point
524to its new location. To edit the object's parameters, select it and
525make the changes in the input area at the bottom.
526
527To delete an object, select the delete tool and click on the object.
528Deleted objects can be undeleted by pressing "u". If any other changes
529have been made since deletion, fped may misbehave. If deleting a vector,
530all items that reference it are deleted as well.
531
532
533Experimental: new-style measurements
534------------------------------------
535
536New-style measurements can measure the distance between various pairs
537of points, not only between points in the same instance and the same
538frame. They operate on the set of points produced during instantiation.
539
540New-style measurements are placed in the root frame after all other
541items.
542
543Known issues:
544- they currently can't be edited through the GUI
545- tie-breaking heuristics don't always do what one expects
546
547Syntax:
548
549<type> [<label>] <from> <op> <to> [<offset>]
550
551Types:
552- meas: measure diagonally
553- measx: measure along the X axis
554- measy: measure along the y axis
555
556Note that the type also affects the selection of the points. E.g.,
557measx will select maximum x values.
558
559Operators:
560- A -> B: smallest value of A and smallest B greater than A
561- A <- B: like A -> B, but normal (for offset and text) is inverted
562- A >> B: smallest value of A and greatest value of B
563- A << B: like A -> B, but normal (for offset and text) is inverted
564
565Operands are qualified vector names. Vectors in the root frame are
566referenced by their name. Vectors in other frames are prefixed with
567the name of the frame followed by a dot.
568
569Example:
570
571measx pad.sw -> pad.se 1mm
572
573The optional label is printed directly before the distance. Example:
574
575a: vec @(0mm, 0mm)
576b: vec @(1mm, 0mm)
577measx "width = " a >> b 0mm
578
579would print "width = 1mm"
580
581
582Experimental: debugging directives
583----------------------------------
584
585For debugging and regression tests, fped supports the following commands,
586most of which mimick the effect of GUI operations:
587
588%del <identifier>
589%move <identifier> [<number>] <identifier>
590%print <expression>
591%dump
592%exit
593%tsort { -<id> | +<id> | <id-before> <id-after> [<number>] ... }
594
595%del and %move take as their first argument the name of the vector or
596object to manipulate. For this purpose, also objects can be labeled.
597
598Object labels behave like vector labels and share the same name space.
599They are not shown anywhere in the GUI.
600
601%move sets an anchor point to the vector named as its last argument.
602The anchor point is identified by index as follows:
603
604anchor index vec/frame line/rect/pad arc measurement
605-------------- --------- ------------- ------------ -----------
6060 (or omitted) base first point center low point
6071 - second point end of arc high point
6082 - - start of arc -
609
610%dump writes the footprint definition in the fped language to standard
611output. %exit immediately exits fped, without invoking the GUI.
612
613%tsort is used to test-drive the topological sort algorithm. The items
614in the curly braces are declarations of nodes with (-<id>) or without
615(+<id>) decay or edges in the partial order. The optional number is
616the edge's priority. See tsort.c for details.
617

Archive Download this file

Branches:
master



interactive