Wiki

Welcome!

Here you will find work-in-progress instructions on how to get started with PCBmodE!

Clone the repo

Clone the repo to a local directory.

Use the development branch

This is important: switch to the development branch of the repo (git checkout development). The production branch doesn't get updated often.

Get the required packages and software

You'll need Python 2.7 (Python 3 is untested, but may work), the latest Inkscape, and the latest lxml and pyparsing Python packages.

Directory structure

If pcbmode.py is in /pcbmode/ then the board's data should be in /pcbmode/boards/<board_name>.

Compiling an example board

There are quite a few example boards within the PCBmodE repository. Try compiling some of them to test that the mechanics work. Here's how you'd compile the 'redditoken' board:

cd pcbmode
python pcbmode.py --board-name redditoken --make-board --fab --make-pngs

or alternatively in short-hand switches:

python pcbmode.py -b redditoken -m --fab -p

PCBmodE will create a build directory within the board's path to store the generated files. This directory can be safely deleted (unless you made changes to the SVG that haven't been extracted; details later). Within the build directory, you'll find the SVG, which in this case will be called redditoken.svg. The PNGs will be within images and Gerbers within production sub-paths.

NOTE: typing python pcbmode.py --help will give you a list of possible switches

Examine generated files

Open the SVG with Inkscape. If you open the layers pane (CTRL+SHIFT+L) you'll be able to show/hide or lock layers.

NOTE: Copper pours are always locked because they have focus, but are rarely need changing, so they are just in the way.

Open the Gerbers with a Gerber viewer. Under Linux, gerbv works really well.

Finally, open the PNGs with an image viewer or a browser.

Take a break

This should have been rather painless, one hopes. Now please go get a cup of tea, and relax.

NOTE: PCBmodE was written under the influence of the Russian Caravan tea blend. Results may be better for you if that's the tea you'll be drinking!

PCBmodE is in an "alpha" stage and will require patience and perhaps some experimentation on your part. But first, while you're sipping your tea, here's the basics of the PCBmodE structure.

The input files for the boards are in JSON format. That's where the data required for generating a board is stored and what goes into the board's repository. A typical board consists of a board file, <board-name>.json and component files that are stored in the board/<board-name>/parts path. Those files are edited by hand. So, for example, in order to place a new component, you'd add something like this:

#!json

"LED1": {
  "footprint": "led-1206", 
  "location": [
    5.44, 
    3.345
  ],
  "rotation": 90
}

to the placement->components->top hierarchy. The reference designator for this component is LED1 and must be unique. The value for the key footprint corresponds to the filename of the part you want to instantiate -- in this case led-1206.json. The component will be rotated 90 degrees clock-wise and will be placed at location X=5.44 Y=3.345 millimeters from the centre of the board [0, 0].

NOTE: PCBmodE uses the metric system, and places the origin at the centre of the board's outline.

PCBmodE uses SVG paths to define shapes. You'll see that the redditoken's outline is defined as follows

#!json

"board_outline": {
  "measurements": {
    "font": "UbuntuMono-R-webfont", 
    "scale": 0.0008
  }, 
  "shape": {
    "type": "path", 
    "value": "m -8.222,0 c 0,-3.5802836 -2.868656,-7.1825497 -1.778,-10.592667 0.2738992,-0.856391 1.0646304,-1.593839 1.9073333,-1.907333 2.5350476,-0.943063 5.3878868,0.592667 8.0926667,0.592667 2.7047799,0 5.5576191,-1.53573 8.0926667,-0.592667 C 8.9353696,-12.186506 9.7261008,-11.449058 10,-10.592667 11.090656,-7.1825497 8.222,-3.5802836 8.222,0 8.222,3.5802835 11.090656,7.1825494 10,10.592667 9.7261009,11.449058 8.9353696,12.186506 8.0926667,12.5 5.5576192,13.443063 2.7047799,11.907333 0,11.907333 c -2.7047799,0 -5.5576192,1.53573 -8.0926667,0.592667 C -8.9353696,12.186506 -9.7261009,11.449058 -10,10.592667 -11.090656,7.1825494 -8.222,3.5802835 -8.222,0 z"
  }
},

The outline shape is of type path and the value is an SVG path. So you're probably wondering where did this come from? Well, it comes from Inkscape and manually pasted into the JSON files.

NOTE: PCBmodE only takes paths, not any of the SVG constructs for rectangles, arcs, circles, etc.

In addition to using Inkscape as a viewer, it is also possible to move components and draw routes, which are then extracted by PCBmodE and put into JSON source files for us. We'll see how this is done later.

OK, your tea should be nearly done by now. Let's get both hands ready for some heavy lifting.

Getting things done

Let's try changing the the board's outline shown above. Open the redditoken SVG and move one of the outline nodes. Then open Inkscape's built-in XML editor (CTRL+SHIFT+X) and click on the outline path. In the XML editor you'll see under the key d the SVG path. Choose it, and copy and paste that into the board's JSON file replacing the original path. Save the JSON file and re-generate the board:

