soldermaskdocs

Electrical rule check

The electrical rule check reads the netlist before anything is placed. It reports wiring mistakes, such as a wrong pin or an LED with no resistor, and what the parts' datasheets ask for. It fixes none of them.

The check is erc.check(netlist). It runs the design check too, so a design-check finding is an ERC finding. Each finding has a rule name and a severity:

SeverityWhat it does
ErrorFails the board's verdict, turns the ERC check red, and makes the command line exit with status 1
WarningShown beside the errors. It blocks nothing.

The rules

These need only the netlist.

RuleSeverityFires when
dup-refdeserrorA reference designator is used by more than one part
dup-neterrorA net name is declared more than once
unknown-referrorA net names a part that does not exist
bad-pinerrorA pin is not a pad on the part's footprint. The message lists the pads it has.
no-grounderrorNo net is declared ground
multi-groundwarningThere is more than one ground net
orphanerrorA part is on no net at all
floating-pinwarningAn IC, module, connector, switch or transistor has unconnected pins
merged-padserrorPads the footprint draws as one piece of copper are on different nets, or some of them are on no net
no-bulk-capwarningA power net has no capacitor of 1 µF or more
ic-no-railwarningAn IC or module touches no power net
ic-no-gnderrorAn IC or module has a ground pin on no ground net and no negative rail. Ground pins are GND, VSS, VEE, V-, VS- and VCC-, with a prefix or suffix.
ic-no-gndwarningAn IC or module touches no ground and has no symbol to say whether it needs one
no-decouplingwarningAn IC or module has no capacitor of 1 µF or less between its rail and ground
rail-conflicterrorMore than one power_out pin drives the same net
output-conflicterrorMore than one output or tristate pin is on the same net
undriven-railerrorA net feeds power_in pins and nothing drives it
led-no-resistorerrorAn LED shares no net with any resistor, so a rail drives it directly

Rules that read pin types

rail-conflict, output-conflict and undriven-rail read each pin's type from the part's symbol. A part with no symbol is left out of them.

ic-no-gnd asks the part's own pinout. A part whose symbol names no ground pin, such as a relay, has nothing to tie and gets no finding. A split-supply amplifier whose V- sits on a negative rail is tied where it belongs.

undriven-rail looks past passive parts. A rail counts as driven when a connector, a power_out pin or an untyped IC pin reaches it. The path may run through a resistor, inductor, diode, switch or transistor. So a battery rail fed through a slide switch and a load-switch FET is driven by the battery connector.

The checks that needed a voltage

These rules apply Ohm's law, so they need the voltage a net declares (voltage_v). They are computed in electrical.py.

RuleSeverityFires when
led-resistor-too-smallerrorThe series resistor passes more than 30 mA. The message gives the resistor for 20 mA.
led-resistor-too-largewarningUnder 1 mA: the LED will be very dim
led-resistor-powererror or warningThe series resistor dissipates more than its package allows
resistor-powererror or warningA resistor between two declared voltages dissipates (V₁−V₂)²/R, more than its package allows
regulator-powererror or warningA linear regulator burns (V_in−V_out)×I_out, more than its package can shed
cap-over-voltageerrorA capacitor sees more than its rated voltage
cap-voltage-deratingwarningA capacitor sees over 70% of its rating, where a class-2 ceramic has lost most of its capacitance

LED current is worked out at the lowest forward voltage for the LED's colour, which is the worst case for too much current.

A net with no voltage gets no check, and the board says so. Most designs leave some voltages out. The nets that declared nothing are named in the board's notes:

2 power net(s) declare no voltage (+12V, +3V3) -- so Ohm's law is unavailable
on them: LED series resistors, resistor and regulator dissipation and
capacitor ratings go unchecked rather than checked and passed

Package ratings

A part over half its package's rating is a warning. Over the rating is an error. The figures for three-terminal packages are what they shed on ordinary two-layer copper with no heatsinking.

PackageRating
040262.5 mW
0603100 mW
0805125 mW
1206250 mW
SOD-123, SOT-23, SOT-23-3300 mW
SOP-8, SOIC-8450 mW
TSSOP-20500 mW
SOIC-16600 mW
SOT-2231 W

A package not in this table is left alone rather than guessed. So is a regulator that is not clearly linear or clearly switching: a switcher does not burn the difference, so flagging one would be wrong.

The design check

The design check asks what the parts themselves require, and what a bus between two of them requires. It is designcheck.py, and erc.check() runs it. Its errors fail the verdict like any other ERC error. Its warnings are for the designer to fix, or to answer in the design's assumptions.

