gsproremote/README.md

# GSPro Remote

A companion application for GSPro golf simulator that allows remote control from any device on your network.

## 🎯 Overview

GSPro Remote is a web-based remote control application for GSPro golf simulator running on Windows. Control GSPro from your tablet, phone, or another PC without needing a keyboard nearby.

### Key Features

- **Touch-Friendly Interface** - Optimized for tablets and phones
- **All GSPro Shortcuts** - Full keyboard shortcut support via touch controls
- **Live Map Streaming** - Real-time streaming of the GSPro mini-map
- **mDNS Discovery** - Access via `gsproapp.local` on your network
- **Persistent Settings** - Configuration saved between sessions
- **Zero Cloud Dependencies** - Everything runs locally on your network

## 🚀 Quick Start

### Prerequisites

- Windows PC running GSPro
- Python 3.11+
- Node.js 20+
- GSPro golf simulator

### Installation

1. Clone the repository:
```bash
git clone https://github.com/yourusername/gspro-remote.git
cd gspro-remote
```

2. Run the development setup:
```powershell
.\scripts\dev.ps1
```

This will:
- Install all backend dependencies
- Install all frontend dependencies
- Start both development servers
- Open the UI at http://localhost:5173

### Access Points

- **Frontend UI**: http://localhost:5173
- **Backend API**: http://localhost:5005
- **API Documentation**: http://localhost:5005/api/docs
- **mDNS Access**: http://gsproapp.local:5005

## 📁 Project Structure

```
gspro-remote/
├── backend/                 # Python FastAPI backend
│   ├── app/
│   │   ├── api/            # API endpoints
│   │   │   ├── actions.py  # Keyboard control
│   │   │   ├── vision.py   # Screen streaming
│   │   │   ├── config.py   # Configuration
│   │   │   └── system.py   # System utilities
│   │   ├── core/           # Core functionality
│   │   │   ├── config.py   # Config management
│   │   │   ├── input_ctrl.py # Windows input
│   │   │   ├── screen.py   # Screen capture
│   │   │   └── mdns.py     # mDNS service
│   │   └── main.py         # FastAPI app
│   └── pyproject.toml      # Python dependencies
│
├── frontend/               # React TypeScript frontend
│   ├── src/
│   │   ├── pages/         # Page components
│   │   ├── components/    # UI components
│   │   ├── api/          # API client
│   │   ├── stores/       # State management
│   │   └── App.tsx       # Main app
│   └── package.json      # Node dependencies
│
├── scripts/              # Development scripts
│   └── dev.ps1          # Windows dev script
│
└── PRD.md              # Product requirements
```

## 🎮 Features

### Phase 1 (MVP) - Current
- ✅ Directional pad for aim control
- ✅ Club selection (up/down)
- ✅ Mulligan button
- ✅ Tee box navigation
- ✅ Map panel with streaming
- ✅ All GSPro keyboard shortcuts
- ✅ WebSocket-based streaming
- ✅ Configuration persistence
- ✅ mDNS service discovery

### Phase 2 (Planned)
- ⏳ OCR-based auto-detection
- ⏳ Visual marker tracking
- ⏳ Background monitoring
- ⏳ Advanced automation

### Phase 3 (Future)
- ⏳ Enhanced UI/UX
- ⏳ Subscription features
- ⏳ Extended documentation

## 🛠️ Development

### Backend Development

```bash
cd backend
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
uvicorn app.main:app --reload --host 0.0.0.0 --port 5005
```

### Frontend Development

```bash
cd frontend
npm install
npm run dev
```

### Running Tests

Backend:
```bash
cd backend
pytest
```

Frontend:
```bash
cd frontend
npm test
```

## 📖 API Documentation

The backend provides a comprehensive REST API with WebSocket support for streaming.

### Key Endpoints

- `POST /api/actions/key` - Send keyboard input to GSPro
- `WS /api/vision/ws/stream` - WebSocket for map streaming
- `GET /api/config` - Get current configuration
- `GET /api/system/health` - Health check

Full API documentation available at http://localhost:5005/api/docs when running.

## 🔧 Configuration

Configuration is stored at `%LOCALAPPDATA%\GSPro Remote\config.json`

### Default Configuration

```json
{
  "server": {
    "host": "0.0.0.0",
    "port": 5005,
    "mdns_enabled": true
  },
  "capture": {
    "fps": 30,
    "quality": 85,
    "resolution": "720p"
  },
  "gspro": {
    "window_title": "GSPro",
    "auto_focus": true
  }
}
```

## 🐛 Troubleshooting

### GSPro Window Not Found
- Ensure GSPro is running
- Check window title in configuration
- Run backend as administrator if needed

### Connection Issues
- Verify both frontend and backend are running
- Check Windows firewall settings
- Ensure devices are on same network

### Port Already in Use
- Check if another instance is running
- Change port in configuration
- Use `netstat -an | findstr :5005` to check

## 📝 License

MIT License - See LICENSE file for details

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📞 Support

For issues and questions:
- Create an issue on GitHub
- Check existing issues for solutions