pcb-rnd knowledge pool


Doc/mech layer group type/purpose conventions

doc_grps by Tibor 'Igor2' Palinkas on 2019-08-09

Tags: RFC, layer, group, keepout, mech, doc, courtyard, assembly, assy, fab, drawing

node source



Abstract: pcb-rnd can handle arbitrary doc layer groups and layers set up by the user. This document contains recommendations on how to use these custom layers and layer groups.


Purpose of this document

This document tries to establish a minimum set of conventions that footprint designers are recommended to follow. The reasons for this:

What this document intentionally does not cover is the case of less common, more exotic custom layers that affect only a small fraction of use cases ( Rationale ).

The doc type is used for a layer group to indicate that objects drawn on these layers are not to be fabbed in any way. They are rather part of the documentation, to document the intentions of the designer in a computer readable format.

The mech type is used for a layer group to indicate that objects drawn on these layers will have some direct impact on fabbing - some CNC code will need to cut or drill or otherwise alter some material using the shape of these objects.

The boundary layer type is used to indicate the perimeter of the boards and larger internal cutouts. This is distinguished from slots because these often need different processes on the fab side.

type loc purpose layers code dflt description
boundary g cut 1p yes no To save fabbing costs, straight edges can be cut with a saw instead of routing. Especially useful for rectangular boards, where routing, if any, happens only for slots. Not compatible with panelizing.
boundary g vcut 1p yes no A must for finger connectors made in PCB that will slide into a slot (e.g. how PCI works). Often used for panelizing rectangular boards on cheap production - slicing up the populated/soldered panel is done by cracking them off along the v-cut. This covers not only real v-cuts but connector chamfer edge too.
doc t, b assy 1p yes yes Assembly drawing for building the board. Contains information for (mainly manual) part population and an overview of the assembled board for debugging. Later on will also contain the automatically generated assembly drawing.

Code: the renderer draws the assy layer here, often from silk.

doc t fab 1p no yes Fab drawing for building the board. Contains information for (mainly manual) cutting and drilling the board, but may also be useful for a generic mechanical drawing for testing if a board shape fits in a box. Later on will also contain the automatically generated fab drawing.

Code: the draw_fab plugin draws the fab layer here using padstacks.

doc t, b ko.courtyard 1p no (yes) Mechanical keepout (ko): mechanical parts of a component sticking out in the top or bottom direction. If ko.courtyard graphics of two subcircuits intersect, that's considered a mechanical error (board can not be built). The programmable DRC is able to check for this. Never use layer compositing , only a single, positive layer. Prefer drawing only polygons on this layer. DRC scripts use the purpose string.
doc t ko@top-copper 1p no no Copper keepout (ko): the part does not tolerate copper features in the top copper layer group. Never use layer compositing , only a single, positive layer. Prefer drawing only polygons on this layer. DRC scripts use the purpose string.
doc b ko@bottom-copper 1p no no Copper keepout (ko): the part does not tolerate copper features in the bottom copper layer group. Never use layer compositing , only a single, positive layer. Prefer drawing only polygons on this layer. DRC scripts use the purpose string.
doc t ko@top-mask 1p no no same as copper-keepout, but for mask
doc t ko@bottom-mask 1p no no same as copper-keepout, but for mask
doc t ko@top-paste 1p no no same as copper-keepout, but for paste
doc t ko@bottom-paste 1p no no same as copper-keepout, but for paste
doc t ko@top-silk 1p no no same as copper-keepout, but for silk
doc t ko@bottom-silk 1p no no same as copper-keepout, but for silk
doc t, b, g placement 1p no no General, free form information about part placement for the layout designer. Typical examples:
  • indicating location of the board edge in case of connectors or other parts that has to be mounted near the edge
  • drawing of the mating pair of the connector or wires exiting from the part or other, external mechanical parts that are not connected to the bare board at assembly time but connected by the user
mech t, b adhesive c maybe no Where to put adhesive (glue) dots. Commonly used on double sided smt assembly to hold bottom side parts in place. Also used in some rare cases to fixate otherwise loose or moving parts, e.g. cores attached for a PCB transformer. Objects drawn depends on the gluing technology available, but it normally should be used with a single positive layer and zero length lines for glue dots.

The core later on might be processing this layer to make sure it ends up on top of the layer stack.

mech t, b finish. material c no no Indicate where local special finish should go, like gold fingers, carbon patterns. The material is one of:
  • gold
  • carbon
or a custom word. How exactly this should be indicated, e.g. drawing a polygon around the area or drawing lines over the fingers, depends on the fab.


What is not added

Overlay/coat: in some rare cases people print extra insulation layers on top of the finished board, maybe glue around the edges of BGA parts. These cases are so rare that I don't think it should have a centrally documented convention. The mech/finish could be abused for this.

