fped/README

fped - Footprint editor
=======================

fped is an editor that allows the interactive creation of footprints of
electronic components. Footprint definitions are stored in a text format
that resembles a programming language.

The language is constrained such that anything that can be expressed in
the textual definition also has a straightforward equivalent operation
that can be performed through the GUI.


Motivation
----------

KiCad already includes a footprint ("module") editor, so why do we need
a new one ? The issue with footprint generation for KiCad is that the
built-in module editor is basically a drawing program that only captures
the result of the module author's interpretation of a footprint drawing,
but does not include the steps that led to this construction.

Furthermore, accurate measuring of dimensions in the drawing can only be
done manually in the module editor, which makes review difficult and
time-consuming.

In fped, the construction process is made explicit and each step can be
expressed in terms of the parameters that appear in the vendor's
drawing. Dimensions can be explicitly measured and the results can be
included in the graphical output generated by fped.

Directly using parameters and construction steps from the reference
drawing reduces the risk of mistakes. Visualizing the construction
process and verificative measurements helps efficient and accurate
review.


Footprint definition file format
--------------------------------

Footprint definitions are stored in text files. The program "fped" reads
and (soon) writes such files, visualizes their content, and provides a
graphical editor for them.

The syntax is unique and draws from elements of a variety of languages
commonly found on unix systems. One specialty is that there are no
reserved words - the language keywords appear only at the beginning of
a line and can thus be recognized as such without restricting their use
for identifiers. This reduces the risk of creating incompatibilities
with existing designs when introduction future language features.

fped uses the C preprocessor for comments, conditional compilation,
and - to a limited extent - also macros. Long lines can be split by
ending them with a backslash.


Geometry model
--------------

The geometry model consists of frames, vectors, and objects. The shape of
objects is defined by a number of points. These points are produced by
concatenating vectors.

E.g., to draw a line from (1mm, 1mm) to (2mm, 2mm), one would make a
vector from the origin to (1mm, 1mm) and one either from the origin or
from the previous vector to (2mm, 2mm), and then make a line connecting
the two points.


Units
- - -

fped can calculate in mm and mil. Units are specified by following a
number with "mm" or "mil", separated by zero or more spaces or tabs.

Examples:

1mm
2 mil

Units can be mixed in calculations, e.g.,

set a = 1mm+20mil
set b = 10*1mm

All values used as dimensions must be either mm or mil.


Vectors
- - - -

Vectors can be anonymous or they can be named for future reference:

vec <base> ( <x-expr>, <y-expr> )
<identifier>: vec <base>  ( <x-expr>, <y-expr> )

The base can be one of the following items:

- @ is the origin of the frame containing the vector
- . is the end of the previous vector in this frame
- <identifier> is the name of a previous vector in the same frame

The following example would draw the line described in the previous
section:

a: vec @(1mm, 1mm)
b: vec .(1mm, 1mm)
line a b


Silk screen objects
- - - - - - - - - -

The output of fped is a footprint definition that contains pads and silk
screen drawings (we may add more layers in the future). These items are
called "objects". Their geometry is defined through points obtained with
vectors.

A line connects two points:

line <point-a> <point-b> [<width>]

The points can be specified with @, ., and an identifier, just like
a vector base. The option width specifies the thickness of the silk
screen line. If omitted, a hard-coded default of 15 mil is used.

A rectangle has sides parallel to the x and y axis and is defined
by two diagonally opposite corners:

rect <point-a> <point-b> [<width>]

A circle is defined by its center and a point on the circle:

circ <center> <point> [<width>]

This example draws a unit circle:

vec @(1mm, 0mm)
circ @ .

An arc is like a circle, but the part of the circle drawn is determined
by two points. The first point determines the radius and the starting
angle. The second point only determines the end angle but its distance
from the center is ignored.

arc <center> <radius> <end> [<width>]

The arc is drawn in a counter-clockwise direction. The following example
draws an arc of the unit circle in the x > 0, y > 0 quadrant:

