docs/wiki/geda-tragesym_tutorial.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html>
   4 <head>
   5   <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
   6   <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
   7   <link rel="stylesheet" media="print" type="text/css" href="./print.css" />
   8
   9   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  10 </head>
  11 <body>
  12
  13 <p>
  14 <em>Translations of this page are also available in the following languages:</em> <a href="geda-tragesym_tutorial.fr.html" class="wikilink1" title="geda-tragesym_tutorial.fr.html">Français</a>, <a href="geda-tragesym_tutorial.ru.html" class="wikilink1" title="geda-tragesym_tutorial.ru.html">Русский</a>.
  15 </p>
  16
  17 <h1 class="sectionedit1" id="creating_gschem_symbols_quickly_and_easily_using_tragesym_and_a_spreadsheet_program">Creating gschem symbols quickly and easily using tragesym and a spreadsheet program</h1>
  18 <div class="level1">
  19
  20 <p>
  21 Creating symbols for schematic capture can be very time consuming, error prone, and an all around pain. Luckily, gschem uses an open, text based file format that is very easy to use with scripting. This short tutorial describes how to use the tragesym script, to create symbols very quickly (probably more quickly than with any commercial package).
  22 </p>
  23
  24 </div>
  25 <!-- EDIT1 SECTION "Creating gschem symbols quickly and easily using tragesym and a spreadsheet program" [156-604] -->
  26 <h2 class="sectionedit2" id="required_steps">Required Steps</h2>
  27 <div class="level2">
  28 <ul>
  29 <li class="level1"><div class="li"> Step1: Open a tragesym template file</div>
  30 </li>
  31 <li class="level1"><div class="li"> Step2: Download the part data sheet and find the pin list</div>
  32 </li>
  33 <li class="level1"><div class="li"> Step3: Copy the pin list into an editor and prepare it</div>
  34 </li>
  35 <li class="level1"><div class="li"> Step4: Insert all missing data into the spreadsheet</div>
  36 </li>
  37 <li class="level1"><div class="li"> Step5: Export the spreadsheet into a tab separated text file</div>
  38 </li>
  39 <li class="level1"><div class="li"> Step6: execute tragesym and create the symbol</div>
  40 </li>
  41 <li class="level1"><div class="li"> Step7: check the result with gschem and do some artwork</div>
  42 </li>
  43 </ul>
  44
  45 </div>
  46 <!-- EDIT2 SECTION "Required Steps" [605-1027] -->
  47 <h2 class="sectionedit3" id="step1open_a_tragesym_template_file">Step1: Open a tragesym template file</h2>
  48 <div class="level2">
  49
  50 <p>
  51 tragesym comes with two template files. One is <a href="media/tragesym/template2.txt.src" class="media" target="_blank" title="tragesym:template2.txt.src">ASCII text</a>, the second is a <a href="media/tragesym/template2.ods" class="media" target="_blank" title="tragesym:template2.ods">OpenOffice spreadsheet file</a>. You can obtain them from the gEDA utility package, too (utils/examples/tragesym/template.src and utils/examples/tragesym/template.ods).
  52  If you prefer a different spreadsheet program, like gnumeric or kspread, just create your own template out of the textual template file. The only difference between the textual template and the spreadsheet template is the syntax of the key value pairs in the [options] and [geda_attr] sections. The textfile splits them with an equal sign (key=value), the spreadsheet has the value in the second column (which becomes a tab after being exported).
  53 </p>
  54
  55 </div>
  56 <!-- EDIT3 SECTION "Step1: Open a tragesym template file" [1028-1826] -->
  57 <h2 class="sectionedit4" id="step2download_the_part_data_sheet_and_find_the_pin_list">Step2: Download the part data sheet and find the pin list</h2>
  58 <div class="level2">
  59
  60 <p>
  61 For this example, we will create a symbol from the Philips Semiconductor PCA9555 16-bit IIC IO port. The description of product and datasheet is available at Philips:  <a href="http://www-us.semiconductors.philips.com/cgi-bin/pldb/pip/pca9555.html" class="urlextern" title="http://www-us.semiconductors.philips.com/cgi-bin/pldb/pip/pca9555.html" rel="nofollow">http://www-us.semiconductors.philips.com/cgi-bin/pldb/pip/pca9555.html</a>. Download the datasheet and open it with a pdf viewer that allows copying text out of the pdf file, such as kpdf or acroread. Flip through the pages until you find the pinout for the device:
  62 </p>
  63
  64 <p>
  65 <a href="media/tragesym/kpdf_pinconfiguration.png" class="media" target="_blank" title="tragesym:kpdf_pinconfiguration.png"><img src="media/tragesym/kpdf_pinconfiguration.png" class="media" alt="" /></a> <a href="media/tragesym/acroread_selectiontable.png" class="media" target="_blank" title="tragesym:acroread_selectiontable.png"><img src="media/tragesym/acroread_selectiontable.png" class="media" alt="" /></a>
  66 </p>
  67
  68 <p>
  69 Inside the datasheet the pin list may only be in the drawing of the pin configuration. If there’s a nice table, like in the second picture from a different datasheet, use this one.
  70 </p>
  71
  72 </div>
  73 <!-- EDIT4 SECTION "Step2: Download the part data sheet and find the pin list" [1827-2599] -->
  74 <h2 class="sectionedit5" id="step3copy_the_pin_list_into_an_editor_and_prepare_it">Step3: Copy the pin list into an editor and prepare it</h2>
  75 <div class="level2">
  76
  77 <p>
  78 Select the pin list and copy it into a text editor. This intermediate step is required as your spreadsheet program may need a special field separator, like comma or tab. You may have to remove duplicate separators or replace it with tabs.
  79 </p>
  80
  81 <p>
  82 <strong>Note:</strong> The selection behaviour of kpdf is different from the acroread viewer. The kpdf viewer seems to give you a copy that looks more like the graphical representation, while the acroread viewer produces an output that is more “file order” oriented. If you have to create a lot of symbols, try both and compare the results.
  83 </p>
  84
  85 <p>
  86 <a href="media/tragesym/xemacs_rawselection.png" class="media" target="_blank" title="tragesym:xemacs_rawselection.png"><img src="media/tragesym/xemacs_rawselection.png" class="media" alt="" /></a> <a href="media/tragesym/xemacs_modifiedselection.png" class="media" target="_blank" title="tragesym:xemacs_modifiedselection.png"><img src="media/tragesym/xemacs_modifiedselection.png" class="media" alt="" /></a> <a href="media/tragesym/ooo_selection.png" class="media" target="_blank" title="tragesym:ooo_selection.png"><img src="media/tragesym/ooo_selection.png" class="media" alt="" /></a>
  87 </p>
  88
  89 <p>
  90 The pictures above illustrate the steps:
  91 </p>
  92 <ul>
  93 <li class="level1"><div class="li"> insert the selection from your pdf viewer into a text editor</div>
  94 </li>
  95 <li class="level1 node"><div class="li"> modify the pinlist to make your spreadsheet program happy</div>
  96 <ul>
  97 <li class="level2"><div class="li"> cut out pinlist 24 to 13 with a rectangular selection</div>
  98 </li>
  99 <li class="level2"><div class="li"> insert the rectangular selection below the pins 1 to 12</div>
 100 </li>
 101 <li class="level2"><div class="li"> sort the lines (xemacs can do that <img src="images/smileys/icon_wink.gif" align="middle" alt=";-)" />)</div>
 102 </li>
 103 <li class="level2"><div class="li"> remove or repair the lines with the numbers 2,3,… They are not in the same line. You can easily recreate the pin numbers later</div>
 104 </li>
 105 <li class="level2"><div class="li"> replace the spaces with tabs (not really need when using OpenOffice)</div>
 106 </li>
 107 </ul>
 108 </li>
 109 <li class="level1"><div class="li"> copy the modified data into the spreadsheet template somewhere beside</div>
 110 </li>
 111 </ul>
 112
 113 </div>
 114 <!-- EDIT5 SECTION "Step3: Copy the pin list into an editor and prepare it" [2600-3970] -->
 115 <h2 class="sectionedit6" id="step4insert_all_missing_data_into_the_spreadsheet">Step4: Insert all missing data into the spreadsheet</h2>
 116 <div class="level2">
 117
 118 <p>
 119 Now, move the labels into the label column and the pin numbers into the pin number column. You can use the autofill feature of your spreadsheet program to create the pin numbers, too.
 120 </p>
 121
 122 <p>
 123 <a href="media/tragesym/ooo_rearanged.png" class="media" target="_blank" title="tragesym:ooo_rearanged.png"><img src="media/tragesym/ooo_rearanged.png" class="media" alt="" /></a>
 124 </p>
 125
 126 <p>
 127 Set the type, style and position column to the most common value. You can use the autofill feature again.
 128 </p>
 129
 130 <p>
 131 Now you want to change some of the values. Take a look at the pin description table in the datasheet:
 132 </p>
 133
 134 <p>
 135 <a href="media/tragesym/kpdf_pindescription.png" class="media" target="_blank" title="tragesym:kpdf_pindescription.png"><img src="media/tragesym/kpdf_pindescription.png" class="media" alt="" /></a>
 136 </p>
 137
 138 <p>
 139 Regarding to that table we change the following things (see result below):
 140 </p>
 141 <ul>
 142 <li class="level1"><div class="li"> Pin 1 is an output, we like to have a negation bubble and a negation overbar</div>
 143 </li>
 144 <li class="level1"><div class="li"> A1 to A3 are inputs, we change the type and move them to the left side</div>
 145 </li>
 146 <li class="level1"><div class="li"> set the SCL type to input and move SCL and SDA to the left side, too</div>
 147 </li>
 148 <li class="level1"><div class="li"> change the type of the power pins VSS and VDD and add net names. We use the more usual GND and Vcc.</div>
 149 </li>
 150 </ul>
 151
 152 <p>
 153 <strong>Note:</strong> If one of your pin labels has a backslash “\” inside, you have to replace it with it&#039;s escape sequence “\\”.
 154 </p>
 155
 156 <p>
 157 <a href="media/tragesym/ooo_changedpins.png" class="media" target="_blank" title="tragesym:ooo_changedpins.png"><img src="media/tragesym/ooo_changedpins.png" class="media" alt="" /></a>
 158 </p>
 159
 160 <p>
 161 Before going on set the attributes and the options to appropriate values.
 162 </p>
 163
 164 <p>
 165 <a href="media/tragesym/ooo_attributes.png" class="media" target="_blank" title="tragesym:ooo_attributes.png"><img src="media/tragesym/ooo_attributes.png" class="media" alt="" /></a>
 166 </p>
 167
 168 </div>
 169 <!-- EDIT6 SECTION "Step4: Insert all missing data into the spreadsheet" [3971-5176] -->
 170 <h2 class="sectionedit7" id="step5export_the_spreadsheet_into_a_tab_separated_text_file">Step5: Export the spreadsheet into a tab separated text file</h2>
 171 <div class="level2">
 172
 173 <p>
 174 You can either use the export function of your spreadsheet program to create a tab separated textfile or just select the table and copy the content into your text editor and save the file.
 175 </p>
 176
 177 </div>
 178 <!-- EDIT7 SECTION "Step5: Export the spreadsheet into a tab separated text file" [5177-5440] -->
 179 <h2 class="sectionedit8" id="step6execute_tragesym_and_create_the_symbol">Step6: execute tragesym and create the symbol</h2>
 180 <div class="level2">
 181
 182 <p>
 183 Use a shell and execute tragesym:
 184 </p>
 185
 186 <p>
 187 <code>werner@werner-amd64:~/Desktop/tragesym_tutorial&gt; tragesym pca555.src pca555.sch</code>
 188 </p>
 189
 190 <p>
 191 If tragesym says that there&#039;s an error, just make some changes in the spreadsheet and export the file again, or just edit the exported file.
 192 </p>
 193
 194 </div>
 195 <!-- EDIT8 SECTION "Step6: execute tragesym and create the symbol" [5441-5760] -->
 196 <h2 class="sectionedit9" id="step7check_the_result_with_gschem_and_do_some_artwork">Step7: check the result with gschem and do some artwork</h2>
 197 <div class="level2">
 198
 199 <p>
 200 Now open the generated symbol with gschem and check the result
 201 </p>
 202
 203 <p>
 204 <code>werner@werner-amd64:~/Desktop/tragesym_tutorial&gt; gschem pca555.sch</code>
 205 </p>
 206
 207 <p>
 208 Enabling the hidden text (“en”, Edit→Show/Hide Inv Text), you can see the whole generated symbol. It&#039;s not really necessary to change anything, but it might improve the look of the symbol if you rearrange the pins a little bit.
 209 </p>
 210
 211 <p>
 212 <a href="media/tragesym/gschem_showhidden.png" class="media" target="_blank" title="tragesym:gschem_showhidden.png"><img src="media/tragesym/gschem_showhidden.png" class="media" alt="" /></a> <a href="media/tragesym/gschem_finished.png" class="media" target="_blank" title="tragesym:gschem_finished.png"><img src="media/tragesym/gschem_finished.png" class="media" alt="" /></a>
 213 </p>
 214
 215 <p>
 216 Now we have a complete symbol. You can copy the symbol to your local symbol library e.g. /usr/local/share/gEDA/sym/local/ and use it.
 217 </p>
 218
 219 </div>
 220 <!-- EDIT9 SECTION "Step7: check the result with gschem and do some artwork" [5761-6401] -->
 221 <h2 class="sectionedit10" id="conclusion">Conclusion</h2>
 222 <div class="level2">
 223
 224 <p>
 225 This was a simple example with a small pincount, but this method really pays off when you have high pin counts (ie, bga-272, tfqp-100, etc).
 226 </p>
 227
 228 </div>
 229 <!-- EDIT10 SECTION "Conclusion" [6402-6566] -->
 230 <h2 class="sectionedit11" id="credits">Credits</h2>
 231 <div class="level2">
 232
 233 <p>
 234 Many thanks to &lt;Russ.Dill(AT)asu.edu&gt;, who wrote the first version of this tutorial.
 235 You can find that tutorial at
 236 <a href="http://www-mdp.eng.cam.ac.uk/web/CD/engapps/geda/geda-doc/tutorials/tragesym/tragesym.html" class="urlextern" title="http://www-mdp.eng.cam.ac.uk/web/CD/engapps/geda/geda-doc/tutorials/tragesym/tragesym.html" rel="nofollow">http://www-mdp.eng.cam.ac.uk/web/CD/engapps/geda/geda-doc/tutorials/tragesym/tragesym.html</a>
 237 </p>
 238
 239 </div>
 240 <!-- EDIT11 SECTION "Credits" [6567-] --></body>
 241 </html>