Some trapezoid or T shaped parts may need different (mechanical) courtyard at different heights. This is a rare case and when this matters one should probably use a 3d CAD to place those critical parts first, then import the placement info in pcb-rnd, place the footprints and lock the subcircuits. Still, if a pcb-rnd-only path is chosen, the user is free to create multiple custom ko layer groups, e.g. using

Such 3d courtyard layers are not standardized here because they are not common enough.

Via filling and via plugging: that will be probably handled by padstack attributes, not layer drawings.

Special, printed heat sink plate: too rare. The finish purpose could be abused.

Conventions modern footprint design

This section describes what extras a footprint designer needs to pay attention to when designing a modern footprint (compared to mid 2010's conventions with pcb-rnd or geda/PCB).

Use the silk layer only for silk graphics and nothing else. Silk graphics is what will be printed on the top (or bottom) of your physical board. Don't draw anything else here than what really needs to be printed on the board:

Draw your keepouts properly. Both the rough mechanical dimensions as a polygon on ko.courtyard and any copper keepouts on the corresponding ko@ layer if the part has anything that requires copper avoided under it.

Check mask and paste layers. Some pads may require paste patterns or round mask cutout.

Avoid using heavy terminals if the task can be solved with padstacks. Padstacks can do arbitrary polygon shaped smd pads or through hole pins by now and the thermal tool does work on them.

Don't assign term ID to vias and copper lines. If your subcircuit needs to add vias and tracks, just draw them as if the subcircuit was a board. There's no need to do any trickery, it will just work. A via grid is typical for small outline DC/DC chips under the center pad. Make the center pad a terminal, but the vias can be just vias.

You can print any attribute, not only the refdes, on any layer. If you need the refdes etched in copper, just move it to a copper layer. If you have some ID that should be printed on silk, etched in copper or put on mask, and that ID should be coming from the schematics, e.g. "port A" or "port B", just invent an attribute and add a DYNTEXT object that references that attribute. No need to manually add text objects per subc on the board and then try to keep them around the subc if it can automate this.

If you have objects that need to be near the subc, but their specific location, don't afraid to use the floater flag . That will let the user of the footprint grab and move the object, while it's still part of the subc - just like it happens with the refdes text normally.

Add attributes to indicate the author, preferably with a contact address, the distribution and the use license. Please consider uploading your footprint to edakrill .

You may want to design your footprint in 1, 2, 3 or even more variants, depending on population density. For manual soldering, the pads should be bigger, smd pads especially longer for easier soldering; for mass production of dense boards, pads should be about as small as the minimum the datasheet permits so more can be squeezed onto the board.

If you have a range of very similar footprints, like an IC with different number of pins, consider writing a parametric footprint script instead of manually drawing each footprint.

Rationale, plans and connections

Exotic conventions not covered

We do not want to end up with a table of layers containing 200 entries because then nobody will read or use them. We do not want to end up with a fixed, static layer stack either: we want to leave room for the users to set up their own, custom, local conventions.

Assembly and fab drawing

At the moment the assembly drawing is generated only on export, and only in the gerber and ps exporters. It is not possible to see this "layer" on the screen within pcb-rnd or to edit it. In the future, the assy layer will behave similar to the silk, paste or mask layers: there will be explicit, editable layers for the assy drawing. The assy drawing code will be changed so that:

A bit more automatic merging will happen with our fab drawing:

Indicate keepout with polygons

Since the programmable DRC is able to check keepouts, using object-object intersection calculations. Assume there is a large part that has a ko layer group G1 that needs to be clear of objects on layer group G2. For example G1 is the "top copper keepout layer" and G2 is the "top copper layer group", which literally means wherever G1 has an object, G2 shouldn't have.

If the large subc's keepout area is a rectangle, drawn using lines, that means the DRC will check if the 4 lines used in the rectangle do not intersect with anything on G2. This will miss a small G2 object in the center of the rectangle if this small object doesn't happen to touch any of the lines.

So instead of using lines on G1, polygons shall be drawn, to make sure they intersect with anything under them.

Keepout purpose strings

DRC scripts can look at the purpose string to figure what to do. If purpose does not start with ko , it is typically not considered a keepout. If it starts with ko , the next character decides how to use it:

You can define any amount of any of these keepout groups. You can draw objects directly on them, you don't need to have subcircuits. For example you can use a referenced keepout layer group of purpose "ko@copper" and draw an arbitrary polygon on it to make sure no copper ever lands on any copper group within a high voltage insulation gap. This may even be relevant to some special case parts, like high voltage transformers or opto couplers.

keepout layer by default

These layers should be present by default but are not yet added to the default layer stackup because without DRC scripts finished and added to the default distribution they are not yet useful.


The example sot23a and sot23b footprints demonstrate recommended layer usage (but dimensions might be off). The difference between the two is assy drawing style. The recommendations are: