Each rule reads the parts and nets of your design, decides whether it applies (an STM32 rule does nothing on an ESP32 board), and reports findings with the parts and nets involved. Severity describes how likely the issue is to stop a board from working:
- Error - very likely to break the board or make it unprogrammable if the finding is correct.
- Warning - a real risk that depends on details the netlist cannot show; check it.
- Info - a heuristic or a best practice. The rule explains its assumption; ignore it if it does not apply.
The listed severity is the highest a rule normally uses; individual findings may be lower. Rules identify parts by reference prefix, value, library symbol and pin names, so they work with KiCad's standard libraries and with most vendor libraries. They are open about their limits: a netlist has no placement, trace or firmware information.
Power
Supply rails, decoupling, regulators and input protection.
Decoupling capacitors on IC supply pins
power.decoupling - up to Error
Counts capacitors between each IC supply net and ground and compares them with the number of IC power pins on that net.
Why it matters and how to fix it
- Why it matters
- Every IC draws current in fast pulses. Without a small ceramic capacitor next to each supply pin those pulses come through the trace inductance, the rail droops and the chip browns out, resets or radiates noise.
- How to fix
- Place one 100 nF ceramic (X7R/X5R, 0402/0603) per power pin, as close to the pin as possible, plus one 4.7-10 µF bulk capacitor per rail.
Regulator input and output capacitors
power.regulator-caps - up to Error
Every linear or switching regulator needs a capacitor on its input and on its output; LDOs are often unstable without the output one.
Why it matters and how to fix it
- Why it matters
- An LDO's control loop is compensated by its output capacitor: with none (or the wrong ESR) it can oscillate. Switching regulators draw pulsed input current and need a low-ESR input capacitor right at the VIN pin, and an output capacitor to form the LC filter.
- How to fix
- Follow the regulator datasheet: typically 1-10 µF ceramic at the input and the specified output capacitance (for example 1 µF for many CMOS LDOs, 10-22 µF on 1117-class LDOs and on buck outputs), placed next to the pins.
Source: TI SLVA079: Understanding the Terms and Definitions of LDO Voltage Regulators
Bulk capacitance on power rails
power.bulk-caps - up to Warning
Checks that regulator inputs and rails feeding an MCU have at least one microfarad-class capacitor, not only 100 nF parts.
Why it matters and how to fix it
- Why it matters
- Small 100 nF capacitors handle nanosecond edges but hold very little charge. Wi-Fi transmit bursts, USB hot-plug and motor/LED switching need a bulk reservoir or the rail sags and the MCU resets (the classic ESP32 "brownout detector was triggered").
- How to fix
- Add a 10 µF (or larger) ceramic or low-ESR capacitor where each rail enters the board and at each regulator input/output; Espressif recommends 10 µF on the ESP32 supply, ST at least 4.7 µF (typically 10 µF) per STM32 package.
Source: Espressif: ESP32 Hardware Design Guidelines - Schematic Checklist
Power nets that look alike but are not connected
power.rail-names - up to Warning
Finds rails like "3V3" and "+3.3V", or "GND" and "GNDA", that KiCad treats as separate nets because their names differ.
Why it matters and how to fix it
- Why it matters
- KiCad connects power symbols and labels by exact name. Mixing "+3V3" from one library with "3.3V" from another silently creates two rails: half of the board is left unpowered even though every symbol looks connected.
- How to fix
- Use one power symbol per rail across the whole project. If two grounds or rails are separate on purpose, join them at one point with a net-tie, 0 Ω resistor or ferrite so the intent is explicit.
Source: KiCad Schematic Editor manual: labels and power symbols
Reverse-polarity protection on DC inputs
power.reverse-polarity - up to Info
Looks at barrel jacks, battery connectors and screw-terminal power inputs and checks for a series diode, P-MOSFET or ideal-diode controller before the first load.
Why it matters and how to fix it
- Why it matters
- Barrel plugs with the wrong polarity and JST battery leads wired the other way round are common (different vendors use different conventions). Without protection a reversed input drives current backwards through every regulator and ESD diode on the board.
- How to fix
- Add a series Schottky diode (simple, costs ~0.3-0.5 V) or a P-channel MOSFET "ideal diode" (gate to ground through a resistor, with a Zener gate clamp above ~12 V), or an ideal-diode controller.
Source: TI SLVA139: Reverse Current/Battery Protection Circuits
USB
USB-C configuration channel, data-pair wiring and protection.
USB-C sink: separate 5.1 kΩ pull-down on CC1 and CC2
usbc.cc-resistors - up to Error
A USB-C receptacle used as a power sink / device needs its own 5.1 kΩ (±10%) resistor from CC1 to GND and another from CC2 to GND - never one shared resistor, never left open.
Why it matters and how to fix it
- Why it matters
- A USB-C source only switches VBUS on after it sees Rd on a CC pin. Without Rd the board powers from USB-A-to-C cables (which carry their own pull-up) but stays dead on C-to-C cables and USB-C chargers. Tying CC1 and CC2 together makes the source see Rd on both lines (a "debug accessory") or, with an e-marked cable, an audio accessory - and it may refuse to power the board.
- How to fix
- Place one 5.1 kΩ resistor from CC1 to GND and a second 5.1 kΩ from CC2 to GND, right at the connector. If you need more than 5 V or PD, use a sink controller (it provides Rd itself).
Source: ST AN5225: Introduction to USB Type-C Power Delivery for STM32 MCUs and MPUs
USB-C D+/D- connected on both rows (A6/B6, A7/B7)
usbc.dp-dm-both-rows - up to Error
A USB-C receptacle has two D+ pins (A6, B6) and two D- pins (A7, B7); both of each pair must be joined, or USB data only works in one plug orientation.
Why it matters and how to fix it
- Why it matters
- The plug can be inserted either way round. The cable's single D+/D- pair lands on row A or row B depending on orientation, so a board that only wires A6/A7 enumerates one way and is invisible when flipped.
- How to fix
- Join A6 to B6 (D+) and A7 to B7 (D-) right at the connector, with short equal stubs.
Source: USB-IF: USB Type-C Cable and Connector Specification
USB D+ and D- swapped between connector and chip
usb.dp-dm-swap - up to Error
Follows each connector data line (through series resistors) to the MCU or USB bridge and checks that D+ lands on the chip's D+ pin and D- on D- (ESP32-S3 GPIO20/19, ESP32-C3 GPIO19/18, STM32 PA12/PA11, RP2040 USB_DP/USB_DM, CH340 UD+/UD-).
Why it matters and how to fix it
- Why it matters
- Unlike UART, USB data lines do not cross over. A swapped pair is the single most common reason a new board is "not recognised" - and it cannot be fixed without cutting traces.
- How to fix
- Connect connector D+ to the chip's D+ (DP) pin and D- to D- (DM). Double-check alternate-function pin names in the datasheet.
Source: ST AN4879: Introduction to USB hardware and PCB guidelines using STM32 MCUs
ESD protection on USB data lines
usb.esd - up to Warning
Looks for a TVS/ESD array (USBLC6-2, TPD2E2U06, PRTR5V0U2X, ...) on the D+/D- lines of every USB connector.
Why it matters and how to fix it
- Why it matters
- The USB connector is the part people touch and hot-plug. The MCU's internal ESD structures are only rated for handling during assembly; a discharge through the connector can kill the USB PHY or the whole chip.
- How to fix
- Add a low-capacitance USB ESD array (for example USBLC6-2SC6) between the connector and the MCU, placed as close to the connector as possible, with a short path to ground.
Source: ST AN4879: Introduction to USB hardware and PCB guidelines using STM32 MCUs
USB D+/D- series resistor sanity
usb.series-resistors - up to Info
Checks that series resistors on D+/D- are small and matched, and notes when the MCU vendor recommends them (RP2040: 27 Ω; ESP32-S2/S3/C3/C6: reserve 22-33 Ω; STM32: not needed).
Why it matters and how to fix it
- Why it matters
- Full-speed USB is a 90 Ω differential pair. A few tens of ohms can help edge rates and EMI; hundreds of ohms (or mismatched values) distort the eye and cause enumeration failures.
- How to fix
- Use equal resistors on D+ and D- (27 Ω for RP2040, 22-33 Ω footprints for Espressif chips), placed next to the MCU. Do not use values above ~50 Ω.
Source: ST AN4879: Introduction to USB hardware and PCB guidelines using STM32 MCUs
ESP32
ESP32, ESP32-S2, S3, C3, C6 and ESP8266 boot and pin rules from Espressif's hardware design guidelines.
ESP32 EN (CHIP_PU) needs a pull-up and an RC delay
esp32.en-rc - up to Error
The chip-enable pin must be pulled high with a delay so the chip starts only after the 3.3 V rail is stable: 10 kΩ to 3V3 plus 1 µF to GND.
Why it matters and how to fix it
- Why it matters
- If EN rises together with a slowly ramping 3.3 V supply, the ESP32 can start before the rail is valid and hang or boot-loop. EN has no internal pull-up, so a floating EN leaves the chip off or randomly resetting.
- How to fix
- Add R = 10 kΩ from EN to 3V3 and C = 1 µF from EN to GND (Espressif's recommended RC delay), placed close to the module. Keep the reset button and auto-reset transistor on the same EN net.
Source: Espressif: ESP32 Hardware Design Guidelines - Schematic Checklist
ESP32 boot pin: a way into download mode, and not stuck low
esp32.boot-pin - up to Error
GPIO0 (GPIO9 on ESP32-C3/C6/H2) must be high for normal boot and pulled low only when you want the serial bootloader: a BOOT button, an auto-program circuit or a header.
Why it matters and how to fix it
- Why it matters
- Holding the boot pin low at reset starts the ROM bootloader instead of your firmware; leaving no way to pull it low means a blank or bricked chip cannot be flashed over UART. A large capacitor on the pin can also make the chip randomly enter download mode.
- How to fix
- Keep the internal/external pull-up, add a BOOT push-button from the pin to GND (with the usual EN reset button), or use the two-transistor DTR/RTS auto-program circuit from a USB-UART bridge. Do not put a large capacitor on the pin.
ESP32 strapping pins pulled the wrong way at reset
esp32.strapping - up to Error
ESP32: GPIO12 (flash voltage), GPIO2, GPIO15, GPIO5. ESP32-S2/S3: GPIO45, GPIO46 (and GPIO3 on S3). ESP32-C3: GPIO2, GPIO8. ESP32-C6: GPIO8, GPIO15. ESP8266: GPIO2, GPIO15.
Why it matters and how to fix it
- Why it matters
- Strapping pins are sampled once when the chip leaves reset and set the boot mode, the flash supply voltage or boot logging. A pull resistor, LED or peripheral that forces the wrong level produces a board that will not boot or cannot be flashed - and it looks fine in the schematic.
- How to fix
- Keep strapping pins at their required reset level (use their internal pulls), move pull-ups/pull-downs, LEDs and peripheral inputs to non-strapping GPIOs, or verify the peripheral does not drive the pin during reset.
Source: Espressif: ESP32 Hardware Design Guidelines - Schematic Checklist
ESP32 GPIOs that belong to the internal flash/PSRAM
esp32.flash-pins - up to Error
ESP32 modules wire GPIO6-11 (and GPIO16/17 on WROVER) to their SPI flash/PSRAM; ESP32-S3 modules with octal PSRAM use GPIO35-37. Anything else connected there crashes the chip.
Why it matters and how to fix it
- Why it matters
- These pins run the flash and PSRAM buses inside the module. Using them for LEDs, buttons or peripherals corrupts every instruction fetch: the classic result is an immediate crash or boot loop as soon as the pin toggles.
- How to fix
- Move the signal to a free GPIO and leave these pins unconnected (add no-connect flags).
Source: Espressif: ESP32 Hardware Design Guidelines - Schematic Checklist
ESP32 GPIO34-39 are input-only without pull-ups
esp32.input-only - up to Warning
On the original ESP32, GPIO34-39 can only be inputs and have no internal pull-up or pull-down resistors.
Why it matters and how to fix it
- Why it matters
- Firmware cannot drive an LED, chip-select, I2C clock or UART TX from these pins, and a button on them floats unless there is an external resistor - a mistake that usually only shows up when the board is powered.
- How to fix
- Move outputs, I2C and anything bidirectional to a normal GPIO. For buttons or open-drain signals on GPIO34-39, add an external 10 kΩ pull-up (or pull-down).
Source: Espressif: ESP32 Hardware Design Guidelines - Schematic Checklist
ESP32 can be programmed (UART0 or native USB reachable)
esp32.programming - up to Warning
Checks that UART0 TX/RX reach a USB-UART bridge, header or test points, or that native USB (S2/S3/C3/C6/H2) reaches a USB connector.
Why it matters and how to fix it
- Why it matters
- Without a programming path the first firmware can only be loaded by soldering wires to module pads - a surprisingly common first-revision mistake on custom ESP32 boards.
- How to fix
- Bring U0TXD/U0RXD (plus EN and the boot pin) to a header or test points, add a USB-UART bridge with auto-program transistors, or on S2/S3/C3/C6 route the native USB D+/D- pins to the USB connector.
STM32
Boot, reset, analog supply, core regulator and USB rules from ST's hardware getting-started notes.
STM32 BOOT0 must be pulled down
stm32.boot0 - up to Error
BOOT0 selects between your firmware in flash (low) and the ROM bootloader (high); it must never float and normally goes to GND through about 10 kΩ.
Why it matters and how to fix it
- Why it matters
- A floating BOOT0 makes the MCU pick the boot source at random on every reset; tied high, it always runs the ST bootloader and never your code. A resistor (instead of a hard short) still lets you enter the bootloader with a button or jumper.
- How to fix
- Connect BOOT0 to GND through a 10 kΩ resistor; optionally add a button or jumper to 3V3 to enter the system bootloader.
Source: ST AN2586: Getting started with STM32F10xxx hardware development
STM32 NRST needs a 100 nF capacitor
stm32.nrst - up to Warning
NRST has an internal pull-up; ST recommends only a 100 nF capacitor to ground (it can be reduced to 10 nF). It must never be tied to VDD.
Why it matters and how to fix it
- Why it matters
- Without the capacitor, noise on the reset line causes parasitic resets. NRST is bidirectional - the MCU pulls it low itself on watchdog or brown-out resets - so tying it to VDD fights the internal driver and breaks those resets.
- How to fix
- Place 100 nF from NRST to GND close to the pin; add a reset button to GND if you like. Do not connect NRST directly to 3V3.
Source: ST AN2586: Getting started with STM32F10xxx hardware development
STM32 VDDA must be powered and decoupled
stm32.vdda - up to Error
VDDA must always be connected (even if the ADC is unused) and needs its own 100 nF + 1 µF decoupling.
Why it matters and how to fix it
- Why it matters
- VDDA powers the ADC and, on many STM32 families, analog blocks such as the reset circuitry, RC oscillators and PLL. Unconnected, the part may not start; undecoupled, ADC readings are noisy.
- How to fix
- Connect VDDA to 3V3 (optionally through a ferrite bead) with 100 nF ceramic + 1 µF next to the pin, and VSSA to GND.
Source: ST AN2586: Getting started with STM32F10xxx hardware development
STM32 VCAP pins need their low-ESR capacitors
stm32.vcap - up to Error
STM32F4/F7/H7 (and others with VCAP pins) expose the internal core regulator output: each VCAP pin needs its own low-ESR ceramic capacitor to ground and must never connect to a supply.
Why it matters and how to fix it
- Why it matters
- The 1.2 V core regulator is only stable with the specified capacitor. Missing it, the core supply oscillates and the MCU crashes or does not start; connecting VCAP to 3.3 V over-voltages the core.
- How to fix
- STM32F4: 2.2 µF low-ESR (< 2 Ω) ceramic on each of VCAP_1 and VCAP_2, or one 4.7 µF (< 1 Ω) if the package has only VCAP_1 (AN4488). For F7/H7 use the value from the family's hardware getting-started note.
Source: ST AN4488: Getting started with STM32F4xxxx MCU hardware development
STM32 VBAT connected (to VDD if there is no battery)
stm32.vbat - up to Warning
If no backup battery is used, ST recommends connecting VBAT to VDD with a 100 nF capacitor.
Why it matters and how to fix it
- Why it matters
- VBAT powers the backup domain (RTC, backup registers, LSE). Left floating it is undefined, which can disturb the backup domain and the RTC.
- How to fix
- Connect VBAT to VDD (with 100 nF) when there is no coin cell; with a battery, feed it through a Schottky or the ST-recommended circuit.
Source: ST AN2586: Getting started with STM32F10xxx hardware development
STM32 SWD pins reachable for programming
stm32.swd - up to Warning
SWDIO (PA13) and SWCLK (PA14) should reach a header, Tag-Connect pad or test points, together with NRST and GND.
Why it matters and how to fix it
- Why it matters
- SWD is the only way to program and debug most STM32 boards reliably. Using PA13/PA14 as ordinary GPIO or leaving them unrouted means a bricked or blank board cannot be recovered.
- How to fix
- Bring SWDIO, SWCLK, NRST, 3V3 and GND to a 2x5 1.27 mm Cortex debug header, a Tag-Connect footprint or labelled test points.
Source: ST AN2586: Getting started with STM32F10xxx hardware development
STM32F1 USB needs an external 1.5 kΩ D+ pull-up
stm32.usb-dp-pullup - up to Error
STM32F102/F103 have no internal D+ pull-up: a full-speed device must add 1.5 kΩ from D+ (PA12) to 3.3 V, or the host never sees it.
Why it matters and how to fix it
- Why it matters
- The host detects a full-speed device by the pull-up on D+. Without it nothing enumerates; with the wrong value (the famous 10 kΩ on early "Blue Pill" boards) some hosts detect it and others do not.
- How to fix
- Fit 1.5 kΩ from D+ to 3.3 V (not 5 V). To allow software re-enumeration, switch it with a small PNP/P-MOSFET from a GPIO.
Source: ST AN4879: Introduction to USB hardware and PCB guidelines using STM32 MCUs
Clocks
Quartz crystals and their load capacitors.
Crystal load capacitors
clock.crystal-load-caps - up to Warning
Each side of a quartz crystal needs a load capacitor to ground; when the crystal's CL is in its value/fields, the capacitors are checked against CL = C1*C2/(C1+C2) + Cstray.
Why it matters and how to fix it
- Why it matters
- A Pierce oscillator only starts reliably, and runs at the marked frequency, with the right load capacitance. Missing caps give no start-up or an off-frequency clock (USB, CAN and Wi-Fi then fail); wrong values pull the frequency by tens of ppm.
- How to fix
- Put one capacitor from each crystal pin to ground. Choose C1 = C2 = 2 x (CL - Cstray), with Cstray typically 2-5 pF (for CL = 12 pF, about 15-18 pF each). Keep them next to the crystal.
Source: ST AN2867: Guidelines for oscillator design on STM8AF/AL/S and STM32 MCUs/MPUs
Buses
I2C and UART wiring.
I2C SDA/SCL pull-up resistors
i2c.pullups - up to Warning
Finds I2C lines by net name and pin function and checks for pull-ups to the bus supply, sizing them with the UM10204 limits (Rp min from 3 mA at 0.4 V; Rp max from the rise time with an assumed 50 pF small-board bus).
Why it matters and how to fix it
- Why it matters
- I2C is open-drain: nothing drives the line high except the pull-up. With none the bus never idles high; too weak and edges are too slow for 400 kHz; too strong and devices cannot pull the line below 0.4 V. MCU internal pull-ups (tens of kΩ) are too weak for anything but slow, short buses.
- How to fix
- Fit one pull-up per line to the I2C supply (3.3 V): 2.2-4.7 kΩ is typical for 100-400 kHz. Use the calculator in the I2C guide for your bus capacitance.
UART TX wired to TX (or RX to RX)
uart.crossover - up to Warning
Looks at nets joining UART pins of two chips; the transmitter of one must go to the receiver of the other.
Why it matters and how to fix it
- Why it matters
- UART lines cross over: TX -> RX and RX -> TX. Two outputs tied together fight each other and nothing is received; two inputs tied together float. Pin names on modules are sometimes written from the host's point of view, so check the datasheet before re-spinning.
- How to fix
- Connect each chip's TX(D) to the other chip's RX(D). If a module labels its pins from the host side ("connect to TX"), follow its datasheet.
Source: Analog Dialogue: UART - A Hardware Communication Protocol
MCU
Voltage compatibility of microcontroller pins.
5 V net on an ESP32/STM32/RP2040 pin
mcu.5v-on-3v3-pin - up to Error
Flags 5 V rails (5V, +5V, VBUS...) wired straight to pins of 3.3 V MCUs, and 5 V pull-ups on their I/O (heuristic based on net names).
Why it matters and how to fix it
- Why it matters
- Espressif and RP2040 I/Os are 3.3 V-domain pins (ESP32 supply pins have a 3.6 V absolute maximum). STM32 pins survive 5 V only when they are FT (five-volt tolerant) pins, VDD is present and the pin is not in analog mode; non-FT STM32 pins are limited to 4.0 V absolute maximum.
- How to fix
- Use a resistor divider (for sensing VBUS), a level shifter, or a 3.3 V pull-up. On STM32, only use FT pins for 5 V signals and check the datasheet pin table.
Source: ST STM32F103x8/xB datasheet (pin table, FT 5 V-tolerant I/Os)
Parts
Discrete-part mistakes: LEDs and MOSFET gates.
LED without a current-limiting resistor
led.series-resistor - up to Warning
Every plain LED (not addressable ones like WS2812) needs a series resistor or a constant-current driver somewhere in its path.
Why it matters and how to fix it
- Why it matters
- An LED's forward voltage barely changes with current, so a small voltage difference makes a huge current difference. Straight from a GPIO or rail it either burns out, browns out the rail, or over-stresses the pin driving it.
- How to fix
- Add a series resistor R = (Vsupply - Vf) / I; for a 3.3 V rail, a 2 V LED and 2 mA that is about 680 Ω (1 kΩ is a common, comfortable choice).
Source: LED circuit: series resistor R = (Vs - Vf) / I (overview)
MOSFET gate driven by a GPIO needs a pull resistor
mosfet.gate-pulldown - up to Info
An N-channel MOSFET whose gate is driven by an MCU pin should have a gate-to-source (or ground) pull-down; a P-channel high-side switch needs a gate pull-up to its source.
Why it matters and how to fix it
- Why it matters
- During reset, boot and firmware updates the MCU pin is high-impedance. With no pull resistor the gate floats and can sit half-on: loads twitch, motors or heaters switch on at power-up, and the FET can overheat in its linear region.
- How to fix
- Add 10-100 kΩ from gate to source (N-channel: to GND; P-channel: to the supply at the source). A 22-100 Ω series gate resistor is also good practice.
Source: TI SLUA618: Fundamentals of MOSFET and IGBT Gate Driver Circuits
Nets
Connectivity problems a netlist reveals: label typos and floating pins.
Labeled net with only one connection
nets.single-pin - up to Warning
A net that has a name (label, global label or power symbol) but reaches only one pin is usually a label typo or a missing wire.
Why it matters and how to fix it
- Why it matters
- Labels connect by exact text and scope. "SDA" vs "SDA1", or a local label used where a global/hierarchical one was needed, leaves both ends silently unconnected even though the schematic looks wired.
- How to fix
- Check the spelling and the scope of the label (local labels only connect within one sheet; use global or hierarchical labels between sheets), or add the missing wire. If the pin is meant to be unused, place a no-connect flag instead of a label.
Source: KiCad Schematic Editor manual: labels and power symbols
IC pins left unconnected that must not float
nets.unconnected-pins - up to Error
Flags IC supply/ground pins with no connection and floating digital inputs on non-MCU ICs (pins with a no-connect flag are respected).
Why it matters and how to fix it
- Why it matters
- A missing VDD or GND pin (often an exposed pad or a second supply pin) leaves part of the die unpowered. A floating CMOS input can sit mid-rail, draw extra current, oscillate and make the part behave randomly.
- How to fix
- Connect every supply and ground pin (including exposed pads). Tie unused inputs to GND or VDD (directly or through a resistor) as the datasheet recommends. Mark truly unused pins with a no-connect flag so the intent is recorded.
Source: KiCad Schematic Editor manual: labels and power symbols
Found a rule that misfires on your design? Report a false positive - include the rule id and what the circuit does.