hid/gtk: Call ghid_fill_pcb_polygon via (HID_DRAW *)->fill_pcb_polygon()

[geda-pcb/pcjc2.git] / doc / gs / fb-led.texi

@node LED Board
@section LED Board

This first board will show you the basic operation of @code{pcb}.
Each new command or operation that is introduced will be described in
full the first time, but not subsequent times.  Many operations can be
invoked either by a menu option, like @mnuu{File,Quit Program} to
select the ``Quit'' option in the ``File'' menu, or by a keyboard
shortcut, like @kbd{Ctrl-Q}.  When we say @kbd{Ctrl-Q} we mean to hold
the @key{Ctrl} key while pressing the @key{Q} key.  When we say
@kbd{Shift-Q} we mean to hold either @key{Shift} key while pressing
the @key{Q} key.

For example, the first time we describe the Quit command, we'd say,
``now exit @code{pcb} by using the Quit command (@mnuu{File,Quit} or
@kbd{Ctrl-Q})''.  Any other time, we'd just say ``now Quit.''

The first step in this project is to run @code{pcb}.  Since @code{pcb}
defaults to using the current directory for its files, it's a good
idea to create a new subdirectory for this project, @code{cd} into it
in a terminal window, and then run pcb from there:

@center @image{fb-led-1} @image{fb-led-2}

Now is a good time to practice that Quit command :-)

Also, if you ever ask for @code{pcb} help from someone else, they'll
probably want to know what version and GUI you're using.  To see this,
use the About command (@mnuu{Window,About...}).

Note that when @code{pcb} starts, it creates not only its main window
(pictured above), but two additional windows.  One is the ``PCB
Library'', which we'll talk about later, and the other is the ``PCB
Log'' that contains all the messages - warnings, errors, etc.  For
now, you can just move these out of the way.  If you close these, you
can re-open them using @mnuu{Window,Library} and @mnuu{Window,Message
Log}.

For any board you create, one of the first things you need to decide
on is how big the board is going to be.  If you want it to be ``as
small as possible'', then you can create it bigger than you need and
change the size later.  For this simple board, we can guess - we want
it to be one inch by one inch.  The board size controls are located in
the Preferences window (@mnuu{File,Preferences}), which contains both
board-specific and user-specific preferences.  We want the @b{Sizes}
preferences, so click on the word @b{Sizes}.  The window should look
like this:

@img{fb-led-3}

We won't be using the Text Scale or DRC preferences yet.  Note that
the units are mils, so the default board size is six inches wide and
five inches high.  Change these numbers to @code{1000.0} each:

@img{fb-led-4}

We will next set up our layers, which define how many copper layers
we'll have and what they'll be called.  Select the @b{Layers}
preferences.  You'll see three tabs along the top; click on the
@b{Groups} tab to show the layer group preferences.  For this project,
all we want to do is make sure that the solder layer is on the solder
side, and the component layer is on the component side.  Click in the
boxes to make ``component'' and ``component side'' in group 1, and
``solder'' and ``solder side'' in group 2, then click on @b{OK}:

@img{fb-led-6}

