pcblander, First Release, April 30, 2007

This is the first release of the pcblander program.  pcblander is a land
pattern generator for the gEDA tool suite.  There are many land pattern
programs available, but pcblander is a bit different.  pcblander runs
from scripts, and it makes it possible to script most any land pattern.
Why a script?  When building a land pattern, it's important to define
exactly what the dimensions are.  A script allows for this sort of
control.  Later, days after you have built the land pattern, you may
need to verify or modify what you have done.  A script documents what has
been built, so you can review and change what you have done.  I've been
using pcblander to script land patterns for BGAs, QFPs, DIPs, SIPs, and
lots of standard and non-standard surface mount and through hole parts.
There's also quite a bit of flexibility that I won't cover here.  If you
are building your own land patterns and want script driven control,
pcblander may be what you are looking for.


A Quick Introduction

pcblander scripts can come from files, you can type them in interactively,
or you can pipe them from another Unix process.  Hows does pcblander
work?  pcblander reads scripts, a line at a time, and performs a few key
functions that you can use to build most any footprint.  Here's a quick
rundown of the functions.  The array() function makes a two dimensional
array of pads/pins/holes with a given spacing, size, placement, and set
of pin numbers.  There's a handful of silk functions for making silk
lines and arcs.  Finally, there's the writeland() function for writing
out all that you have done to to a gEDA compatible footprint file.
That's pretty much it.

What makes pcblander quite useful is you can use the simple array() and
silk functions as they are, and/or you can build larger functions using
these functions as building blocks.  Common, complex land patterns can
be scripted once and called with a few simple parameters.  If you like,
you can supplement these bigger functions by calling the basic functions,
or calling the bigger functions more than once (for an array of parts
or dual footprints, for example).


An Example

# pcblander script starts here - comments start with '#'

pad_type = "pad"             # use "hole" if you want a pin hole or hole
pad_shape = "rectangular"    # use "circular" for round pads 
pad_width = 1mm
pad_height = 1mil 
array(0,0,{1},{})            # put pad 1 at (0,0)
writeland("myfile")          # write the footprint out to file, "myfile"

The script above writes a single pad, centered at (0,0) to a file.
If you had written the array() line as:

pitch_x = 1.5mm              # center to center horiz. distance of pads
array(0,0,{1:20},{})

it would have generated a row of 20 pads whose centers were 1.5mm apart.
The leftmost pad would be pad 1 and the rightmost would be pad 20  You
can try this script by putting it into a file (you can call it anything,
but I'll call it myfile.landgen) and typing "pcblander myfile.landgen",
or "pcblander <myfile.landgen", or "cat myfile.landgen | pcblander".
pcblander can also be run interactively.  If you type pcblander -SH,
you'll get a prompt.  You can type in the file a line at a time.

When defining distances, you have the option of using mm, cm, mils,
and inches.  If you don't give any units, distances are in pcb units
(which are in 100,000th's of an inch).


More about the array() Function

The array() function's first 2 parameters tell it where to place the
center of the array it is generating.  The parameters are the (x,y)
coordinates where x & y are Cartesian coordinates (x increases to the
right, y increases upwards).  You can use pure numbers, if you want
place using gEDA pcb units, or you can use dimensioned units (like we
did with the pad sizes in the example above).

The array() function takes 2 more parameters that are in brackets.  In the
example above, the first parameter is populated, but the second is called
with nothing.  The second set of brackets is used to create a vertical
array of pads/pins.  array(0,0,{},{1:20})  would draw a column of 20 pads
with pad 1 at the top and pad 20 at the bottom.  If you called array()
with both sets of brackets populated, you would get a 2 dimensional array
of pads/pins.  "pitch_y" determines the center to center distance of the
pads vertically.  Just be sure the pad ranges make sense.  The first
set gives the pin/pad numbers of the top row.  The second set gives
the pin/pad numbers of the leftmost column.  If all goes well, array()
should be able to fill in the rest of the pads using that information.
It works for BGA type labels ( {A1:A16}, {A1:T1} ), too.  Bracket pin/pad
numbers can be any one of: {1:20} or {1,2,3,4,5:20} or {1:5,6,7,8:20}
or even {20:1}, if you want things numbered in reverse order.

One last capability.  Anytime you use the array() function, it looks at
the pad_omit variable to see if there are any pads that should be left
out of the array.  If it omits a pad, it will leave an empty hole in the
array where the pad/pin should have been.  pad_omit takes a bracketed set
of pins, just like the array function does.  If we had set pad_omit to
{3:4,5} in the example above, pads 3-5 would have been missing, and there
would have been blank spots in the pad array where pads 3-5 used to be.

There are a bunch of examples included with this release.  They all
end in ".lander".  You can generate land patterns by typing: "pcblander
<somefile.lander>" (you can also type "pcblander *.lander", if you want
to do them all at once).  template.lander is a general file that is a
good starting point for creating your own land patterns. Take a look in
the files to see more details on how land patterns are built.


Installation

Put the files the bin directory in a directory in your search path.
The demos can go anywhere you want.  You should be all set to go.

Note, the scripteaser.pp file is a packaged perl file.  It has all the
perl extensions it needs included.  Though this is not recommended for
starting out, you can unpack the scripteaser.pp file and use the source
files directly, but you may find some perl library functions are missing
(most perl installations don't have the ReadLine module installed,
and the -SH option uses this).  You'll need to go to CPAN for those.

If you have an older Linux system, you may find that some of the
packagaged libraries in scripteaser.pp won't run.  If this happens,
you'll need to unpack the installation and run the pure perl files.

To unpack scripteaser.pp use unzip -l to see what is inside.
The script/scripteaser.pl file, and all the files in the teaserlib
directory should be placed in a directory in your search path (overwrite
scripteaser with one one in the pp file).


Steve