# GSPro Remote - Setup & Run Instructions

## 🚀 Quick Setup Guide

Follow these steps to get GSPro Remote running on your network and accessible from your phone/tablet.

## Prerequisites

1. **Windows PC** with GSPro installed
2. **Python 3.11+** installed ([Download Python](https://www.python.org/downloads/))
3. **Node.js 20+** installed ([Download Node.js](https://nodejs.org/))
4. **Git** (optional, for cloning the repository)

## Step 1: Initial Setup

### Option A: Using PowerShell Script (Recommended)

1. Open PowerShell as Administrator
2. Navigate to the project directory:
   ```powershell
   cd "path\to\GSPro Remote"
   ```
3. Run the development script:
   ```powershell
   .\scripts\dev.ps1
   ```

This script will:
- Check all prerequisites
- Install Python dependencies
- Install Node.js dependencies
- Start both backend and frontend servers
- Open browser windows with the application

### Option B: Manual Setup

#### Backend Setup:
```bash
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -e .
```

#### Frontend Setup:
```bash
cd frontend
npm install
```

## Step 2: Running the Application

### Start Backend Server:
```bash
cd backend
.venv\Scripts\activate
python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 5005
```

The backend will be available at:
- API: `http://localhost:5005`
- API Docs: `http://localhost:5005/api/docs`

### Start Frontend Server:
```bash
cd frontend
npm run dev -- --host
```

The frontend will be available at:
- Local: `http://localhost:5173`
- Network: `http://[YOUR-IP]:5173`

## Step 3: Access from Your Phone/Tablet

### Find Your PC's IP Address

1. Open Command Prompt or PowerShell
2. Run: `ipconfig`
3. Look for your IPv4 Address (e.g., `192.168.1.100`)

### Connect from Mobile Device

1. **Ensure your phone/tablet is on the same WiFi network as your PC**

2. Open a web browser on your mobile device

3. Navigate to one of these URLs:
   - `http://[YOUR-PC-IP]:5173` (e.g., `http://192.168.1.100:5173`)
   - `http://gsproapp.local:5005/ui` (if mDNS is working)

### Install as Mobile App (PWA)

**On iPhone/iPad:**
1. Open Safari (must be Safari)
2. Navigate to the app URL
3. Tap the Share button
4. Scroll down and tap "Add to Home Screen"
5. Name it "GSPro Remote" and tap Add

**On Android:**
1. Open Chrome
2. Navigate to the app URL
3. Tap the menu (3 dots)
4. Tap "Add to Home screen" or "Install app"
5. Follow the prompts

## Step 4: Configure Windows Firewall

If you can't connect from your mobile device, you may need to allow the app through Windows Firewall:

1. Open Windows Defender Firewall
2. Click "Allow an app or feature through Windows Defender Firewall"
3. Click "Change settings" then "Allow another app..."
4. Browse and add:
   - Python.exe (from your Python installation)
   - Node.exe (from your Node.js installation)
5. Check both Private and Public networks
6. Click OK

### Alternative: Create Firewall Rules via PowerShell (Admin)
```powershell
# Allow backend port
New-NetFirewallRule -DisplayName "GSPro Remote Backend" -Direction Inbound -Protocol TCP -LocalPort 5005 -Action Allow

# Allow frontend port
New-NetFirewallRule -DisplayName "GSPro Remote Frontend" -Direction Inbound -Protocol TCP -LocalPort 5173 -Action Allow
```

## Step 5: Start Using GSPro Remote

1. **Start GSPro** on your PC
2. **Open GSPro Remote** on your mobile device
3. The app should show "Connected" status
4. You can now control GSPro from your mobile device!

## 🎮 Using the App

### Main Controls:
- **Aim Pad**: Hold arrows to adjust aim continuously
- **Center Button**: Press to reset aim
- **Club Selection**: Tap up/down to change clubs
- **Mulligan**: Toggle mulligan mode
- **Tee Box**: Move left/right on the tee
- **Map**: Start streaming to see live mini-map
- **Shot Options**: Select different shot types
- **Quick Actions** (+ button): Access additional controls

### Gestures:
- **Hold** directional buttons for continuous movement
- **Tap** for single adjustments
- **Expand Map**: Tap expand button for fullscreen map

## 🔧 Troubleshooting

### Can't connect from phone
- ✅ Check both devices are on the same WiFi network
- ✅ Check Windows Firewall settings
- ✅ Try using IP address instead of hostname
- ✅ Disable VPN if active
- ✅ Make sure backend shows "Server running on 0.0.0.0:5005"

### GSPro not responding to commands
- ✅ Ensure GSPro is running and focused
- ✅ Check GSPro window title matches config (default: "GSPro")
- ✅ Try running backend as Administrator
- ✅ Check backend console for errors

### Map streaming not working
- ✅ Click "Start Streaming" button in map panel
- ✅ Check backend console for WebSocket connection
- ✅ Verify GSPro is on the main game screen
- ✅ Adjust map region in settings if needed

### Poor performance on mobile
- ✅ Reduce stream quality in settings
- ✅ Lower FPS to 15-20
- ✅ Use 5GHz WiFi if available
- ✅ Move closer to WiFi router

## 📱 Mobile-Specific Tips

### For Best Experience:
1. **Lock screen orientation** to prevent rotation while playing
2. **Enable "Add to Home Screen"** for full-screen experience
3. **Disable browser gestures** if they interfere
4. **Use landscape mode** on tablets for optimal layout
5. **Keep screen awake** during gameplay

### Battery Optimization:
- Lower stream quality to "Low" or "Medium"
- Reduce FPS to 15-20
- Disable haptic feedback if not needed
- Dim screen brightness when possible

## 🔒 Security Notes

- The app only works on your local network
- No data is sent to external servers
- All communication is between your PC and mobile device
- Consider using a dedicated WiFi network for gaming

## 🆘 Getting Help

### Check Status:
1. Backend health: `http://localhost:5005/api/system/health`
2. API docs: `http://localhost:5005/api/docs`
3. System info: `http://localhost:5005/api/system/info`
4. Diagnostics: `http://localhost:5005/api/system/diagnostics`

### View Logs:
- Backend logs appear in the terminal where you started the server
- Frontend logs appear in the browser console (F12)

### Common Commands:
```bash
# Check if ports are in use
netstat -an | findstr :5005
netstat -an | findstr :5173

# Check Python version
python --version

# Check Node version
node --version

# Check network interfaces
ipconfig /all

# Test backend directly
curl http://localhost:5005/api/system/health
```

## 🎯 Production Deployment

For permanent installation:

1. **Build the frontend**:
   ```bash
   cd frontend
   npm run build
   ```

2. **Configure backend to serve UI**:
   - Frontend will be built to `backend/ui`
   - Access complete app at `http://gsproapp.local:5005`

3. **Create Windows Service** (optional):
   - Use NSSM or similar to run backend as service
   - Auto-starts with Windows
   - Runs in background

4. **Configure auto-start**:
   - Add to Windows startup folder
   - Or use Task Scheduler

---

**Enjoy controlling GSPro from anywhere in your simulator room!** 🏌️‍♂️