RuleSeverityFires when
supply-limiterrorA pin sits on a rail above its datasheet's absolute maximum to ground. A limit measured from another pin, such as BOOT to SW, is not applied.
supply-rangewarningA supply pin is outside its recommended range
held-offerrorAn active-high enable, such as CE, EN or RUN, is tied to ground
usb-c-ccerrorA USB-C receptacle has CC1 or CC2 open, so a charger never turns on VBUS
usb-c-cc-shared, usb-c-rdwarningBoth CC pins share one pull-down, or a pull-down is not 5.1k
i2c-pulluperrorAn I2C line between two chips has no pull-up to a rail
crystal-loadwarningA crystal terminal has no load capacitor to ground
datasheet-partwarningA bypass, bulk or program part the datasheet asks for is missing or too small
regulator-outputwarningA fixed regulator drives a rail declared at another voltage
load-bulkerrorA motor supply has under 10 µF
load-bulkwarningBulk is under the driver datasheet's figure, a strip's supply is under 470 µF, or a servo rail is under 100 µF a servo
led-currenterrorAn LED cannot conduct from its rail
led-currentwarningAn LED runs under 0.5 mA, or its low corner falls under 0.5 mA and under half its nominal current
crystal-drivewarningA crystal's series resistor is on the oscillator's input pin instead of its output
enable-delaywarningAn Espressif part's EN pin has no capacitor to ground
audio-cornerwarningA coupling capacitor cuts a headphone or speaker output above 20 Hz
debug-resetwarningAn SWD header lacks the chip's reset, so a probe cannot connect under reset
diode-directionerrorA diode or LED is wired backwards: a flyback or bootstrap diode reversed, a clamp across the supply, or an LED's anode on ground
diode-pinswarningA diode's ends are given as numbers. Name them A and K.
design-checkwarningOne of the rules above could not run. The message says which, and why.

Each message names its source, such as the part's datasheet or a vendor's design guide.

Datasheet records

The datasheet rules read a part's datasheet record, and only its verified items. The records ship in soldermask/assets/components/. A record the datasheet reader wrote is read under the same rule. A part with neither is checked by the bus and enable rules alone. soldermask parts show <LCSC> prints a part's record (Command line).

SettingDefaultWhat it does
SOLDERMASK_DESIGN_CHECKon0 turns every design-check rule off

What the parts on a net can push through it

A net that declares no current is routed at the board's signal track, 0.127 mm unless a person sets a floor. The check below reads the parts on the net instead. If they can drive more current than that track carries, the board carries a note:

net LOAD_DRAIN declares no current, so it is routed at 0.127mm, which carries
0.54A -- but Q1 on it is rated 5.7A (the drain current in its own
description …), 11x more. IPC-2221 asks for 3.31mm

Three functions in electrical.py do it:

  1. rating_a() reads a part's continuous current rating, and says where the number came from.
  2. carriers() maps each rating onto the nets that reach a conducting terminal of the part.
  3. carrier_gaps() reports any net routed narrower than its parts can drive.

A net that states its own current is sized from that, and is not checked here. These are notes, not ERC findings.

Copper that runs too hot for the current its net declares does fail the verdict. See Copper too narrow for its current.

Where the rating comes from

The catalogue's typed attributes are read where they exist. The list is split by what the number is evidence of.

AttributePartsCounts as
Output CurrentRegulatorsA driver: a claim about the net
Continuous Drain Current (Id)MOSFETsA driver
Hold CurrentResettable fusesA driver
Send CurrentRadio modulesA driver
Forward CurrentLEDs and indicator diodesA driver
Rated CurrentPin headers, wire-to-board connectorsA contact: a claim about the pin
Power Current RatingUSB connectorsA contact

MOSFETs are the exception. None of 400 sampled carry a value for Continuous Drain Current (Id), though the description states it. So for MOSFETs, and only MOSFETs, the rating is the largest current in the description.

Surge, leakage, quiescent and trip currents (SURGE_ATTRS) are excluded on purpose. They are real currents, but none is a rating for continuous conduction.

Three things it refuses to say

  1. A MOSFET's gate is not sized for the drain current. The gate carries charge to a resistor, not the load.
  2. A contact rating speaks only on a net the design typed power or ground. On signal nets it produced 13 false findings for every true one.
  3. Ground is left out. It carries every return, and the answer there is a pour, not a wider track.

Where findings appear

WhereWhat
WorkbenchThe Electrical group in the board's findings, and the ERC check in the readout
board.jsonUnder erc
Command lineThe line ERC n errors, m warnings, with each finding under it
MCP check_designThe same findings, under erc, before anything is built. See MCP server.

What ERC is not

ERC reads the netlist and asks whether the design is sane. It does not read the copper. Whether the board can be built is a DRC question, which KiCad answers when it is installed. See KiCad and 3D models.

On this page