Howdy Hackers!
I'm assuming you are here because your Raspberry Pi is acting up. Going to do a small intro here before jumping to the recipe for this cookbook but going to keep it short so you can get back to hacking :)

My name is Maria, I work for Major League Hacking, and we bring hardware to many of the events we support including Raspberry Pis! I get lots of questions asking about debugging, and our documentation has 3 different resources we point to for Raspberry Pis. We wanted to consolidate here, but as a full disclaimer, we used AI to help us with the merge. If you see something wonky, just comment so that I and others can see what is off.

Now to the meat and potatos you are here for.

Midnight Rescue: The Ultimate Raspberry Pi Hackathon Revival Guide 🚀

Welcome, midnight builder! It’s late, your code is almost there, but your Raspberry Pi is throwing a full-blown tantrum. Don't panic! Hackathon hardware gets heavily used, and SD cards often carry ghost settings or corruption from previous events. You didn't break anything—this is just a right of passage.

We’ve provided a Troubleshooting Kit in the Hardware Lab specifically to handle this exact moment. Grab your kit, take a breath, and let’s get your hardware back on track step by step! Please note that this kit must stay at the Hardware Lab table so that others can use it during the event as needed. Feel free to pull up a chair as you debug!

🧰 Meet Your Troubleshooting Toolkit

Before diving in, make sure you’ve grabbed the Hardware Lab’s Troubleshooting Kit. Inside your toolkit, you’ll find:

We’ll use these tools in two main phases: Direct Hardware Diagnostics (seeing what’s wrong) and SD Card Re-Flashing (resetting to a squeaky-clean state).

Phase 1: Direct Visual Diagnostics (Using the Kit)

Instead of guessing why you can’t SSH into your Pi, let's look directly at what it's doing on boot!

1. Plug in the HDMI Cable: Connect the Micro-HDMI end to your Raspberry Pi 4 (use HDMI 0, the port closest to the USB-C power port) and the standard HDMI end to the 7-inch screen.
2. Power the Screen & Keyboard: Turn on the 7-inch screen and plug in the mini keyboard's USB dongle into one of the Pi’s USB slots.
3. Power Up the Pi: Plug in the USB-C power cord. Watch the screen!

What are you seeing on screen?

• Rainbow Screen / Red LED only: The Pi can’t read the SD card at all. Move straight to Phase 2 below!
• Kernel Panic / Endless Errors scrolling past: The OS on the SD card is corrupted from a previous team. Head to Phase 2 to re-flash it!
• Asks for Login: The OS is alive! Try default credentials (pi / raspberry). If that fails, someone changed the password—time for a quick re-flash in Phase 2.

Phase 2: Nuclear Option—Wiping & Re-Flashing the MicroSD Card

If the SD card is corrupted or locked, re-flashing gives you a 100% clean OS in just a few minutes. Grab a spare MicroSD card from the kit or use your current one.

Step 1: Format & Wipe the Card

Insert the MicroSD card into the USB Reader/Writer and plug it into your laptop.

• Windows: Download and open SD Formatter or Raspberry Pi Imager. Select your SD card drive, select Quick Format, and click Format.
• Mac / Linux: You can use Raspberry Pi Imager or Disk Utility to format the card to FAT32.

Step 2: Flash the Operating System

We recommend using Raspberry Pi Imager (or Win32 Disk Imager / BalenaEtcher):

1. Download the latest Raspbian / Raspberry Pi OS Lite (or full desktop version) zip/img.
2. Open your imaging software and select the downloaded .img or .zip file.
3. Select your USB SD Card Reader as the target device.
4. Click Write / Flash! (This takes about 5 to 10 minutes—great time to grab a snack!).

Important Note: Windows might pop up messages after flashing saying "You need to format the disk in drive X: before you can use it." Ignore and close these pop-ups! Windows just doesn't natively read Linux partitions.

Step 3: Enable Headless SSH Access

Want to control your Pi from your laptop terminal without keeping the 7-inch screen attached forever?

1. Keep the SD card plugged into your laptop. Open your file explorer.
2. Look for the drive partition named boot.
3. Inside the boot directory, create a brand-new empty file and name it simply ssh (make sure there is no file extension like .txt or .docx!). # On Mac/Linux terminal, you can just run: touch /Volumes/boot/ssh
4. Eject the SD card safely and insert it into your Pi.

Phase 3: Connecting to Your Pi via Ethernet or SSH

Now that your Pi has a fresh OS and SSH enabled, let’s get you connected!

Option A: Direct Screen & Mini Keyboard (Fastest!)

Just leave the 7-inch screen and mini keyboard plugged into the Pi. Boot it up, log in with default credentials (username: pi, password: raspberry), and start coding!

Option B: Ethernet / Network SSH Connection

1. Connect an Ethernet cable from the Pi into your computer (use a USB Ethernet adapter if needed).
2. Power up the Pi. Give it about 60 seconds to complete its initial boot routines.
3. Open your laptop's terminal (or PuTTY on Windows) and run: ssh pi@raspberrypi.local
4. When prompted, enter the default password: raspberry
5. Test your connection by running a quick ping test: ping -c 4 google.com

🎉 You're Back in Business!

If you see ping responses coming back, congratulations—you have successfully brought your Raspberry Pi back from the dead at 12:30 AM! You are now ready to build your awesome hackathon project.

Still stuck or getting unexpected error messages? Don't hesitate to flag down an MLH Coach! We are here to help you. Happy hacking!