openFPGALoader GUI by exxos - v1.0.8
=====================================

Program CPLDs and FPGAs using open source tools.
Supports Xilinx Platform Cable USB (DLC9) and many other JTAG cables.

WHY THIS EXISTS
---------------
This project was born out of frustration. I use retro hardware and older
development tools -- including Xilinx ISE 14.7, which is over 15 years old.
Modern software increasingly drops support for older operating systems like
Windows 7, which doesn't help when your entire toolchain depends on them.

I also wanted support for the inexpensive, off-the-shelf Xilinx Platform
Cable USB (DLC9) clones that are widely available online for just a few
pounds. These are cheap and cheerful programmers, but they've always been a
pain to get working -- even Xilinx's own iMPACT needed a fiddly two-stage
firmware loading process. The upstream openFPGALoader project didn't support
them at all: the cable has a quirk where its FX2 microcontroller loads
firmware but doesn't re-enumerate to the expected USB product ID, causing
every open source tool to fail.

Rather than give up, I patched openFPGALoader to handle this cable properly
and wrapped it in a simple GUI that works on Windows 7, Linux and Mac. The
patched version (ofl-exxos) is pinned to a specific upstream commit so that
future changes can never break it. It supports all the standard JTAG cables
that openFPGALoader supports, plus the DLC9 and its siblings.

If you're working with retro hardware, old tools, or cheap programmers that
nobody else bothers to support, I hope this saves you the headaches it
saved me.

WINDOWS (7, 10, 11 - 64 bit)
-----------------------------
1. Extract the "windows" folder anywhere (e.g. C:\ofl-exxos)
2. Run install.bat (creates a desktop shortcut)
3. Double-click "ofl-exxos GUI" on your desktop
4. First time: click "USB Driver" to install the WinUSB driver for your cable
5. Click Detect to scan the JTAG chain

No other software needs to be installed. Everything is self-contained.

LINUX (Debian, Ubuntu, MX Linux)
---------------------------------
1. Extract the "linux" folder anywhere
2. Open a terminal in that folder
3. Run:  bash install-ofl-gui.sh
4. The installer builds everything, creates a menu entry and desktop icon
5. Run "ofl-gui" from the menu or terminal

Needs an internet connection for the first install (downloads build tools).

MAC (macOS 10.13+)
------------------
1. Install Homebrew if not already present (https://brew.sh)
2. Extract the "mac" folder anywhere
3. Open Terminal in that folder
4. Run:  bash build-mac.sh
5. Drag the resulting ofl-exxos-gui.app to /Applications
6. Double-click to run

Needs Xcode command line tools and an internet connection for the first build.

TECHNICAL NOTES
---------------
This project uses a patched build of openFPGALoader
(https://github.com/trabucayre/openFPGALoader), pinned to commit 4c6fb13.
The patch adds support for Xilinx Platform Cable USB models that the upstream
project does not handle (USB IDs 03fd:0007, 0009, 000f, 0015), fixes a
firmware loading issue where DLC9 cables run the firmware but don't
re-enumerate, adds a firmware-already-loaded check to skip reloading, and
adds a verify-only mode that reads the CPLD back without erasing or
programming.

The patched binary is installed as "ofl-exxos" so it never clashes with any
system copy of openFPGALoader. It supports all the same cables and devices
as the upstream project, plus the DLC9 family.

WARNING: Do NOT update openFPGALoader from upstream or replace the ofl-exxos
binary with a newer version. The patches are written for one specific commit
and will break if the upstream code changes. If you need to rebuild, always
use the install script provided (install-ofl-gui.sh or build-mac.sh) which
checks out the correct commit and applies the patch automatically.

DONATE
------
If you find this program useful please consider making a small donation.
It shows your appreciation and helps support continued development.
https://buy.stripe.com/5kQ6oId9F2G88W23QOcAo02

DISCLAIMER
----------
This software is provided "as is", without warranty of any kind, express or
implied, including but not limited to the warranties of merchantability,
fitness for a particular purpose and noninfringement. In no event shall the
author be liable for any claim, damages or other liability, whether in an
action of contract, tort or otherwise, arising from, out of or in connection
with the software or the use or other dealings in the software.

Use entirely at your own risk. This software communicates directly with
hardware via USB and JTAG. Incorrect use, faulty cables, incompatible
firmware, or unexpected hardware behaviour could potentially damage your
programmer, target device, or connected equipment. The author accepts no
responsibility for any damage, data loss, or other consequences resulting
from the use of this software.

Always verify your target device and cable are compatible before programming.
Use the Verify function to confirm contents before relying on a programmed
device.

VERSION HISTORY
---------------
v1.0.8 (2026-10-30)
  - Read button: read CPLD contents and save to file as backup
  - Auto-backup before programming: saves current contents to
    ofl-gui-backups folder, keeps last 3 backups per device
  - About dialog with version, credits and disclaimer

v1.0.7 (2026-10-30)
  - Added About button with version, credits and disclaimer

v1.0.6 (2026-10-30)
  - Find Cable now auto-scans USB, tries all hex files, and auto-detects
    the cable and firmware combination (no manual setup needed)
  - Auto-retry (up to 3 attempts) on first-run timing failures
  - All Xilinx firmware hex files bundled (7 files for all cable variants)
  - Full cable list in dropdown (58 cables, all supported by openFPGALoader)
  - Find Cable auto-populates the device chain (no separate Detect click)
  - Disclaimer added

v1.0.5 (2026-10-30)
  - Initial release
  - Patched openFPGALoader for Xilinx DLC9 cable support (03fd:0007)
  - Linux GUI (Python/Tk) with detect, verify-only, program
  - Windows native GUI (Win32) with built-in WinUSB driver installer
  - macOS build script with .app bundle
  - Firmware-already-loaded detection (instant startup on repeat runs)
  - Multi-device JTAG chain list with per-device JED assignment
  - Donate button (Stripe)
  - Desktop shortcuts on all platforms

Copyright 2026 exxos. All rights reserved.
