pi-pm3/GETTING_STARTED.md

# Getting Started with Dangerous Pi

Complete guide to running the Dangerous Pi stack (backend + frontend).

## Quick Start (Development)

### 1. Start Backend

```bash
# Install Python dependencies
pip install -r requirements.txt

# Run backend
python -m app.backend.main
```

Backend will be available at **http://localhost:8000**

API Documentation: http://localhost:8000/docs

### 2. Start Frontend

```bash
# Navigate to frontend
cd app/frontend

# Install dependencies
npm install

# Run development server
npm run dev
```

Frontend will be available at **http://localhost:3000**

### 3. Open Browser

Navigate to http://localhost:3000 and you should see the Dangerous Pi dashboard!

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────────┐
│                    Browser (User)                        │
│              http://localhost:3000                       │
└────────────────────┬────────────────────────────────────┘
                     │
                     ├─── SSE (/sse/events)
                     │    Real-time notifications
                     │
                     ├─── REST API (/api/*)
                     │    Command execution, status
                     │
┌────────────────────▼────────────────────────────────────┐
│              Frontend (Remix.js)                         │
│                   Port 3000                              │
│                                                          │
│  • Dashboard     • Commands                              │
│  • Settings      • Logs                                  │
│  • Cyberpunk Theme                                       │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ Proxies to backend
                     │
┌────────────────────▼────────────────────────────────────┐
│              Backend (FastAPI)                           │
│                  Port 8000                               │
│                                                          │
│  • PM3 Worker    • Session Manager                       │
│  • SSE Events    • Database (SQLite)                     │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ pm3 Python module
                     │
┌────────────────────▼────────────────────────────────────┐
│             Proxmark3 Hardware                           │
│              /dev/ttyACM0                                │
└─────────────────────────────────────────────────────────┘
```

---

## Features

### ✅ Implemented

**Backend:**
- FastAPI with async support
- SQLite database for sessions and history
- PM3 worker with built-in `pm3` module integration
- Mock PM3 worker for development without hardware
- Session management (single-user with takeover)
- SSE for real-time notifications
- Health check and system info endpoints

**Frontend:**
- Responsive Remix.js application
- Cyberpunk theme (dark default, light mode available)
- Dashboard with system status
- Command interface with history
- Settings page
- Command logs
- Real-time SSE integration
- Mobile-first responsive design

### 🚧 Planned

- Wi-Fi manager (AP/Client/Dual modes)
- Update manager (GitHub releases)
- UPS monitoring
- BLE notifications
- Backup/restore system
- Authentication
- HTTPS support

---

## Testing the Stack

### 1. Backend Health Check

```bash
curl http://localhost:8000/api/health
```

Expected response:
```json
{
  "status": "healthy",
  "version": "0.1.0"
}
```

### 2. PM3 Status

```bash
curl http://localhost:8000/api/pm3/status
```

Expected response (with mock):
```json
{
  "connected": true,
  "device": "/dev/ttyACM0",
  "version": null,
  "session_active": false
}
```

### 3. Execute Command

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

# Execute command (replace SESSION_ID)
curl -X POST http://localhost:8000/api/pm3/command \
  -H "Content-Type: application/json" \
  -d '{
    "command": "hw version",
    "session_id": "SESSION_ID"
  }'
```

### 4. SSE Events

```bash
# Connect to SSE stream
curl -N http://localhost:8000/sse/events
```

You should see:
```
event: connected
data: {"message":"Connected to Dangerous Pi event stream"}
```

---

## Using the Web Interface

### Dashboard
- View system status (CPU, memory, disk)
- Check PM3 connection
- Quick action buttons
- Real-time event notifications

### Commands Page
1. Click "Commands" in navigation
2. Enter a PM3 command (e.g., `hw status`)
3. Click "Execute" or press Enter
4. View output in terminal-style display
5. Use ↑/↓ arrow keys to navigate history

**Quick Commands:**
- `hw status` - Hardware status
- `hw version` - Firmware version
- `hf search` - Search for HF tags
- `lf search` - Search for LF tags
- `hw tune` - Tune antenna

### Settings Page
- View current configuration
- Change Wi-Fi mode (planned)
- Enable/disable features
- Restart backend or shutdown system

### Logs Page
- View command history
- See success/failure status
- Export logs (planned)

---

## Development Tips

### Hot Reload

Both backend and frontend support hot reload:

- **Backend**: Uvicorn watches for file changes
- **Frontend**: Vite HMR (Hot Module Replacement)

Edit code and see changes immediately!

### Mock PM3 vs Real PM3

The backend automatically uses `MockPM3Worker` when the `pm3` module is not available.

**Mock responses:**
```python
"hw version" → "Proxmark3 RFID instrument\n  client: RRG/Iceman/master/v4.14831"
"hw status"  → "Device: PM3 GENERIC\nBootrom: master/v4.14831"
"hw tune"    → "Measuring antenna characteristics..."
```

**To use real PM3:**
1. Install Proxmark3 client with Python support
2. Connect PM3 hardware
3. Set `PM3_DEVICE` environment variable
4. Restart backend

### Theme Toggle

Click the theme button (◐ / ○ / ◑) in the header to cycle:
- **Dark** → **Auto** → **Light** → **Dark**

Default is Dark (cyberpunk aesthetic for Dangerous Things).

---

## Project Structure

```
dangerous-pi/
├── app/
│   ├── backend/              # FastAPI backend
│   │   ├── api/              # REST endpoints
│   │   ├── sse/              # SSE events
│   │   ├── workers/          # PM3 worker
│   │   ├── managers/         # Session, updates, etc.
│   │   ├── models/           # Database models
│   │   └── main.py           # Entry point
│   └── frontend/             # Remix.js frontend
│       ├── app/
│       │   ├── routes/       # Page routes
│       │   ├── root.tsx      # Layout
│       │   └── styles.css    # Cyberpunk theme
│       └── package.json
├── data/                     # SQLite database
├── requirements.txt          # Python dependencies
├── test_backend.py           # Backend tests
└── claude.md                 # AI development guide
```

---

## Troubleshooting

### Backend won't start

**Error: Port 8000 already in use**

The existing pi-pm3 uses ttyd on port 8000. Either:
- Change PORT to 8001 in config
- Stop ttyd: `sudo systemctl stop ttyd-bash`

**Error: pm3 module not found**

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

### Frontend won't start

**Error: Cannot connect to backend**

Make sure backend is running on http://localhost:8000

**Error: npm install fails**

Try:
```bash
rm -rf node_modules package-lock.json
npm install
```

### SSE not working

Check browser console for errors. SSE requires:
- Backend running
- Modern browser (no IE11)
- No aggressive ad blockers

---

## Next Steps

1. **Try the interface**: Execute some commands
2. **Explore the code**: See how SSE, workers, and sessions work
3. **Add features**: Wi-Fi manager, updates, backups
4. **Test on Pi**: Transfer code to actual hardware
5. **Customize theme**: Edit `app/frontend/app/styles.css`

---

## Resources

- **Backend**: [README_DEV.md](README_DEV.md)
- **Frontend**: [app/frontend/README.md](app/frontend/README.md)
- **UI Guidelines**: [UI_GUIDELINES.md](UI_GUIDELINES.md)
- **AI Guide**: [claude.md](claude.md)

---

## Support

For issues or questions:
- Check [claude.md](claude.md) for detailed architecture
- Review API docs at http://localhost:8000/docs
- Test with curl before debugging frontend

Built with ❤️ for [Dangerous Things](https://dangerousthings.com)