A board acting up, dark screen, won't connect, ignoring your code, "address in use," anything? Work down this page from the top. Stop as soon as it's working. Nothing here can hurt the board.
Nine times out of ten, this alone fixes it. Do it in order, each step clears a different kind of "stuck."
In Viper, click Stop (or click the terminal and press Ctrl+C). A running program can't be changed.
Click disconnect (top right). This lets go of the board so nothing is holding it.
Pull the USB. This is a full power-off, it clears leftover network sockets and any wedged state. (A "soft reset" does not; only real power-off does.)
Reload viper-ide.org in the browser. Clears any stuck connection on the computer's side.
Use a cable you know carries data (charge-only cables power the board but won't connect). Reseat both ends firmly.
Connect button → USB → pick the Pico. You should land at the >>> prompt.
Press Viper's reset, or run main.py. Fresh start, fresh code.
Working now? You're done. Still off? Don't guess, test one layer at a time. ↓
Instead of poking at the whole station, load these tiny programs in order. Each one proves a single layer works. The first one that fails tells you exactly where the problem is, no more mystery.
No wiring needed. Loads a program that blinks the Pico's own green light. Install & run Blink
Light blinks? The Pico, its firmware, and code-pushing all work. Go to Test 2.
Nothing blinks / can't install? The board isn't running code. Re-flash the firmware (bottom of page).
Needs the OLED wired (4 wires: 3V3, GND, SDA=GP0, SCL=GP1). Draws text to the screen. Install & run Display
Text on the screen? Your wiring and the screen are good. Go to Test 3.
Blank screen / error? It's the wiring, not the code. Check those four wires, especially 3V3 and GND to the breadboard rail (if power's out, the whole bus goes dark). Then reseat SDA (GP0) and SCL (GP1).
No wiring. The Pico makes its own WiFi network and serves a web page. Install & run Webserver
You can join its WiFi and see the page? Everything works, load your real station, it should be fine.
"Address in use" error? A leftover socket from a previous run. Do the clean-slate ritual above (the unplug step clears it). Our current code also recovers from this on its own, reinstall to get the latest.
Removes every file (old programs, leftover settings, junk from past projects) back to bare MicroPython. The reliable "make it behave" reset. Then reinstall.
tools/wipe.py, paste into a new file, Run. Then reinstall.mpremote connect <port> run tools/wipe.py
The nuclear option: wipes everything, firmware included, and lays down a fresh known-good MicroPython. Use when a board is truly unresponsive, or Blink (Test 1) won't run.
RP2350.Already-working board? From the >>> prompt,
import machine; machine.bootloader() jumps to that drive with no button.
.mpy files that override newer code. If an update won't take even after reinstalling,
Wipe it (above) and reinstall, that clears them for good. New installs are all readable source, so
this won't happen going forward.When in doubt, wipe and reinstall. Ten seconds of certainty beats an hour of chasing a ghost.
And remember: a finished board needs only power, it runs main.py from flash every
time it boots and rejoins the network on its own.