python pcbmode.py -b redditoken -m

In Inkscape close the XML editor and press ALT+F and then V to reload the SVG. You'll now see the new outline.

Basic shapes such at rectangles and circles can be generated automatically with simple definitions like this:

#!json

{
  "type": "rect",
  "width": 1.25,
  "height": 1.1,
  "offset": [0, 0],
  "style": "outline",
  "stroke_width": 0.3,
  "rotate": 0,
  "radii": {
    "bl": 0.15, 
    "br": 0, 
    "tl": 0.15, 
    "tr": 0
  }
}

will generate a 1.25 by 1 mm square with 0.3 mm stroke width. The radii field defines the radius of a corner, so the left-hand corners will be rounded with 0.15 mm radius. And

#!json

{
  "type": "circle",
  "diameter": 5,
  "style": "fill",
  "offset": [0, 0]
}

will place a 5 mm filled shape.

These definitions can be used for every layer.

Component JSON files are made in a similar way -- open some up, and it'll be pretty clear.

So components are placed by manually entering a coordinate in the value of the location key. However, it is useful to be able to move them inside of Inkscape, and be able to use the powerful alignment tools it provides.

NOTE: For component movement, the only thing that matters are the pads, which should stay grouped as they are when the board is generated.

Open the 'redditoken' board and highlight a component by choosing all its components. Use the arrow keys to move the entire thing, although only the pads are important. Save the SVG, and run the following command

python pcbmode.py --board-name redditoken --extract-from-svg

or in short-hand

python pcbmode.py --board-name redditoken -e

Then re-generate the board

python pcbmode.py --board-name redditoken -m

and re-load the SVG (ALT+F, V). You'll see the component has now moved. If you reload the board JSON file in your editor, you'll see that the coordinates have changed to reflect the new location.

Inkscape is also used for drawing routing. There are two types of routing

stroke: a stroke of constant width
fill: a closed filled arbitrary shape

The most convenient is stroke because it easier to manipulate. When needing a varying width route, it's best to keep it a stroke to the very end, and then convert it to a filled shape and edit the nodes of the shape.

To place a route you must be editing the 'routing' layer of the PCB layer. You can choose that layer using Inkscape's layer pane (CTRL+SHIFT+L). Then draw a stroke. In a bit of a clunky procedure, you'll now need to edit the properties of this stroke so PCBmodE knows how to process it. Using Inkscape's XML editor, make the style field look something like this:

#!XML


fill:none;stroke-width:0.35;stroke-linejoin:round;stroke-linecap:round;

The fill:none; tells PCBmodE that this is a stroke; stroke-width:0.35; tells it the stroke width. stroke-linejoin:round;stroke-linecap:round; makes sure that the SVG looks the same as the resultant Gerber files (why this is necessary is outside the scope of this document). If you created a closed shape and want it filled, the style should look like this:

#!XML


stroke:none;

Now save and extract as before. The new routes will be saved in <board-name>_routing.json. Re-generate the board to see if you've been successful with your first PCBmodE route! You can now simply copy and paste the route without needing to edit its properties.

NOTE: PCBmodE can only read paths, not any other SVG construct. So if you're drawing an elipse, for example, you must first convert it into a path in order to have PCBmodE process it. You do this using Inkscape's path->object to path and path->stroke to path.

In PCBmodE, vias are defined just like any other component, so any shape of pads, soldermask, silkscreen, etc are possible (drills need to be round, though multiple ones can be defined). In the parts library, create any type of via that's needed -- the name of the file is what is used as the via's identifier (for example, VIA.json)

To add a via, choose the a routing layer as above. Then choose the pencil tool (or press F6), go to via's location and click CTRL+LEFT-CLICK. This will place a dot of a particular diameter -- the size of the dot does not matter, only its centre position. Right click on the dot and choose 'Object Properties', and in the Label field enter via: plus the via's identifier. So if the via file is called VIA.json (on the board's parts directory), enter via:VIA. If the board's configuration file has a vias entry to define a default via,

#!json

"vias":
{
  "default_via": "VIA"
}

then via: or via:default will instantiate that via type. This way you can use any number of via types on your board.

Now extract and re-generate as above, and a via will be placed where the dot was. To move or delete a via, simply move or delete the via's drill; there's no need to move or delete any other of the via's feature on any other layer.

Getting further help

You'll undoubtedly encounter issues and bugs. If you are able to identify a solution and issue a pull-request, that'd be awesome.

The following resources are available for getting help:

Bitbucket's issue tracker
Boldport's discussion group

Since these resources are public, use them instead of emailing Saar directly. This will help others that are encountering similar issues, and will help build a healthy vibrant community around PCBmodE. That said, Saar would love to hear your thoughts, so feel free to email him at saardrimer@gmail.com. for updates please also follow Boldport's blog and twitter account.