Statement of work: Improving PCB's usability within the gEDA Suite framework

Background and motivation

The open-source layout tool PCB has been a member of the gEDA Project for many years. It is an essential part of the end-to-end design flow offered by the gEDA tool set. That is, although gschem/gnetlist can (in principle) support many back-end PCB layout tools, the most advanced forward annotation tools have been developed for PCB, and the vast majority (if not all) of the gEDA Project's user base uses PCB as their layout tool. PCB is a core part of the gEDA Project's software offerings.

For a variety of reasons, many electronics designers find PCB's user interface difficult to master. Many tasks are best performed using PCB's internal command line (instead of menus or buttons), dropping to the unix shell, or even hand-editing design files using scripts or emacs. Some specific shortcomings of PCB have been widely noted on the geda-* e-mail lists, along with reasonable solutions. A list of the biggest issues includes:

We envision that addressing the above problems will provide a significant, powerful benefit to PCB's usability within the larger framework of the gEDA toolkit. Addressing the usability issues will bring the following specific benefits to the gEDA Project:

Therefore, the purpose of this document is to specify modifications to PCB which we hope will bring about a renaissance in the gEDA Project itself by making the critical tool PCB more accessible to the ordinary electronics engineer.

Statement of work

This section provides descriptions of what work is desired in each area of PCB's functionality. This is not a full specification; it is assumed that the person chosen to perform this work is familiar enough with the concepts associated with PCB design and the internals of PCB that this statement of work provides sufficient guidance about what to do.


General guidelines

GTK HID

PCB supports several HIDs. The HID is the interface layer which the user interacts with. The two major HIDs provided for interactive use are based upon 1) the GTK GUI widget set, and 2) The X/Motif GUI widget set. The work called out for this project shall be targeted at the GTK HID. The reason for this is simple: The rest of gEDA uses GTK. A primary goal the renovation work in PCB is to more tightly bind PCB into the entire gEDA workflow. More to the point: the gEDA tool chain should present a more uniform interface to the user. Users expect to see the same “look and feel” in all the tools they use. However, any changes made as part of this work shall not break any feature present in any other HID, including the Motif HID.

Code clarity

Many other changes are desirable in PCB. However, they are outside the scope of this work. The idea behind the changes specified here is that they create a launching point for other developers to come in afterward and continue improving PCB. Therefore, the developer must strive to make his code clear and well commented. Do not use hard to understand code tricks, obfuscating macros, or other devices which will hamper any follow-on work by other developers.

Doxygen

The developer should place Doxygen comments into the header of any new function he writes. Fully doxygenating PCB is outside the scope of this project, but the developer should at least use doxygen for the changes he makes.

Platforms

The upgrades to PCB must work on the usual platforms supported by the gEDA Project. Specifically:

Hooks for support on Windows systems are outside the scope of this project. However, any Windows features present currently in PCB should not break as a result of these changes.

Backwards compatibility

Any changes made to PCB should not break the ability of PCB to import existing .pcb files. It is allowed to break import of .new.pcb files (i.e. the output of gsch2pcb).


Forward annotation upgrade

Ideas, commentary, and examples from users

Feature description

The goal of forward annotation is to read the design information output from e.g. a netlister, and use it to import all information required into PCB, ready for use in creating or modifying a layout. Reading the following information is a required part of creating a PCB layout:

The scheme currently used by PCB is to read a file – already in PCB format – containing the actual footprints embedded within it. The netlist is read in using a separate step.

The new scheme would read a file containing a list of actions. Each line in the file would correspond to a separate action. The file would be generated by a forward annotation tool (e.g. gsch2pcb). The actions would correspond to the atomic actions performed by PCB itself when it finds a footprint by searching its footprint library.

