Pi Hotspot Injector

Source-available · Non-commercial · Linux desktop · Pi 1 to Pi 5 · Project page

Licence: free for non-commercial use (personal, hobby, educational, charity). Provided as is, with no warranty and no liability. See LICENSE.md (PolyForm Noncommercial 1.0.0). Use it at your own risk: it can erase the wrong drive if you pick the wrong one.

A point-and-click Linux tool that turns a blank SD card into a Klipper 3D-printer controller that broadcasts its own Wi-Fi hotspot. It's handy in a workshop or garage with no Wi-Fi network around: power the Pi on, join its Wi-Fi from your phone or laptop, and open Mainsail in a browser.

One card works in every Raspberry Pi, from the original Pi 1 and Pi Zero W up to the Pi 4, 400 and 5.

It does everything from your Linux PC, with no need to boot the Pi first or plug in a keyboard and screen:

1. Write the OS image (Raspberry Pi OS Lite, or MainsailOS) to an SD card or USB stick, straight from the downloaded .img.xz / .zip.
2. Build Klipper: install Klipper, Moonraker and Mainsail (plus Crowsnest if you want a webcam, and the experimental KlipPlug plugin manager if you want plugins) onto a clean Raspberry Pi OS Lite card. Everything comes clean and straight from each project, compiled so it runs on every Pi.
3. Set up the hotspot: Wi-Fi name, password, country and IP address.
4. Clone & Backup (optional): save a finished card as an image file, and copy it onto more cards, each one becoming a separate Pi with its own name.
5. Extras: a Pi Zero / Pi 1 compatibility check-and-fix for existing cards, the Card Inquisitor boot diagnostics, and a standalone hostapd + dnsmasq installer.

---

⚠️ Read this first

This tool writes directly to disks. Used on the wrong drive, it permanently erases that drive's data. It has several safety guards (below), but back up anything important before you use it, and double-check which drive you pick.

More documentation

• HOW_IT_WORKS.md: what the tool does to your card and PC, step by step
• RESEARCH_NOTES.md: what was found out along the way, and what is and isn't tested on real hardware
• CHANGELOG.md: what changed in each version
• THIRD_PARTY.md: the software it installs, and their licences
• Project page (GitHub Pages)
• CONTRIBUTING.md and SECURITY.md: reporting problems

Start it

Double-click PiInjector.desktop. The first time, your file manager may ask whether you trust it. That's a one-off security check you have to click through:

Then enter your password when asked. The tool needs administrator rights to write to SD cards, and it asks for them itself.

Or, from a terminal: python3 pi_injector.py

Once it's running, Extras → Add to applications menu puts it in your start menu like any other app.

On startup, a short disclaimer appears that you must accept before you can use the tool. Reading the full licence from that screen is optional.

How to use it

1. Write Image

1. Press Download Raspberry Pi OS Lite (32-bit). It fetches the official image (about 530 MB) from raspberrypi.com, checks it against their published checksum, and fills it in for you. Flaky Wi-Fi is fine: progress is saved as it goes (a checkpoint every 10 MB, plus wherever the connection drops), and it reconnects by itself and carries on from there. Cancel just pauses it; press Download again later, even after a restart, to continue. (Downloading it yourself is fine too: it's the …-raspios-…-armhf-lite.img.xz file. Not "Raspberry Pi Desktop for PC and Mac", which is a PC ISO that can't run on a Pi.) MainsailOS works too; then skip step 2.
2. Plug in your SD card (in a USB reader) or USB stick.
3. Browse... to the image, pick the drive, then Write Image to Drive.
4. Get past the two sanity checks (below). Writing and verifying take a few minutes.

2. Build Klipper

