MikeFaith/pi-pm3
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit - Phase 3/4

Browse Source 
🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
michael
2026-01-06 13:45:29 -08:00
parent 1da6730735
commit 4f35df1781
323 changed files with 98287 additions and 1195 deletions
Download Patch File Download Diff File Expand all files Collapse all files

295
PROJECT_STATUS.md
View File

@@ -1,10 +1,14 @@
# Dangerous Pi - Project Status
**Last Updated**: 2025-11-26
**Last Updated**: 2026-01-04
## 🚧 MVP Implementation Complete - Hardware Testing Phase
## ✅ Phase 3 Complete - Hardware Testing Passed
All MVP features are implemented and tested locally. Next: deploy and test on actual Raspberry Pi Zero 2 W + Proxmark3 hardware.
All MVP features tested on actual hardware:
- Raspberry Pi Zero 2 W with Proxmark3 Easy
- PiSugar 2 UPS (auto-detected via I2C)
- Bluetooth LE advertising working
- WiFi AP mode active (192.168.4.1)
---
@@ -23,14 +27,16 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
- ✅ System info (`/api/system/info`)
- ✅ PM3 status (`/api/pm3/status`)
- ✅ PM3 command execution (`/api/pm3/command`)
- ✅ PM3 device management (`/api/pm3/devices/*`)
- ✅ Session management (`/api/system/session/*`)
- ✅ SSE events (`/sse/events`)
- ✅ WebSocket events (`/ws/events`)
**Core Components:**
- ✅ **PM3 Worker** - Uses built-in `pm3` Python module
- ✅ **Mock PM3 Worker** - For development without hardware
- ✅ **Session Manager** - Single-user with takeover support
- ✅ **Event Broadcaster** - SSE for real-time notifications
- ✅ **PM3 Worker** - Uses built-in `pm3` Python module (SWIG bindings)
- ✅ **PM3 Device Manager** - Multi-device support with unique device IDs
- ✅ **Session Manager** - Per-device sessions with takeover support
- ✅ **WebSocket Manager** - Real-time event broadcasting to all clients
- ✅ **Service Container** - Dependency injection for services
**WiFi Manager (Complete):**
- ✅ Interface detection (USB vs built-in)
@@ -61,10 +67,15 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
- ✅ Safe shutdown triggers at configurable thresholds
- ✅ Battery status (Charging, Discharging, Full, Critical)
- ✅ Event callbacks for battery warnings
- ✅ SSE and BLE notification integration
- ✅ WebSocket and BLE notification integration
- ✅ 3 UPS API endpoints
- ✅ **Power Management Policy** (NEW - 2025-11-26)
- Assumes AC power when UPS not detected (no restrictions)
- Battery-level restrictions when on UPS battery
- Power restrictions API endpoint for firmware flashing
- Safe defaults: all operations allowed without UPS
**BLE Manager (Complete):**
**BLE Manager (Complete - MVP):**
- ✅ Bluetooth Low Energy notification support
- ✅ Auto-detects BLE capability
- ✅ Configurable device name
@@ -73,6 +84,11 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
- ✅ Device connection tracking
- ✅ Notification queueing
- ✅ 4 BLE API endpoints
- 🚧 **Planned Enhancement**: Full web client feature parity via BLE
- Command execution via BLE
- Status queries via BLE
- Guided workflow triggers via BLE
- For React Native mobile app integration
**Plugin Framework (Complete):**
- ✅ Dynamic plugin loading/unloading
@@ -84,6 +100,19 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
- ✅ Example "Hello World" plugin
- ✅ 7 Plugin API endpoints
**Proxmark3 Firmware Enhancements (Complete - 2025-12-02):**
- ✅ Two-channel hardware PWM LED brightness control
- LED A (Green, PA0/PWM0): 0-100% brightness
- LED B (Blue, PA2/PWM2): 0-100% brightness
- LED C/D: Basic on/off/toggle
- ✅ New `hw led` command with full LED control
- ✅ PWM channel reallocation (timing moved PWM0→PWM1)
- ✅ Backward compatible protocol (CMD_LED_CONTROL 0x011A)
- ✅ Multi-device identification via brightness levels
- ✅ Zero performance impact on RF operations
- ✅ Tested and flashed to Proxmark3 Easy
- 📄 Documentation: [LED_PWM_IMPLEMENTATION.md](LED_PWM_IMPLEMENTATION.md)
**System Integration (Complete):**
- ✅ Systemd service units with security hardening
- ✅ Automated install/uninstall scripts
@@ -113,9 +142,9 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
**Pages:**
- ✅ **Dashboard** (`/`)
- System status (CPU, memory, disk)
- PM3 connection status
- PM3 connection status with multi-device support
- Quick actions
- Real-time SSE notifications
- Real-time WebSocket notifications
- ✅ **Commands** (`/commands`)
- Command input with history (↑/↓ navigation)
@@ -142,23 +171,46 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
- ✅ Toast notifications
- ✅ Loading states
- ✅ Form validation
- ✅ **DeviceSelector** - Multi-PM3 device selection with LED identification
- ✅ **PowerWidget** - Real-time UPS/battery status in header
- ✅ **ConnectDialog** - PM3 connection management
- ✅ **QRScanner** - HTML5-based QR code scanning
**Hooks:**
- ✅ **useWebSocket** - Singleton WebSocket manager with event subscriptions
**Performance:**
- ✅ Server-side rendering (SSR)
- ✅ Code splitting by route
- ✅ Progressive enhancement
- ✅ Bundle size < 150KB (target met)
- ✅ Bundle size < 150KB (target - with room for Victory charts)
**Visualization (Planned):**
- 📋 **Victory Charts** - Cross-platform charting library
- Mobile-first design with touch gestures
- Shared components across Web/Mobile/Desktop
- Real-time data visualization
- ~50KB bundle impact (within budget via code splitting)
- 📋 **Guided Workflows** - Multi-step wizards for common tasks
- ID Transponder
- Clone MIFARE Classic 1K
- Clone to T5577
- HF/LF/HW Tune with live charts
- Sniffing utility
### Documentation
- ✅ **claude.md** - AI development guide (updated)
- ✅ **claude.md** - AI development guide (updated with Victory)
- ✅ **README_DEV.md** - Developer quick start
- ✅ **UI_GUIDELINES.md** - Design system and UX principles
- ✅ **UI_GUIDELINES.md** - Design system and UX principles (mobile-first)
- ✅ **GETTING_STARTED.md** - Complete setup guide
- ✅ **WIFI_MANAGER.md** - WiFi management guide
- ✅ **UPDATE_MANAGER.md** - Update system guide
- ✅ **PORT_CONFLICT.md** - Port conflict resolution guide
- ✅ **MVP_COMPLETE.md** - MVP completion summary
- ✅ **BUILD_GUIDE.md** - Pi-gen image building guide
- ✅ **QUICK_BUILD.md** - Quick build reference
- ✅ **VISUALIZATION_PLAN.md** - Charting and guided workflows plan
- ✅ **systemd/README.md** - Service management documentation
- ✅ **pi-gen/stageDTPM3/04-dangerous-pi/README.md** - Build integration docs
- ✅ **app/frontend/README.md** - Frontend documentation
@@ -168,14 +220,46 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
## 🚧 Future Enhancements (Post-MVP)
### High Priority
### High Priority (Next Phase)
1. **Frontend Build Integration**
1. **Data Visualization & Guided Workflows** 🎯 **IN PLANNING**
- Victory charts integration (~50KB bundle)
- PM3 output parser layer (text → structured JSON)
- Real-time tuning visualizations (HF/LF/HW tune)
- Guided workflow framework (multi-step wizards)
- Touch-optimized interactive charts
- Mobile-first UI components
- **Target**: 4-6 weeks implementation
- **Dependencies**: Victory, PM3 output parsers
2. **Cross-Platform Apps** 🎯 **PLANNED**
- **React Native Mobile App** (iOS/Android)
- Shared Victory chart components with web
- Full BLE integration for offline operation
- Native performance and UX
- Share ~90% codebase with web app
- **Electron Desktop App** (Windows/Mac/Linux)
- Same codebase as web + React Native
- Native system integration
- Offline-first capabilities
- **Target**: Post-visualization implementation
3. **Enhanced BLE Manager** 🎯 **PLANNED**
- Full web client feature parity via BLE
- Command execution over BLE (for mobile app)
- Bidirectional communication (GATT server)
- Status queries and responses
- Guided workflow triggers
- Notification improvements
- **Target**: Concurrent with React Native app
4. **Frontend Build Integration**
- Serve frontend from backend in production
- Build script for combined deployment
- Asset optimization
- Service worker for offline support
2. **Backup System**
5. **Backup System**
- Application directory backup
- Optional SD card image backup
- Scheduled backups
@@ -184,21 +268,22 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
### Medium Priority
3. **Authentication**
6. **Authentication**
- Optional password protection
- Session cookies
- Login page
4. **HTTPS Support**
7. **HTTPS Support**
- Self-signed certificate generation
- Automatic cert creation on first boot
- Toggle in settings
5. **Advanced PM3 Features**
- Guided wizards (Clone Card, Format T5577)
8. **Advanced PM3 Features**
- Waveform viewer with pan/zoom
- Protocol trace analyzer
- Antenna tuning dashboard
- Command templates
- Favorite commands
- Syntax highlighting
### Low Priority
@@ -222,18 +307,20 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
## 📊 Project Metrics
### Backend
- **Lines of Code**: ~5,000+
- **Files**: 25+
- **API Endpoints**: 40+ (10 health/PM3, 10 WiFi, 6 updates, 7 plugins, 3 UPS, 4 BLE)
- **Managers**: 6 (Session, WiFi, Update, UPS, BLE, Plugin)
- **Lines of Code**: ~7,000+
- **Files**: 40+
- **API Endpoints**: 54+ (PM3 10+, System 18+, WiFi 10, Updates 6, Plugins 7, Auth 3)
- **Managers**: 7 (PM3Device, Session, WiFi, Update, UPS, BLE, Plugin)
- **Services**: 4 (PM3, System, WiFi, Update) + ServiceContainer
- **Dependencies**: 11 packages
- **Test Coverage**: All managers tested
### Frontend
- **Lines of Code**: ~1,500
- **Files**: 9
- **Pages**: 4
- **Components**: Inline (no separate components yet)
- **Lines of Code**: ~2,500+
- **Files**: 13+
- **Pages**: 5 (Dashboard, Commands, Settings, Logs, Updates)
- **Components**: 4 (DeviceSelector, PowerWidget, ConnectDialog, QRScanner)
- **Hooks**: 1 (useWebSocket)
- **CSS**: 15KB (uncompressed)
- **Bundle Size**: ~120KB (estimated, gzipped)
@@ -253,13 +340,25 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
## 🎯 Next Steps
### Immediate
1. **Hardware Testing**
1. ✅ **Power Management Policy** (COMPLETE - 2025-11-26)
- Power restrictions API implemented
- UPS-aware power management
- Safe defaults for systems without UPS
- Ready for hardware deployment
2. **Hardware Testing** (NEXT - Blocked until pi-gen build complete)
- Test on actual Raspberry Pi Zero 2 W
- Test with real UPS HAT
- Test with real UPS HAT (optional hardware)
- Test BLE notifications with mobile device
- Performance optimization for Pi hardware
2. **Frontend Build Integration**
3. **Pi-gen Build Testing** (READY)
- Run `./build-image.sh quick` to test PM3 client build
- Verify Python bindings compilation
- Test full image build
- Deploy to Pi hardware
4. **Frontend Build Integration**
- Create production build script
- Serve frontend from backend
- Single-server deployment
@@ -322,13 +421,14 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
│
┌───────────────┼───────────────┐
│ │ │
REST API SSE Events Static Assets
REST API WebSocket Static Assets
│ │ │
┌───────▼───────────────▼───────────────▼─────────────────┐
│ Remix.js Frontend (React) │
│ │
│ • Dashboard • Commands • Settings • Logs │
│ • Cyberpunk Theme • Mobile-First • SSR │
│ • useWebSocket hook • DeviceSelector • PowerWidget │
└───────────────────────┬─────────────────────────────────┘
│
Proxy to
@@ -337,30 +437,33 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
│ FastAPI Backend (Python) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ API Layer │ │ SSE Events │ │ Workers │ │
│ │ API Layer │ │ WebSocket │ │ Services │ │
│ │ │ │ │ │ │ │
│ │ • Health │ │ • PM3 Status │ │ • PM3 Worker │ │
│ │ • System │ │ • Updates │ │ • Mock PM3 │ │
│ │ • PM3 │ │ • Battery │ │ │ │
│ └──────────────┘ └──────────────┘ └──────┬───────┘ │
│ │ │
│ ┌──────────────┐ ┌──────────────┐ │ │
│ │ Managers │ │ Database │ │ │
│ │ │ │ │ │ │
│ │ • Session │ │ SQLite │ │ │
│ │ • WiFi │ │ │ │ │
│ │ • Updates │ │ • Sessions │ │ │
│ │ • UPS │ │ • Config │ │ │
│ │ • BLE │ │ • History │ │ │
│ │ • Plugin │ │ • Crashes │ │ │
│ └──────────────┘ └──────────────┘ │ │
└─────────────────────────────────────────────┼──────────┘
│
pm3 Python module
│
┌─────────────────────────────────────────────▼──────────┐
│ Proxmark3 Hardware │
│ /dev/ttyACM0 │
│ │ • Health │ │ • PM3 Status │ │ • PM3Service │ │
│ │ • System │ │ • Devices │ │ • System │ │
│ │ • PM3 │ │ • UPS/Battery│ │ • WiFi │ │
│ │ • WiFi │ │ • Updates │ │ • Update │ │
│ │ • Updates │ │ │ │ │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Managers │ │ Workers │ │ Database │ │
│ │ │ │ │ │ │ │
│ │ • PM3Device │ │ • PM3 Worker │ │ SQLite │ │
│ │ • Session │ │ (SWIG) │ │ │ │
│ │ • WiFi │ │ │ │ • Sessions │ │
│ │ • Updates │ └──────────────┘ │ • Config │ │
│ │ • UPS │ │ • History │ │
│ │ • BLE │ ServiceContainer │ • Crashes │ │
│ │ • Plugin │ (DI) │ │ │
│ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────┘
│
pm3 Python module (SWIG)
│
┌───────────────────────▼─────────────────────────────────┐
│ Proxmark3 Hardware (Multi-device) │
│ /dev/ttyACM0, /dev/ttyACM1, ... │
└─────────────────────────────────────────────────────────┘
```
@@ -380,7 +483,7 @@ All MVP features are implemented and tested locally. Next: deploy and test on ac
- **Language**: TypeScript
- **Build**: Vite
- **Styling**: Vanilla CSS (no framework)
- **Transport**: Fetch API + EventSource (SSE)
- **Transport**: Fetch API + WebSocket
### Infrastructure
- **OS**: Raspberry Pi OS (Debian Trixie)
@@ -398,22 +501,41 @@ dangerous-pi/
│ ├── backend/ # FastAPI backend
│ │ ├── api/ # REST endpoints
│ │ │ ├── health.py # Health checks
│ │ │ ├── pm3.py # PM3 commands
│ │ │ ├── system.py # System + UPS + BLE
│ │ │ ├── pm3.py # PM3 commands + devices
│ │ │ ├── system.py # System + UPS + BLE + CPU
│ │ │ ├── wifi.py # WiFi management
│ │ │ ├── updates.py # Update management
│ │ │ └── plugins.py # Plugin management
│ │ ├── sse/ # Server-Sent Events
│ │ │ └── events.py # Event broadcaster
│ │ │ ├── plugins.py # Plugin management
│ │ │ └── auth.py # Authentication
│ │ ├── websocket/ # WebSocket real-time events
│ │ │ ├── manager.py # Connection manager
│ │ │ ├── routes.py # WebSocket endpoint
│ │ │ └── notifications.py # Event broadcasting helpers
│ │ ├── services/ # Business logic layer
│ │ │ ├── container.py # Dependency injection
│ │ │ ├── pm3_service.py # PM3 operations
│ │ │ ├── system_service.py # System operations
│ │ │ ├── wifi_service.py # WiFi operations
│ │ │ └── update_service.py # Update operations
│ │ ├── workers/ # Background workers
│ │ │ └── pm3_worker.py # PM3 command executor
│ │ ├── managers/ # Business logic
│ │ │ ├── session_manager.py # Session handling
│ │ │ └── pm3_worker.py # PM3 command executor (SWIG)
│ │ ├── managers/ # State management
│ │ │ ├── pm3_device_manager.py # Multi-device PM3 management
│ │ │ ├── session_manager.py # Per-device sessions
│ │ │ ├── wifi_manager.py # WiFi management
│ │ │ ├── update_manager.py # Update system
│ │ │ ├── ups_manager.py # UPS monitoring
│ │ │ ├── ups_drivers/ # UPS driver implementations
│ │ │ │ ├── base.py # Abstract base driver
│ │ │ │ ├── i2c_driver.py # Generic I2C fuel gauge
│ │ │ │ ├── pisugar_driver.py # PiSugar TCP driver
│ │ │ │ └── pisugar_i2c_driver.py # PiSugar I2C driver
│ │ │ ├── ble_manager.py # BLE notifications
│ │ │ └── plugin_manager.py # Plugin framework
│ │ ├── ble/ # BLE GATT implementation
│ │ │ ├── gatt_server.py # GATT server
│ │ │ ├── characteristics.py # GATT characteristics
│ │ │ └── bluez_adapter.py # BlueZ D-Bus adapter
│ │ ├── models/ # Database models
│ │ │ └── database.py # SQLite schema
│ │ ├── config.py # Configuration
@@ -424,7 +546,15 @@ dangerous-pi/
│ │ │ │ ├── _index.tsx # Dashboard
│ │ │ │ ├── commands.tsx # Command interface
│ │ │ │ ├── settings.tsx # Settings + WiFi + Updates
│ │ │ │ ├── updates.tsx # Update management
│ │ │ │ └── logs.tsx # Command logs
│ │ │ ├── components/ # React components
│ │ │ │ ├── DeviceSelector.tsx # Multi-device selection
│ │ │ │ ├── PowerWidget.tsx # UPS/battery status
│ │ │ │ ├── ConnectDialog.tsx # Connection management
│ │ │ │ └── QRScanner.tsx # QR code scanning
│ │ │ ├── hooks/ # Custom React hooks
│ │ │ │ └── useWebSocket.ts # WebSocket singleton manager
│ │ │ ├── root.tsx # Root layout
│ │ │ ├── styles.css # Cyberpunk theme
│ │ │ ├── entry.client.tsx # Client entry
@@ -524,7 +654,7 @@ Frontend: npm run dev (separate server)
### Backend
- Response time: < 100ms (health checks)
- Command execution: < 1s (most PM3 commands)
- SSE latency: < 50ms (event delivery)
- WebSocket latency: < 50ms (event delivery)
- Memory usage: < 100MB
### Frontend
@@ -593,7 +723,7 @@ Want to add features? Follow these steps:
- Settings page with WiFi UI
- Command logs
- Session management
- SSE real-time notifications
- Real-time notifications (migrated to WebSocket in v1.0.0)
- Comprehensive documentation
**Technical:**
@@ -612,7 +742,7 @@ Want to add features? Follow these steps:
- [x] Working frontend UI
- [x] PM3 command execution
- [x] Session management
- [x] Real-time updates (SSE)
- [x] Real-time updates (WebSocket)
- [x] Comprehensive documentation
### Phase 2: Core Features (Implementation) ✅ COMPLETE
@@ -626,15 +756,16 @@ Want to add features? Follow these steps:
- [x] Port conflict resolution scripts
- [x] Local testing (all tests passing)
### Phase 3: MVP Deployment & Hardware Testing 🚧 CURRENT
- [ ] Deploy to actual Raspberry Pi Zero 2 W
- [ ] Test with real Proxmark3 hardware
- [ ] Test UPS HAT integration
- [ ] Test BLE on Pi hardware
- [ ] Combined frontend/backend deployment
- [ ] Build custom OS image with pi-gen
- [ ] Performance optimization on Pi Zero 2 W
- [ ] Fix any hardware-specific issues
### Phase 3: MVP Deployment & Hardware Testing ✅ COMPLETE
- [x] Deploy to actual Raspberry Pi Zero 2 W
- [x] Test with real Proxmark3 hardware (Iceman firmware 2025-12-30)
- [x] Test UPS HAT integration (PiSugar 2 detected and working)
- [x] Test BLE on Pi hardware (advertising as DangerousPi)
- [x] Combined frontend/backend deployment
- [x] Build custom OS image with pi-gen
- [x] Fix any hardware-specific issues (PATH fix for iw command)
- [ ] Performance optimization on Pi Zero 2 W (ongoing)
- [ ] WiFi mode detection fix (reports "client" when in AP mode)
### Phase 4: Enhancement 📋 PLANNED
- [ ] Backup system
@@ -658,7 +789,8 @@ Want to add features? Follow these steps:
- FastAPI: Async support, auto-docs, fast
- Remix: SSR performance, progressive enhancement
- SQLite: Simple, no external database needed
- SSE: Lighter than WebSockets for one-way updates
- WebSocket: Bidirectional real-time communication, better reconnection handling
- Service Layer: Clean separation of concerns, dependency injection for testability
**Why cyberpunk theme?**
- Matches Dangerous Things brand aesthetic
@@ -674,6 +806,5 @@ Want to add features? Follow these steps:
---
Built with ❤️ for **[Dangerous Things](https://dangerousthings.com)**
Built with ❤️ by **[Dangerous Things](https://dangerousthings.com)**
*"Augmenting humanity with technology"*