pi-pm3/BUILD_SYSTEM.md

Dangerous Pi Build System

Overview

The build system is now split into two separate stages for faster iteration:

stage0, stage1, stage2 → stagePM3 → stageDangerousPi
                        (cached)   (cached)

Build Commands

./build-image.sh full

Build all stages from scratch (~1 hour)

• Use for: First build or major system changes
• Builds: stage0 → stage1 → stage2 → stagePM3 → stageDangerousPi
• Creates cached .qcow2 images for future builds

./build-image.sh from-pm3

Rebuild PM3 + customizations (~50 min)

• Use for: Updating Proxmark3 firmware/client version
• Skips: stage0, stage1, stage2 (uses cached images)
• Builds: stagePM3 → stageDangerousPi
• Updates PM3 cache for future from-dtpi builds

./build-image.sh from-dtpi ⭐ Daily Development

Rebuild only customizations (~5 min)

• Use for: Daily development, iterating on your app
• Skips: stage0, stage1, stage2, stagePM3 (all cached)
• Builds: stageDangerousPi only
• Fastest iteration cycle for app development
• Requires: Previous full or from-pm3 build

./build-image.sh test

Validate all scripts without building

• Syntax checks all stage scripts
• Verifies required files exist
• Quick sanity check before building

Stage Structure

stagePM3 (Proxmark3 Base)

• 01-proxmark3/ - PM3 firmware + client + Python bindings
• EXPORT_IMAGE - Creates cached image at this point
• Build time: ~45 minutes
• Change frequency: Rarely (only when updating PM3)

stageDangerousPi (Customizations)

• 01-Wireless-AP/ - WiFi access point + captive portal
• 02-ttyd/ - Web terminal (bash + PM3)
• 03-dangerous-pi/ - Your FastAPI app + frontend
• EXPORT_IMAGE - Creates final deployable image
• Build time: ~5 minutes
• Change frequency: Daily (your code)

Workflow Examples

First-time setup:

./build-image.sh full
# Wait ~1 hour
# Image: deploy/Proxmark3-dangerous-pi.img

Daily development (app changes):

# Edit your code in app/
./build-image.sh from-dtpi
# Wait ~5 minutes
# Image: deploy/Proxmark3-dangerous-pi.img

Update PM3 version:

# Edit pi-gen/stagePM3/01-proxmark3/00-run-chroot.sh
./build-image.sh from-pm3
# Wait ~50 minutes
# Updates PM3 cache + final image

Clean rebuild:

docker rm pigen_work
./build-image.sh full

Cache Management

QCOW2 caching is enabled (USE_QCOW2=1 in config)

Cached images are stored in:

• work/*/stage2/*.qcow2 - Base OS (30 min to rebuild)
• work/*/stagePM3/*.qcow2 - PM3 build (45 min to rebuild)

To clear cache and force full rebuild:

rm -rf /home/work/pi-gen-builder/work

Build Fixes Applied

1. Directory creation - Fixed missing /etc/network/interfaces.d/ errors
2. No sudo requirement - Patched pi-gen to skip sudo prompts
3. Source file copying - Automated app/systemd/scripts integration
4. Stage caching - Enabled QCOW2 for fast incremental builds

Time Savings

Build Type	Time	Use Case
Full	~60 min	First build
from-pm3	~50 min	Update PM3
from-dtpi	~5 min	Daily dev ⭐

Daily workflow time savings: 55 minutes per build!