There's a couple of settings you'll want to set up now, as they get
saved with the board.  First, let's turn on the grid
(@mnuu{View,Enable visible grid} if it isn't already checked) and set
it to 0.1" or 100 mil (@mnuuu{View,Grid Size,100 mil}).  The grid is
drawn as a field of tiny dots, which may be hard to see on our board
but would be easier to see if there were more of them.  For example,
switch to a 10 mil grid and note the difference (don't forget to
switch back to 100 mil).

Next, we want to make sure any new traces we create won't
automatically connect with any polygons we might add - for example,
adding a ground plane or ``flood fill''.  The @b{Settings} menu has
many settings in it, but for now, just make sure that @b{New lines,
arcs clear polygons} and @b{Crosshair snaps to pins and pads} are
checked, and @b{Auto enforce DRC clearance} is not checked.

Now that we've set up our board, it's a good time to save it.  Use the
Save command (@mnuu{File,Save layout}).  Since this is the first time,
it will ask you for a layout name.  We're going to call this layout
@code{fb-led.pcb} so type that in where it says @b{Name} and click OK.
Now that your board has a file associated with it, you can just
@mnuu{File,Save layout} whenever you want to save your work.

Now we'll start adding the actual circuit.  This circuit will be a
simple LED in series with a resistor, and a header for a battery.  We
won't need schematics, we'll just add the parts and connections
manually.  The first step is to choose a @emph{route style} for your
new traces.  The lower left corner lists the four available route
styles.  Make sure @b{Signal} is selected, then click @b{Route Style}
to bring up the route style window.  We're going to use fairly large
traces, which is typical of a simple board.  In that window, set the
Line width to 20, Via hole to 36, Via size of 76, and Clearance to 20;
then click @b{OK}:

@center @image{fb-led-7} @image{fb-led-8}

Next we'll add the three parts we need.  In larger projects, this will
be done by @code{gsch2pcb} but you'll need to know the footprint names
for that.  Find the library window (if you left it open) or open it
(if you closed it) with @mnuu{Window,Library}.  Click on the triangle next
to @b{pcblib} to open the pcblib library.  Scroll down to @b{~geda} and
click on it, to open the ~geda library.

@center @image{fb-led-9} @image{fb-led-10} @image{fb-led-11}

When you choose the parts out of the library, notice that there is
some text in square brackets - this is the footprint name you'll need
for @code{gsch2pcb}.  The first we want is the LED.  We'll use
@code{RCY100P} for the LED, which is a radial cylinder, polarized, 100
mil spacing.  Scroll down until you find it, and click on it.  When
you move the cursor back to the @code{pcb} window, you'll see that it
now carries the outline of the part with it:

@img{fb-led-12}

Press the left mouse button to place a part on your board.  We'll move
it later.  Do the same for an @code{ACY400} footprint for the
resistor, and a @code{HEADER2_1}.  Your board should now look
something like this:

@img{fb-led-13}

We will use the selection and rotate tools to position the parts where
we want them.  The palette of tools is just above the route styles, on
the left.  The two we want are @b{SEL} and @b{ROT}:

@img{fb-led-14}

First click on the ROT (rotate) tool.  The cursor should change shape to act as
a hint that you'll rotate whatever you click on.  Position the cursor
over the square pad on the header and click the left mouse button:

@center @image{fb-led-15} @image{fb-led-16}

Now click on the SEL (selection) tool, also known as the ``arrow
tool''.  You move parts by pressing the left mouse button while the
cursor is over the part, and moving the mouse while holding the mouse
button down.  The part itself doesn't move; instead, a wire-frame
outline of the part is moved (much like when placing parts).  When you
release the mouse button, the part is moved.

@center @image{fb-led-17} @image{fb-led-18} @image{fb-led-19}

Move the header so that the square pin is at 200,600 (the crosshair's
coordinates are shown in the upper right corner of the window), the
resistor's square pin at 400,400, and the LED's square pin at 500,700.
Your board should now look like this:

@img{fb-led-20}

Now is a really good time to save your layout.

Next we'll start adding the traces that connect the parts.  We'll use
the LINE tool to add them.  Since this is a simple board, it's likely
to be built as a single-sided board, with the traces on the ``back''
side, so we want the @b{solder} layer to be the drawing layer.  On the
left side of the window is a collection of buttons named after various
layers in your board.  One of them is named @b{solder}.  To the left
of that button is a small indicator.  Click on it.  Don't click on the
button itself - that changes the visibility of the layer.  Click on
the indicator.

@center @image{fb-led-21} @image{fb-led-22}

The way the line tool works is that you click on the starting point,
move the crosshair to the end point, and click again.  By not
requiring you to hold the mouse button down, you have the ability to
scroll and zoom to find the endpoint.  You can also click on
intermediate points to make lines with multiple corners.  To end the
trace, or start a new trace elsewhere, press the @kbd{Esc} key.  If
you press the @kbd{Esc} key again, you return to the selection tool.

If you attempt to connect two points that aren't on the same vertical,
horizontal, or diagonal line, the line tool will create a pair of
traces to connect them.  One will be either vertical or horizontal,
and the other will be diagonal.  The vertical/horizontal segment will
be connected to the starting point, and the diagonal segment will
follow the crosshair.  If you look in the status bar, you'll see a
@code{_/} symbol that indicates this:

@img{fb-led-23}

Pressing the @kbd{/} key changes this mode.  If it says @code{\_} the
diagonal will attach to the starting point, and the
vertical/horizontal will attach to the crosshair.  If it says neither,
only one segment at a time will be drawn, instead of two.  Also, you
can use the @kbd{Shift} key to temporarily toggle between @code{\_}
and @code{_/} modes.

@center @image{fb-led-24} @image{fb-led-25} @image{fb-led-26}

So let's add the three traces we need.  Press the @kbd{/} key until
@code{_/} is shown (this is the default when you start @code{pcb}) and
connect the left resistor pin to the top header pin.  Click, move,
click, @kbd{Esc}.  Connect the left LED pin to the bottom header pin.
Connect the right resistor pin to the right LED pin.

@center @image{fb-led-27} @image{fb-led-28}

Next we'll make some adjustments to our PCB.  Unless you have your own
library that you've tweaked to be ``just right'', it's likely that
you'll need to adjust some things during the board layout process.
For example, you might need to make room for a trace between two pins.
In our case, we're going to make some adjustments that are appropriate
for home-made boards.  We're going to make the pads bigger, in case we
drill off-center.  There is a generic ``change size'' command that's
tied to the @kbd{S} key.  Place the crosshair over one of the pins and
type @kbd{S} and the pin gets bigger.  Press @kbd{Shift-S} and the pin
gets smaller.  You can change the size of pins, pads, traces, and even
silk this way.  However, if you want to change a lot of things at
once, there's a simpler way.  Use the @mnuu{Select,Select all visible
objects} menu entry to select everything.  Now you can use the
@mnuu{Select,Change size of selected objects} menu to change all the
selected things at once.  In our case, we want the @mnu{Pins +10 mil}
option to make our pins a little bigger.  After clicking that, see
that all the pins are a little bigger.  Now you can
@mnuu{Select,Unselect all objects} to unselect them all.

