Utility · use it before asking for help
Troubleshoot by layer
A dark LED can be a wiring fault, a wrong pin number, a code bug, a missing library, or a script running on the wrong machine entirely. The layers sort it: find the first one that fails, fix it there.
Find the layer that failed
- A. Are you on the Pi? The prompt says
username@lastname-pi. GPIO code run on the lab PC fails with pin-factory errors, because the lab PC has no pins. SSH problems themselves are Week 3's ladder. - B. Is the environment right?
(.venv)in the prompt, andpython -c "import gpiozero"silent. No prefix →source .venv/bin/activate. Import error inside the venv → it was created without--system-site-packages; delete.venvand recreate (how). - C. Does the code run? A traceback names file and line; read it bottom-up (how). No traceback but instant exit → the script has no loop or
pause()keeping it alive. - D. Does the circuit agree with the code? Only now touch wires, and in the order below.
Symptom table
| Symptom | Layer | Most likely cause | What to do |
|---|---|---|---|
error: externally-managed-environment | B | pip run outside a venv | Activate the environment first; this is the system working as designed (why) |
ModuleNotFoundError: No module named 'gpiozero' | B | venv made without the system window, or not activated, or a typo in the import | (.venv) present? Recreate with --system-site-packages; check spelling |
BadPinFactory / cannot determine pin factory | A | Script running on the lab PC or laptop, not the Pi | Run it in the SSH session; check the prompt's hostname |
SyntaxError pointing at a normal-looking line | C | Missing colon, unclosed quote or bracket, often on the line above | Read the reported line and the one before it |
IndentationError / block runs at the wrong time | C | Inconsistent indent, or a line accidentally outside its block | Re-indent with 4 spaces per level; the grammar rule |
NameError: name 'X' is not defined | C | Misspelling, or use before assignment | The traceback usually suggests the fix ("Did you mean...") |
| Script prints nothing and exits at once | C | No loop, or event code without pause() | Add the while loop or pause() (why) |
...pin already in use / device busy | C | A previous script still holds the pin (another SSH window, a forgotten run) | Ctrl+C the old script; if lost, close that terminal; last resort, reboot |
| LED never lights, code runs clean | D | LED backwards; wrong physical pin; missing ground return | The circuit order below, starting with polarity |
| LED stays dimly or brightly on regardless of code | D | Wired to 3.3 V instead of GPIO17 (pin 1 vs pin 11 miscount) | Recount physical pins from the square-pad corner |
| Button reads pressed constantly, or randomly | D | Wired to 3.3 V instead of GND; legs on the same side of the gap; loose jumper | Button spans the gap; its far side goes to ground; reseat jumpers |
| One press counts as several | D | Contact bounce | bounce_time=0.05 on the Button (why) |
Circuit debugging in order
When code is clean and the LED is dark, change one thing at a time, in this order, script stopped between changes:
- Polarity. Reverse the LED. It is the single most common fault, costs ten seconds, and diodes do not mind being backwards; they just do nothing.
- Pin count. Finger on the square pad, count to 11 and to 6. Off-by-one on the header explains most of the rest.
- Rows. On the breadboard, components connect only if their legs share a five-hole row on the same side of the gap. Legs one row apart connect nothing.
- Substitution. Swap in a second LED (they do die), then a second jumper. Your kit has spares for exactly this.
- Known-good test. In the REPL:
from gpiozero import LED; led = LED(17); led.on(). If a multimeter is at the station, measure the pin: ~3.3 V on, ~0 V off, and the fault's side (Pi versus breadboard) is decided by evidence.
Before you ask for help
Bring evidence, and the teacher can help in one minute instead of ten. For this week that means:
- Which layer (A to D) you got stuck at, and how the earlier layers passed: the SSH prompt,
(.venv),python -c "import gpiozero". - The full traceback, copied, not paraphrased, plus the script (it is in your repository; push it).
- For circuit cases: which steps of the order above you tried, and a photo of the wiring.
- What you changed since it last worked.