pi-pm3/claude.md

Dangerous Pi - Development Guide for Claude

Project Overview

Dangerous Pi is a modern web-based management interface for the Proxmark3 RFID research tool, designed to run on a Raspberry Pi Zero 2 W. It extends the existing pi-pm3 project with advanced features and a Python/FastAPI backend.

Architecture

Backend (Python + FastAPI)

• Location: /app/backend/
• Framework: FastAPI with async support
• Database: SQLite (aiosqlite)
• Transport: REST + WebSocket for real-time events

Frontend (Remix.js)

• Location: /app/frontend/
• 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

1. PM3 Worker (workers/pm3_worker.py)

   • Uses built-in pm3 Python module from RfidResearchGroup/proxmark3
   • API: pm3.open(device) and .cmd(command)
   • Handles async command execution
   • Single-threaded, sequential command processing

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)

4. Update Manager (managers/update_manager.py)

   • Polls GitHub Releases API
   • Downloads and applies updates
   • Rebuilds PM3 client after updates
   • WebSocket notifications for update status

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

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

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

The RfidResearchGroup/proxmark3 (iceman fork) includes SWIG-based Python bindings:

# Standalone mode (for our backend)
import pm3
device = pm3.open("/dev/ttyACM0")
result = device.cmd("hw status")

Important Notes:

• PM3 does NOT support streaming responses
• Most commands complete and return full output
• Use REST endpoints for commands
• Use WebSocket for backend-to-frontend notifications

Current Status

✅ Completed (MVP Features)

• Backend Foundation

  • FastAPI application with async support
  • SQLite database (sessions, config, crash_reports, command_history)
  • Health check endpoints
  • Configuration management
  • 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)
  • Network scanning with signal strength
  • Full mode switching (AP/Client/Dual/Auto/Off)
  • Network connection with password support
  • Hidden SSID support
  • Saved networks management
  • Forget network functionality
  • Static IP configuration
  • DHCP management
  • 10 WiFi API endpoints

• Frontend (Complete)

  • Cyberpunk-themed responsive UI
  • Dashboard with system status
  • PM3 command interface
  • Settings with WiFi management
  • Command logs
  • Connection dialog with password input
  • Saved networks UI
  • Theme toggle (Dark/Light/Auto)

✅ Update Manager (Complete)

• GitHub releases API integration
• Automatic periodic update checks (configurable interval)
• Version comparison (semantic versioning)
• Update download with progress tracking
• Checksum verification (SHA256)
• Automatic installation with backup
• PM3 client rebuild after updates
• Rollback on installation failure
• 6 Update API endpoints
• Frontend UI with release notes and progress tracking

📋 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

Code Style

• Use async/await throughout
• Type hints on all functions
• Docstrings for all modules and classes
• Keep functions focused and simple

API Design

• REST for all client-initiated actions
• WebSocket for server-initiated notifications
• Clear error messages with appropriate status codes
• Consistent response format

Security

• Run services as non-root user
• Optional authentication (configurable)
• Optional HTTPS (self-signed cert)
• Input validation on all endpoints
• No secrets in code (use environment variables)

Testing Strategy

• Test endpoints with curl before building frontend
• 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:

# 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

# 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:

// 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:

// 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
│   │   ├── config.py            # Configuration
│   │   ├── api/                 # REST endpoints
│   │   │   ├── health.py        # Health checks
│   │   │   ├── pm3.py           # Proxmark3 commands
│   │   │   ├── 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/            # State management
│   │   │   ├── pm3_device_manager.py  # Multi-device PM3
│   │   │   ├── session_manager.py
│   │   │   ├── update_manager.py
│   │   │   ├── wifi_manager.py
│   │   │   ├── ups_manager.py
│   │   │   ├── ups_drivers/     # UPS driver implementations
│   │   │   ├── ble_manager.py
│   │   │   └── plugin_manager.py  # Plugin lifecycle
│   │   └── models/              # Database models
│   │       └── database.py
│   ├── frontend/                # Remix.js web UI
│   ├── plugins/                 # Installed plugins
│   │   └── hello_world/         # Demo plugin
│   └── scripts/                 # Helper scripts
├── data/                        # SQLite database, backups
├── logs/                        # Application logs
├── pi-gen/                      # Custom OS image builder
├── requirements.txt             # Python dependencies
└── claude.md                    # This file

Integration with Existing pi-pm3

The existing pi-pm3 project provides:

• Custom Raspberry Pi OS image (pi-gen based)
• RaspAP (PHP-based WiFi management on port 80)
• ttyd web terminals (bash on 8000, pm3 on 8080)
• PM3 client built and installed

Dangerous Pi will:

• Keep RaspAP initially, potentially replace later
• Replace ttyd terminals with web UI
• Add FastAPI backend on port 8000 (conflicts with ttyd-bash)
• Update pi-gen stage to install new application

Next Steps for Implementation

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
   • Update manager with GitHub integration
   • UPS monitoring daemon

3. Build frontend:

   • Decide: Remix vs minimal SPA
   • Dashboard with status indicators
   • Command interface (simpler than full terminal)
   • Settings pages

4. Create installer:

   • Update pi-gen stage scripts
   • Create systemd service units
   • Handle port conflicts with existing ttyd

Useful Resources

• Proxmark3 Python API Discussion
• Python API Bug Fix
• RaspAP Documentation
• FastAPI Documentation

Environment Variables

# PM3 Configuration
PM3_DEVICE=/dev/ttyACM0
PM3_TIMEOUT=30

# Session Configuration
SESSION_TIMEOUT=300

# Server Configuration
HOST=0.0.0.0
PORT=8000

# Update Configuration
GITHUB_REPO=yourusername/dangerous-pi
UPDATE_CHECK_INTERVAL=3600

# Wi-Fi Configuration
WLAN_INTERFACE=wlan0
USB_WLAN_INTERFACE=wlan1

# UPS Configuration
UPS_I2C_ADDRESS=0x36
UPS_CHECK_INTERVAL=60

# BLE Configuration
BLE_ENABLED=true
BLE_DEVICE_NAME=DangerousPi

# Security
AUTH_ENABLED=false
HTTPS_ENABLED=false

Common PM3 Commands

For testing the PM3 worker:

hw version          # Get hardware/firmware version
hw status           # Get hardware status
hw tune             # Tune antenna
hf search           # Search for HF tags
lf search           # Search for LF tags
hf mf autopwn       # Auto-attack MIFARE Classic

Notes

• Pi Zero 2 W has limited CPU/RAM - optimize for efficiency
• 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