gsproremote/backend

GSPro Remote Backend

FastAPI-based backend service for GSPro Remote, providing keyboard control and screen streaming capabilities for GSPro golf simulator.

Features

• Keyboard Control API: Send keyboard shortcuts to GSPro
• Screen Streaming: WebSocket-based map region streaming
• Configuration Management: Persistent settings storage
• mDNS Discovery: Auto-discoverable at gsproapp.local
• Windows Integration: Native Windows input simulation

Requirements

• Python 3.11+
• Windows OS (for GSPro integration)
• GSPro running on the same machine

Installation

Using pip

python -m venv .venv
.venv\Scripts\activate
pip install -e .

Using UV (recommended)

uv venv
uv pip install -e .

Development Setup

1. Install development dependencies:

pip install -e ".[dev]"

2. Run the development server:

uvicorn app.main:app --reload --host 0.0.0.0 --port 5005

API Structure

/api/actions/
  POST /key         - Send single key press
  POST /keydown     - Hold key down
  POST /keyup       - Release key
  POST /combo       - Send key combination

/api/config/
  GET /             - Get current configuration
  PUT /             - Update configuration
  POST /save        - Persist to disk

/api/vision/
  WS /ws/stream     - WebSocket map streaming
  GET /regions      - Get defined screen regions
  POST /capture     - Capture screen region

/api/system/
  GET /health       - Health check
  GET /info         - System information

Configuration

Configuration is stored in %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
  }
}

Project Structure

backend/
  app/
    __init__.py
    main.py           # FastAPI application
    api/
      actions.py      # Keyboard control endpoints
      config.py       # Configuration endpoints
      vision.py       # Screen capture/streaming
      system.py       # System utilities
    core/
      config.py       # Configuration management
      input_ctrl.py   # Windows input simulation
      screen.py       # Screen capture utilities
      mdns.py         # mDNS service registration
    models/
      requests.py     # Pydantic request models
      responses.py    # Pydantic response models
  tests/
    test_*.py         # Unit tests
  pyproject.toml      # Project dependencies

Testing

Run tests with pytest:

pytest

With coverage:

pytest --cov=app --cov-report=html

Building for Distribution

Build standalone executable:

pip install ".[build]"
python -m PyInstaller --onefile --name gspro-remote app/main.py

Environment Variables

• GSPRO_REMOTE_PORT: Override default port (5005)
• GSPRO_REMOTE_HOST: Override default host (0.0.0.0)
• GSPRO_REMOTE_CONFIG_PATH: Override config location
• GSPRO_REMOTE_DEBUG: Enable debug logging

Troubleshooting

GSPro window not found

• Ensure GSPro is running
• Check window title matches configuration
• Run as administrator if permission issues

Port already in use

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

mDNS not working

• Check Windows firewall settings
• Ensure Bonjour service is running
• Try accessing directly via IP instead

License

MIT License - See parent LICENSE file for details