# 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

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

### Using UV (recommended)

```bash
uv venv
uv pip install -e .
```

## Development Setup

1. Install development dependencies:
```bash
pip install -e ".[dev]"
```

2. Run the development server:
```bash
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:
```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
  }
}
```

## 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:
```bash
pytest
```

With coverage:
```bash
pytest --cov=app --cov-report=html
```

## Building for Distribution

Build standalone executable:
```bash
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