pcb-rnd - user manual

2. Model of the world

Pcb-rnd is designed to handle the geometric data of a PCB. This section describes how pcb-rnd represents reality (e.g. copper shapes) in memory.

2.1. Board

Each design pcb-rnd handles is a board. The board has global properties and hosts layers. Most drawing primitives (objects) are on layers. This section describes the most important global properties.

Board size is given as a width and a height. For rectangular boards this can be the real board size, but more commonly it is used to simply determine the on-screen drawing area and the final board dimensions are specified using the outline layer. If the board is not rectangular, the contour must be specified on the outline layer and the board size must be large enough that the outline fits in it.

Netlist is the list of logical connections to be realized in copper. A netlist is a list of named nets. Each net consists of a list of terminals (pins or pads) to connect. A terminal is given as elementname-pinname, e.g. U4-7 means "pin number 7 in element called U4".

Fonts are always embedded in the design file in order to guarantee that the file can be ported and will look the same on different hosts.

Misc editor settings, such as grid size and offset.

2.2. Layers

The main use of pcb-rnd is to aide the user in the process of producing real pcbs composed of real physical layers. pcb-rnd also refers to layers to conceptualize this process, but pcb-rnd layers are different than the physical layers.

Unlike a physical layer, a pcb-rnd layer has no thickness. Any pcb-rnd layer is always part of a layer group. It is a 2 dimensional logical canvas, similar to layers in image manipulation software like GIMP. In pcb-rnd there are explicit, virtual or implicit layers. An explicit layer contains drawing primitives (objects) placed by the user. The user has full control over an explicit layer: objects can be added or removed or changed any time. A virtual or implicit layer has no such flexibility: pcb-rnd computes its content from explicit layers and there's no way for the user to change the result directly.

Pcb-rnd currently maintains some layers types as virtual layers for compatibility with the PCB package. In a pcb-rnd board design started from default configuration options, the mask, silk, and paste layers currently start out as virtual layers. The content for these layers is computed by pcb-rnd as for a virtual or explicit layer, until the user decides to use features that require user control over one or more of the layers in the group. At that point, the virtual layer is replaced with an explicit layer group.

For example, in pcb-rnd when using one of the gtk GUIs, if the user right clicks on a solder mask ('mask') layer and choose an option to 'insert new layer before this one', pcb-rnd replaces the virtual mask layer with an explicit mask layer group. The mask layer group can contain one to many pcb-rnd layers each with individual settings to control implicit generation, and additive or subtractive behavior when adding objects to the layers.

2.3. Layer Groups

One or more explicit layers form a layer group. All pcb-rnd layers of a layer group will end up on the same physical layer. The visibility of layers in a layer group are toggled together. Having more than one layer in a group may be useful to:

Since layer groups donate the physical layers, a board stack-up is built of layer groups. Substrates are layer groups without drawable layers in them. The mask, paste, silk layer groups behave the same and can host zero or more logical layers.

Each layer group has a type. Types are:

Each layer group has a location. Locations are:

Not all combination of type and location are supported: e.g. for an outline layer group the location is always global. The table below lists whether a combination is supported or not.

Layer Combination Support
  top bottom intern global composite
copper yes yes yes no no
silk yes yes no no yes
mask yes yes no no yes
paste yes yes no no yes
outline no no no yes no

2.4. Basic Drawing Objects

Pcb-rnd supports a small number of basic drawing objects, from which complex objects can be build. The following figure demonstrates all basic objects:

[Arc, Line, Polygon, Pin, Via]

Objects have flags that control their behavior. The following flags are common to all objects:

Object Flags
name description
selected selected by the user ("cyan")
found found as a galvanic connection in the last connection lookup ("green")
warn offending object e.g. in a short circuit ("orange")
lock locked by the user: can't be selected, moved or changed

2.4.1. Line Objects

Lines are round ended straight line segments with a width and a clearance. The above image shows 3 lines connected. Lines are mainly used to construct traces. A line is always on a specific layer. The user interface allows drawing lines aligned to 90 or 45 degree axes or lines with random angle.

A line is specified by its two endpoints, width and clearance:

[Line interacting with a polygon]

A clearance is the gap between a line and the surrounding polygon in the same layer group. The gap is made only if the surrounding polygon has the "clearpoly" flag set and the line has the "clearline" flag set. If either of these flags is not set, no gap is made - or in pcb-rnd terminology, the line is joined to the polygon.

Line Object Flags
name description
clearline clears polygons with the "clearpoly" flag in the same layer group

2.4.2. Arc Objects

Arcs are round ended circular arcs with trace width and clearance. They behave like lines in all respects.

[Arc interacting with a polygon]

Although the arc is described with its center, radius, start and end angles, the user interface may offer drawing arcs by endpoints.

