docs/gsch2pcb_tutorial/tutorial-old.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
   2 <html>
   3 <head>
   4     <title>gsch2pcb tutorial</title>
   5 </head>
   6 <body background="./images/paper1.gif">
   7
   8 <center><h2>gschem -> gsch2pcb -> PCB</h2></center>
   9 <hr width=100% size=2>
  10
  11 <blockquote>
  12 This is a tutorial on the process of using gsch2pcb as an
  13 interface between gschem and PCB.
  14 It assumes the gEDA, PCB and gsch2pcb packages
  15 are already installed and ready to use.  Starting with gEDA 20030901,
  16 gsch2pcb version 0.9 is packaged with gEDA, but some of the steps below
  17 will require gsch2pcb 1.0.  This tutorial is functional and intended to
  18 generate results as quickly as possible.  It is not a complete reference
  19 on gschem or PCB, but it does show with a simple example design
  20 all the steps one might need to take.
  21 <p>
  22 The goal is to use gsch2pcb as the bridge between gschem and PCB so
  23 that the schematics can always be in sync with the PCB layout
  24 because all element additions or deletions in the layout will
  25 automatically be driven by changes in the schematics.
  26 </blockquote>
  27
  28 <h3> Tutorial Release Notes </h3>
  29 <blockquote>
  30 <ul>
  31         <li>If you have versions less than gschem 20030525 or PCB 1.99 these
  32         tutorial examples may not work as expected.
  33         </li>
  34         <li>If you have gEDA version 20030901 installed such that you are
  35         using its included gsch2pcb 0.9 and you are getting an error:
  36         <blockquote><pre>
  37 ERROR: Unbound variable: open-output-pipe
  38         </pre></blockquote>
  39         then the problem is syntax in <i>gnet-gsch2pcb.scm</i> that worked
  40         in guile 1.4 but does not work in guile 1.6.  You'll need to upgrade to
  41         using at least gsch2pcb 1.0.1 to solve this problem.
  42         </li>
  43         <li>As of about 1/9/2004 CVS PCB versions changed to using a hi
  44         resolution output file format which will require using at
  45         least gsch2pcb-1.4.
  46         </li>
  47         <li><h5> Mini Changelog</h5>
  48         <ul>
  49                 <li> 1/10/2004 - corrected my sloppy PCB file elements which had
  50                         silkscreen lines overlapping solder pads.
  51                 </li>
  52                 <li> 12/23/2003 - added comments about new CVS PCB versions which
  53                         have the m4 and newlib directories default installed under
  54                         /usr/share or /usr/local/share.
  55                 </li>
  56         </ul>
  57         </li>
  58 </blockquote>
  59
  60 <h3> Terminology </h3>
  61 <blockquote>
  62 With gschem, you add symbols representing electronic components to a
  63 schematic.  A symbol is a group of pins, attributes, and lines showing
  64 an iconic representation of an electronic component.
  65 Pins in symbols are connected to other pins by drawing a net
  66 connection between them.  Attributes are just named tags attached to
  67 symbols to convey some bit of information.  For using the schematic with PCB,
  68 there are three of these attributes which are relevant and must be
  69 specified. Each added symbol should have a <b>footprint, value,</b> and
  70 <b>refdes</b> attribute.
  71 <p>
  72 The schematic <b>footprint</b> attribute value of a symbol is the name of the
  73 PCB element to be placed on the layout for that instance of the symbol.
  74 A PCB element is a group of pins, pads, and silk layer outlines physically
  75 corresponding
  76 to electronic components.  It is probably a source of confusion for
  77 newcomers to PCB that elements are of two different types.  There are the
  78 original m4 macro generated PCB elements and since PCB version 1.7
  79 there are also the
  80 newlib style file elements.  A file element is a single fixed element
  81 in a single file.  However, many m4 macro element definitions may exist in a
  82 single m4 element file.  The macros can be given arguments to provide
  83 programmable elements of variable number of pins or spacings.
  84 Using these two types will be covered
  85 in this tutorial and I will be referring to
  86 these distinct element types as
  87 <b>m4 elements</b> and <b>file elements</b>.
  88 When rou run PCB, the gschem <b>footprint</b> attribute
  89 value will appear as the displayed element name when you
  90 select <b>description</b> from the <b>Screen</b> menu because gsch2pcb
  91 uses this field to keep track of which <b>footprint</b> corresponds
  92 to a particular PCB element.
  93 <p>
  94 The gschem <b>refdes</b> attribute value is the reference designator
  95 on the schematic such as Q1, U1, R1, etc.  When you run PCB, this
  96 refdes will appear as the displayed element name when you select
  97 <b>name on PCB</b> from the <b>Screen</b> menu.
  98 <p>
  99 The gschem <b>value</b> attribute value is the particular component value
 100 such as BC546, 7400, 1K, etc.  When you run PCB, this
 101 <b>value</b> will appear as the displayed element name when you select
 102 <b>value</b> from the <b>Screen</b> menu.
 103 </blockquote>
 104
 105
 106 <h3> Setup </h3>
 107 <blockquote>
 108 You should have a directory structure in mind for organizing your
 109 design projects. The install of gEDA
 110 and PCB gives you a set of default gschem symbols and
 111 default PCB elements, but you can also provide for creating your own custom
 112 libraries of gschem symbols and PCB elements.
 113 <ul>
 114         <li> Somewhere, probably under your home directory, create your
 115                 directory structure.  Use directory names you like, but
 116                 this tutorial will reference the directory name structure
 117                 I use:
 118                 <blockquote><pre>
 119 gaf/
 120 gaf/gschem-sym/                    Where I put the custom gschem symbols I create.
 121 gaf/gschem-sym/transistors/        You can organize your custom symbols into subdirectories.
 122 gaf/pcb-elements/                  Where I put the custom PCB file elements I create.
 123                                        These can also be organized into subdirectories.
 124 gaf/myproject1/
 125 gaf/myproject2/
 126 ...
 127                 </pre></blockquote>
 128         With this organization, your custom gschem symbols and PCB elements can
 129         be common to all of your projects and is good enough to get you started.
 130         However, I'll mention other possibilities which will be revealed
 131         below.  There can be project specific PCB <b>file element</b>
 132         subdirectories  or <b>m4 element</b> files.  Or, CAD administrators can
 133         set up site wide custom PCB <b>file element</b> directories and
 134         <b>m4 element</b> files.
 135
 136         </li>
 137         <p>
 138         <li> <b>gschem setup: </b> So gschem will be able to find any custom
 139         symbols you will make and put in <b>gaf/gschem-sym</b> create the
 140         file <b>~/.gEDA/gschemrc</b> with this content (plus an entry for each
 141         additional <b>gschem-sym </b> subdirectory you want):
 142         <blockquote><pre>
 143 (component-library "${HOME}/gaf/gschem-sym")
 144 (component-library "${HOME}/gaf/gschem-sym/transistors")
 145         </pre></blockquote>
 146         <b>gnetlist setup: </b> gnetlist will also need to find these symbols
 147         so duplicate those lines into <b>~/.gEDA/gnetlistrc</b>.
 148         <p>
 149         If you want a more detailed customization of gschem and gnetlist, you
 150         can override other initializations that are setup in the global rc files.
 151         In Debian, look at rc files in <b>/etc/gEDA/</b> for settings
 152         you can make.
 153         For example, I like the light gschem background, so I also put in
 154         my <b>~/.gEDA/gschemrc</b> the line:
 155         <blockquote><pre>
 156 (load (string-append gedadatarc "/gschem-lightbg")) ; light background
 157         </pre></blockquote>
 158         </li>
 159         <li> <b>PCB setup: </b> A PCB distribution usually is set up so that
 160         PCB will automatically look in a <b>packages</b> subdirectory of the
 161         working directory.  So, to make PCB find all the custom elements I
 162         put in <b>gaf/pcb-elements</b> I make a link in each of my project
 163         directories.  Note that this link is actually not required when using
 164         gsch2pcb because, as described below, you may alternatively
 165         specify the <b>pcb-elements</b> directory in a
 166         <b>project</b> file.  But if you do want to make the link,
 167         in directory <b>gaf/myproject1</b> enter the command:
 168         <blockquote><pre>
 169 ln -s ../pcb-elements packages
 170         </pre></blockquote>
 171         </li>
 172         <li> <b> gsch2pcb setup: </b> In each of your project directories, create
 173         a gsch2pcb project file which can be named anything that does not
 174         end in <i>.sch</i>.
 175         A poject file will be created in the example below.
 176         </li>
 177 </ul>
 178         This is all the setup you need beyond the initial install of the
 179         gschem, gsch2pcb, and PCB packages.
 180 </blockquote>
 181
 182 <a name="SIMPLE_EXAMPLE">
 183 <h3> Simple Example </h3>
 184 <blockquote>
 185         Let's generate a trivial design from schematics to PCB layout
 186         almost as quickly as possible and then we can use it as a base for
 187         doing some more advanced stuff.  I'll complicate it just a bit by
 188         making it a two schematic design.
 189         <p>
 190         Assuming you setup the directory structure described
 191         above, go to the <b>gaf/myproject1</b> directory and create
 192         a file named <b>project</b> with this content:
 193         <blockquote><pre>
 194 schematics one.sch two.sch
 195 output-name board
 196         </pre></blockquote>
 197         <h4> Create schematic: one.sch</h4>
 198         <blockquote>
 199         If you are using gschem for the first time, try stepping through
 200         this simple
 201         <a href="gschem-warmup.html" name="gschem-warmup.html">gschem warmup. </a>
 202         <br>
 203         Run <b>gschem one.sch</b> and create this schematic (the second opamp
 204         is redundant, but this is just a tutorial):
 205         <p>
 206         <table border=1>
 207         <tr bgcolor=#b0b0a8>
 208                 <td>
 209                 <img src="images/one-sch-1.png" alt="images/one-sch-1.png"
 210                         border="0" align="top"><br> <center>one.sch</center>
 211                 </td>
 212                 <td>
 213                 <ul>
 214                         <li> Add component <b>title-B.sym</b> from the <b>titleblock</b>
 215                         library.  Hit keys <b>ve</b> to zoom to the titleblock extents.
 216                         Lock the titleblock with the menu <b>Edit->Lock</b>.
 217                         <li> Add components:<br>
 218                         From the <b>analog</b> library three <b>resistor-1.sym</b> and
 219                         two <b>dual-opamp-1.sym</b>.<br>
 220                         From the <b>io</b> library one <b>output-2.sym</b>.<br>
 221                         From the <b>power</b> library one <b>gnd-1.sym</b>
 222                         two <b>vcc-1.sym</b> and two <b>vee-1.sym</b>
 223                         </li>
 224                         <li> Move components with the middle mouse button and rotate
 225                         selected components by hitting keys <b>er</b> until everything
 226                         is placed nicely.  Rotate the bottom opamp and mirror it with
 227                         the <b>ei</b> keys.
 228                         </li>
 229                         <li> Use the <b>n</b> key and the mouse to draw net connections.
 230                         </li>
 231                 </ul>
 232                 </td>
 233         </tr>
 234         </table>
 235 <p>
 236 Edit the attributes of the components on the schematic.
 237 <p>
 238         <table border=1>
 239         <tr bgcolor=#b0b0a8>
 240                 <td>
 241                 <img src="images/one-sch-2.png" alt="images/one-sch-2.png"
 242                         border="0" align="top"><br> <center>one.sch</center>
 243                 </td>
 244                 <td>
 245                 For each component, select it and bring up its attributes
 246                 window by hitting keys <b>ee</b>.  Do not edit the <b>refdes</b>
 247                 attribute here, but do make these edits:
 248                 <ul>
 249                         <li> For resistors and the opamps, add visible <b>value</b>
 250                         attributes and assign appropriate values to them (10K, TL072).
 251                         Move these newly visible attributes to nice locations with the
 252                         middle mouse button.  Zoom in and repeat clicking the middle mouse
 253                         button if it is difficult to select them.
 254
 255                         </li>
 256                         <li> For the resistors, add a <b>footprint</b> attribute and
 257                         give it the value <b>R025</b> which is the PCB <i>m4 element</i>
 258                         for a 1/4 watt resistor.  Make this attribute invisible.
 259                         </li>
 260                         <li> For the opamps, edit the already existing <b>footprint</b>
 261                         attribute to be <b>DIL 8 300</b>.  Yes, include those spaces
 262                         because <b>DIL</b> is a <b>m4 element</b> that takes two args.
 263                         We're telling it to make a dual in line package with 8 pins in a
 264                         300 mil package.
 265                         Edit the <b>slot</b> attribute of
 266                         the second opamp to be <b>2</b>.  Its I/O pin numbers should
 267                         change from (1,2,3) to (5,6,7).
 268                         </li>
 269                         <li> For the output module port, edit its <b>net</b> attribute
 270                         to be <b>vmixer:1</b> and make it invisible.  Edit its <b>value</b>
 271                         attribute to be <b>Vmixer</b>.
 272                         </li>
 273                 </ul>
 274                 </td>
 275         </tr>
 276         </table>
 277 <p>
 278         It may have occurred to you that this editing will be painful for a
 279         schematic with a large number of components that don't have reasonable
 280         initial attribute values.  At least for the footprints,
 281         there are a couple of things that could help.  You can create your own
 282         library symbols having an initial <b>footprint</b> (and even <b>value</b>)
 283         attribute default that covers most of your uses.  Or, when you add your
 284         first component, edit it to have a good footprint default and then copy it
 285         (select it and hit the <b>ec</b> keys) for all
 286         remaining components instead of adding them from the library.<br>
 287         Anyway, we're done for now with <b>one.sch</b>, so save it with
 288         the menu <b>File->Save Page</b> and quit gschem.
 289         </blockquote>
 290         <h4> Create schematic: two.sch</h4>
 291         <blockquote>
 292         This will be really trivial and stupid since we're doing it only to
 293         demonstrate multiple schematic capability.  Run <b>gschem two.sch:</b>
 294         <p>
 295         </blockquote>
 296         <table border=1>
 297         <tr bgcolor=#b0b0a8>
 298                 <td>
 299                 <img src="images/two-sch-1.png" alt="images/two-sch-1.png"
 300                         border="0" align="top"><br> <center>two.sch</center>
 301                 </td>
 302                 <td>
 303                 <ul>
 304                         <li> Add component <b>title-B.sym</b> as you did in one.sch.
 305                         <li> Add components:<br>
 306                         From the <b>io</b> library one <b>input-2.sym</b>.<br>
 307                         From the <b>analog</b> library one <b>resistor-1.sym</b>.<br>
 308                         From the <b>transistor</b> library one <b>2N3904-1.sym</b>.<br>
 309                         From the <b>power</b> library one <b>gnd-1.sym</b>,
 310                         one <b>vcc-1.sym</b> and one <b>vee-1.sym</b>.<br>
 311                         From the <b>connector</b> library one <b>BNC-1.sym</b>
 312                         </li>
 313                         <li> Move components and draw nets as before.
 314                         </li>
 315                         <li> Edit component attributes:<br>
 316                         Input module port: edit <b>net</b> attribute to be invisible
 317                         and have value <b>vmixer:1</b>
 318                         so this net will be connected
 319                         to the <b>vmixer</b> in one.sch.
 320                         Make the <b>value</b> attribute be <b>Vmixer</b>.<br>
 321                         Resistor: give it invisible <b>footprint</b> attribute
 322                         <b>R025</b>
 323                         and a visible <b>value</b> attribute 10K.<br>
 324                         Transistor: add <b>value</b> attribute <b>2N3904</b> and
 325                         invisible <b>footprint</b> attribute <b>TO92</b>.<br>
 326                         BNC connector: add invisible <b>footprint</b> attribute
 327                         <b>CONNECTOR 2 1</b>.
 328                         which is a <b>m4 element</b> that takes arguments
 329                         and we're telling it to make a connector with 2 rows and 1 column.
 330                         We put a BNC connector on the schematic, but I'm pretending
 331                         we'll just jumper wires from this pc board header to a panel
 332                         mounted connector.
 333                         </li>
 334                 </ul>
 335                 </td>
 336         </tr>
 337         </table>
 338         <blockquote>
 339         <p>
 340         Unfortunately, the 2N3904 symbol we added has the text "2N3904" as an
 341         integral part of its symbol.  So when we add the <b>value</b> attribute
 342         (which we want so the PCB layout will show appropriate values), there are
 343         two "2N3904" designations visible on our schematic unless we would
 344         make the <b>value</b>
 345         attribute invisible.  This is not good and for this example
 346         we have to live with it, but note that in most cases it's not a good
 347         idea to hardwire information into symbols like this.
 348         Also the default <b>device</b> attribute
 349         is wrong and should be <b>NPN_TRANSISTOR</b> but it won't affect
 350         this tutorial.  This is just to inform you that currently there
 351         are some symbols in gschem that carry over outdated
 352         attribute usage from older versions of gschem.  If you get into
 353         running spice on schematics, then your symbols will need to have
 354         proper <b>device</b> attributes.
 355         <p>
 356         Now we are done with the schematics except for assigning <b>refdes</b>
 357         attributes and we can use the command <b>refdes_renum</b> to do this
 358         for both schematics at once.  So, save <b>two.sch</b>, quit gschem and run:
 359         <blockquote><pre>
 360 $ refdes_renum --pgskip one.sch two.sch
 361         </pre></blockquote>
 362         and run gschem on the schematics again to see how the components
 363         have been given a <b>refdes</b> attribute.  The <i>--pgksip</i> option
 364         makes numbering begin at 101 for one.sch and at 201 for two.sch.
 365         But you should know that
 366         running <b>refdes_renum</b> is really only useful for an initial
 367         numbering.  If you later edit your schematics and add or delete
 368         components, there is no guarantee when rerunning <b>refdes_renum</b>
 369         that components will keep an
 370         existing <b>refdes</b> value.  If in the meantime you've generated
 371         a pc board using gsch2pcb, this reference designator number mixup
 372         will put your schematics out of sync with your PCB layout.  So,
 373         after you initially run <b>refdes_renum</b> and start a PCB
 374         layout, to be safe you will
 375         need to manually add (unique) <b>refdes</b> attributes for any
 376         schematic components you might add.  Also note that <b>refdes_renum</b> may
 377         number your resistors differently than it did for my examples here
 378         depending on the order in which resistors were added.  Keep that in
 379         mind when comparing your eventual PCB layout to what you see in the
 380         images below.
 381         </blockquote>
 382         <h4> Generate PCB Files from Schematics</h4>
 383         <blockquote>
 384         We have to fix one thing in <b>one.sch</b> before we can proceed.
 385         Run <b>gschem one.sch</b> and notice that <b>refdes_renum</b> has
 386         given our opamps <b>refdes</b> values of <b>U101</b> and <b>U102</b>
 387         and did not know we really want to be using two opamps out of a single
 388         TL072 package.  That's why we edited the <b>slot</b> attribute of the
 389         second opamp.  We have to go back and fix this by editing the
 390         <b>refdes</b> attribute of the second opamp to be <b>U101</b> so
 391         both opamps will have the same <b>refdes</b>
 392         and there will be only one TL072 package on our pc board.
 393         <p>
 394         Now, since we have already set up a gsch2pcb <b>project</b> file,
 395         all we need to do to create an initial set of PCB files is to run
 396         gsch2pcb:
 397         <blockquote><pre>
 398 ~/gaf/myproject1$ gsch2pcb project
 399 0 file elements and 7 m4 elements added to board.pcb.
 400         </pre></blockquote>
 401         Since the project file specifed <b>board</b> as the output-name,
 402         the PCB files created are named <b>board.pcb</b> and <b>board.net</b>.
 403         <p>
 404         If you get output from gsch2pcb like:
 405         <i>2 unknown elements added to board.pcb.</i>, then run with the -v
 406         flag: <b>gsch2pcb -v project</b> and the gsch2pcb output will tell
 407         you which schematic components don't have a known <b>footprint</b>.  Either
 408         you forgot to add the attribute, the
 409         attribute value is wrong,
 410         or the PCB element for it is missing from your installation.  But if
 411         gsch2pcb can't find any elements and all 7 are unknown, then probably
 412         gsch2pcb can't find your PCB m4 install directory.  In this case,
 413         look at the first part of the
 414         <a href="tutorial.html#CUSTOM_M4"> Custom M4 Elements </a> section.
 415         </blockquote>
 416
 417         <h4> Layout PCB Files</h4>
 418         <blockquote>
 419         When you run PCB on a <b>.pcb</b> file for the first time as in Step 1
 420         below, you should set up various intial values.  I usually set a
 421         25 mil grid spacing with <b>Screen->25 mil</b> for the bulk of my
 422         layout work and then change grid spacing to smaller values as needed
 423         for tight layout situations.  You should also set the default line
 424         and via sizes you
 425         want for Signal, Power, Fat, and Skinny drawing in the
 426         <b>Sizes->adjust...</b> menu.  Then select the routing style you want
 427         to use from the <b>Sizes</b> menu. You can set your
 428         board size now or wait until later with <b>Edit->change board size</b>.
 429         And it may be useful to you to set <b>Screen->display grid</b>.
 430
 431         </blockquote>
 432         <table cellspacing=10>
 433         <tr>
 434                 <td>
 435                         <table border=1>
 436                         <tr bgcolor=#b0b0a8>
 437                         <td>
 438                         <img src="images/board-1.png" alt="images/board-1.png"
 439                                 border="0" align="top"><br> <center>Step 1</center>
 440                         </td>
 441                         <td>
 442                         Run <b>pcb board.pcb</b>
 443                         <p>
 444                         You'll see grouped into a big pile the PCB elements for all
 445                         the schematic component footprints.
 446                         </td>
 447                         </tr></table>
 448                 </td>
 449                 <td>
 450                         <table border=1>
 451                         <tr bgcolor=#b0b0a8>
 452
 453                         <td>
 454                         <img src="images/board-2.png" alt="images/board-2.png"
 455                                 border="0" align="top"><br> <center>Step 2</center>
 456                         </td>
 457                         <td>
 458                                 Use the middle mouse button to grab and move elements one
 459                                 at a time until you have separated all the elements.
 460                         </td>
 461                         </tr></table>
 462                 </td>
 463         </tr>
 464
 465         <tr>
 466                 <td>
 467                         <table border=1>
 468                         <tr bgcolor=#b0b0a8>
 469                         <td>
 470                         <img src="images/board-3.png" alt="images/board-3.png"
 471                                 border="0" align="top"><br> <center>Step 3</center>
 472                         </td>
 473                         <td>
 474                         <ul>
 475                                 <li><b>File->load netlist file</b> and select <b>board.net</b>
 476                                 </li>
 477                                 <li><b>Connects->optimize rats-nest</b>
 478                                 </li>
 479                                 <li>As you move elements around in later steps,
 480                                 it will clean up the lines to re-do the optimize rats-nest.
 481                                 </li>
 482                         </ul>
 483                         </tr></table>
 484                 </td>
 485                 <td>
 486                         <table border=1>
 487                         <tr bgcolor=#b0b0a8>
 488
 489                         <td>
 490                         <img src="images/board-4.png" alt="images/board-4.png"
 491                                 border="0" align="top"><br> <center>Step 4</center>
 492                         </td>
 493                         <td>
 494                                 Select the <b>ROT</b> tool and move elements with the
 495                                 middle mouse button and rotate them with the left mouse
 496                                 button until the rats-nest lines look minimized.  Hit the
 497                                 <b>f</b> key with the mouse on a pin to highlight
 498                                 particular routes to help visualize the routes.  <b>Shift f</b>
 499                                 to unhighlight.
 500                         </td>
 501                         </tr></table>
 502                 </td>
 503         </tr>
 504         </table>
 505
 506         <blockquote>
 507         Note: you can use the PCB auto placement feature instead of
 508         manually placing the components as described above.  To do this
 509         you would load the netlist, select the components you want to be
 510         autoplaced (if this is the first PCB run, just <b>Select->select all
 511         objects</b>) then do <b>Select->auto place selected elements</b>.
 512         Then you can manually tune the PCB generated placements.
 513         <p>
 514         At this point you can start routing traces between pins connected
 515         by rats nest lines.  On the left PCB toolbar,
 516         select the <b>LINE</b> tool, select the layer you want to draw on
 517         (solder, component, etc), and start drawing lines by selecting
 518         endpoints with the left
 519         mouse button.  Again, it can help to use the <b>f</b> key to highlight
 520         routes that need to be connected.
 521         If you want to stop the current trace so you can start
 522         drawing a new trace somewhere else, finish the current trace with
 523         a middle mouse click.  Or you can play with auto routing here.
 524         <p>
 525         A very useful operation with the <b>SEL</b>
 526         tool is to select multiple objects and then cut or copy them to a
 527         buffer with the menu <b>Buffer->cut selection to buffer</b> (or copy).
 528         You can immediately paste the buffer contents or abort the current
 529         paste by selecting another tool.  The buffer contents can be pasted
 530         any time later with <b>Buffer->paste buffer to layout</b>.  With
 531         this you can move layout
 532         areas around or step and repeat common trace patterns.  To
 533         select multiple objects with the <b>SEL</b> tool, click and drag
 534         to select rectangular regions, and SHIFT click to toggle additional
 535         selections to the currently selected set.
 536         <p>
 537         When you've finished routing the traces (PCB will congratulate you if all
 538         traces are routed when you optimze the rats nest) the board can look
 539         something like this.  For this view I've selected <b>Screen->value</b>.
 540         <p>
 541         <center><table border=1>
 542         <tr bgcolor=#b0b0a8>
 543                 <td>
 544                 <img src="images/board-5.png" alt="images/board-5.png"
 545                         border="0" align="top">
 546                 </td>
 547         </tr>
 548         </table></center>
 549         <p>
 550         You will want more information on using PCB and there is a set
 551         of html docs in the PCB source tarball.  I don't know of a link to
 552         put here, but you can get the latest tarball from the
 553         <a href="http://sourceforge.net/projects/pcb/"
 554         name="1.99 development">PCB 1.99 development </a> site.
 555         Or the docs may be installed somewhere on your system.
 556         The Debian package has them installed in <b>/usr/share/doc/pcb/html/</b>.
 557         </blockquote>
 558
 559
 560 <h3>Modifying Schematics</h3>
 561 <blockquote>
 562         The process of transfering schematic modifications to your PCB layout is
 563         made very simple by using gsch2pcb.  After the first <b>board.pcb</b>
 564         was created when you initially ran gsch2pcb,
 565         each time you run gschem on
 566         your schematics and make changes, run <b>gsch2pcb project</b>.  Then run
 567         <b>pcb board.pcb</b> and do whatever is necessary based on the work
 568         gsch2pcb has done.  Each time gsch2pcb is run, this will happen:
 569 <ul>
 570         <li> gsch2pcb always generates a new <b>board.net</b>.  If the net
 571                 was changed, load the new netlist file when you run pcb.
 572         <li> If you added components (with a footprint attribute) to a schematic
 573                 gsch2pcb will generate a <b>board.new.pcb</b> containing all the
 574                 new PCB elements corresponding to the footprints.
 575                 You then run <b>pcb board.pcb</b> and load the <b>board.new.pcb</b>
 576                 with new elements into
 577                 the existing layout with <b>File->load layout data to paste-buffer</b>.
 578                 Place the new elements, load the new netlist, and route new traces.<br>
 579         </li>
 580         <li> If you deleted components from a schematic, gsch2pcb will delete
 581                 the corresponding PCB elements from <b>board.pcb</b>.  You only
 582                 need to run <b>pcb board.pcb</b> and clean up dangling traces from
 583                 around the deleted elements.
 584         </li>
 585         <li> If you change an existing component's <b>footprint</b>, gsch2pcb
 586                 will delete the corresponding old element from <b>board.pcb</b>
 587                 and add the new element to <b>board.new.pcb</b>.
 588         </li>
 589         <li> If you changed schematic component <b>value</b> attributes, the
 590                 value changes will be forward annotated to <b>board.pcb</b> in place.
 591         </li>
 592 </ul>
 593         So by using gsch2pcb, all PCB element changes are driven by the
 594         schematics and you should never need to manually add or delete elements
 595         for schematic components.
 596         <p>
 597         However, you will need to manually add PCB
 598         elements that are not part of the schematics such as pc board mounting
 599         holes.  For these manually added PCB elements, make sure you never give
 600         them a <b>name on PCB</b> name because that is reserved for schematic
 601         component <b>refdes</b> attributes and gsch2pcb will want to delete
 602         elements which have a non-empty <b>name on PCB</b> and don't match
 603         any schematic component <b>refdes</b>.
 604         <p>
 605         Now, so far we've only used <b>m4 elements</b> in our layout so let's
 606         modify a schematic to use a <b>file element</b>.  But first, it would
 607         help to know about the default elements PCB provides.  Depending
 608         on the location of your PCB install there will be a directory
 609         <b>/usr/local/share/pcb/newlib, /usr/share/pcb/newlib</b>, or possibly
 610         something else (depending on the <i>prefix</i> specified when PCB
 611         was installed).  PCB versions before 20031113 used <b>pcb_lib</b> instead
 612         of <b>newlib</b> in the locations
 613         <b>/usr/local/pcb_lib, </b> or <b>/usr/lib/pcb_lib,</b>.
 614         Once you find your <b>newlib</b> directory,
 615         look at the file names in each subdirectory.  Each file name
 616         is a name which may be used as a <b>footprint</b> attribute
 617         for a schematic component.  For example, there is the file
 618         <b>xxx/newlib/2_pin_thru-hole_packages/0.125W_Carbon_Resistor</b>
 619         so if we wanted 1/8 watt resistors on our layout, we could
 620         use <b>0.125W_Carbon_Resistor</b> as the resistor <b>footprint</b>
 621         attribute instead of <b>R025</b>.  Try changing, say resistor R101 to
 622         use <b>0.125W_Carbon_Resistor</b> in <b>one.sch</b> and
 623         then run <b>gsch2pcb project</b>.  If gsch2pcb does not find
 624         this element, then you need to add your <b>newlib</b>
 625         directory to your <b>project</b> file with a line like:
 626         <blockquote><pre>
 627 elements-dir /usr/lib/newlib
 628         </pre></blockquote>
 629         If gsch2pcb does find it, you will get:
 630         <blockquote><pre>
 631 ~/gaf/myproject1$ gsch2pcb project
 632 board.pcb is backed up as board.pcb.bak1.
 633 1 elements deleted from board.pcb.
 634 1 file elements and 0 m4 elements added to board.new.pcb.
 635         </pre></blockquote>
 636         Now you need to run <b>pcb board.pcb</b>.  You will see that the
 637         element for resistor R101 is gone and that you will get the
 638         new element by loading <b>board.new.pcb</b> with
 639         <b>File->load layout data to paste-buffer</b>.
 640         <p>
 641
 642
 643 </blockquote>
 644
 645 <h3>Custom gschem Symbols</h3>
 646 <blockquote>
 647         A common way to generate a custom symbol is to start with an
 648         existing symbol and modify it.  One thing I don't like about
 649         the <b>dual-opamp-1.sym</b> we used is that the power pins are
 650         repeated on each symbol.  While some will prefer this, I
 651         think it makes a page full of opamps
 652         look a little cluttered and it presents a good opportunity to
 653         learn about <b>net</b> attributes in this tutorial.
 654         It's possible with gschem for symbols to
 655         have <b>net</b> attributes which can assign pins to a particular
 656         net.  Instead of hooking up each opamp pin 8 to Vcc and pin 4 to
 657         to Vee on the schematic, we can have that happen automatically and
 658         eliminate the pins on the schematic.  To do this, just copy the
 659         original symbol to our custom gschem symbol directory, giving it
 660         a new name,  and edit it. Do these
 661         steps (however, your gEDA symbol install directory may be something
 662         different like <b>/usr/local/share/gEDA/sym/</b>):
 663         <blockquote><pre>
 664 cd /usr/share/gEDA/sym/analog/
 665 cp dual-opamp-1.sym ~/gaf/gschem-sym/opamp-dual.sym
 666 cd ~/gaf/gschem-sym
 667 gschem opamp-dual.sym
 668         </pre></blockquote>
 669
 670         </blockquote>
 671         <table cellspacing=10>
 672         <tr>
 673                 <td>
 674                         <table border=1>
 675                         <tr bgcolor=#b0b0a8>
 676                         <td>
 677                         <img src="images/gschem-sym-1.png" alt="images/gschem-sym-1.png"
 678                                 border="0" align="top"><br> <center>Step 1</center>
 679                         </td>
 680                         <td>
 681                         <ul>
 682                                 <li>Hit keys <b>en</b> to make attributes visible.
 683                                 </li>
 684                                 <li>Hit keys <b>ve</b> to view extents.
 685                                 </li>
 686                                 <li>Left mouse click on pin 8 to select it.
 687                                 </li>
 688                         </ul>
 689
 690                         </td>
 691                         </tr></table>
 692                 </td>
 693                 <td>
 694                         <table border=1>
 695                         <tr bgcolor=#b0b0a8>
 696                         <td>
 697                         <img src="images/gschem-sym-2.png" alt="images/gschem-sym-2.png"
 698                                 border="0" align="top"><br> <center>Step 2</center>
 699                         </td>
 700                         <td>
 701                         <ul>
 702                                 <li>Hit <b>Delete</b> key to delete pin 8.
 703                                 </li>
 704                                 <li>Similarly select and delete pin 4.
 705                                 </li>
 706                                 <li>Double click to select and edit the <b>slotdef</b>
 707                                         lines.  Edit them by removing the pins 4 and 8.
 708                         </ul>
 709
 710                         </td>
 711                         </tr></table>
 712                 </td>
 713         </tr>
 714
 715         <tr>
 716                 <td>
 717                         <table border=1>
 718                         <tr bgcolor=#b0b0a8>
 719                         <td>
 720                         <img src="images/gschem-sym-3.png" alt="images/gschem-sym-3.png"
 721                                 border="0" align="top"><br> <center>Step 3</center>
 722                         </td>
 723                         <td>
 724                         From the menu <b>Add->Attribute</b>
 725                         <ul>
 726                                 <li>Add a <b>net</b> attribute with value <b>Vcc:8</b>
 727                                         Select <b>Show Name & Value</b> and make it invisible.
 728                                 </li>
 729                                 <li>Add a <b>net</b> attribute with value <b>Vee:4</b>
 730                                         Make it <b>Show Name & Value</b> and invisible.
 731                                 </li>
 732                                 <li>Make the <b>device</b> attribute be just <b>OPAMP</b>.
 733                                 </li>
 734                         </ul>
 735                         Clean up by moving these new attributes as shown.<br>
 736                         Change the footprint default if you wish.
 737                         </tr></table>
 738                 </td>
 739         </tr>
 740         </table>
 741
 742         <blockquote>
 743         When all the edits are done, it's very important when editing
 744         symbols to do a <b>Edit->Symbol Translate</b> to zero before saving.
 745         Do that and then save the symbol with <b>File->Save Page</b>
 746         I made the <b>footprint</b> default be <b>DIP8</b> because I have
 747         that as a custom element.
 748         <p>
 749         Run <b>gschem one.sch</b>.  Select and delete with the <b>Delete</b>
 750         key both opamps.  Also delete the <b>Vcc</b> and <b>Vee</b> symbols that
 751         were connected to them.  Bring up the Add Components window
 752         and from the <b>gschem-sym</b> library which should now have your
 753         new custom symbol, place two of the <b>opamp-dual.sym</b>
 754         Move them to the right place on the schematic and don't forget to
 755         mirror and rotate the bottom opamp as before.  Edit the attributes
 756         of each opamp giving them the same attributes they had, that
 757         is make the <b>footprint</b> be <b>DIL 8 300</b>, add a <b>value</b>
 758         attribute of <b>TL072</b>, and make the <b>refdes</b> of both
 759         opamps be <b>U101</b>.  Make the <b>slot</b> of the second opamp
 760         be <b>2</b>.  If you don't make the attributes the same as they were
 761         before, gsch2pcb will think it is a different component and delete the
 762         existing <b>DIL</b> package from the layout.  If you did everything
 763         right, running gsch2pcb should give:
 764         <blockquote><pre>
 765 ~/gaf/myproject1$ gsch2pcb project
 766 Found a cpinlist head with a netname! [Vcc]
 767 Found a cpinlist head with a netname! [Vee]
 768 Found a cpinlist head with a netname! [Vcc]
 769 Found a cpinlist head with a netname! [Vee]
 770 Found a cpinlist head with a netname! [Vcc]
 771 Found a cpinlist head with a netname! [Vee]
 772 Found a cpinlist head with a netname! [Vcc]
 773 Found a cpinlist head with a netname! [Vee]
 774 No elements to add so not creating board.new.pcb
 775 </pre></blockquote>
 776 Where the gEDA gnetlist program seems a bit excited about finding the new
 777 Vcc and Vee <b>net</b> attributes we just added, and a new netlist
 778 was generated.  Now I think the schematic looks
 779 cleaner:
 780         <p>
 781         <center><table border=1>
 782         <tr bgcolor=#b0b0a8>
 783                 <td>
 784                 <img src="images/one-sch-3.png" alt="images/one-sch-3.png"
 785                         border="0" align="top"><br> <center>one.sch</center>
 786                 </td>
 787         </tr>
 788         </table></center>
 789         <p>
 790         And if you run <b>pcb board.pcb</b> and load the new netlist and then
 791         optimize the rats nest, PCB should tell you the board is complete
 792         which means connecting the opamp power pins via the <b>net</b>
 793         attribute has worked.
 794         <p>
 795         For complete details on making symbols, read through the
 796         Symbol Creation Document on the
 797         <a href="http://www.geda.seul.org/docs/index.html"
 798                         name="gEDA Documentation"> gEDA Documentation </a> page.<br>
 799         </blockquote>
 800
 801
 802
 803
 804 <h3>Custom <i>file elements</i></h3>
 805 <blockquote>
 806         You can create custom <b>file elements</b>
 807         in the middle of running PCB on any layout or you can run PCB
 808         just for making the element.  As a demonstration, lets make a
 809         custom element for a 1N4004 diode.  There are axial packages
 810         provided by PCB, but we want to be sure the drill size will be
 811         right for this 1 amp
 812         diode with slightly fatter leads.  It needs about a 42 mil (#58) drill.
 813         <p>
 814         Run <b>pcb</b> and the first thing to do is go to the <b>Sizes</b>
 815         menu and select <b>adjust "Signal" sizes</b>.  Set the via hole
 816         to 42 and the via size to 70 or larger as you like.  Then make
 817         sure you use this via
 818         size by selecting <b>Sizes->use "Signal" routing style</b>.  Select
 819         <b>Screen->25 mil</b> and <b>Screen->display grid</b>.
 820         Zoom in a couple of steps, then make the element:
 821
 822         </blockquote>
 823         <table cellspacing=10>
 824         <tr>
 825                 <td>
 826                         <table border=1>
 827                         <tr bgcolor=#b0b0a8>
 828                         <td>
 829                         <img src="images/pcb-el-1.png" alt="images/pcb-el-1.png"
 830                                 border="0" align="top"><br> <center>Step 1</center>
 831                         </td>
 832                         <td>
 833                         <ul>
 834                                 <li>Select the <b>VIA</b> tool and place two vias 400 mils
 835                                 apart.</li>
 836                                 <li>With the mouse on the left via, hit the <b>n</b>
 837                                 key and give the via the name <b>1</b>.  Give the
 838                                 right via the name <b>2</b>
 839                                 </li>
 840                                 <li> Pin 1 will be the cathode and this must agree with the
 841                                 pin numbers in your diode gschem symbol.
 842                                 </li>
 843                         </ul>
 844
 845                         </td>
 846                         </tr></table>
 847                 </td>
 848                 <td>
 849                         <table border=1>
 850                         <tr bgcolor=#b0b0a8>
 851                         <td>
 852                         <img src="images/pcb-el-2.png" alt="images/pcb-el-2.png"
 853                                 border="0" align="top"><br> <center>Step 2</center>
 854                         </td>
 855                         <td>
 856                         <ul>
 857                                 <li>Select the <b>Silk</b> layer and the <b>LINE</b> tool.
 858                                 </li>
 859                                 <li>Draw the component outline as shown with line width set
 860                                         to 10 mils and the grid setting set to 10 mils.
 861                                 </li>
 862                                 <li>Draw the left fat cathode indicator with three lines after
 863                                         setting the line width to 20 mils.
 864                                 </li>
 865                                 <li> Don't let silk layer lines overlap solder pads. </li>
 866                         </ul>
 867
 868                         </td>
 869                         </tr></table>
 870                 </td>
 871         </tr>
 872         </table>
 873         <blockquote>
 874
 875         Select the vias and the outline just drawn using the <b>SEL</b> tool
 876         and finish making the element:
 877         <ul>
 878                 <li><b>Buffer->cut selection to buffer</b> and move the cursor
 879                         to the center of the left via and click.
 880                 </li>
 881                 <li><b>Buffer->convert buffer to element</b>
 882                 </li>
 883                 <li><b>Buffer->save buffer elements to file</b> and navigate to
 884                         <b>~/gaf/pcb-elements</b> and save the element as
 885                         <b>D400-1A</b> since it's a package for a 1A diode with
 886                         400 mil spaced pins.  Or give it any descriptive name you like.
 887         </ul>
 888         <b>Note:</b> if you save the element with a name which is the same
 889         as a <b>m4 element</b>, gsch2pcb will preferentially use the m4
 890         element unless you give gsch2pcb the --use-files (or -f) option.
 891         You may put <b>use-files</b> in a project file if you want to always
 892         give priority to using <b>file elements</b>.  The m4 element names appear
 893         to use upper case, so you could also avoid the problem by using
 894         lower case in your file element names.  Also, the only way I know to make
 895         the pin 1 of the symbol square is to edit the D400-1A file manually and
 896         change the square flag in the Pin "1" line.  For example, change the
 897         line:
 898         <blockquote><pre>
 899     Pin(0 0 70 20 70 42 "" "1" 0x00000001)
 900 to:
 901     Pin(0 0 70 20 70 42 "" "1" 0x00000101)
 902         </pre></blockquote>
 903
 904         You can now use <b>D400-1A</b> in a gschem schematic symbol
 905         <b>footprint</b> attribute and gsch2pcb will find it provided
 906         you have made the <b>packages</b> link described in the <b>Setup</b>
 907         section.  If you have not made that link, you can still tell gsch2pcb
 908         about the elements directory with a line in a project file:
 909         <blockquote><pre>
 910 elements-dir ~/gaf/pcb-elements
 911         </pre></blockquote>
 912
 913         Possibly you've noticed, but there are some things not right about the
 914         <b>myproject1</b> example.  For one thing, silk layer lines are
 915         overlapping solder pads on some of the elements, and for another,
 916         the transistor is backwards on the layout!
 917         You otherwise shouldn't have a problem like this when working
 918         with gschem and PCB, but transistor pin numbering can be confusing.
 919         If you will be using transistors in your designs, here's a description
 920         of my approach to
 921         making sure my gschem transistor symbol pin numbering is
 922         coordinated with PCB element pin numbers:
 923         <a href="transistor-guide.html" name="transistor-guide.html">
 924         transistor guide.</a>
 925         <p>
 926         From the transistor guide, you can see that the problem here is that
 927         the <b>TO92</b> element has its pins numbered
 928         in the less common (3,2,1) configuration while the <b>2N3904-1.sym</b>
 929         is like a npn-ebc symbol which needs a (1,2,3) numbering.  You can
 930         see the 2N3904 pin numbers in gschem by hitting the <b>en</b> keys
 931         (and don't be confused by the <b>pinseq</b> attribute that nearly
 932         covers up the <b>pinnumber</b>).  And in PCB, you can see the <b>TO92</b>
 933         pin numbers by hitting the <b>d</b> key with the mouse over
 934         the element.  To be sure you are seeing pin numbers and not pin
 935         names, select <b>Screen->pinout shows number</b>.
 936         <p>
 937         I have libraries with transistor symbols and elements that you might
 938         find useful, so as a convenience you can get your custom
 939         libraries initially populated by installing my
 940         <a href="gsch2pcb-libs-20040110.tar.gz"
 941         name="gsch2pcb-libs-20040110.tar.gz"> gschem/PCB libraries </a>.
 942         Untar them under ~/gaf to mirror the setup of our example
 943         and there will also be a
 944         <b>~/gaf/pcb-elements.Readme</b> which documents the PCB elements.
 945         <blockquote>
 946         <i>Note: as of 1/10/2004 I've corrected the tarball pcb elements
 947         to not overlap solder pads with silk layer lines.</i>
 948         </blockquote>
 949         If you untar them somewhere else,
 950         you will need to make sure that gschem knows about them with
 951         gschemrc/gnetlistrc <b>component-library</b> lines and that
 952         gsch2pcb can find them with <b>elements-dir</b> lines in a
 953         project file.
 954         <p>
 955         If you install them, you can fix Q201 in <b>two.sch</b>
 956         by changing its footprint to <b>TO-92</b> which is my custom
 957         element with (1,2,3) pin numbering.
 958         Then run <b>gsch2pcb project</b>
 959         and then <b>pcb board.pcb</b> and load the new element for
 960         the transistor.  In the next images, <b>two.sch</b> is showing
 961         the <b>footprint</b> attribute visible to emphasize it, and it also
 962         shows a new symbol for the 2N3904 which I created from my
 963         custom <b>npn-ebc.sym</b> as described in my transistor guide.
 964           In the updated board.pcb layout,
 965         if you compare the outline appearance of the transistor to the original
 966         layout you see that the orientation is now correct and that silk layer
 967         lines don't overlap the solder pads.
 968         I also changed the <b>footprint</b> attribute for
 969         resistors R102 and R103 in <b>one.sch</b> to my custom
 970         1/8 watt <b>R0w8</b> and 1/4 watt <b>R0w4</b> elements to
 971         illustrate the differences in style you can have with
 972         custom elements.  You can also see the R101 style after its
 973         footprint was changed to <b>0.125W_Carbon_Resistor</b> as suggested
 974         above.  As you evaluate the differences in these styles, I'll mention
 975         that for my custom elements I wanted to maximize room to display
 976         value and refdes text (the 0.125W... element body could be a little
 977         larger) and I wanted the solder pad diameter a little larger
 978         so it will be more forgiving of board fabrication technique.
 979         Also, the resistor pin spacing for my <b>R0w4</b> is slightly less
 980         than in <b>R025</b> to improve component density.
 981
 982         </blockquote>
 983         <center><table cellspacing=30>
 984         <tr>
 985                 <td>
 986                         <table border=1>
 987                         <tr bgcolor=#b0b0a8>
 988                         <td>
 989                         <img src="images/two-sch-2.png" alt="images/two-sch-2.png"
 990                                 border="0" align="top"><br><center> two.sch</center>
 991                         </ul>
 992                         </td>
 993                         </tr></table>
 994                 </td>
 995                 <td>
 996                         <table border=1>
 997                         <tr bgcolor=#b0b0a8>
 998                         <td>
 999                         <img src="images/board-6.png" alt="images/board-6.png"
1000                                 border="0" align="top"><br>
1001                         </td>
1002                         </tr></table>
1003                 </td>
1004         </tr>
1005         </table></center>
1006         <blockquote>
1007 </blockquote>
1008
1009 <a name="CUSTOM_M4">
1010 <h3>Custom <i>m4 elements</i> (Requires gsch2pcb >= 1.0)</h3>
1011 <blockquote>
1012         First, some words about how to find out about
1013         the  default <b>m4 elements</b>
1014         available in PCB.  I think there is some documention forthcoming
1015         in the PCB project, but at this point I don't know of anything
1016         to refer you to
1017         and you can't just look at filenames as you can for
1018         the <b>file elements</b>.  Not only that, but many of these elements
1019         require arguments and you need to determine what they are.
1020         So for now all I can say is that the best
1021         way to find out what's available is to read the m4 element files and
1022         for this you need to know where the PCB
1023         m4 files install location is.  As of PCB 20031113 this install
1024         directory will most likely be <b>/usr/share/pcb/m4</b> or
1025         <b>/usr/local/share/pcb/m4</b>, while on earlier PCB versions it could be
1026         <b>/usr/X11R6/lib/X11/pcb/m4</b> (run <i>gsch2pcb --help</i> or
1027         <i>gsch2pcb -v project</i> to see which of these directories gsch2pcb
1028         is using).  But if your install is somewhere else you will
1029         have to track it down.  By the way, if the m4 directory <i>is</i> somewhere
1030         different from the above three, then gsch2pcb won't be finding your
1031         <b>m4 elements</b> in the above examples and you will need to add
1032         the correct m4 directory to your <b>project</b> file with a line like:
1033         <blockquote><pre>
1034 m4-pcbdir /path/to/pcb/m4
1035         </pre></blockquote>
1036
1037         Just read the <b>.inc</b> files in the m4 install directory.  For
1038         example, in the <b>misc.inc</b> file you will find the <b>R025</b> element
1039         we've used and it starts out with:
1040         <blockquote><pre>
1041 # -------------------------------------------------------------------
1042 # the definition of a resistor (0.25W) package
1043 # $1: canonical name
1044 # $2: name on PCB
1045 # $3: value
1046 define(`PKG_R025',
1047 `Element(0x00 "$1" "$2" "$3" 120 30 0 100 0x00)
1048 (
1049     ...
1050         </pre></blockquote>
1051 The information you can extract from this is that a m4 <b>PKG_</b> macro
1052 named <b>R025</b> is being defined and it takes 3 arguments.  Now, all PCB
1053 <b>m4 element</b> macros take at least three
1054 arguments and these are automatically
1055 filled in by gsch2pcb with the gschem attributes <b>footprint</b> for
1056 <b>canonical name</b>, <b>refdes</b> for <b>name on PCB</b>, and
1057 <b>value</b> for <b>value</b>.  The "canonical name" used in these
1058 m4 files is just an older way of referring to the current PCB usage of
1059 <b>description</b> as mentioned above in the <b>Terminology</b> section.
1060 Since these args are automatically filled in, you don't need to specify
1061 any additional args to <b>R025</b> when you use it as a gschem
1062 <b>footprint</b>.  But now look at the very next m4 element define
1063 in <b>misc.inc</b>:
1064         <blockquote><pre>
1065 # -------------------------------------------------------------------
1066 # the definition of a SIL package without a common pin
1067 # $1: canonical name
1068 # $2: name on PCB
1069 # $3: value
1070 # $4: number of pins
1071 define(`PKG_SIL',
1072     `define(`MAXY', `eval(`$4' * 100 -50)')
1073 Element(0x00 "$1" "$2" "$3" 160 10 3 100 0x00)
1074 (
1075     ...
1076         </pre></blockquote>
1077 From this you can determine there is a <b>SIL</b> package you can use
1078 as a <b>footprint</b>.  It has 4 arguments, but only the first three are
1079 handled automatically so there is one argument you must give when using it.
1080 You get a flash of insight and realize this is a "Single In Line" package!
1081 So, instead of the <b>CONNECTOR 2 1</b> element specifying 1 column we used
1082 in our example above, you might think we could have used <b>SIL 2</b>.
1083 But you would be wrong!  Because if you read the macro body you will see
1084 that if the argument is <b>2</b> the second forloop can't handle it.
1085 In fact, it will only work for arguments >= 4.  If you ever run gsch2pcb
1086 and it appears stuck in an infinite loop, a m4 macro argument problem
1087 is likely the cause.  As you look through <b>misc.inc</b> here's a summary
1088 of what you will find as possible elements you can use:
1089         <blockquote><pre>
1090 Package      Args you need to supply
1091   SD           1      number of pins of a ZIP package
1092   MULTIWATT15  0
1093   R025         0
1094   SIL          1      number of pins (we know now must be >= 4)
1095   CSIL         1      number of pins
1096   QFP132       0
1097   LED          1      diameter of LED
1098   DIODE_LAY    1      pin separation
1099   AXIAL_LAY    1      pin separation
1100   CRYSTAL      1      package width
1101   OSC          0
1102   ISA8         0
1103   OVEN_OSC     0
1104   RADIAL_CAN   1
1105   SMD_BASE     2      length and width of surface mount device
1106   SMD_CHIP     1      package length
1107
1108         </pre></blockquote>
1109 And so on for the other <b>.inc</b> files...
1110 <p>
1111
1112 The reality is that the m4 setup is less user friendly (you can't create
1113 the elements graphically) and more complicated (you need to understand
1114 m4 macros) than the simple
1115 <b>file element</b> approach.  So for most of your custom elements I
1116 suggest you are better off staying with <b>file elements</b>.  However,
1117 with the m4 macro method a single element
1118 definition that takes arguments gives you a programmable
1119 element which can be very useful for large pin count packages.
1120 It is particularly nice for IC packages with variable widths
1121 and number of pins, so a good example
1122 of using a custom <b>m4 element</b> would be to copy and modify to
1123 our taste the existing
1124 m4 macro for IC packages (the <b>DIL</b> macro) into a m4 file gsch2pcb
1125 will search.  The destination m4 file can be any of these:
1126         <ul>
1127                 <li><b>pcb.inc</b> in our <b>myproject1</b> directory and the custom
1128                         element will be local to this project.
1129                 </li>
1130                 <li><b>~/.pcb/pcb.inc</b> and the element will be known to all of
1131                         our projects.
1132                 </li>
1133                 <li><b>/path/to/anyfile</b> if this path is made known to gsch2pcb
1134                         by adding a line to a project file like:
1135                         <blockquote><pre>
1136 m4-file /path/to/anyfile
1137                         </pre></blockquote>
1138                         Depending on whether you want the file known only to this
1139                         project, to all of your projects, or to all projects of all
1140                         users, this line may be added to any of the project files:
1141                         <blockquote><pre>
1142 ~/gaf/myproject1/project
1143 ~/.gsch2pcb
1144 /usr/local/etc/gsch2pcb
1145 /etc/gsch2pcb
1146                         </pre></blockquote>
1147                 </li>
1148         </ul>
1149
1150         For this tutorial, I'll use the first <b>pcb.inc</b> way, so copy over
1151         the existing macro file:
1152         <blockquote><pre>
1153 cd /usr/local/share/pcb/m4  (or /usr/share/pcb/m4 or /usr/X11R6/lib/X11/pcb/m4)
1154 cp dil.inc ~/gaf/myproject1/pcb.inc
1155 cd ~/gaf/myproject1
1156         </pre></blockquote>
1157
1158 Now, edit the <b>pcb.inc</b> file you just copied and cut everything
1159 out except for the PKG_DIL macro.  Change the name of
1160 the package to something like PKG_DILFAT because the change we'll make
1161 will be to make larger diameter pins.  Actually, we could leave the name
1162 alone and our new definition would override the old one, but for now
1163 let's go with the new name.  Change the pin diameter from <b>60</b>
1164 to <b>70</b> on the <b>PIN</b> lines.
1165 When done, this should
1166 be the entire contents of the new <b>pcb.inc</b> file:
1167         <blockquote><pre>
1168 # -------------------------------------------------------------------
1169 # the definition of a dual-inline package N and similar types
1170 # $1: canonical name
1171 # $2: name on PCB
1172 # $3: value
1173 # $4: number of pins
1174 # $5: package size (300, 600, 900 + 100 for socket space)
1175 #
1176 define(`PKG_DILFAT',
1177     `define(`MAXY', `eval(`$4' / 2 * 100)')
1178     define(`MAXX', `eval(`$5' + 100)')
1179     define(`CENTERX', `eval(MAXX / 2)')
1180 Element(0x00 "$1" "$2" "$3" eval(CENTERX + 20) 100 3 100 0x00)
1181 (
1182     forloop(`i', 1, eval($4 / 2),
1183         `PIN(50, eval(i * 100 -50), 70, 28, i)
1184     ')
1185     forloop(`i', 1, eval($4 / 2),
1186         `PIN(eval(MAXX -50), eval(MAXY - i * 100 +50), 70, 28, eval(i + $4/2))
1187     ')
1188     ElementLine(0 0 0 MAXY 10)
1189     ElementLine(0 MAXY MAXX MAXY 10)
1190     ElementLine(MAXX MAXY MAXX 0 10)
1191     ElementLine(0 0 eval(CENTERX - 50) 0 10)
1192     ElementLine(eval(CENTERX + 50) 0 MAXX 0 10)
1193     ElementArc(CENTERX 0 50 50 0 180 10)
1194     Mark(50 50)
1195 )')
1196         </pre></blockquote>
1197
1198 Run <b>gschem one.sch</b> and edit the <b>footprint</b> attribute of
1199 the opamps to be <b>DILFAT 8 300</b>.
1200 Then run <b>gsch2pcb project</b>
1201 and gsch2pcb will remove the <b>DIL</b> element from <b>board.pcb</b>
1202 and add into <b>board.new.pcb</b> a new <b>DILFAT</b> element from your
1203 custom m4 file <b>pcb.inc</b>.  Run <b>pcb board.pcb</b> and
1204 load the <b>board.new.pcb</b> into
1205 your layout.  Move the new element with its fatter pins to the location
1206 left vacant by the removal of the old element.
1207 </blockquote>
1208
1209 <h3>Multi-user Setup (requires gsch2pcb >= 1.0)</h3>
1210 <blockquote>
1211 The above examples are oriented towards a single user with projects and
1212 custom gschem and PCB libraries under his home directory.  Here's a
1213 way to set up for multiple users who need to share resources:
1214         <ul>
1215                 <li> Put site wide custom PCB <b>file elements</b> under, for example,
1216                         <b>/usr/local/share/pcb/pcb-elements</b>.  Make this directory
1217                         searched by gsch2pcb for all users by putting a line into
1218                         <b>/etc/gsch2pcb</b> or <b>/usr/local/etc/gsch2pcb</b>:
1219                         <pre>
1220     elements-dir /usr/local/share/pcb/pcb-elements
1221                         </pre>
1222                         If there are any site wide custom PCB <b>m4 element</b> files,
1223                         for example, <b>/usr/local/share/pcb/pcb.inc</b>, add another
1224                         line into <b>/etc/gsch2pcb</b> or <b>/usr/local/etc/gsch2pcb</b>:
1225                         <pre>
1226     m4-file /usr/local/share/pcb/pcb.inc
1227                         </pre>
1228                 </li>
1229                 <li> If the default PCB m4 install is not
1230                         <b>/usr/local/share/pcb/m4, /usr/share/pcb/m4,</b> or
1231                         <b>/usr/X11R6/lib/X11/pcb/m4</b>, then make the install location
1232                         known to all users of gsch2pcb by putting into
1233                         <b>/etc/gsch2pcb</b> or <b>/usr/local/etc/gsch2pcb</b> the line:
1234                         <pre>
1235     m4-pcbdir /path/to/pcb/m4
1236                         </pre>
1237                         If the m4 program is gm4 instead of m4, add to the gsch2pcb file:
1238                         <pre>
1239     m4-command gm4
1240                         </pre>
1241                 </li>
1242                 <li> If there are site wide custom gschem symbols under some
1243                         directory, you will have to edit the system gschemrc and gnetlistrc
1244                         files and add <b>component-library</b> lines for them.
1245                 </li>
1246         </ul>
1247          With the above, users will have access to site wide libraries
1248         and only need to put in a design <b>project</b> file
1249         lines for <b>schematics</b> and <b>output-name</b>.  But they
1250         also are free to have their own additional user and/or project
1251         specific symbol and element libraries.
1252 </blockquote>
1253
1254 <h3>PC Board Fabrication</h3>
1255 <blockquote>
1256         Someday I may add some notes here on how I make pc boards.
1257 </blockquote>
1258
1259 <hr>
1260         <address>
1261         <p align=center>
1262         <a href="http://web.wt.net/~billw/gsch2pcb/gsch2pcb.html"
1263                 name="www.gkrellm.net">gsch2pcb Home</a>
1264         <br>
1265         Bill Wilson <A HREF="mailto:bill--at--gkrellm.net">bill--at--gkrellm.net</A>
1266         <br>
1267         </p>
1268         </address>
1269
1270
1271 </body>
1272 </html>