Skip to content
jaredbehuninPublic

About

Offline emergency library on a Raspberry Pi: its own Wi-Fi, a QR join, and search across Wikipedia, medical, repair and field manuals. Free DIY build.

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Repository files navigation

Piper

Piper

An offline emergency library, built for Raspberry Pi. The Pi broadcasts its own open Wi-Fi, a QR code joins it, and the phone's captive-portal sheet opens a start page with ranked search across Kiwix archives (Wikipedia, WikiMed, iFixit, Stack Exchange, Army doctrine, Gutenberg and more) plus an offline US map. No internet, app or account is needed once it is built.

Search returns result cards (source, section title, the matching passage, a link to open it on the box). Nothing is generated, so nothing is made up. Every archive is split into sections and searched with a full-text index (field-manual PDFs are converted to searchable text first), and a small on-device reranker (MiniLM) puts the best passages on top.

This repository holds the code and instructions. It does not contain any archive: you download each one from its source (CONTENT-SOURCES.md).

Disclaimer

This is an educational DIY project, provided as is with no warranty (see LICENSE). The reference content it serves is not medical, legal or professional advice and may be out of date or wrong; in an emergency call your local emergency number if you can. Not affiliated with prepperdisk.com, Kiwix, or any content source. You are responsible for the licenses of the content you load and give away (CONTENT-SOURCES.md, THIRD-PARTY-NOTICES.md).

Parts

On the build machine you also need: uv, sqlite3, rsync, jq, coreutils (numfmt, sha256sum), qrencode, and ImageMagick with the DejaVu fonts (for the label).

part notes
Raspberry Pi 5, 8 GB A Pi 4 works for testing, slowly.
Official Pi 5 case with fan, or the official active cooler Searching keeps the CPU busy; a bare board throttles.
1 TB NVMe SSD on an M.2 HAT, or a 1 TB USB 3 SSD The Pi 5 boots from either. The library does not fit on a microSD card (a 32 GB+ microSD is enough for a Pi 4 test with a small library).
Official 27 W USB-C supply The Pi 5 needs 5 V at 5 A for full USB current.
Optional: RTC battery The Pi has no internet time and no clock backup without it.

The onboard Wi-Fi handles a handful of phones; expect a ceiling of about eight.

Build time depends on the library: the core set is about 65 GB of downloads, the full set with Gutenberg about 300 GB.

Try it on a PC first

Needs Docker, uv, curl, and about 3 GB of disk for this minimal run.

cp .env.example .env                      # DATA_DIR=./data
mkdir -p data/index data/maps
./fetch-library.sh data/zim wikipedia_en_medicine        # WikiMed, about 2 GB, checksum-verified
./fetch-reranker.sh data/reranker
cd section-index && ./build-index.sh ../data/zim ../data/index/sections.db && cd ..
docker compose up -d --build

Open http://127.0.0.1:6042/ and search "how do I treat a burn". docker compose down stops it. The Maps tile needs data/maps/us.pmtiles (below). The optional model: put qwen2.5-1.5b-instruct-q4_k_m.gguf (from https://huggingface.co/Qwen/Qwen2.5-1.5B-Instruct-GGUF) in data/models/ and run docker compose --profile phrasing up.

Tests: cd ask-service && uv run pytest (likewise assemble, section-index, battery, image).

