Root/README

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

Archive Download this file

Branches:
master



interactive