AOG Connector - Farming Simulator 25 / AgOpenGPS
========================================================

REQUIREMENTS
- Windows 64-bit PC running Farming Simulator 25. Single-player only.
- Python Windows 64-bit installer, including the Python launcher (py)
  and pip. Python 3.12 is the supported/tested baseline, not a claim that
  all other Python versions are incompatible.
  Official downloads: https://www.python.org/downloads/windows/
- AgOpenGPS and AgIO, installed separately:
  https://github.com/AgOpenGPS-Official/AgOpenGPS/releases
- Internet access for first-time bridge setup (downloads pywin32==312).
  Python, AgOpenGPS, FS25 and other mods are NOT bundled.
- The bridge MUST run on the FS25 PC. AgIO can run there or on another
  Windows PC/tablet on the same trusted local network.

INSTALL (ONCE PER EXTRACTED RELEASE)
1. Extract AOGConnector-xxx.zip to a writable folder on your PC.
   Do not run the scripts from inside the ZIP viewer.
2. Close FS25. Copy the INNER FS25_AOGConnector.zip into your FS25 mods
   folder. KEEP THIS INNER ZIP CLOSED; do not extract or rename it.
   The usual folder is:
   C:\Users\<your-user>\Documents\My Games\FarmingSimulator2025\mods
   If Documents is redirected to OneDrive or your game uses a custom
   profile/mods directory, use that actual location instead.
   Remove old AOGConnector folders/ZIPs so only one copy is installed.
3. Double-click Setup.cmd. It creates a local .venv and installs pywin32;
   it does not change your system-wide Python packages. Wait for
   "Setup complete" before continuing. No administrator rights normally
   needed. Keep the companion folder and launchers together.
4. Start FS25, select your single-player save, and enable "AOG Connector"
   in its mod selection. Back up your save before experimenting.

PLAY
1. Start AgOpenGPS/AgIO. Use its UDP GPS/module connection rather than
   simulator GPS or a physical serial GPS. Scan for modules in AgIO;
   the bridge emulates GPS, autosteer and IMU traffic. Exact menus vary
   by AgOpenGPS version; follow its documentation for vehicle/tool setup.
2. Run Start-Bridge.cmd on the FS25 PC. Leave its window open.
3. Load your enabled save and enter a drivable vehicle. Allow a few
   seconds for the pipe connection. The bridge should report
   "Connected. Forwarding to AgIO" and "Connected to FS25 command buffer".
4. Confirm position/speed/heading reach AgOpenGPS before trying guidance.
   Create a test field and guidance line in AgOpenGPS, configure your
   simulated vehicle, and only then engage autosteer at low speed.
5. Disengage guidance when finished. Focus the bridge window and press Q
   to stop it. Restart the bridge after restarting FS25/loading a new save
   if the process-memory connection does not recover.

NETWORK
- It is STRONGLY recommended to use ethernet rather than wifi if using
  agOpenGPS on a separate computer/tablet. Wifi is very laggy
- Allow Python and AgIO through Windows Firewall on your trusted private
  network only. Do not disable the firewall or expose ports to the Internet.
- The bridge sends UDP to AgIO port 9999 and listens on UDP port 8888 for
  AgIO steering/module messages. Allow inbound 8888 on the game PC and
  inbound 9999 on the AgIO PC, plus the corresponding outbound traffic.
- Broadcast is the default. If needed, open Command Prompt in the extracted
  release folder and target AgIO explicitly (replace the example address):
    set AOG_AGIO_HOST=192.168.1.50
    Start-Bridge.cmd
  For AgIO on the same PC, try 127.0.0.1. This setting only changes the
  bridge's destination; AgIO must also be configured to send module traffic
  back to the game PC. Guest Wi-Fi/client isolation can block communication.
- Disconnect real autosteer/GPS hardware while using the simulator bridge.
  Its broadcast packets emulate real modules.

TROUBLESHOOTING / LIMITATIONS
- "py" not found: install Python x64 including its launcher. Re-run Setup.
- Missing win32 modules: run Setup.cmd again; always use Start-Bridge.cmd.
- No mod in FS25: check you copied the inner ZIP (modDesc.xml must be at
  its root), the actual mods folder, and the save's enabled-mod selection.
- "Waiting for FS25" or "buffer unavailable" before a save loads is normal.
  If it persists, check the mod is enabled and inspect log.txt beside the
  FS25 mods folder for AOGTelemetry/pipe errors. Run only one bridge.
- Access denied to game memory: run the game and bridge under the same
  Windows user/elevation; prefer both non-administrator. Do not disable
  security software. The bridge reads/writes the game's marked command
  buffer; security tools may flag this experimental behavior.
- Port 8888 already in use: close duplicate bridges or conflicting apps.
- Connected but no GPS/modules: check AgIO UDP configuration, firewall,
  correct network adapter/IP, and that simulator GPS is disabled.
- Experimental steering: process-memory access and wheel-angle assumptions
  may behave differently across game updates/vehicles. GPS coordinates are
  synthetic, not georeferenced to the real world. No specific AgOpenGPS
  version compatibility or in-game accuracy is guaranteed by CI tests.
- Multiplayer, consoles and non-Windows bridge hosts are not supported.
- To upgrade, stop the bridge and FS25, extract the new release into a new
  folder, replace the mod ZIP and run the new Setup.cmd. To uninstall, stop
  both programs, remove the mod ZIP, and delete the extracted release folder.

OPTIONAL DOWNLOAD CHECK
Download SHA256SUMS.txt beside the ZIP on the download page. In PowerShell:
  Get-FileHash .\AOGConnector-xxx.zip -Algorithm SHA256
Compare its hash with SHA256SUMS.txt before extracting.