4f35df1781
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
6.7 KiB
Dangerous Pi — Architecture & Dev Plan (Updated)
- Overview
Dangerous Pi extends the existing pi-pm3 project with:
Modern web UI (Remix optional, Python + SSE preferred for efficiency)
Single-user session management with web terminal fallback
Automatic application updates via GitHub Releases
Proxmark3 client rebuild on boot
UPS / safe power management
Wi-Fi / AP management (auto / captive portal / dual Wi-Fi detection)
Optional authentication
Backup plugin scaffolding
BLE notifications using built-in Pi Zero 2 W Bluetooth
Target hardware: Raspberry Pi Zero 2 W
- Hardware Architecture Component Purpose Notes Pi Zero 2 W Main controller Runs backend & web UI; includes built-in Bluetooth 4.2 (BLE) UPS HAT Safe shutdown / battery monitoring Expose battery % via I2C or API PNP transistor Programmatically “press” proxmark button 50–100ms pulse to emulate press 2x Slide switches Hardware mode switches One: On/Off → safe shutdown, Two: Wi-Fi → Auto/AP Optional USB Wi-Fi dongle Enables dual Wi-Fi mode Detected dynamically; allows client + AP mode Proxmark3 NFC/LF hardware Interfaced via Python wrapper (client/proxmark3.py)
- Backend Architecture 3.1 Stack
Language: Python 3.11+
Framework: FastAPI (async, SSE support)
Database: SQLite (for config, crash reports, session info)
Job Queue: Async queue for Proxmark commands + rebuild tasks
System services: Systemd units for:
Backend FastAPI server
Rebuild on boot / auto-update
UPS monitoring daemon
3.2 Components
API Layer
REST endpoints for:
Triggering proxmark commands
Changing Wi-Fi mode (auto/AP/client/dual)
Initiating backup
Updating auth config
SSE endpoints for:
Notifications (update available, backup complete, PM3 rebuild required)
Command completion messages
Proxmark Worker
Python async task runner
Uses client/proxmark3.py wrapper
Fire-and-wait commands (no live streaming)
Handles one active session at a time
Arbitrates web terminal vs web UI commands
Update Manager
Polls GitHub Releases API
Downloads latest release archive
Overwrites Dangerous Pi app code + rebuilds proxmark client
Restarts backend
SSE notifies user of:
Available update
Download progress
Rebuild pending restart
Option to restart immediately
Backup Plugin Scaffold
Default: periodic full application directory backup (config + logs + scripts)
Optional: full SD image backup
User notified via SSE & BLE
Plugin can optionally push backups to file storage service
Session Manager
Only one session allowed at a time
Force takeover option in web UI
Graceful disconnect handling (releases lock)
Optional session idle timeout (default: 5min) - releases PM3 lock after inactivity
BLE Manager
Uses built-in Pi Zero 2 W Bluetooth
Detects BLE functionality at runtime
Handles notifications for:
Updates available
Backups completed
PM3 rebuild pending
UPS low battery
Wi-Fi Detection
On boot, backend detects available network interfaces:
Built-in Wi-Fi → client / AP / auto mode
USB Wi-Fi → enables dual Wi-Fi (client + AP) mode
Web UI only exposes viable modes depending on detected hardware
- Frontend Architecture 4.1 Stack
Framework: Remix (preferred) or minimal SPA
Transport:
SSE for server → client notifications
REST for client → server commands
Components:
Dashboard: status, UPS %, Wi-Fi mode, battery, logs, available updates
Scan: antenna placement overlay (SVG)
Clone: step-by-step wizard (MIFARE Classic, LF → T5577)
Terminal: xterm.js-based web terminal
Settings: auth, BLE pairing, backup options, SSL toggle
Wi-Fi Settings: dynamically show only available modes (auto, AP, client, client+AP if second module detected)
4.2 Design Patterns
SSR (server-side rendering) where possible to reduce Pi load
Islands/hydration only for dynamic components (terminal, wizards, notifications)
Minimal external JS libraries to keep bundles small
- Networking / Wi-Fi Mode Description AP (captive portal) Forced by hardware switch; default IP: 10.3.141.1; simple portal page Auto UI chooses mode: client / dual (if second Wi-Fi detected) / BLE / client+BLE / off Client + BLE Only available if BLE dongle is present Authentication Optional; user can enable password in web UI
Optional HTTPS: self-signed certificate generated at first boot if enabled
- UPS / Power Management
UPS daemon monitors battery, triggers safe shutdown
Web UI shows battery %, UPS health, charge status
Hardware On/Off switch triggers systemd shutdown sequence
Optional PNP transistor to safely trigger proxmark button
- Update & Rebuild Flow
On boot:
Backend service starts
Update manager checks GitHub Releases
If new release available, download + overwrite app code
Rebuild proxmark3 client using native compiler
SSE notifies user: “PM client rebuild will occur on restart”
User can choose “restart now” or defer
On update failure:
Rollback to previous working directory (retain backups)
SSE alert to user
- Backup & Recovery
Periodic: full application directory backup by default
Optional: full SD image backup
User notifications: web UI + BLE
Restore:
UI button triggers restoration from last backup
Optional plugin can extend cloud storage
Installer: full custom OS image preconfigured for appliance mode
-
OS / Installer Layout /dangerous-pi/ ├─ /boot/ # Raspberry Pi boot partition │ └─ config.txt ├─ /root/ # OS root │ ├─ /app/ │ │ ├─ backend/ # FastAPI + proxmark worker │ │ ├─ frontend/ # Remix or SPA bundle │ │ ├─ plugins/ # backup, optional future extensions │ │ └─ scripts/ # PM3 rebuild, installer helpers │ ├─ /data/ │ │ ├─ sqlite.db # config, crash logs, session lock │ │ └─ backups/ │ └─ /logs/ # application logs ├─ systemd/ │ ├─ dangerous-pi.service │ └─ dangerous-pi-backup.service └─ installer.sh # Optional installer for existing Pi OS
-
Security
Local network only (LAN)
Optional password authentication
Optional HTTPS (self-signed cert)
Backend and worker run as non-root user
Crash/error reports opt-in
- Development / Performance Notes
FastAPI async endpoints to minimize Pi Zero 2 W CPU load
SSR for static pages, dynamic islands for interactive features
SQLite chosen for small-footprint persistence
xterm.js terminal uses a single PTY; session management prevents concurrent conflicts
Minimal JS and CSS bundles to preserve performance
PM3 commands handled asynchronously, sequentially, single-threaded
BLE automatically enabled if built-in Bluetooth functional
Dual Wi-Fi UI dynamically reflects detected hardware
- Optional Future Plugins
Cloud backup / restore
BLE remote control
Advanced telemetry
External API integration