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 + Server-Sent Events (SSE)

Frontend (Remix or SPA)

• Location: /app/frontend/
• Framework: TBD - Remix (preferred) or minimal SPA
• Transport: REST API + SSE for notifications

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. Session Manager (managers/session_manager.py)

   • Single active session enforcement
   • Takeover mechanism for new sessions
   • Idle timeout (default: 5 minutes)

3. Update Manager (managers/update_manager.py)

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

4. 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
   • Safe shutdown triggers
   • Battery percentage reporting

6. 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

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 SSE only 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
  • Mock PM3 worker for development
  • Session manager (single-user with takeover)
  • SSE endpoints 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

📋 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

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
• SSE 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

File Structure

/home/work/dangerous-pi/
├── 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
│   │   ├── sse/                 # Server-Sent Events
│   │   │   └── events.py        # SSE endpoints
│   │   ├── workers/             # Background workers
│   │   │   └── pm3_worker.py    # PM3 command executor
│   │   ├── managers/            # Business logic
│   │   │   ├── session_manager.py
│   │   │   ├── update_manager.py
│   │   │   ├── wifi_manager.py
│   │   │   ├── ups_manager.py
│   │   │   └── ble_manager.py
│   │   └── models/              # Database models
│   │       └── database.py
│   ├── frontend/                # Web UI (TBD)
│   ├── plugins/                 # Optional plugins
│   └── 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:

   • PM3 worker with actual pm3 module integration
   • Session manager with proper locking
   • SSE 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
• SSE is lighter than WebSockets for one-way notifications
• SQLite is sufficient for single-device deployment
• Keep bundles small for faster load times
• Test thoroughly on actual hardware, not just desktop