Arc Object Flags
name description
clearline clears polygons with the "clearpoly" flag in the same layer group

2.4.3. Polygon Objects

Polygons are solid, filled copper areas with optional holes in them. Polygon contour consists of lines - when they look curvy, its really high resolution line approximation. There are two type of holes in a polygon: explicit, user drawn holes and clearance cutouts. User drawn holes are "negative" polygons drawn manually. To keep polygons simple, if an user drawn hole touches the contour of a polygon, the hole is removed and the contour is modified; if two holes touch, they are merged into one hole.

If the polygon has the "clearpoly" flag set (default), clearance cutouts are automatically inserted around objects on the same layer group:

Overlapping or touching polygons are not automatically merged. An object with the "clearline" flag set will clear all "clearpolys" it is over - if there are multiple such polygons overlapping under the objects (on the same layer group), all such polygons get the clearance cutout.

If a polygon is cut into multiple islands, the behavior depends on the "fullpoly" flag of the polygon. If it is not set (default), only the largest island is kept, else all islands are kept. In the "fullpoly" mode islands will have no galvanic connection (unless the user adds vias and connect them on another layer), still the program will handle all islands as a single polygon. This is risky: the program will indicate connection between polygon islands that are not really connected, only because they are part of the same polygon!

Polygon Object Flags
name description
clearpoly should have clearance around objects, if the objects have the appropriate flags too
fullpoly keep all islands, not only the largest

2.4.4. Text Objects

