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:
| Severity | What it does |
|---|---|
| Error | Fails the board's verdict, turns the ERC check red, and makes the command line exit with status 1 |
| Warning | Shown beside the errors. It blocks nothing. |
The rules
These need only the netlist.
| Rule | Severity | Fires when |
|---|---|---|
dup-refdes | error | A reference designator is used by more than one part |
dup-net | error | A net name is declared more than once |
unknown-ref | error | A net names a part that does not exist |
bad-pin | error | A pin is not a pad on the part's footprint. The message lists the pads it has. |
no-ground | error | No net is declared ground |
multi-ground | warning | There is more than one ground net |
orphan | error | A part is on no net at all |
floating-pin | warning | An IC, module, connector, switch or transistor has unconnected pins |
merged-pads | error | Pads the footprint draws as one piece of copper are on different nets, or some of them are on no net |
no-bulk-cap | warning | A power net has no capacitor of 1 µF or more |
ic-no-rail | warning | An IC or module touches no power net |
ic-no-gnd | error | An 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-gnd | warning | An IC or module touches no ground and has no symbol to say whether it needs one |
no-decoupling | warning | An IC or module has no capacitor of 1 µF or less between its rail and ground |
rail-conflict | error | More than one power_out pin drives the same net |
output-conflict | error | More than one output or tristate pin is on the same net |
undriven-rail | error | A net feeds power_in pins and nothing drives it |
led-no-resistor | error | An 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.
| Rule | Severity | Fires when |
|---|---|---|
led-resistor-too-small | error | The series resistor passes more than 30 mA. The message gives the resistor for 20 mA. |
led-resistor-too-large | warning | Under 1 mA: the LED will be very dim |
led-resistor-power | error or warning | The series resistor dissipates more than its package allows |
resistor-power | error or warning | A resistor between two declared voltages dissipates (V₁−V₂)²/R, more than its package allows |
regulator-power | error or warning | A linear regulator burns (V_in−V_out)×I_out, more than its package can shed |
cap-over-voltage | error | A capacitor sees more than its rated voltage |
cap-voltage-derating | warning | A 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 passedPackage 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.
| Package | Rating |
|---|---|
0402 | 62.5 mW |
0603 | 100 mW |
0805 | 125 mW |
1206 | 250 mW |
SOD-123, SOT-23, SOT-23-3 | 300 mW |
SOP-8, SOIC-8 | 450 mW |
TSSOP-20 | 500 mW |
SOIC-16 | 600 mW |
SOT-223 | 1 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.
| Rule | Severity | Fires when |
|---|---|---|
supply-limit | error | A 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-range | warning | A supply pin is outside its recommended range |
held-off | error | An active-high enable, such as CE, EN or RUN, is tied to ground |
usb-c-cc | error | A USB-C receptacle has CC1 or CC2 open, so a charger never turns on VBUS |
usb-c-cc-shared, usb-c-rd | warning | Both CC pins share one pull-down, or a pull-down is not 5.1k |
i2c-pullup | error | An I2C line between two chips has no pull-up to a rail |
crystal-load | warning | A crystal terminal has no load capacitor to ground |
datasheet-part | warning | A bypass, bulk or program part the datasheet asks for is missing or too small |
regulator-output | warning | A fixed regulator drives a rail declared at another voltage |
load-bulk | error | A motor supply has under 10 µF |
load-bulk | warning | Bulk 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-current | error | An LED cannot conduct from its rail |
led-current | warning | An LED runs under 0.5 mA, or its low corner falls under 0.5 mA and under half its nominal current |
crystal-drive | warning | A crystal's series resistor is on the oscillator's input pin instead of its output |
enable-delay | warning | An Espressif part's EN pin has no capacitor to ground |
audio-corner | warning | A coupling capacitor cuts a headphone or speaker output above 20 Hz |
debug-reset | warning | An SWD header lacks the chip's reset, so a probe cannot connect under reset |
diode-direction | error | A 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-pins | warning | A diode's ends are given as numbers. Name them A and K. |
design-check | warning | One 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).
| Setting | Default | What it does |
|---|---|---|
SOLDERMASK_DESIGN_CHECK | on | 0 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.31mmThree functions in electrical.py do it:
rating_a()reads a part's continuous current rating, and says where the number came from.carriers()maps each rating onto the nets that reach a conducting terminal of the part.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.
| Attribute | Parts | Counts as |
|---|---|---|
Output Current | Regulators | A driver: a claim about the net |
Continuous Drain Current (Id) | MOSFETs | A driver |
Hold Current | Resettable fuses | A driver |
Send Current | Radio modules | A driver |
Forward Current | LEDs and indicator diodes | A driver |
Rated Current | Pin headers, wire-to-board connectors | A contact: a claim about the pin |
Power Current Rating | USB connectors | A 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
- A MOSFET's gate is not sized for the drain current. The gate carries charge to a resistor, not the load.
- A contact rating speaks only on a net the design typed
powerorground. On signal nets it produced 13 false findings for every true one. - Ground is left out. It carries every return, and the answer there is a pour, not a wider track.
Where findings appear
| Where | What |
|---|---|
| Workbench | The Electrical group in the board's findings, and the ERC check in the readout |
board.json | Under erc |
| Command line | The line ERC n errors, m warnings, with each finding under it |
MCP check_design | The 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.
Simulation
The simulation switches the board's rails on in ngspice and reads what every net settles to. It runs after the parts are resolved and before anything is placed.
Placement and routing
This page explains how the placer arranges parts, how the router joins them with copper, and how ground is poured over both layers.