pi-pm3/README_DEV.md

Dangerous Pi - Development Guide

Quick Start

1. Install Dependencies

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

2. Run Tests

# Test backend components
python test_backend.py

3. Start Backend Server

# Development mode with auto-reload
python -m app.backend.main

# Or using uvicorn directly
uvicorn app.backend.main:app --reload --host 0.0.0.0 --port 8000

4. Test API Endpoints

# Health check
curl http://localhost:8000/api/health

# System info
curl http://localhost:8000/api/system/info

# PM3 status (uses mock when no hardware present)
curl http://localhost:8000/api/pm3/status

# Create session
curl -X POST http://localhost:8000/api/system/session/create \
  -H "Content-Type: application/json" \
  -d '{"force_takeover": false}'

# Execute PM3 command (mock)
curl -X POST http://localhost:8000/api/pm3/command \
  -H "Content-Type: application/json" \
  -d '{"command": "hw version", "session_id": "your-session-id"}'

# SSE events stream
curl -N http://localhost:8000/sse/events

Project Structure

dangerous-pi/
├── app/
│   ├── backend/           # FastAPI backend
│   │   ├── main.py        # App entry point
│   │   ├── config.py      # Configuration
│   │   ├── api/           # REST endpoints
│   │   ├── sse/           # SSE endpoints
│   │   ├── workers/       # PM3 worker
│   │   ├── managers/      # Business logic
│   │   └── models/        # Database models
│   ├── frontend/          # Web UI (TBD)
│   ├── plugins/           # Optional plugins
│   └── scripts/           # Helper scripts
├── data/                  # SQLite database
├── logs/                  # Application logs
├── pi-gen/                # OS image builder
├── requirements.txt       # Python deps
├── test_backend.py        # Backend tests
└── claude.md              # AI dev guide

API Documentation

Once the server is running, visit:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Development Workflow

Backend Development

1. Add new endpoint:

   • Create/edit router in app/backend/api/
   • Register router in app/backend/main.py
   • Test with curl or Swagger UI

2. Add new manager:

   • Create manager in app/backend/managers/
   • Use in API endpoints
   • Add tests

3. Add SSE event:

   • Add helper function in app/backend/sse/events.py
   • Call from managers/workers
   • Test with curl -N

Testing on Raspberry Pi

1. Transfer code:

   rsync -avz --exclude 'venv' --exclude '__pycache__' \
     . dt@10.3.141.1:/home/dt/dangerous-pi/
   

2. SSH into Pi:

   ssh dt@10.3.141.1
   

3. Install and run:

   cd dangerous-pi
   pip3 install -r requirements.txt
   python3 -m app.backend.main
   

Mock vs Real PM3

The backend automatically uses MockPM3Worker when the pm3 module is not available. This allows development without Proxmark3 hardware.

To use real PM3:

• Ensure Proxmark3 client is installed with Python support
• The pm3 module must be importable
• Set PM3_DEVICE environment variable to your device path

Environment Variables

Copy .env.example to .env and customize:

cp .env.example .env
nano .env

See claude.md for full list of environment variables.

Next Steps

See claude.md for:

• Detailed architecture
• Implementation roadmap
• PM3 API usage
• Integration guidelines

Troubleshooting

Port 8000 already in use

The existing pi-pm3 uses ttyd on port 8000. Either:

• Change PORT in config to 8001
• Stop ttyd: sudo systemctl stop ttyd-bash

PM3 module not found

Expected during development. The mock worker will be used automatically.

Database locked

Stop all running instances of the backend.