When the board does nothing: debugging microcontroller hardware

The single most expensive habit in hobby electronics is debugging from the top down — reading the code first, because the code is the part you wrote and the part you can see. Hardware faults are far more common in a first year, far quicker to check, and they produce symptoms that look exactly like software bugs. A sensor returning nonsense reads as a parsing error. A board that restarts mid-loop reads as a crash. Both are usually wiring.

So the order below is deliberately bottom-up: power, then ground, then connection, then signal, then code. Each step is quick, each one either eliminates a whole class of fault or finds it, and none of them requires equipment beyond a multimeter. Working through it takes about ten minutes and it is faster than reading your own code once.

The other reason for a fixed order is that hardware faults compound. A loose ground makes a sensor read badly *and* makes the serial output unreliable *and* makes the board brown out under load, which presents as three separate mysteries. Checking ground early collapses all three into one fix.

1. 1

   Step 1: Is there power, at the pin, under load?

   Measure the supply voltage at the board itself, not at the power supply, and measure it while the project is doing the thing that fails. A supply that reads 5 V idle and 4.1 V when a motor starts is the fault, and no amount of code will fix it. USB ports and cheap adaptors both sag badly.

   You will know it worked when: A voltage you have measured rather than assumed.

2. 2

   Step 2: Is everything on the same ground?

   Every device in the project must share a ground connection with the microcontroller — a separately powered sensor, motor driver or LED strip that does not have its ground tied to the board’s ground will behave randomly or not at all. This is the single commonest fault in hobby projects and it is invisible in a photograph of the circuit.

   You will know it worked when: One continuous ground, confirmed with a continuity test.

3. 3

   Step 3: Is the connection actually a connection?

   Breadboard contacts wear out, jumper wires fail inside the insulation at the crimp, and the centre rails of many breadboards are split in the middle without any marking. Test continuity end to end rather than looking at it. If a circuit works when you press on a wire, that wire is the fault.

   You will know it worked when: Continuity proven on every line that matters.

4. 4

   Step 4: Is the pin the pin you think it is?

   Board pin numbering and chip GPIO numbering are frequently different, silkscreen is often wrong on inexpensive clones, and several pins on most boards are unusable for general input or output because they are tied to boot behaviour or to internal flash. Check the pinout diagram for the exact board variant.

   You will know it worked when: A pin choice verified against a pinout, not against memory.

5. 5

   Step 5: Is the signal what you expect?

   A floating input reads randomly, which is what an unconnected pin with no pull-up or pull-down does. A logic level mismatch — a 5 V sensor on a 3.3 V board — reads as intermittent nonsense at best. Confirm the idle state of every input before blaming the reading.

   You will know it worked when: Inputs that are defined when nothing is happening.

6. 6

   Step 6: Now read the code

   And read it in that state: with the hardware proven, a bug in the code is now genuinely likely to be a bug in the code. Add output at the point where behaviour diverges rather than at the top.

   You will know it worked when: Debugging one layer instead of two at once.

• A multimeter with a continuity beeper — The single highest-value purchase in the hobby, and an inexpensive one is entirely adequate. Continuity testing turns "is that wire connected" from a guess into a beep, and the voltage range turns brownouts from a mystery into a number.
• A second, known-good everything — A spare board, a spare cable, a spare breadboard. Substitution is the fastest diagnostic technique there is, and it is unavailable if there is only one of each thing on the bench.
• A logic analyser, eventually — Not a first purchase, but inexpensive ones are genuinely cheap and they make serial protocols visible. The moment a project has two devices talking to each other, guessing stops working and this is what replaces it.