errors · flashopenFPGALoader, when you program the board

ERROR [board-not-found]: board not found by openFPGALoader: it could not open the Basys3 USB interface. Fix: check power and the PROG data cable; if macOS lists the Digilent device, check whether this process can access USB. A failed open does not prove the board is unplugged.

The build went through, then dewfpga flash (or make flash) stops with these lines. The build produced a bitstream, but programming did not complete. This message alone does not tell whether macOS can see the board.

unable to open ftdi device: -3 (device not found)
JTAG init failed with: unable to open ftdi device
ERROR [board-not-found]: board not found by openFPGALoader: it could not open the Basys3 USB interface. Fix: check power and the PROG data cable; if macOS lists the Digilent device, check whether this process can access USB. A failed open does not prove the board is unplugged. https://nosey-dewdrop.github.io/dewfpga/errors/board-not-found/

Why does it happen?

openFPGALoader talks to the FTDI chip on the Basys3 over USB. device not found describes what the programmer could access. The board may be disconnected, or macOS may list it while the programmer cannot enumerate or open USB devices. A restricted execution environment can produce this difference; rebuilding the HDL does not fix USB access.

What is the fix?

First check whether macOS lists the Digilent device. If it does not, inspect these physical connections:

  1. The power switch. It is next to the PROG port, top left of the board. It has to be ON; the red power LED lights.
  2. The PROG port, not the USB host port. The micro-USB socket next to the power switch. The full-size USB-A socket on the board is for a keyboard or a mouse, and programming through it does nothing.
  3. The cable carries data. Some micro-USB cables are charge-only. If the power LED lights but the Mac still sees nothing, try another cable.
  4. The adapter or hub. Apple Silicon MacBooks have USB-C only, so the cable goes through a USB-C to USB-A adapter or a hub. Plug the adapter directly into the Mac; a hub that is itself unpowered can drop the board.
  5. The JP2 jumper. It selects where the board takes power from and has to sit on USB. On a board that has been used with an external supply it may sit on EXT.

To see whether the Mac has the board at all, before blaming the tools:

system_profiler SPUSBDataType | grep -A 4 -i "digilent\|ftdi\|basys"

If no matching device is listed, check the connection. If macOS lists Digilent but openFPGALoader --scan-usb sees no devices, investigate USB access in the environment running the programmer. Do not infer that the cable is faulty or reinstall the toolchain from this message alone. Physical connection, programmer access, successful programming and correct circuit behavior are separate checks.

The design lives in the FPGA's SRAM, so after a power cycle the board is blank again and you flash once more; that is normal, not this error.

Section 2 of the guide: How do you install it in one line?

Which command prints it?