1da6730735
This commit adds the complete Dangerous Pi web management interface with all MVP features implemented and tested locally. ## New Features ### Backend (Python + FastAPI) - Complete FastAPI backend with async support - 40+ API endpoints (Health, PM3, WiFi, Updates, UPS, BLE, Plugins) - 6 managers: Session, WiFi, Update, UPS, BLE, Plugin - SQLite database with sessions, config, history, crash reports - Server-Sent Events (SSE) for real-time notifications - Mock PM3 worker for development without hardware ### WiFi Manager - Interface detection (USB vs built-in) - Network scanning with signal strength - Mode switching (AP/Client/Dual/Auto/Off) - Network connection with password support - Hidden SSID and saved networks support - Static IP and DHCP configuration - 10 WiFi API endpoints ### Update Manager - GitHub releases API integration - Automatic periodic update checks - Semantic version comparison - Update download with progress tracking - SHA256 checksum verification - Automatic installation with backup and rollback - PM3 client rebuild after updates - 6 Update API endpoints ### UPS Manager - I2C battery monitoring (MAX17040-compatible) - Battery percentage, voltage, current tracking - Power source detection (AC/Battery) - Safe shutdown triggers at configurable thresholds - Event callbacks for battery warnings - SSE and BLE notification integration - 3 UPS API endpoints ### BLE Manager - Bluetooth Low Energy notification support - Auto-detects BLE capability - Multiple notification types (updates, battery, shutdown, etc.) - BLE advertising management - Device connection tracking - 4 BLE API endpoints ### Plugin Framework - Dynamic plugin loading/unloading - Plugin lifecycle management (load, enable, disable, unload) - Hook system for extensibility - JSON-based metadata - Example "Hello World" plugin included - 7 Plugin API endpoints ### Frontend (Remix.js + React) - Cyberpunk-themed responsive UI - Dashboard with system status - PM3 command interface with history - Settings page with WiFi and Update management - Command logs viewer - Theme toggle (Dark/Light/Auto) - Server-side rendering (SSR) - Mobile-first responsive design ### System Integration - Systemd service with security hardening - Automated install/uninstall scripts - Environment configuration template - Hardware access groups (i2c, bluetooth, gpio, dialout) - Pi-gen stage 04 integration for OS image building - Port conflict resolution with ttyd-bash - I2C interface auto-enable for UPS HAT ### Testing - test_backend.py - Backend API tests - test_ups.py - UPS manager tests - test_ble.py - BLE manager tests - test_plugins.py - Plugin manager tests - All tests passing locally ### Documentation - 12 comprehensive documentation files - claude.md - AI development guide - WIFI_MANAGER.md - WiFi management guide - UPDATE_MANAGER.md - Update system guide - PORT_CONFLICT.md - Port conflict resolution guide - MVP_COMPLETE.md - MVP implementation summary - PROJECT_STATUS.md - Project status and roadmap - systemd/README.md - Service management docs - pi-gen integration documentation ## Technical Details - ~5,000+ lines of backend code - 11 Python dependencies (smbus2 added for UPS) - FastAPI with async/await throughout - Type hints and docstrings on all functions - RESTful API design with SSE for notifications - Security hardening (non-root, protected dirs, resource limits) ## Next Steps - Deploy to Raspberry Pi Zero 2 W hardware - Test with real Proxmark3 device - Test UPS HAT integration - Test BLE on Pi hardware - Build custom OS image with pi-gen - Performance optimization for Pi Zero 2 W 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <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 idle timeout (default: 5min)
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