Build the box

  1. Build the image (on a native aarch64 Linux host; a Pi works): image/build.sh. It writes ~/piper-image/out/piper-<date>.img.xz and its sha256. Details: image/README.md.
  2. Flash it to the SSD with Raspberry Pi Imager ("Use custom image") or dd (image/README.md). Optional: name the network with image/set-network-name.sh (default piper). Outside the US, write your two-letter Wi-Fi country code to state/wifi-country on the data partition (default US). Raspberry Pi OS keeps the radio off until a country is set.
  3. Download the archives and verify them. ./fetch-library.sh ~/library/zim core extra downloads each file and checks its published .sha256; a truncated archive serves nothing. ./fetch-library.sh --list shows every file and group. Read CONTENT-SOURCES.md first: iFixit is non-commercial, and several sources are deliberately left out.
  4. Assemble the PDF archives (Army doctrine, USDA canning): ./fetch-library.sh ~/library-src army canning, then follow assemble/README.md; write the resulting ZIMs into ~/library/zim/. It needs poppler-utils, and tesseract for scanned pages.
  5. Build the search index: section-index/build-index.sh ~/library/zim ~/library/index/sections.db. Wikipedia takes hours; the build is resumable.
  6. Maps (optional): install the pmtiles CLI (https://github.com/protomaps/go-pmtiles/releases), copy the URL of the latest build from https://maps.protomaps.com/builds, then pmtiles extract <build-url> ~/library/maps/us.pmtiles --bbox=-125,24,-66.5,49.5 (the contiguous US; adjust the box for Alaska and Hawaii). Verify the download with the BLAKE3 hash the builds page lists (b3sum).
  7. Load the library onto the SSD's data partition (mounted, or over SSH once the box is up): image/load-library.sh ~/library /path/to/mounted/prepperdata. It copies with checksums and writes the manifest the services wait for.
  8. Print the label: ./make-labels.sh piper http://10.42.0.1/ (needs qrencode and ImageMagick). One image with a Wi-Fi join QR code, a start-page QR code, and the name and address as text.
  9. First boot: plug the SSD-equipped Pi in. No screen is needed. After 20 to 40 seconds of boot it reboots once by itself (it is switching the root filesystem to read-only), and is ready about a minute after power-on.
  10. Join: scan the left QR code. The phone's sign-in sheet should open the start page. If not, scan the right code or open http://10.42.0.1/ or http://prepper.local.

Check the finished box against image/hardware-checklist.md. To measure search quality, run the question battery against a running service: cd battery && uv run python run.py --url http://127.0.0.1:6042.

Archive file names are pinned. ask-service/app/data/*.json, ask-service/app/search.py and ask-service/static/index.html name them, so a source link or tile only works for the files in fetch-library.sh. A tile or shortcut for an archive you did not load simply 404s.

Keeping content current

Wikipedia refreshes roughly every six months (the no-images build more often), medical archives yearly. To update: download the newer files (https://download.kiwix.org/zim/), verify their checksums, replace the old name with the new one everywhere (grep -rl OLD . | xargs sed -i s/OLD/NEW/), rebuild the index, and run load-library.sh again (then delete the old files from the box). Re-read CONTENT-SOURCES.md for any source whose license changed.

Troubleshooting

  • Archive will not open or serves nothing: the download was truncated. Re-run fetch-library.sh (it resumes) and watch for a checksum failure.
  • Search says "Nothing in the library matched" for everything, or the service will not start: sections.db is in WAL journal mode, which a read-only mount cannot open. Rebuild with section-index/build-index.sh, which leaves it in the right mode.
  • Services do not start on the Pi: /data/library/manifest.json is missing. Run load-library.sh.
  • The Pi throttles or drops out: it needs the fan or active cooler; never run a bare board.
  • SD card corruption after power loss: boot from the SSD. After first boot the root filesystem is read-only, so pulling the plug is safe.
  • Phones drop off: the onboard radio supports about eight clients.
  • Wrong time: there is no internet time and no clock backup. Fit the RTC battery.
  • The phone does not open the start page by itself: use the second QR code or the address.

Layout

directory what it is
ask-service/ the search service and start page (FastAPI), static map page
section-index/ builds the section-level search index (sections.db)
assemble/ turns PDF collections into searchable ZIMs that also carry the original PDFs
image/ the Raspberry Pi image builder, first-boot logic, load script, hardware checklist
battery/ the fixed question set and its scorer
docs/captive-portal.md how phones detect a captive portal

Support Piper

Piper is free. If it helped you build a box for your family, you can buy me a coffee:

Support Piper on Ko-fi

License

MIT for this repository's own code and docs (LICENSE). Third-party software and assets: THIRD-PARTY-NOTICES.md. Archive content: CONTENT-SOURCES.md.

The Piper name and fox logo (docs/piper-logo.png) are not covered by the MIT license: copyright 2026 Jared Behunin, all rights reserved. You may show the logo when linking to or describing this project.

About

Offline emergency library on a Raspberry Pi: its own Wi-Fi, a QR join, and search across Wikipedia, medical, repair and field manuals. Free DIY build.

Topics

Resources

Stars

3 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages