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

212
claude.md
View File

@@ -10,12 +10,15 @@ Dangerous Pi is a modern web-based management interface for the Proxmark3 RFID r
- **Location**: `/app/backend/`
- **Framework**: FastAPI with async support
- **Database**: SQLite (aiosqlite)
- **Transport**: REST + Server-Sent Events (SSE)
- **Transport**: REST + WebSocket for real-time events
### Frontend (Remix or SPA)
### Frontend (Remix.js)
- **Location**: `/app/frontend/`
- **Framework**: TBD - Remix (preferred) or minimal SPA
- **Transport**: REST API + SSE for notifications
- **Framework**: Remix v2 (React Router with SSR)
- **Styling**: Vanilla CSS (cyberpunk theme, ~15KB)
- **Charts**: Victory (cross-platform, mobile-first)
- **Transport**: REST API + WebSocket for notifications
- **Target Users**: Mobile (primary), Desktop (secondary)
### Key Components
@@ -25,31 +28,61 @@ Dangerous Pi is a modern web-based management interface for the Proxmark3 RFID r
- Handles async command execution
- Single-threaded, sequential command processing
2. **Session Manager** (`managers/session_manager.py`)
- Single active session enforcement
2. **PM3 Device Manager** (`managers/pm3_device_manager.py`)
- Multi-device support with unique device IDs
- Device discovery via pyudev
- Per-device worker management
- Firmware version tracking
3. **Session Manager** (`managers/session_manager.py`)
- Per-device session management
- Takeover mechanism for new sessions
- Idle timeout (default: 5 minutes)
3. **Update Manager** (`managers/update_manager.py`)
4. **Update Manager** (`managers/update_manager.py`)
- Polls GitHub Releases API
- Downloads and applies updates
- Rebuilds PM3 client after updates
- SSE notifications for update status
- WebSocket notifications for update status
4. **Wi-Fi Manager** (`managers/wifi_manager.py`)
5. **Service Layer** (`services/`)
- **ServiceContainer** - Dependency injection
- **PM3Service** - PM3 command execution
- **SystemService** - System operations
- **WiFiService** - WiFi management
- **UpdateService** - Update operations
6. **Wi-Fi Manager** (`managers/wifi_manager.py`)
- Detects available interfaces (wlan0, wlan1)
- Manages modes: AP, Client, Auto, Dual (client+AP)
- Integrates with existing RaspAP setup initially
5. **UPS Manager** (`managers/ups_manager.py`)
- I2C battery monitoring
7. **UPS Manager** (`managers/ups_manager.py`)
- Multiple driver support (auto-detection)
- PiSugar TCP driver
- I2C fuel gauge driver (MAX17040/48)
- Safe shutdown triggers
- Battery percentage reporting
6. **BLE Manager** (`managers/ble_manager.py`)
8. **WebSocket Manager** (`websocket/`)
- Real-time event broadcasting
- Connection management
- Event types: system_stats, pm3_status, ups_battery, etc.
9. **BLE Manager** (`managers/ble_manager.py`)
- Uses built-in Pi Zero 2 W Bluetooth
- Sends notifications for updates, backups, low battery
- Auto-detects BLE capability
- **Planned**: Full GATT server for React Native app
- **Planned**: Command execution via BLE (offline operation)
10. **Plugin Manager** (`managers/plugin_manager.py`)
- Extensible plugin architecture
- Remote plugin installation from GitHub releases
- Automatic pip dependency management
- Hardware access (GPIO, I2C, SPI, serial, camera)
- Permission system for user consent
- See `.claude/instructions/plugin-architecture.md` for details
## Proxmark3 Python API
@@ -66,7 +99,7 @@ result = device.cmd("hw status")
- PM3 does NOT support streaming responses
- Most commands complete and return full output
- Use REST endpoints for commands
- Use SSE only for backend-to-frontend notifications
- Use WebSocket for backend-to-frontend notifications
## Current Status
@@ -76,10 +109,11 @@ result = device.cmd("hw status")
- SQLite database (sessions, config, crash_reports, command_history)
- Health check endpoints
- Configuration management
- PM3 worker with built-in pm3 module integration
- Mock PM3 worker for development
- Session manager (single-user with takeover)
- SSE endpoints for real-time notifications
- PM3 worker with built-in pm3 module integration (SWIG)
- PM3 device manager for multi-device support
- Session manager (per-device with takeover)
- Service layer (PM3Service, SystemService, WiFiService)
- WebSocket for real-time notifications
- **WiFi Manager (Full MVP)**
- Interface detection (USB vs built-in)
@@ -115,12 +149,20 @@ result = device.cmd("hw status")
- 6 Update API endpoints
- Frontend UI with release notes and progress tracking
### 📋 Remaining Features
1. UPS monitoring daemon
2. BLE notification system
3. Plugin framework -- planned appstore + intergration later
4. Create systemd services
5. Update pi-gen stage to install Dangerous Pi
### 📋 Next Phase Features
**Visualization & Guided Workflows (In Planning)**
1. Victory charts integration (cross-platform)
2. PM3 output parsers (text → JSON)
3. Real-time tuning visualizations
4. Guided workflow framework
5. Mobile-optimized touch interactions
**Cross-Platform Apps (Planned)**
1. React Native mobile app (iOS/Android)
2. Electron desktop app (Windows/Mac/Linux)
3. Enhanced BLE manager (full feature parity)
4. Shared component library (~90% code reuse)
## Development Guidelines
@@ -132,7 +174,7 @@ result = device.cmd("hw status")
### API Design
- REST for all client-initiated actions
- SSE for server-initiated notifications
- WebSocket for server-initiated notifications
- Clear error messages with appropriate status codes
- Consistent response format
@@ -148,10 +190,94 @@ result = device.cmd("hw status")
- Mock PM3 module for testing without hardware
- Test on actual Pi Zero 2 W for performance
## Data Visualization (Victory Charts)
### Why Victory?
Victory is the **only** major charting library designed for true cross-platform development:
- **Web**: Works with Remix/React
- **React Native**: `victory-native` with native rendering
- **Electron**: Same as web version
- **Mobile-First**: Touch gestures, responsive, 44px targets
- **Bundle Size**: ~50KB (acceptable with code splitting)
### Parser Layer Architecture
PM3 commands return text output. We need parsers to convert to structured data:
```python
# app/backend/parsers/pm3_output.py
def parse_antenna_tuning(output: str) -> dict:
"""Parse hw tune output into plottable data."""
# Input: "# LF antenna: 50.00 V @ 125.00 kHz"
# Output: {"voltage": 50.0, "frequency": 125.0}
def parse_waveform_data(output: str) -> dict:
"""Parse data samples into array."""
# Output: {"samples": [1, 2, 3, ...], "rate": 48000}
def parse_protocol_trace(output: str) -> dict:
"""Parse hf list output into structured frames."""
# Output: {"frames": [...], "timestamps": [...]}
```
### Enhanced API Response Format
```python
# New response format
class CommandWithDataResponse(BaseModel):
success: bool
output: str # Original text (for compatibility)
data: Optional[Dict] = None # Structured data for charts
visualization_type: Optional[str] = None # "waveform", "tune", "trace"
```
### Shared Chart Components
Create in `/app/shared/components/charts/` for cross-platform reuse:
```typescript
// TuneChart.tsx - Works on Web + React Native + Electron
import { VictoryLine, VictoryChart, VictoryAxis } from 'victory'
export function TuneChart({ data, title }) {
return (
<VictoryChart>
<VictoryLine data={data} x="frequency" y="voltage" />
</VictoryChart>
)
}
```
### Guided Workflow Framework
Multi-step wizards for common PM3 operations:
```typescript
// Workflow definition
const cloneMifareWorkflow = {
steps: [
{ id: 'tune', component: StepTuneAntenna, validation: () => tuned },
{ id: 'read', component: StepReadSource, validation: () => hasData },
{ id: 'write', component: StepWriteTarget }
]
}
```
### Testing Strategy
- Mock PM3 output for parser testing
- Test charts with sample data (no hardware needed)
- Verify touch interactions on actual mobile device
- Performance testing on Pi Zero 2 W
## File Structure
```
/home/work/dangerous-pi/
├── .claude/
│ ├── instructions/ # Custom instructions for Claude
│ │ └── plugin-architecture.md # Plugin system guide
│ └── plans/ # Implementation plans
├── app/
│ ├── backend/
│ │ ├── main.py # FastAPI app entry
@@ -159,21 +285,33 @@ result = device.cmd("hw status")
│ │ ├── api/ # REST endpoints
│ │ │ ├── health.py # Health checks
│ │ │ ├── pm3.py # Proxmark3 commands
│ │ │ └── system.py # System management
│ │ ├── sse/ # Server-Sent Events
│ │ │ └── events.py # SSE endpoints
│ │ │ ├── system.py # System management
│ │ │ └── plugins.py # Plugin management
│ │ ├── websocket/ # WebSocket real-time events
│ │ │ ├── manager.py # Connection manager
│ │ │ ├── routes.py # WebSocket endpoint
│ │ │ └── notifications.py # Event broadcasting
│ │ ├── services/ # Business logic layer
│ │ │ ├── container.py # Dependency injection
│ │ │ ├── pm3_service.py # PM3 operations
│ │ │ ├── system_service.py
│ │ │ └── wifi_service.py
│ │ ├── workers/ # Background workers
│ │ │ └── pm3_worker.py # PM3 command executor
│ │ ├── managers/ # Business logic
│ │ ├── managers/ # State management
│ │ │ ├── pm3_device_manager.py # Multi-device PM3
│ │ │ ├── session_manager.py
│ │ │ ├── update_manager.py
│ │ │ ├── wifi_manager.py
│ │ │ ├── ups_manager.py
│ │ │ └── ble_manager.py
│ │ │ ├── ups_drivers/ # UPS driver implementations
│ │ │ ├── ble_manager.py
│ │ │ └── plugin_manager.py # Plugin lifecycle
│ │ └── models/ # Database models
│ │ └── database.py
│ ├── frontend/ # Web UI (TBD)
│ ├── plugins/ # Optional plugins
│ ├── frontend/ # Remix.js web UI
│ ├── plugins/ # Installed plugins
│ │ └── hello_world/ # Demo plugin
│ └── scripts/ # Helper scripts
├── data/ # SQLite database, backups
├── logs/ # Application logs
@@ -199,10 +337,11 @@ Dangerous Pi will:
## Next Steps for Implementation
1. **Complete core backend**:
- PM3 worker with actual pm3 module integration
- Session manager with proper locking
- SSE event system for notifications
1. **Complete core backend**: ✅ DONE
- PM3 worker with SWIG bindings
- PM3 device manager for multi-device
- Session manager with per-device locking
- WebSocket event system for notifications
2. **Add system management**:
- Wi-Fi detection and mode switching
@@ -277,7 +416,8 @@ hf mf autopwn # Auto-attack MIFARE Classic
## Notes
- Pi Zero 2 W has limited CPU/RAM - optimize for efficiency
- SSE is lighter than WebSockets for one-way notifications
- WebSocket provides bidirectional real-time communication with better reconnection handling
- SQLite is sufficient for single-device deployment
- Keep bundles small for faster load times
- Test thoroughly on actual hardware, not just desktop
- Multi-device PM3 support requires per-device session management