Add Dangerous Pi MVP implementation - complete backend and system integration
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>
This commit is contained in:
michael
299
dangerous-pi-project-outline.md
Normal file
299
dangerous-pi-project-outline.md
Normal file
@@ -0,0 +1,299 @@
|
||||
Dangerous Pi — Architecture & Dev Plan (Updated)
|
||||
1. 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
|
||||
|
||||
2. 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)
|
||||
3. 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
|
||||
|
||||
4. 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
|
||||
|
||||
5. 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
|
||||
|
||||
6. 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
|
||||
|
||||
7. 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
|
||||
|
||||
8. 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
|
||||
|
||||
9. 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
|
||||
|
||||
10. 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
|
||||
|
||||
11. 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
|
||||
|
||||
12. Optional Future Plugins
|
||||
|
||||
Cloud backup / restore
|
||||
|
||||
BLE remote control
|
||||
|
||||
Advanced telemetry
|
||||
|
||||
External API integration
|
||||
Reference in New Issue
Block a user