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>
300 lines
6.7 KiB
Markdown
300 lines
6.7 KiB
Markdown
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
|