from: vec @(1mm, 0mm)
to: vec @(0mm, 1mm)
arc @ from to


Pads
- -

Pads are similar to rectangles, but they also have a name.

pad "<name>" <point-a> <point-b>

Variables can be expanded in a pad's name by prefixing their name with
a dollar sign. The ${name} syntax is also available.

Example:

vec @(1mm, 1mm)
pad "1" @ .


Measurements
- - - - - -

Measurements show the distance between two points:

meas <point-a> <point-b> <offset>

The offset is the distance from the imaginary line connecting points A
and B the measurement line is draw:

- if the offset is 0mm, the line will connect A and B
- if the offset is positive, the line would be on the left-hand side when
  traveling from A to B
- if the offset is negative , the line would be on the right-hand side when
  traveling from A to B

Example:

a: vec @(-1mm, 1mm)
b: vec @(1mm, 1mm)
meas a b 0.2 mm


Frames
- - -

Frames are used to group things and to reuse them multiple times. Frames
must be defined before they can be used:

frame <name> {
    ... items ...
}

Once defined, a frame is placed at a given location with

frame <name> <point>

The frame definitions must precede all other items in a footprint
description. Frames cannot be defined inside other frames, but frames
can invoke each other recursively.

For example, this puts two unity squares, one centered at (0 mm, 0 mm),
the other at (2 mm, 0 mm):

frame unit_square {
	a: vec @(-0.5mm, -0.5mm)
	b: vec .(1mm, 1mm)
	rect a b
}

frame unit_square @
vec @(2mm, 0mm)
frame unit_square .


Names and variables
-------------------

fped uses several name spaces:

- frame names occupy one global name space

- vector names occupy name spaces delimited by the frame they're
  contained in. A vector name is only visible inside the frame in which
  it is defined.
  
- variable names occupy name spaces delimited by the frame they're
  contained in. A variable lookup starts in the frame in which the
  corresponding expression appears and propagates to outer frames
  until the variable is found.

- pads occupy one global name space (this is currently not enforced)

Note that names cannot be redefined. E.g., this does not work:

set a = 1
set a = a+1

The names spaces of frames, vectors, variables, and pads are separate
from each other.


Simple variables
- - - - - - - -

A variable with a single value is defined with the following
assignment syntax:

set <identifier> = <expression>

Example:

set a = b+2


Loops
- - -

A loop is a variable with a range of values:

loop <identifier> = <from>, <to>

The variable assumes all the values i for <from> <= i <= <to>, in
increments of one. E.g.,

loop n = 1, 3

and

loop n = 1, 3

both assigns the values 1, 2, and 3 to the variable "n".

When a loop is executed, the objects contained in the body of the
enclosing frame are generated for each value of the variable. If
a frame contains multiple loops, all possible combinations of the
values are generated.

The following example draws three concentric circles around the
origin, with radii 1, 2, and 3:

loop x = 1, 3
vec @(x*1mm, 0mm)
circ @ .


Tables
- - -

Tables combine values for multiple variables. Like loops, they are
used to iteratively generate objects. A table begins with a row of
variable names, followed by one or more rows with values. Rows are
enclosed in curly braces and their elements are separated by commas.

table
    { <identifier>, ... }
    { <expression>, ... }
    ...

Like loops, tables are iterated to generate objects. The following
example is equivalent to the one in the previous section:

table
    { x }
    { 1mm }
    { 2mm }
    { 3mm }
vec @(x, 0mm)
circ @ .

Note that we can set the unit of the values directly in this case.

Iteration is performed over rows. All variables of the table are set
to the value in the respective row at the same time. For example, in

table
    { x, y }
    { 1, 2 }
    { 3, 4 }

(x, y) assume the values (1, 2) and (3, 4).


Expressions
-----------

Expressions can contain numeric constants (in non-exponential notation),
variable names, the arithmetic operations +, -, *, /, and unary -.
Parentheses can be used to change precedence.