You can also use the Select tool (@b{SEL}) to select and deselect.  To
select, either click with the left mouse button on the object you want
to select, or drag a rectangle around a group of things.  To deselect,
just click somewhere where there isn't anything.  You can also
Shift-click to select something without deselecting anything else,
like if you wanted to select two or three things that aren't grouped
nicely.

Next we will label our components.  Each element has three text
strings it can display; you choose which through a @mnu{View} menu
option.  The default is to display the reference designator (refdes),
which is what we want for now.

Since both pins and elements can have labels, turn off the grid so we
can select the elements (@mnuuu{View,Grid size,No Grid}).  Now
select the @mnuuu{Edit,Edit name of,text on layout} menu.  Most of
the GUI goes ``grey'' and @code{pcb} asks you to @b{Select an Object}.
Left-click on the resistor (on the body, not on the pins).  A dialog
box pops up asking you for the new name.  Make sure it says
``Element'' and not ``Pin'', and type in @code{R1}:

@center @image{fb-led-29} @image{fb-led-30} @image{fb-led-31}

You can now drag and drop the name to where you want it, being careful
to pick up the label and not any traces:

@img{fb-led-32}

You can also use keyboard shortcuts.  Position the crosshair over the
LED, but not over the pins, and press the @kbd{n} key (for ``name'').
Type in @code{D1}.  Set the name of the header to @code{J1} and arrange
the names so they look like this:

@img{fb-led-33}

Don't forget to save your work occasionally.  @code{pcb} will normally
save a copy automatically every once in a while, but it's a good habit
to save it manually when you're at a good stopping point.

We can also add additional text to the silkscreen and copper layers.
Let's add some text to the header, so we know which way to plug the
battery in.  We want to use the text tool:

@img{fb-led-34}

We also want the silkscreen layer to be the default drawing layer:

@img{fb-led-35}

Now, click below the header's square pin, and enter @code{+} in the
dialog that pops up.  Use the @kbd{S} key a whole bunch of times to
make it bigger, then use the selection tool to move it in place.  Do
the same for the @code{-} label.

@center @image{fb-led-36} @image{fb-led-37} @image{fb-led-38}

Now that we're done with the labels, set the grid back to 100 mil in
case you move any of the traces or parts; once they're off-grid it's
hard to get them back on to the grid.

We're done editing the board now, so if you haven't already, save your
work.  But now that the board is done, what do we do with it?  Well,
that depends on how you're going to make your board.  If you want to
do it yourself, you probably want to send it to your printer.  If you
want someone else to make it, they'll probably want gerber files.

In your @mnu{File} menu, there are three options we're interested in.

@img{fb-led-39}

The @mnu{Print Layout...} option prints your layout, but note that it
will print 11 pages of board layers!  This probably isn't what you
normally want, but let's do it anyway.

@img{fb-led-40}

There are a lot of options there, but there's only a couple you need
to worry about right now.  Select ``fill-page'' and ``ps-color'' and
click @b{OK}.  ``Fill-page'' zooms your prints to fill the page.
``PS-color'' causes each layer to be printed in the same color as you
see on the screen.  If you're making boards at home using toner
transfer, you want these options @emph{off}, and you want ``mirror''
on.

In most cases, you don't want to just print the whole design.  Usually
you'll use the @mnu{Export Layout...} option to export your layout in
a format that others can use.  When you export, a list of possible
export types is offered:

@img{fb-led-41}

Click on @mnu{gerber} so we can create some Gerber (RS-274X) files,
which are industry standard file for describing circuit boards.

@img{fb-led-42}

Click on @b{verbose} then @b{OK}.  You'll see something like this in
your terminal:

@smallexample
Gerber: 5 apertures in fb-led.front.gbr
Gerber: 5 apertures in fb-led.back.gbr
Gerber: 3 apertures in fb-led.frontmask.gbr
Gerber: 3 apertures in fb-led.backmask.gbr
Gerber: 2 apertures in fb-led.plated-drill.cnc
Gerber: 3 apertures in fb-led.frontsilk.gbr
Gerber: 3 apertures in fb-led.fab.gbr
@end smallexample

For a single sided board, most fab houses will need the back,
backmask, plated-drill, frontsilk, and fab files.  @code{pcb} always
produces ``positive'' gerbers in case the fab asks.

For home fabrication, you'll want to print (see above) without the
ps-color or fill-page options.  For this simple board, printer
calibration is not needed.  If you're drilling your own holes, you may
want to select the @b{drill helper} option, which reduces the diameter
of the holes in the copper wherever you're drilling to help you center
the drill properly.  If you use the @b{ps} exporter, selecting the
``multi-file'' option puts each layer in a separate file.  That way,
you can print only the layers you're interested in.

So let's see what we've produced.  Exit from @code{pcb} with
@mnuu{File,Quit Program} and find your terminal again.  I use the free
programs @code{gv} and @code{gerbv} to view my exported files;
@code{gv} is GhostScript, but your desktop probably knows what to do
if you double click on a .ps file in your file browser.  @code{gerbv}
is a gerber file viewer that's part of gEDA:

@smallexample
$ gerbv fb-led.*.gbr fb-led.*.cnc
@end smallexample

@img{fb-led-43}

That's it!  The next step is to actually make board (or have them
made), which is beyond the scope of this tutorial.