1. Leave the freshly written card plugged in. Don't boot it in a Pi first, because the build needs a never-started card.
2. Choose a login user (default pi), a password (write it down) and a hostname (give each printer its own).
3. Options: Printer firmware build tools (on by default; lets you compile and flash your printer board's firmware on the Pi, as most guides do; uses about 1 GB), Crowsnest (webcam support) and KlipPlug (plugin manager, experimental; see below).
4. Build Klipper Card. It takes about 1–2 hours and needs this PC online, so keep the PC awake. What it does:
   • enlarges the card's system partition (as the Pi would on its first start);
   • sets up the user, SSH and hostname;
   • installs Klipper, Moonraker, Mainsail, nginx and (optionally) Crowsnest, straight from each project;
   • on a 32-bit card, compiles everything for the oldest Pi and checks every compiled file;
   • if you ticked KlipPlug, installs it and runs it once on the card's own Python;
   • finally test-starts Moonraker on an emulated Pi to prove it works.
5. Cancel is safe. A stopped or failed build can simply be started again, and it carries on where it left off.

After the first start, Mainsail will show a Klipper error until you put your printer's configuration into printer.cfg. Klipper's example configs are in ~/klipper/config/.

The KlipPlug option (experimental)

KlipPlug is a separate project by the same author: a plugin manager for Klipper that can run many OctoPrint plugins. Ticking the box adds it to the card as its own service; its page is at http://<hostname>.local:7130 (on the hotspot: http://192.168.50.1:7130), next to Mainsail, which is not changed.

• Where it comes from: if a klipplug folder or a klipplug….zip sits next to pi_injector.py, that copy is used. Otherwise it is downloaded from GitHub. Use the local copy for a build without that download, or for a version that isn't on GitHub. A local copy goes onto the card without its .git folder (a clone's settings can hold a login token), so Mainsail's update panel won't list it; a copy downloaded from GitHub is listed there.
• If it can't be installed (no download, a broken zip), the build carries on and finishes without it, and tells you so at the end. The Klipper card is complete either way.
• What has and hasn't been tried: this option was tested with a stand-in for the card on a PC (the same install step, run in a chroot, then the installed service started against Klipper and Moonraker). It has not been built onto a real SD card or started on a real Pi yet. KlipPlug itself is work in progress and has not been run on a physical printer. A Pi Zero W has little memory (512 MB); how well KlipPlug runs there beside Klipper is not measured.
• Licence: KlipPlug is under AGPL-3.0, not this tool's licence. See THIRD_PARTY.md.

3. Hotspot Setup

1. Leave the card plugged in (or insert a card flashed with another tool).
2. Check the settings. A random Wi-Fi password is generated for you: write it down. Set the country code to where the Pi will be used.
3. Inject Hotspot. If the card lacks hostapd/dnsmasq, the tool offers to install them (this PC needs internet access; it takes 5–15 min).
4. Note the Wi-Fi name, password and web address it shows you.

4. Use it

Put the card in the Pi and power it on. The first boot takes a few minutes because the Pi sets itself up and may restart once. Then join the Wi-Fi network and open http://192.168.50.1 (or whatever address you chose). On a laptop, http://<hostname>.local works too (e.g. http://klipper.local; the hostname is the one set in step 2, not the login user name). Phones often can't open .local names, so use the number there.

If your phone has joined a hotspot with the same name before, choose Forget network on it first. Otherwise it may quietly try the old saved password.

Running more than one of these hotspots at once? Give each card a different Hotspot address number (or press Random), so they don't clash.

Clone & Backup (several Pis)

Setting up several Pis? Build one card with steps 1–3, then:

1. A. Save a card as an image file: pick the finished card; it is only read, never changed. With Shrink ticked (recommended) the file is only as big as what's on the card, a few GB, so it fits any card big enough. That matters because a "32 GB" card from another brand is often slightly smaller than yours. Optionally compress it to .img.gz.
2. B. Write a copy onto another card: pick the image and a blank card (the same two safety checks as tab 1). The copy is grown to fill the card and, with Make it a separate Pi ticked, gets its own name (klipper2, klipper3…), a fresh machine ID and new SSH keys, so two Pis never get mixed up on a network.
3. Run step 3 on the copy to give it its own hotspot name and password.

