Root/README

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

Archive Download this file

Branches:
master



interactive