Initial commit: GSPro Remote MVP - Phase 1 complete

2025-11-13 15:38:58 -06:00 · 2025-11-13 15:38:58 -06:00 · 74ca4b38eb
commit 74ca4b38eb
50 changed files with 12818 additions and 0 deletions
--- a/backend/README.md
+++ b/backend/README.md
@ -0,0 +1,167 @@
+# 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