Keep the image file as a backup: if a card ever dies, write it again in a few minutes. To restore onto the same Pi, untick Make it a separate Pi.

Which Pi?

A card built from Raspberry Pi OS Lite (32-bit) runs in any of these:

The build emulates the Pi Zero's own processor while it compiles, so nothing ends up built for a newer chip than the oldest Pi's. Every newer Pi runs that code natively. That's also why cards built with this tool don't hit the Moonraker Illegal instruction crash that affects some ready-made images on a Pi Zero.

Safety features

• Size window: only removable drives sold as 8–32 GB (±1 GB tolerance) are ever offered as write targets. External hard drives, SSDs, 64 GB+ sticks and tiny drives are refused outright.
• Internal disks are never offered: SATA/NVMe drives, built-in eMMC storage, the live-USB stick you booted from, and anything holding this PC's system, home folders or swap are excluded.
• Two sanity checks before erasing:
  1. A summary of the drive, what's on it now (partition names), and the image that will replace it. No is the default button.
  2. "Are you reeeeley sure you want to overwrite disk …?" You must type the drive's name (e.g. sdb) to enable the button.
• Re-checks the drive right before writing. If it was unplugged or swapped for another one with the same name, nothing is written.
• Refuses to write an image file that's stored on the drive being overwritten.
• The hotspot, diagnostics and package tools only touch a card that really is a Raspberry Pi OS card (checked read-only first).
• Build Klipper checks read-only first that it's a never-started Raspberry Pi OS card, that the user name doesn't clash with a system account, and that the filesystem checks clean with this PC's tools. Only then does it change anything. It never touches a card that's already been used.
• Checks that the image fits, and warns if the file doesn't look like a bootable disk image.
• Exclusive access: the kernel blocks the write if anything still has the drive open.
• Verify after writing (on by default) reads the drive back and compares checksums. This catches faulty and fake-capacity cards.
• Won't let you close the window mid-job without a warning. Cancel works during writes and package installs, and the card is tidied up (temporary mounts and files removed) even if the tool is closed or killed.
• "Why isn't my drive listed?" explains exactly why each drive was excluded.

The size window is set by MIN_WRITE_TARGET_BYTES / MAX_WRITE_TARGET_BYTES near the top of pi_injector.py. Change it at your own risk.

Compatibility notes

• Target images: Raspberry Pi OS / MainsailOS based on Bookworm or newer (NetworkManager-based).
• The hostapd + dnsmasq method is recommended. NetworkManager's own AP mode is unreliable on the Pi Zero W's BCM43430 Wi-Fi chip on trixie-based images.
• For cards not built with this tool, the optional login user from Hotspot Setup is created via userconf.txt on the boot partition. (A built card already has its user.)
• Built from Raspberry Pi OS with desktop instead of Lite? That works too. The card is set to start without the graphical desktop, to leave memory for Klipper (switch it back on with sudo raspi-config → System Options → Boot).
• A built card has cloud-init and Raspberry Pi OS's first-boot "create a user" wizard switched off. The build has already set up the user, SSH and hostname, and those first-boot tools would otherwise rename the user and break Klipper's paths.
• After you run updates on the Pi itself, pip picks packages for that Pi's own processor. If you later move such a card from a Pi 3/4/5 into a Pi Zero / Pi 1, run Extras → Check card first.
• Pi Zero, Zero W and Pi 1 (ARMv6): some recent images (e.g. MainsailOS 3.x, whose build moved to ARMv7) include compiled software these older boards can't run, so Moonraker crash-loops with Illegal instruction. Hotspot Setup warns you when it spots this, and Extras → Fix for Pi Zero / Pi 1 rebuilds the affected Python packages from source for ARMv6, then tests each one on an emulated Pi Zero CPU. The Pi Zero 2 W, 3, 4 and 5 aren't affected.