A text object is string and a series of symbols (pcb-rnd's terminology for glyph). Symbols are built of lines and are stored in the font. Each board can have its own font, but there can be only one font per board. When the string of the text is edited, the object is rendered again so that the new string appears.

Text objects can be placed on copper and silk layers. Text can be rotated only in 90 degree steps. Each text object has a scale parameter that determines its size in percentage. A scale of 100% means symbols are rendered in 1:1 size.

The clearance around text is rendered as a round corner rectangular cutout. Bug: copper text can not participate in short circuits, the galvanic connection checker code skips texts.

2.4.5. Via Objects

A via is an electrically connected hole that connects copper rings to multiple layers. Thermal relief styles are available to both pads and pins, and the shape styles of a via are available to pins. Since a via hole always punches all layer groups and applies the same ring style on any outside layer groups, blind or buried vias and individually defined layer pad stacks (e.g. with changing ring shape per layer) are not possible using the via object.

A thermal relief property is added to the copper rings of a via when it is connected to the surrounding polygon of any individual layer. Physical designs may use thermal reliefs to enable easy hand soldering, or reduce occurrence of tombstoning in automated production.

The following thermal relief options are available:

Pad/Pin/Via Thermal Relief
Thermal Relief Appearance
no connection unconnected via
solid solid thermal
round x 90 Thermal relief arc style
round x 45 Thermal relief arc style, 45deg
crossbar x 90 Thermal relief crossbar style, 90deg
crossbar x 45 Thermal relief crossbar style, 45deg

A variety of pin pad shapes are also available to the pcb-rnd user. The copper annulus (ring) on the outside layer groups is selectable from a predefined set of shapes that provide solderability or can be used to indicate a special pin. Flags in the via object define the shape used.

Via Annulus Shape Styles
Shape Appearance
ring (default) Ring via style
square Square via style
octagon Octagonal via style
asymmetric Asymmetric via style

2.4.6. Element Objects and Footprints

An element is an instance of a footprint that is already placed on the board or loaded into a paste buffer.

In the footprint form the construct is small and flexible. It describes all the physical parts, like pins, pads, silk lines. In the same time a footprint leaves many details blank, e.g. it doesn't specify exact layers, it doesn't have font and the refdes is random.

When the footprint is loaded, it becomes an element. The element inherits all the physical properties and the blank details are filled in with the data taken from the current board: the layer binding is done, all parts of the element lands on a specific board layer; the refdes is rendered using the font in the current board.

The footprint -> element instantiation is also a copy. Once the element is created from a footprint, the element is a self-containing object and does not have any direct reference to the footprint it was once derived from. Changes to the original footprint will not affect the elements.

In other words, a footprint is an abstract recipe, part of a library, while an element is a land pattern already embedded in a specific design and describes actual copper and silk.

Currently an element or footprint can contain the following objects:

An element has the following properties:

Element Properties
element property description
name: refdes unique identifier, e.g. "C42"
name: value informal value, e.g. "15 pF"
name: description informal element or footprint description, e.g. "1206"

Extra object flags:

Element Flags
name description
ONSOLDER when set, the element is on the bottom side, else it's on the top side
NONETLIST when set, the element is not intended to be on the netlist; useful for elements that are not present on the schematics and are placed during the layout design
HIDENAME when set the name of the element is hidden
DISPLAYNAME when set the names of pins are shown

2.4.7. Pins of Elements

A pin of an element is really a via, plus some metadata and capabilities: Each element has its own list of pins. Pin rings can overlap (which will make galvanic connection). There may be duplicate pin numbers and pin names. Pin numbers are in the same namespace as pad numbers. A pin has the following properties:

Pin Properties
name description
name pin name, e.g. "base"
number pin name, e.g. 2
intconn internal element connections (see section TODO)
Extra object flags:

Pin Element Flags
name description
via flags (extra flags listed for vias are applicable to pins too)
WARN the pin contributes to a short circuit ("orange mark")

2.4.8. Pads of Elements

A pad is an smd pad of an element. It is modelled as a line segment, usually with square cap - this makes the pad look like a rectangle. A pad has the same metadata and capabilities as pins. Overlapping pads are supported. A pad is always on either the top or the bottom copper layer group.

A pad has the following properties:

Pad Properties
name description
name pin name, e.g. "base"
number pin name, e.g. 2
intconn internal element connections (see section TODO)
Extra object flags:

Pad Object Flags
name description
via flags (extra flags listed for vias are applicable to pins too)
WARN the pin contributes to a short circuit ("orange mark")
EDGE2 indicates that the second point is closer to the edge. For pins, indicates that the pin is closer to a horizontal edge and thus pinout text should be vertical. (Padr.Point2 is closer to outside edge also pinout text for pins is vertical)

2.4.9. Subcircuits

A subc (subcircuit) is a group of objects with its own, local layer information. All layers of a subc are bound layers, that is, the user is free to choose on which actual board layer it is placed on. There is no limitation on what layers or objects a subc can contain.

The main uses of subc are:

2.4.9.1 Subcircuits as footprints

When a subcircuit is a footprint, it normally has the refdes attribute set. Refdes is the name that identifies the part on the netlist. Some objects of a footprint will have the term attribute to turn those object into terminals (representing pins or pads). If multiple objects have the same term attribute value, they are all contributing to the same terminal.

When the terminal object is a single padstack, it is called a light terminal. When the terminal is built using multiple objects, it is called a heavy terminal.

A connection on the netlist is identified as refdes-term, e.g. U5-3 means "the object(s) whose term attribute is 3 within the subcircuit whose refdes attribute is 'U5'".

2.4.9.2 Subcircuits as repetitive modules

Compared to subcircuits as footprint, a repetitive module will not have a refdes attribute and will not have terminals.

2.4.10. Pad stacks

A pad stack is a generic pin/pad/via object that may contain any combination of:

Pad stacks are flexible enough to cover the majority of the simple pin/pad/via cases. In a subcircuit, marked as a terminal, a pad stack is called a light terminal. This concept exist in parallel to the heavy terminal concept: a heavy terminal consists of multiple objects (e.g. polygons, lines, arcs, pad stacks), all tagged to the same terminal. When the pad stack model is not capable to describe a complicated pin or pad, the user should chose the heavy terminal model. A typical example is the center pad of a QFN footprint with vias for heat transfer and a specific pattern of paste. The strength of a pad stack is it's relative simplicity and that all objects on the vertical stack are bundled together; the strength of the heavy model is its flexibility: anything that can be drawn on board can be turned into a heavy terminal.

The optional hole of the pad stack is useful if the pad stack is to be used as a mounting hole, via or pin. The span of the hole is described by two integers: how far the hole starts and ends from the top or bottom copper layer group, counted in copper layer groups.

A simple all-way-thru hole's span is 0;0, which means it starts at the top copper group and ends on the bottom copper group. Or precisely, "starts 0 groups down from top copper group and spans until 0 groups up from the bottom group". That is, when hol span values are positive, the top of the hole is counted from the top copper group down and the bottom of the hole is counted from the bottom group up. If a span value is negative, it is counted from the other side, e.g. a 0;-3 means: "hole top is 0 groups down from top copper group, hole bottom is 3 groups down from the top copper group". Or in other words, the topmost four copper layer groups are connected by the via.

The plating of the hole is a boolean and is independent of any other parameter.

For each layer group type, the user may specify zero or one pad shape.

Pad stack layer group types
name remarks
top silk  
top paste  
top mask the first negative layer is used
top copper  
intern copper the same pad will be used on all internal copper groups
bottom copper  
bottom mask the first negative layer is used
bottom paste  
bottom silk  

Pad shapes
name description
fillcircle x;y offset of the center, diameter
line round or square cap, from x1;y1 to x2;y2 with the specified thickness
simple-polygon a simple polygon has a single outer contour and no holes

The pad stack has an origin, a 0;0 point where it is grabbed. If the pad stack features a hole, the origin is the center point of the hole. Pad shapes are all defined in a way that they do not have to be concentric with the hole or the origin. This allows asymmetric pads.

In case of blind/buried vias, the internal copper layer pads are applied only on layers with hole span. However, this does not apply to top/bottom shapes, those are always explicit. This means it is possible to use a pad stack as a pad-pair of an board edge connector, having a copper pad on the top layer and one on the bottom layer, even without having a (plated) hole in between. The code will assume connection between the pads only if the pad stack has a plated hole.

If the global clearance is set, it overrides the per layer type clearance and the padstack will have the same global clearance on all layer groups on which it has copper objects.

Typical pad stack examples
name description
rectangular smd pad no hole; square cap line or polygon on top copper, top mask and top paste
simple pin or via plated hole and the same filled circle on all copper layers; if pin, a slightly bigger circle on the mask layers
octagon pin or via plated hole and the same simple polygon (octagon shaped) on all copper layers; if pin, a slightly bigger polygon on the mask layers
'oblong' pin plated hole, a short round cap line segment on the bottom copper and mask layers, filled circle on all other copper layers and on the top mask layer
blind via plated hole and the same filled circle on internal and top copper layers - nothing on the bottom copper layer
power jack with slot n/a - can not be done with pad stack as the plated slots for the pins can not be represented as plated round holes - use heavy terminals instead

Pad stack prototypes are stored only once per pcb_data_t (only once per board for vias or per each subcircuit for terminals). The actual pad stacks placed on the board (or in subcircuit) are called pad stack references. A pad stack reference has its own x;y coordinate (within the board or subcircuit), a rotation angle and a mirror flag. This means if a TQFP chip has 48 pads along 4 sides, in the simplest setup there will be onlt one pad stack prototype and 48 pad stack references using the same prototype with different coordinates and rotations.

Each padstack reference has an optional global clearance; if it is non-zero, this value is used as clearance on all layers for this instance. When it is zero, the prototype's per shape clearance applies, which makes it possible to have different clearance for internal layers, for example.

Each padstack reference has a per board layer list of thermal relief types.

2.4.11. Rat line Objects

A rat line represents a logical connection that is not yet realized in copper. It requires a loaded netlist for generation, and relies on calculations for any existing copper layers that connect terminals on the pcb-rnd board. Rat connections are straight line connections between the terminals of any two drawing primitives that aren't yet connected

2.4.12. Netlists

A netlist is a list of named logical networks. Each network is a list of netlist terminals that should be connected. A netlist terminal is a pair of element-refdes and pin-number (or pad-number). Thus a typical netlist looks like the following:

The netlist assumes element refdes are unique. If an element has multiple instances of the same pin (or pad) number, the engine picks one randomly and assumes there's an invisible, internal connection within the element.

Rat lines can be regenerated from the current netlist for missing connections. Connections that are realized in copper but not present on the netlist, pcb-rnd gives a "short circuit" warning. Both happens when the net is "optimized" (upon user request).

The netlist is typically derived from a schematics by external tools (such as gnetlist). The netlist can be imported (updated) any time. This process is called "forward annotation".

It is also possible to make changes to the netlist from within pcb-rnd: pins can be swapped, element packages replaced using back annotation actions. Such actions will keep a list of intended netlist and element changes, called the netlist patch. Pcb-rnd will keep these changes even if a new version of the netlist is imported. It is possible to export the netlist patch that can be imported in the schematics editor to change the schematics - this process is called "back annotation". A new forward annotation from the schematics editor to pcb-rnd will then cancel the netlist/element changes as the new netlist import netlist matches the intended (changed) netlist.

2.5. Comparison of Physical world and pcb-rnd world terminology

Pcb-rnd Terminology
Physical board pcb-rnd Description
Layer Layer Group enables the user to design complex physical constructions
Copper layer Layer group with copper layers designed with one to many pcb-rnd layers
Component/Top copper layer Layer group with copper layers any group of copper layers defined as the 'top' of a board
Solder/bottom copper layer Layer group with copper layers any group of copper layers defined as the 'bottom' of a board
Substrate Layer group marked as substrate, hosting no logical layers pcb-rnd does not yet handle properties of physical substrate information
Contour of the board Outline layer designed using standard pcb-rnd elemnts
Outline routing path Outline layer designed using standard pcb-rnd elemnts
Polygon pour Polygon an object available for design in any layer group
Plane Polygon see above
Mask (solder mask) Layer group with implicit and potential explicit content design layers available: automatic, additive, subtractive
Silk Layer group with implicit and potential explicit content design layers available: automatic, additive, subtractive
Paste (paste stencil) Layer group with implicit and potential explicit content design layers available: automatic, additive, subtractive
N/A, or poss. net/circuit Rats assistive layer automatically generated with netlist and copper layer group connection data