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:

git clone https://github.com/yourusername/gspro-remote.git
cd gspro-remote

2. Run the development setup:

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

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

cd frontend
npm install
npm run dev

Running Tests

Backend:

cd backend
pytest

Frontend:

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

{
  "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