gEDA: gschem User Guide Written by: Ales Hvezda ------------------------------------------------------------------------- Contents: 1. Introduction 2. Overview 3. Running gschem 4. User interface 5. Basic operations 6. Files used/created by gschem 7. Electrical connectivity 8. Dialog boxes (TBA) 9. Components/symbols 10. Attributes 11. Resource File 1. Introduction This is a very basic and crude first attempt at getting some real user docs written for gschem. This document is hardly finished or polished but it is better than having no docs at all (which was the case for the longest time). Please forgive the tone of this document; I (Ales) am writing this just to get something done. I am by no means a technical writer so I am sure some of my sentences are truly awful. As everybody says, programmers should not write documentation for their programs and this document is a perfect illustration of a programmer breaking that rule. Please report any errors/inconsistencies to ahvezda@geda.seul.org This document assumes you know understand basic schematic capture, like you understand that a component represents something and that nets and buses interconnect these components to form a schematic etc... Eventually this document will describe all this in more detail, but for now this document is will describe how schematic capture is accomplished in the gEDA system. 2. Overview gschem is the schematic capture program in the gEDA tool suite. It's sole purpose is facilitate the input of circuit schematics or block diagrams graphically. gschem is also the symbols editor for the gEDA system. This is possible because the schematic format and symbol format are exactly the same. 3. Running gschem Running gschem is straightforward once you have installed it on your GNU/Linux or UNIX system. The first step is to build and install the gEDA tools. This step is not covered in this document. You can tell if you have installed the tools correctly by running the following commands: libgeda-config --version gesym-config --version which gschem ldd `which gschem` The first two should return the version of the installed tools (libgeda and the symbol library) and the next command should return the path to the gschem binary. The final command (only on GNU/Linux systems) will return which libraries are linked to gschem; all of the request libraries must be found for gschem to run. If these commands do not return the expected results, then most likely the gEDA tools are not installed properly. Please see the appropriate INSTALL docs (which came with the distribution) for more info on installing the gEDA tools. To run gschem type: gschem at any shell prompt. To look at an example schematic which came with gschem run: gschem schematic_name.sch For a listing of the various command line flags type: gschem -h For a detailed explanation of the command line flags look at the gschem man page (man gschem). 4. User interface There are several ways to interact with gschem. gschem requires a keyboard and mouse. There are three ways to initiate an operation or command: Using the mouse to select the operation off a menu -- or -- Typing the keyboard hotkey(s). -- or -- Draw the appropriate stroke (if stroke support is enabled) To make usage matters more confusing, selecting an operation off of the menus behaves slightly differently than typing the hotkey. Most of the operations operate on the currently selected object(s), hence you need to select the object first before manipulating them. The menu selected operations usually require some more input (usually a mouse click) after they are picked off of the menu. The keyboard hotkey operations take that required input as the current mouse position. This saves an extra click since you can position the mouse at the right place, type in the hotkey(s), and the command then executes. Note, you can change this so that both menu and hotkey behavior is exactly the same. See the section on the resource file for more info on how to configure this. Most of the interaction with gschem is fairly modal (modes like command/editing similar to the great text editor vi). If you select operations off of the menu, the you are placed into corresponding mode (like copy/move mode). You must then select an anchor point (or whatever the appropriate point is) to continue the operation. Most of the commands off of the menu expect the objects to be already selected. The hotkeys are also modal in nature. Most of the default hotkeys are for the various commands are not single keystrokes. There are a few which are single keystrokes (like zoom in: `z' or pan: `x'), but most are typically two keystrokes long. As examples, to execute File/Save you would type `f' and `s' (without the quotes) or Add/Line is `a' and `l'. You can get a listing of the hotkeys by picking Help/Hotkeys. The hotkeys are defined in the resource files (system-gschemrc, ~/.gEDA/gschemrc, or `pwd`/gschemrc). See the section on the resource file for more info. The mouse button actions in gschem are mostly configurable. The first mouse button is always used to select objects or pick points. This button is not configurable. The second mouse button is either a copy/move action (when held down over an object) or a repeat last command or draw a stroke to execute a command. The third mouse button is either a mouse pan (when held down as the mouse is moved) or a popup dialog box. The behavior of the second and third mouse buttons is controlled through the resource file (see the section below for more info). 5. Basic Operations There are seven kinds of operations in gschem: a. File related (Open/Close/Save/Print etc...) b. Addition of objects (Add nets/lines/pins/components etc...) c. Manipulate objects (move/copy/delete/rotate/mirror etc...) d. View operations (Zoom/Pan/Redraw etc...) e. Hierarchy operations (Down Schematic/Down Symbol/Up) f. Attribute operations (Attach/Detach/Toggle visibility etc...) g. Buffer operations h. Option changing (text size/gridding/snap etc...) i. Grips This section will describe each of these. The terms page and schematic both refer to the same thing (a collection of objects that are loaded and being displayed). A window is that big window in which schematics are displayed and manipulated. a. File related operations: New Window Open a new window. Each window is totally separate from all other windows. New Page Open a new page. Usually this page will be called untitled_N.sch, where N is an incrementing number. Open Page... Open an page from disk. This will pop up a dialog box. Please see the later section on how to use the more advance features of this dialog box. Close Page Close the currently displayed page. This will prompt you to save if you have modified the page. Revert Page Close and reopen the currently displayed page. This will not prompt you to save the current page, but will quickly discard any changes you have made and reopen the saved schematic from disk. Use with caution. Save Page Save the page current page. If the page is called untitled_N.sch (where N is a integer), then a Save As... dialog box will appear. Save Page as... Opens the Save As.. dialog box. Clicking Save As will save the currently displayed schematic. The displayed schematic will be called the new specified name. Save All Unconditionally saves all schematics loaded in memory. Print... Brings up the Print dialog box. Please see the dialog box section for more info on this. Write PNG... Brings up the Write PNG dialog box. Please see the dialog box section for more info on this. Note you must have libgdgeda install (and any required dependencies) if you want to output images. Close Window Closes the current window. If there are any modified schematics, a "Are you sure" dialog box will appear. Clicking OK will cause all unsaved schematics to be lost. Quit gschem Like Close window, but close all opened window. A "Are you sure" dialog box will appear for each window which has unsaved schematics Page Manager Brings up a dialog box which lets you pick pages as well as see various info about the pages loaded in memory. Please see the dialog box section for more info on this. Page Next Page Prev These two options allow you to move in between opened pages. Page Discard Closes the current schematic forcefully. If the current schematic is NOT saved then the data is lost forever. You will NOT be prompted or warned if you have modified the current displayed schematic. Use with caution. Useful if you want to unload a schematic quickly. b. Addition of objects: An object is one of the following: line, circle, pin, net, box, bus, text/attribute, and component. A component is a collection of lines, circles, pins, boxes, text, and attributes. Add Component Opens up a dialog box which lets you place components from the component libraries. To place a component do the following: Select a Component library (which btw is specified in the Resource files, see section below) from the left list Select a Component from the right list. Move the mouse into the main drawing window (you should see an outline). Press the first mouse button to place the component. Keep pressing the first mouse button to place additional instances of the component. If a component name is already selected, hitting apply and moving the mouse into the main window will allow you to place that component again. You can rotate the component before you place it by clicking the middle button. For every button click, the component will be rotate 90 degrees. To cancel a component place press the last mouse button or the ESC key. Please see the dialog box section for detailed information on this dialog box. Add Net Draws a net segment. If you select this off of the top menu bar then: 1. Press the first mouse button to start the net. 2. Press the first mouse button to end the net. 3. Another net will start at the last endpoint. 4. Press the first mouse button to end that net etc... Press the last mouse button or ESC to cancel any net in progress. If you started this using the menu hotkey then the net start immediately at the last mouse position and then it behave exactly as above (except for line #1). After drawing a net segment (or segments) and canceling the last net segment, you are automatically placed in select mode. You must pick add net again or type the hotkey to add more nets. You can hold down the control key to draw non-orthogonal nets. Just keep in mind that you cannot connect anything to the middle of a non-orthogonal net. The boxes at the end of the nets are connectivity cues. Filled boxes signified a dangling net (not connected to anything). Filled circles are midpoint connections/junctions. These cues are drawn automatically and are an indicator of electrical connectivity. See the section on electrical connectivity below for more information. Add Bus Basically the same thing as nets, except that it draws buses. Buses are very new and there are many aspects which are not defined yet, so keep that in mind as you uses buses. *More to be added here eventually* Add Attribute... Brings up the add attribute dialog box. This dialog box is ONLY used to add attributes. It does not display or manipulate already placed attributes. An attribute is nothing more than a text item which is in the form name=value (there cannot be any spaced to the left or right of the name,value pair). It can be either unattached or attached. To add an unattached attribute do the following: 1a. Select an attribute name off of the pulldown list -- or -- 1b. Type in the attribute name into the name entry 2. Type in a value for the attribute. 3. Pick any of the attribute options. 4. Click Apply and the attribute will be placed. If you want to attach an attribute to an object then select the desired object first and then press the add attribute apply button. The text should be yellow which signifies an attached attribute. If you click on an object which has attached attributes, the attached attributes should be selected as well. If you select Add/Attribute... off of the pull down menus then you do not have much control as to where the attribute gets placed (it gets places either at the lower left hand corner of the object extents or at the origin of any selected object). However, if you execute Add/Attribute using the hot key then the current mouse position is used as the anchor point for the attribute item. You cannot place an incomplete attribute (an attribute without a name and value). Please see the section on attributes below for more info on how to use attributes and more details. Add Text Opens up the text add dialog box. To place text: 1. Type in text in entry field 2. Hit enter or click Apply 3. Move the mouse into the main window (an outline of the text should appear and follow the mouse) 4. Press the first mouse button to place the text If you leave the text add dialog box open you can place the same text item again and again by just clicking apply (or pressing enter) and moving the mouse into the main window. Text which is placed will be automatically capitalized. Please see the Resource file section below on how to control this behavior. To cancel a text place press the last mouse button or the ESC key. If you create text in the form name=value, then you are creating attributes. gEDA allows for general attributes to be free floating (or unattached). It is a good idea to change the color of these floating attributes to the current attribute color (which is also called the attached attribute color) to signify that this text item is an attribute. Add Line Draws a line in the same fashion as drawing nets with the following exceptions: - A line has no electrical significance - Only a single line is drawn - You keep drawing lines as long as you are in line drawing mode. To cancel a line rubberband in progress press the last mouse button or the ESC key. Add Circle To draw a circle (picking Add Circle off of a menu): 1. Pick the center of the circle with the first button 2. Move the mouse to see an outline of the circle 3. Press the first mouse button to finalize the circle To draw a circle (typing the hotkey), same as above except that the center of the circle is picked for you at the last mouse position when you type the hotkey. To cancel a circle rubberband in progress press the last mouse button or the ESC key. Add Arc To draw an arc (picking Add Arc off of a menu): 1. Pick the center of the arc with first mouse button 2. Move the mouse and pick the next point. The rubberbanded line represents the radius 3. A dialog box will appear: specify the start angle (in degrees) and specify the degrees of sweep. 4. Press OK to finalize the values. The start angle can be positive or negative. The degrees are specified using the standard Cartesian coordinate system. The degrees of sweep can be positive or negative. To cancel an arc in progress (while rubberband the radius) press the last mouse button or the ESC key or press the Cancel button in the arc dialog box. Add Pin Draws a pin in the same fashion as drawing nets with the following exception: - You keep drawing pins as long as you are in pins drawing mode. To cancel a pin rubberband in progress press the last mouse button or the ESC key. c. Manipulate objects: Most of these operations are modes which operate on the current selected objects. Before you can execute the desired function you must select the objects you want to rotate. Undo/Redo Undo does exactly that, it undos the last action which changed the schematic. Here is how gschem implements undo: Basically after every action (including zooming and panning) the schematic is saved to disk (in /tmp). Gschem do clean up after itself when you exit. Should gschem crash, the saved files are left alone in /tmp. Redo only applies when you do an Undo. You can undo something and then immediately redo it. However if you do anything in between you will lose the undo info. You can undo and redo to your hearts desire up and down till you reach the max undo levels. You can change the behavior of undo and redo by changing the defaults in one of the *gschemrc files. Please see the system-gschemrc for more info. Select Mode Select mode is the initial mode gschem starts up in. In select mode you can select objects. You can pick single objects by clicking on them. If an object is already selected than clicking on that object will keep it selected. If multiple objects overlap then clicking in one spot will cycle through the objects. If you hold down the SHIFT key and click, you can select and deselect multiple objects. Doing this with multiple overlapping objects will cause the selection to cycle among the possible object selections. If you hold down the CONTROL key and click, you will toggle the object in and out of the current selection list. To select multiple objects press and hold the first mouse button and drag the mouse till a selection box appears. Drag the mouse (selection box) till it encompasses the objects and release the first mouse button. The objects must be completely encompassed. Using the selection box takes some practice. If any previous objects were selected, they will be unselected. If you hold down the SHIFT key while drawing a selection box then you will add to the currently selected objects. Objects cannot be removed using the selection box and holding down the SHIFT key. If you hold down the CONTROL key while drawing a selection box then you will toggle any encompassed objects. If an object was selected then it will be unselected and vice versa. If you pick an object which has attributes which are attached to it, then these attributes will be selected as well. If you just want to select the object, you must deselect the attributes. Invisible attached attributes are also selected when you pick the object This behavior is handy if you want to manipulate/change an object and all of its attributes (moving/copying the object around). The selection mechanisms are not obvious and do require some practice. There are some quirks so please report them as you come across them. Edit... Allows you to edit: Text - brings up a dialog box which allows you to edit the text string and size Attributes - a much more sophisticated version of above specifically for attributes. All attributes attached to a component - brings up a multi-attribute editing dialog box. 1. Select the item (text/component) to edit. 2. Pick or type the hotkeys for Edit/Edit... 3. Make the appropriate change and press OK Note, only the item will be edited; bulk text/component editing is not supported (yet). Edit Text... Allows you to edit text only, regardless if that text is an attribute or just a plain text string. 1. Select the text item text to edit. 2. Pick or type the hotkeys for Edit/Edit Text... 3. Make the appropriate change and press OK Note, only the item will be edited; bulk text editing is not supported (yet). Copy Mode This mode allows you to copy the currently selected objects. To copy objects (picking Edit/Copy Mode off of a menu): 1. Select the desired object(s) 2. Pick Edit/Copy Mode off of a menu 3. Pick an origin point for the copy (first button) 4. Move the outline to the desired position 5. Pick the destination point (first button) To copy objects using the hotkey for copy mode is almost the same as above except that the origin point is selected automatically for you once you hit the copy mode hotkey. After finishing the copy, you are automatically put back into to select mode. Holding down the CONTROL key as you move the outline around will constrain the movement to be either horizontal or vertical. Move Mode Move mode is just like copy (above) except that instead of copying you are actually moving the objects around. Delete Delete allows you to remove objects off of the page. To delete objects: 1. Pick the desired object(s). 2. Select or type the hotkey for Edit/Delete 3. Objects will be deleted immediately Use this with caution since there is NO undo yet! Rotate 90 Mode Rotate mode allows you to rotate objects 90 degrees around a pivot/center point. To rotate objects (picking Edit/Rotate 90 Mode off of a menu): 1. Pick the desired object(s). 2. Select Edit/Rotate 90 Mode off of a menu 3. Pick the pivot or center point of the rotate Rotating objects using the hotkey is similar to above except that the center point is the last mouse position at which you typed the hotkey. The objects will be rotate 90 counter clockwise. You can keep rotate objects 90 degrees till you have them in the wanted rotation. Text will always appear upright. Mirror Mode Mirror mode allows you to mirror objects horizontally around pivot. To rotate objects (picking Edit/Rotate 90 Mode off of a menu): 1. Pick the desired object(s). 2. Select Edit/Mirror Mode off of a menu 3. Pick the pivot point of the mirror Mirroring objects using the hotkey is similar to above except that the pivot point is the last mouse position at which you typed the hotkey. Objects are mirrored horizontally about the pivot point. If you want to get a vertical mirror then rotate and mirror the object(s) till you get the desired position. Mirroring of embedded components is not supported. Slot... Slot... allows you to change the slot of a multiple slot component. The component must support slotting (see the Components/Symbols section for more info on this). To change the slot: 1. Select the desired component. 2. Pick or type the hotkey for Edit/Slot... 3. Type in the new slot number 4. Press OK. Slotting is still in development so expect some quirks. Color... This option allows you to change the color of any selected object (with the exception of components). To change the color of the currently selected objects: 1. Select the desired object(s). 2. Pick or type the hotkey for Edit/Color... 3. A dialog box with a drop down menu will appear. 4. Pick the new color 5. Press Apply. The color change will only take effect once you press Apply. The dialog box will not change to the color of the current object(s) (ie it only lets you change the color and does not get the current color of selected object(s)). You can leave this dialog box up and select new objects and change their color by pressing Apply. Lock Unlock Lock and unlock allow you to lock/unlock components in a schematic. Locking means that a component cannot be selected by a single click. This is useful for title blocks and other components which should not be selectable because you might have other objects inside its boundaries and clicking inside the component (titleblock) would be a distraction. To lock/unlock components: 1. Select the desired object(s) 2. Pick or type the hot key for lock/unlock The components will not be selectable with a single click. To select a locked component, use a selection box to select it. This is the only way to select a locked component. You can lock and unlock regular objects (lines/pins/boxes...) which is nice when you are drawing something and an object is in the way continuously. Just lock it and you will not have to think about it when you click to select other objects. However, locking an object is not preserved in the file format so once you quit any locked objects (lines/pins/boxes...) will become unlocked. The locked/unlocked state of components is preserved in the file format though. Line Width & Type... This dialog box lets you control the width and type of lines, boxes, circles, and arcs. This dialog box is still under development. Select an object and then select this option will bring up a dialog box which lets you set the line width, line type, line dash length, and line dash spacing. Pressing OK will apply the changes. Symbol Translate... Symbol translate is used to take whatever is drawn and translate it around using a inputed value (in mils). This operation is mainly used to translate symbols around (mainly to the origin). To translate a symbol, just select or type the hotkey for Edit/Symbol Translate... and a dialog box will appear. Enter the amount you want translate (positive or negative) in the X and Y directions (the same value will be applied to both directions). If you enter a 0, then all the objects will be translated to the origin. If you are drawing a symbol, zoom in a bit and then execute this (0 for the amount), since there are still some bugs in this operation. It is a requirement that snap be on and that the grid snap spacing is set 100 mils when creating symbols. Embed Component Unembed Component gschem supports a concept of embedded components which components in a schematics which do not require an external symbol file of any sort. All the information necessary to display a component is placed in the schematic file. This causes schematic files to be significantly larger, but it makes it easy to share schematics with other people or archive schematics away, since you have any dependencies on symbol files. You should only embed components when absolutely necessary. Embed Component and Unembed component work exactly alike: 1. Select any components you wish to (un)embed 2. Pick or type the hotkey for Edit/(Un)Embed Component If you want the unembed a component you must have a symbol with the same name in the component library search path (other wise the unembed will not work). You can only embed and unembed components. Also, you cannot embed and then mirror a component (this is a limitation of gschem and will eventually be fixed). You can also place embedded components directly in the Add Component... dialog box. Show Hidden Text This operation makes all hidden/invisible text visible. To use it, simply pick the option (or type its hotkeys) and all the invisible text will appear. Visible text is unaffected by this operation. This operation is useful when drawing/debugging symbols. d. View operations (Zoom/Pan/Redraw etc...) Redraw This option redraws the current display. This is useful when you have mouse/component/line/text etc... droppings left over from a previous action. It is also useful when you want to update all visual connectivity cues. Pan Pan lets you move around the display. To pan the display (picking View/Pan off of a menu): 1. Select View/Pan off the menu 2. Click the first mouse button at the new center of the display. To pan the display using the hotkey is much simpler, simply type the hotkey and the display will pan the display to the current mouse location. You can also enable mouse panning if you add: (third-button "mousepan") to one of the gschemrc files. See the section on the resource file for more info. Mouse panning is very nice for small schematics, but tends to lag on larger ones. Zoom box Zoom box allows you to specify a zoom window for zooming in. To use the zoom box (picking View/Zoom box off of a menu): 1. Select View/Zoom box off the menu 2. Click and hold the first mouse button 3. Drag the mouse drawing the zoom box around the area you want to zoom 4. Release the mouse button and the display will zoom To use the zoom box by typing the hotkeys is similar. Once you type the hotkey, the zoom box will start immediately using the current mouse location as the first corner of the box. Zoom box will attempt to zoom the requested area, but some boxes are not legal and gschem will do it's best to zoom the requested area. Zoom limits Zoom limits will zoom the display attempting to fit all the placed objects on the screen. Simply pick View/Zoom limits off of a menu or type its hotkey and the display will be redrawn. There are the special cases (like a single horizontal line) which sometimes do not display correctly (or as expected). Hopefully these exceptions will be fixed someday. Zoom In Zoom out Zoom In/Out zoom the display using the picked mouse location as the center of the display (or the current mouse location if using the hotkey). These commands always zoom in/out by a factor. To use Zoom In/Out (picking View/Zoom box off of a menu): 1. Pick Zoom In/Out off of the menu 2. Click the first mouse button as the center of the zoom Using the hotkeys is similar except that the current mouse position serves as the center of the new display. Zoom full Zoom full will zoom the display to the maximum possible displayable view. Simple select it off of a menu or type it's hotkey and the display will be zoomed. Update Cues This menu option is obsolete and will be removed. e. Hierarchy operations (...) Down Schematic Go down into a symbol, opening up any underlying schematics. Basically this will open up an underlying schematic of the selected component if it exists in the source library search path. See the Resource File section on how to define this path. There are currently two ways of specifying that a symbol has an underlying schematic or schematics: 1) The underlying schematic must have the same name as the symbol but have a .sch extension and must follow the _# suffix naming convention. See the Files section below on this convention. 2) Attach an attribute to the symbol called source=filename.sch filename.sch is not a path to the symbol, but rather the basename (last file in the path specifier) of the symbol path. The underlying schematic will still be searched in the source-library path. You can specify multiple source= attributes. The underlying schematics will be opened in the order that the source= attribute is found. If there multiple underlying schematics, they will be loaded. Movement between the schematic pages is restricted (to the same level of the same set of underlying schematics) unless the rc keyword enforce-hierarchy is modified to allow for a freer hierarchy traversal mode. See the Resource File section for more info. It is also recommend that you maintain unique names for the various levels (when using the source= attribute) to avoid possible confusion. The hierarchy mechanisms are fairly new so expect some odd behavior (and please report it) Down Symbol This option will open up the symbol of the selected component. Once the symbol is open, the user can edit it and save it. At this time, the toplevel schematic will not see the symbol change unless the toplevel schematic is reloaded or File/Revert is executed. This will be fixed eventually. Up This option will move up the hierarchy (if there are pages above the currently displayed page). f. Attribute operations (Attach/Detach/Toggle visibility etc...) An attribute is nothing more than a text item which is in the form name=value. It can be either unattached or attached. The operations in this group manipulate attributes only. Most of these operations have no effect on plain text objects. Attach The Attach command allows you to take a text item (in the proper form; name=value) and attach it to another object. To use Attributes/Attach: 1. Select the object which will receive the attributes 2. Select the text object(s) which will be attached to the above object 3. Pick or type the hotkeys for Attributes/Attach The order of the sequence of selecting the object and then the text items is important; gschem will not allow you to select the text items first and then the object. After going through the above sequence the text item will turn yellow (or the current attached attribute color) signifying that the text item is an attached attribute. You cannot attach a single attribute to several different objects. You cannot attach non-text items as attributes. Detach Detach allows you to deassociate attributes from objects. To deselect an object of all attributes: 1. Select the object of interest 2. Pick or type the hotkeys for Attributes/Detach All the attached attributes (even if they are not selected) will be detached from the object. This behavior is probably broken and will eventually be fixed (so that only selected attributes are detached). When you detach attributes then they turn red (or the current detached attribute color). This color changes allows you to spot text which was an attribute and is now dangling (unattached). Show Value Show Name Show Both These operations allow you to control which part of the attribute string is visible. Usually you are just interested in seeing the value of the attribute, but there are circumstances where seeing the name and value (or maybe just the name) would be useful. To use the options: 1. Select the attribute(s) of interest 2. Pick or type the hotkeys for Attributes/Show * The text item(s) should immediately change. These operations only work on text items which are in the form name=value Toggle Vis This operation allows you to toggle the visibility of attributes. To use this option: 1. Select the text item(s) of interest 2. Pick or type the hotkeys for Attributes/Toggle Vis The text item(s) should change their visibility immediately. If you make an attached attribute invisible, then you can simply select the parent object and select Toggle Vis and the attribute will be come visible (likewise any visible attributes attached to that object will become invisible). If you make a free floating (unattached) attribute invisible, then the only way to make it visible (and all other invisible attributes) is to use the Edit/Show Hidden Text option. g. Buffer operations Gschem supports 5 copy/cut/paste buffers which are visible across all opened pages and windows. Copy To copy something into a buffer: 1. Select the objects you want to copy. 2. Select Buffer/Copy/Copy into buffer #. Cut Cut is like copy in that it removes the objects from the schematic Paste To paste a buffer into the current schematic: 1. Fill the buffer using the above Copy or Cut. 2. Go to the new schematic page/window. 3. Select Buffer/Paste/Paste from buffer #. 4. Click the first mouse button to pick an anchor point. 5. Move the mouse to the final spot. 6. Click the first mouse button again. h. Option changing (text size/gridding/snap etc...) Text Size... This command pops up a dialog box which allows you to specify the text size of all text (including attributes placed with the Add/Attribute... dialog box). The text size is in points (1/72"). The default text size is 10 point text. The smallest text size is 2 points. Toggle Grid Toggles the visible grid Toggle Snap Toggles the snap. Be very careful using this. Connections between pins and nets (and nets to nets) depends on being exactly connected. Turning of the grid will almost guarantee that nets/pins do not connect. Before you translate a symbol using Edit/Symbol Translate, make sure the snap is on. Snap Grid Spacing... This option brings up a dialog box which allows you to change the snap grid spacing (not the grid spacing). The units for this spacing are mils. Before you translate a symbol using Edit/Symbol Translate, make sure this spacing is set to 100. Toggle Outline Toggles between drawing the outline of the current selection or just drawing a box when doing moves/copies/component and text places. The outline mode looks better, but tends to be significantly slower than using the box (bounding box) mode. Show Log Window This option displays the log window if it has been closed or disabled from being displayed when you start up gschem. Show Coord Window This option displays a dialog box which displays the current x, y location of the mouse pointer in screen (pixels) and world coordinates (mils) i. Grips Grips are a mechanism used in gschem to provide an easy way of modifying objects inside schematics. When you select an object, little squares are placed in strategic locations (line end points or circle radius point or corners of a box) which allow you to change the object quickly. Grip support currently exists for lines, nets, pins, buses, circles, and boxes. Arcs do not yet have grips, but will eventually. Using grips is easy: 1) Select the object you want to change. The grips (the little boxes) will appear. 2) Click and hold the first mouse button inside the box. 3) Move the mouse around till you have the object where you want it 4) Release the mouse button. 6. Files used/created by gschem There are several files which gschem uses. Here is a list and a brief explanation of each: *.sch Schematic files. These files contain components, nets, text, and sometimes primitive objects (like lines, circles, box etc...) Schematics do not contain pins. Schematic filenames should follow this convention: name_#.sch where: name is a text string which describes what this schematic contains. _# is an underscore and a number (like _1, _2, _7, _13, etc...) This number is used to sequence schematic pages in a multiple page schematic. .sch is the schematic extension/suffix. It is important the schematic pages have this extension. Schematic files are pure ASCII and will always be pure ASCII. gEDA does not support any binary file formats. The file format for schematics is described in the gEDA file formats document. *.sym Symbol files. The schematic and symbol file formats are identical. gschem (or a text editor) is used to create symbol files as well as schematics. Symbol files contain lines, circles, boxes, arcs, pins, text, and attributes. The naming convention for symbol files is: name-#.sym where name is a text string which describes what the symbol represents. -# is a dash and a number (like -1, -2 etc...) The number is used to allow for a symbols to have the same name yet different contents. There might be multiple representations for resistors so these symbols should be called: resistor-1.sym, resistor-2.sym, and resister-3.sym. .sym is the symbol extension/suffix. It is important the symbols have this extension. #if 0 /* this is all old */ For toplevel symbols which have underlying schematics (for a schematics hierarchy) there is a naming convention (it's basically what's described above). This naming convection is best described by an silly example: Suppose you have a symbol called ales-1.sym (which represents an alcoholic beverage generating black box). Now this alcoholic beverage black box has a bunch of underlying schematics. These schematics are called ales_1.sch, ales_2.sch, ales_3.sch etc... So basically the name of the symbol and the name schematics is the same (only the sequence numbers change). Now this also means that ales-2.sym has the same underlying schematics (ales_1.sch, ales_2.sch, ales_3.sch etc...). #endif The new way of specifying hierarchy is by using the source= attribute. Please see the master attribute document for info on this mechanism. The hierarchy mechanism is still in heavy flux, so there might be some more changes. system-gschemrc ~/.gEDA/gschemrc gschemrc Resource files. These contain guile (scheme) keywords which control the various configurable parameters. All three files may exist and are searched in the above listed order. system-gschemrc contains system wide defaults. ~/.gEDA/gschemrc lives in each users home directory and contains project wide defaults. gschemrc lives in each project directory and contains project specific defaults. See the section below on the resource file for more info. gschem.log Log file. This file contains informative, error, warnings etc... messages when gschem was run. This file is created in the working directory that gschem was started in. This allows the user to preserve log files between independent projects. TBA: Suggested format for projects 7. Electrical connectivity As you draw schematics you need be aware of what is considered to be electrically connected by the gEDA programs. Nets which are visually connected to other nets are electrically connected. This connection may be endpoint to endpoint or endpoint to midpoint. When a single endpoint to endpoint (net or pin endpoint) connection is drawn then the visual dangling net cue disappears. When an endpoint ends in the middle of another net (or multiple endpoints coming together at a single point) then a circular filled connectivity cue is drawn. You cannot connect a net to the middle of a pin. Nets can only be connected to the endpoints of pins. You cannot connect to a net if that net is not orthogonal (horizontal or vertical). The visual cues are the primary way of telling if nets/pins are connected. Bus are similar to nets with the exception that you cannot connect a net to the endpoint of a bus (only to the middle). If you do try to connect a net to the end of a bus you will see a big red X at the invalid endpoint connection. Buses are still very new so there are still many quirks. Nets which have the same attribute label= attached to them are also considered electrically connected. You will not get any indication of this connection by gschem, but the netlister (gnetlist) considers nets with the same label= attribute electrically connected. The naming convention for buses has not been formalized yet. More TBA 8. Dialog boxes TBA 9. Components/symbols A component or symbol represents something. Usually it represents a gate, a black box or block, or an entire device. A symbol is a collection of primitives which are grouped together. You can use lines, boxes, circles, arcs, text, attributes and pins as the primitives for building symbols. You cannot have nets, buses, or other symbols inside a component. Components are searched for by specifying (component-library "...") inside one of the *rc files. See below for more info. More to TBA 10. Attributes An attribute is nothing more than a text item which is in the form name=value (there cannot be any spaced to the left or right of the name,value pair). It can be either unattached or attached. Attributes are used extensively in the gEDA project to convey information. Things like device name, pin numbers, hidden nets, and unit reference numbers are specified using attributes. For a list of attributes be sure to look at the attributes.txt document. There are two kinds of attributes: 1) Regular attached attributes. These are attributes which take on the standard form and are attached to some object (pin, net, component, or box etc...). These attributes are usually yellow in color. 2) Unattached attributes. These are attributes which take on the standard form, but are not attached to any object. These attributes are also known as floating or toplevel attributes. Regular attached attributes are attached to an object to associate the info with a specific object. For example: a pin number associated with a pin. Unattached attributes usually convey some information which is global in nature. For example: a device= attribute (which lives inside symbols) and specifies what device the entire symbol represents. There is a third type of attribute which is a special case of #2 but turns into #1. This special type of attribute is known as a prompted attribute. If you place an unattached visible attribute inside a symbol and then instantiate that symbol, then that unattached attribute gets "promoted" to an attached attribute. This newly promoted attribute gets attached to the symbol. This mechanism of attribute reattachement (from within a symbol) is known as attribute promotion. There are some gotchas about attribute promotion: * Promotion *only* happens when the symbol is placed. That means that if you place a symbol (sym1) and then change it on disk (by adding or removing floating attributes), existing sym1's will not reflect these new floating attributes (ie they won't be promoted) in any schematic. * The device= attribute is not promoted. * Invisible attributes are not promoted by default. If you attach a floating attribute (like numslots=#) and make it invisible, it will not be promoted. Now, in order to make everybody happy, this behavior is configurable. If you add: (promote-invisible "enabled") to the *gschemrc files (or editing system-gschemrc), invisible floating attributes will also be promoted (and in memory removed) However, if you enable this, then component slotting will break, because gschem expects certain floating attributes to be inside the symbol (in memory even though they are invisible). So you can add: (keep-invisible "enabled") to the *gschemrc files (or editing system-gschemrc). This is enabled by default, but has no effect unless promote-invisible is enabled. So, to summarize, attribute promotion takes floating attributes inside symbols and attaches them to the outside of a placed symbol. Three *rc keywords control this behavior: attribute-promotion, promote-invisible, and keep-invisible. 11. Resource File Gschem is highly configurable. All configuration is handled through a scheme based rc file. Gschem looks for three rc files: * system-gschemrc: This is usually installed in /usr/share/share/gEDA and is required for gschem to run. * $HOME/.gEDA/gschemrc: A per user file. Users should put defaults in this file they want to apply to all sessions. * local directory gschemrc: This file holds the per project defaults. Things like component-library or source-library keywords go into this file. The order of searching for these three files is as above (first system-gschemrc, then $HOME/.gEDA/gschemrc, and finally the local gschemrc). A few rules about changing the files: - Don't break any syntax rules. Doing so will cause the scheme interpreter (guile) to stop interpreting. - Keywords/defaults always override what came before, with the exception of cumulative keywords (like component-library). For more info as to what can be configured, please look in system-gschemrc. More TBA.