For example, one line in the forward annotation file might say “(load-element-data SOT-23 U6)”. This would make PCB look for an SOT-23 package in its footprint library (using PCB's $FOOTPRINT_PATH), place it in a waiting position on the PCB, and give it the refdes “U6”. Another action might say “(add-line <layer> <X1> <Y1> <X2> <Y2> <width> <flags>)”, which would add a straight line segment onto layer <layer> from position (X1, Y1) to position (X2, Y2) having width <width> and flags <flags>. (The flags would specify things like whether the line ends are round or square, along with the other properties of a line.)

Besides importing footprint and graphical information, the new PCB forward annotation facility should import the netlist at the same time as the rest of the layout information. (This is currently a separate step, which is inconsistent with the goal of ease-of-use.)

Note that the above descriptions of the actions are meant to provide examples of how PCB should be modified. The details of each action are to be determined by the developer and the architecture of PCB itself.

Use cases

Once the forward annotation changes are complete, the following use cases should apply:

New PCB

  1. The user creates his design using gschem.
  2. He creates a forward annotation file by running the .sch files through gsch2pcb, which creates a single .pfa (PCB forward annotation) file.
  3. The user starts PCB.
  4. He clicks “File → new PCB”. A window pops up, providing a place to enter the new board's layer count and size. The window may also provide a way to specify common board templates (PC-104, 3U Eurocard, etc.)
  5. The new board is shown in PCB's main window as a white area on a darker background (as currently implemented).
  6. The user clicks “File → Import forward annotation file”.
  7. A file selection window pops up. The user clicks on his .pfa file and clicks OK.
  8. PCB reads each action in the forward annotation file, and does the corresponding thing.
  9. The PCB netlist is also imported during this activity. No separate netlist readin step is required.
  10. At the end of the file's read-in, the footprints should be present on the board (*not* in the paste buffer), ready to be disbursed and placed.

Existing PCB

  1. The user has a pre-existing .pcb file for the design under consideration. He makes changes to his design using e.g. gschem or gattrib.
  2. The creates a forward annotation file by running the .sch files through gsch2pcb, which creates a single .pfa (PCB forward annotation) file.
  3. The user starts PCB (or re-activates an existing PCB session running in its window).
  4. The user clicks “File → Import forward annotation file”.
  5. A file selection window pops up. The user clicks on his .pfa file and clicks OK.
  6. PCB reads each action in the forward annotation file, and does the corresponding thing. Using the refdes, the importer looks to see if the component in the forward annotation file is already placed in PCB, and if so, it ignores the action.
  7. The netlist is also read in and updated at this stage. No separate netlist readin step is required.
  8. Once this action is complete, the user is ready to continue editing his board.

Other Ideas

Work required

Some of the support for forward annotation already exists. Specifically, many actions are already supported. Therefore, this project involves:

  1. Creating the missing actions required for full forward annotation.
  2. Creating a method for reading in an action script.
  3. Integrating the new script-based forward annotation into PCB's GUI.
  4. Testing and bug cleanup.

GUI modernization

Ideas, commentary, and examples from users

The basic goal is to make the upgraded PCB behave exactly as an inexperienced user might expect, based upon his familiarity with modern GUI-based tools like OpenOffice. This means:

If the descriptions in this specification are ambiguous or unclear, use the behaviors implemented in gschem as the preferred example.

Actions

The following actions should be modified to support a “noun/verb” actions, if they do not support it already. Where possible, support for the current “verb/noun” actions should not be dropped to maintain compatibility for users who have learned the old actions. However, if there is a conflict between the new noun/verb and the old verb/noun actions, the new noun/verb actions take presidence.

Selection modes

The following selection modes must be supported:

Work required

This project involves:

  1. Refactoring and upgrade of program internals to support noun/verb actions.
  2. Create new windows (e.g. object editor, move, rotate, etc.).
  3. Refactoring and upgrade of program internals to support selection modes.
  4. Implementation of GUI resource file which is read in upon program start to configure user interface.
  5. GUI upgrade. Specifically, hook up the callbacks to the menu items and buttons defined in the GUI resource file.
  6. Testing and bug cleanup.

Footprint editor implementation

Incorporating a good footprint editor into PCB is a common request from users. It is important for PCB to clearly distinguish between editing a footprint and editing an entire PCB design. Here are two possible methods to accomplish this:

  1. Although it is not optimal, the symbol editing mode present in gschem provides a reference for how this might be implemented. Specifically, editing a footprint may be implemented as a “mode”, in which the user drills down into the footprint, and is placed into a special mode of the standard PCB editing window which is reserved for editing footprints.
  2. Another way to implement a footprint editor is to have a pop-up window with its own drawing pane along with editing widgets specialized for creating and modifying footprints.

Optionally, features involving editing footprints via the buffer will be removed. Alternately, retain the option allowing the user to draw in the main window, select, then invoke some menu option to convert the selection to a footprint. This option may exist alongside the new footprint editor.

Invocation

There are two ways to invoke the footprint editor:

  1. Create a new footprint. In this case the user will have no object selected on the PCB drawing window. He will then choose an option from the menu, like “tools → down footprint”. This will place the user into the footprint editor, and the drawing area will be empty
  2. Edit an existing footprint. In this case, the user will select a footprint present on the board by clicking on it. Then he will select an option from the menu, like “tools → down footprint”. This will place the user into the footprint editor, and the drawing area will hold a copy of the selected footprint, ready for editing.

As a third possibility, the user should be able to do “tools → create new footprint”, go into the editor, and then do “file → open” and select a footprint from the library to edit.

As a fourth possibility, allow a mode similar to gschem, where a library browser is used to select and place primitive objects. That would save the user from needing to know where the library files are hidden.

Editing

The footprint editor should be a graphical drawing environment similar to that presented by PCB for layout editing.

The design choice of which environment is better is left to the developer to decide based upon factors including input from the community, ease of implementation, etc.

Saving

Once the user has edited his footprint, he will want to save it out. This is a problematic action, since it's not a good idea to allow the user to overwrite a footprint living in the footprint libraries. Moreover, the user may not have write access to the library directories.

Therefore, when the user is done editing his footprint, there should be only one save action available under the file menu: “file → save footprint as”. This will call up the file save dialog, which will default to sticking the footprint in the current working directory (or the last directory he saved a footprint into during this session). The user will then be required to browse to his preferred save directory, and save the footprint there.

Leaving

Once the footprint editing session is done, the user may leave the editor and return to his main PCB editing session. This may be accomplished using a menu item like “tools → up to layout”. If any unsaved changes remain in the footprint, then the user should be prompted to either save or discard his changes before leaving the footprint editor.

Updating a footprint placed on the board

After editing a footprint and saving it out, the user will often want to update a footprint already present on the PCB. Here is the preferred method (use case) to do this:

  1. User selects footprint to update.
  2. From menu, user selects “tools → update footprint”. A keystroke to start this action may also be provided.
  3. A pop-up window opens, giving the user the footprint browser (as described above). The window will have has default footprint the name of the currently selected footprint.
  4. The user will either accept the default footprint presented, or he may search for a different footprint. When he is done, he will click OK.
  5. PCB will load the specified footprint from its library. Note: For this to work after editing a footprint, the user must place his local directory first on the footprint search path.
  6. PCB will then replace the old footprint on the board with the one pulled from the library. The old footprint (currently written into the .pcb file) will go away, and the new one will take its place.

Work required

This project involves:

  1. Create internal structures and methods needed to support a separate footprint editor.
  2. Create footprint editing window (if the separate window approach is adopted).
  3. Integrate access to footprint editor into main PCB GUI.
  4. Testing and bug cleanup.

Upgrade of layer and design objects

Feature Description

Currently, PCB's internal data structures only “know” about metal and silk layers. Other layers commonly used in PCB design are either missing (e.g. DRC layer, outline layer), or are simply derived from the metal layer (solder mask). This task involves implementing full support for layers of arbitrary type and layer count. Also, support for other design objects is part of this upgrade. Specific features required are:

Work required

This project involves:

  1. Upgrade internal structures and methods to enable full layer support.
  2. Create layer configuration window.
  3. Create internal datastructures and methods to support padstacks.
  4. Create padstack configuration window.
  5. Testing and bug cleanup.

Design Rule Checking Upgrade

Feature Description

The goal of design rule checking (DRC) is to insure that a printed circuit board layout conforms to a set of design rules. Design rules will consist of specifications like minimum copper line width, minimum copper spacing, etc. Generating a manufacturable PCB layout without DRC is tedious at best

The current PCB DRC steps through design rule violations one by one using a dialog box that reports the error, the coordinate position of the error and places the cursor at the error. Bouncing back and forth between the layout and the dialog box is time consuming. Knowing all of the errors prior to starting error correction is usually more productive.

A preferred method of reporting DRC violations would be to graphically indicate all errors on the layout. With this method all errors are quickly visible. DJ has suggested a layer for displaying DRC errors. The user should be able to turn the layer visibility on and off.

A useful option for DRC would be to have it run periodically. A proactive DRC should help novices avoid creating multiple similar errors. Threaded operation, or a DRC which works in packets of time where the mainloop hits idle would be possibilities here. Both have their merits and draw-backs. If the operation is slow, we'll need some way to queue the work such that updates to the board in the mean time queue updates for new DRC checking.

Similarly, we'd need to ensure that removing or changing objects on the board doesn't crash the DRC code - if it is running in a thread.

Use Cases

Manual DRC

  1. The user runs DRC using either a hot-key or menu item. An unobtrusive DRC status indicator is displayed. Perhaps the phrase “DRC Check” in yellow text in the top bar.
  2. DRC violation marks are displayed on the DRC layer or on the PCB the layout.
  3. An unobtrusive DRC status indicator is displayed. Perhaps the phrases “DRC PASS” in green text and “DRC FAIL” in red text in the top bar.
  4. If there are DRC failures the user can step to the next error manually or by using a hot-key. After changes are made the DRC can be run manually to verify the fix.

Automatic DRC

  1. Using a menu item the user can set the appropriate time interval for running DRC. A default value is used if a new value is not set.
  2. The user enables automatic DRC mode.
  3. After the DRC idle period has elapsed DRC runs. An unobtrusive DRC status indicator is displayed. Perhaps the phrase “DRC Check” in yellow text in the top bar.
  4. DRC violation marks are displayed on the DRC layer or on the PCB layout.
  5. An unobtrusive DRC status indicator is displayed. Perhaps the phrase “DRC PASS” in green text and “DRC FAIL” in red text in the top bar.
  6. If there are DRC failures the user can step to the next error manually or by using a hot-key. After changes are made the DRC can be run manually to verify the fix.

Work required

This project involves:

  1. Implementation of DRC layer (part of work called out in “DRC Upgrade” section).
  2. Upgrade existing DRC checker with new DRC layer.
  3. Update GUI to use upgraded DRC checker.
  4. Testing and bug cleanup.

Project milestones, duration, and budget estimates

Although they are intertwined, the major focus areas are scoped independently here. Ordinarily, a project manager would put a Gantt chart here, but that level of detail is probably too fine for the purposes of an open source project. Therefore, I simply call out an estimated time required for each subtask. The project duration times are SWAGs based upon my limited experience in estimating software projects. They are based upon 8 hour work days (i.e. this work is performed as a full-time job) at a nominal billing rate of $50/hour. It is up to the developer to validate these estimations and negotiate his own billing rate before he agrees to perform this work.

Forward annotation upgrade

  1. Determine which actions remain to be scripted so that forward annotation of any board is possible using an action list. (2 days).
  2. Define syntax for remaining actions, and document full syntax (2 days). This document will be used to update gsch2pcb (outside the scope of this project).
  3. Write sample action scripts for testing purposes (1 day).
  4. Creating the missing actions required for full forward annotation (3 days).
  5. Creating a method for reading in an action script (2 days)
  6. Integrating the new script-based forward annotation into PCB's GUI (1 day)
  7. Testing and bug cleanup (5 days).

Total duration: 16 days = 128 hours. Cost: $6400

GUI modernization

  1. Refactoring and upgrade of program internals to support noun/verb actions (5 days)
  2. Create new windows (e.g. object editor, move, rotate, etc.) (5 days).
  3. Refactoring and upgrade of program internals to support selection modes (5 days).
  4. Implementation of GUI resource file which is read in upon program start to configure user interface (3 days).
  5. GUI upgrade. Specifically, hook up the callbacks to the menu items and buttons defined in the GUI resource file (3 days).
  6. Testing and bug cleanup (5 days).

Total duration: 26 days = 208 hours Cost: $10400

Footprint editor implementation

  1. Create internal structures and methods needed to support a separate footprint editor (4 days).
  2. Create footprint editing window (if the separate window approach is adopted) (3 days).
  3. Integrate access to footprint editor into main PCB GUI (2 days).
  4. Testing and bug cleanup (5 days).

Total duration: 14 days = 112 hours. Cost: $5600

Layer/design object upgrade

  1. Upgrade internal structures and methods to enable full layer support (5 days).
  2. Create layer configuration window (3 days).
  3. Create internal datastructures and methods to support padstacks (4 days).
  4. Create padstack configuration window (3 days).
  5. Testing and bug cleanup (5 days).

Total duration: 20 days = 160 hours. Cost: $8000

Design Rule Checking Upgrade

  1. Implementation of DRC layer (part of work called out in “DRC Upgrade” section) (0 days, assuming layer upgrade is complete).
  2. Upgrade existing DRC checker with new DRC layer (3 days).
  3. Update GUI to use upgraded DRC checker (2 days).
  4. Testing and bug cleanup (5 days).

Total duration: 10 days = 80 hours. Cost: $4000