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