This page documents how to update the firmware for FPGA1394 Rev 1.x and Rev 2.x, which both use the Xilinx Spartan 6 FPGA. The firmware must actually be written to the M25P16 Configuration PROM on those boards, as documented on this page.

For FPGA1394 Rev 3.x, the firmware is stored on the MicroSD card, so it is only necessary to update the files on this card. The rest of this page can be ignored.

If your FPGA board has already been programmed, you can reprogram it via the Firewire interface (or the Ethernet interface, if the FPGA has Rev 7+ firmware). This provides the following benefits:

• No special cable is needed
• It is much faster than the Xilinx programmer
• If you have the hex file (MCS file), then you don't even need the Xilinx ISE software and you can ignore the rest of this page
• Download the current firmware version from GitHub mechatronics-firmware Releases. Note that you only need the file FPGA1394V1-QLA.mcs (for Rev 1.x boards) or the file FPGA1394V2-QLA.mcs (for Rev 2.x boards, with Ethernet connector).

To do this, use the pgm1394 program and run it as follows:

  pgm1394 <board-id> [<mcs-file>] [-pP]

where board-id is the board ID switch setting (0-15), mcs-file is the name of the MCS file containing the FPGA firmware (the software chooses the correct default, either FPGA1394V1-QLA.mcs or FPGA1394V2-QLA.mcs, depending on which FPGA version is detected; do not specify the mcs file unless you need to force a specific firmware type), and P is the port number (default is FireWire port 0) or port name (e.g., fw0 or udp). For backward compatibility, if FPGA1394V1-QLA.mcs and/or FPGA1394V2-QLA.mcs are not found, the system will search for FPGA1394-QLA.mcs and/or FPGA1394Eth-QLA.mcs (i.e., the file names for Firmware Rev 1-7).

Note: pgm1394 is compiled along the dVRK software and should be in your path if you're using ROS with catkin build and have properly source the devel/setup.bash file. If you are not using the full dVRK stack, pgm1394 can be found under mechatronics-software/programmer/.

Before you get started, we strongly recommend to disconnect the FireWire cables from all controllers except the one you plan to upgrade. Then check that you see the two FireWire nodes for the controller (1 for the SUJ controller) using ls /dev/fw*. You should see fw0, fw1 and fw2. To identify the board IDs in the controller you're about to upgrade, start qladisp without any command line option. Please note the two board IDs. You will then sequentially upgrade the firmware on the boards without powering the controller in between. Power cycle the controller only after both FPGA boards have been upgraded.

Finally, make sure you're using the latest software to program your boards; the program pgm1394 will display the version of the library it is built against, it should be at least 1.3.0, but 1.6.0 (or later) is recommended.

Detailed Steps:

# Download latest released firmware (or, for an older release, choose appropriate files)
cd ~/Downloads 
 
wget https://github.com/jhu-cisst/mechatronics-firmware/releases/latest/download/FPGA1394V1-QLA.mcs
wget https://github.com/jhu-cisst/mechatronics-firmware/releases/latest/download/FPGA1394V2-QLA.mcs

# Program firmware (for board 0)
# Do not specify the MCS file!  pgm1394 will automatically detect which one to use
# The 0 should be replaced by the board ID you plan to upgrade
pgm1394 0

# 1 - press 1 to program firmware
# 2 - press 2 to verify firmware

If this is the first board, don't forget to run pgm1394 with the second board ID so both boards in the controller are updated. Once you've programmed the second board in the controller, power-cycle the controller. You can now use qladisp to verify firmware version on both boards.

NOTE: The last step is important; if you do not power-cycle (or reboot) the board, you will still read the old firmware version in qladisp.

NOTE: If the board id is reported incorrectly after programming, it means that you somehow programmed the wrong firmware image (i.e., programmed V1.x firmware on a V2.x board or V2.x firmware on a V1.x board). The V1.x and V2.x boards have different bit orderings for the board-id switch; the easiest solution is to set the switch to 0 (which is 0 regardless of the bit order) and then program the correct firmware version.

NOTE: Once the FPGA has Firmware Rev 7+, pgm1394 will display an option (8) to reboot and exit. If you use this option, wait for the FPGA to reboot, then unplug and replug the Firewire cable before proceeding to program the next FPGA board.

Everything below is for experienced FPGA programmers. If you're an end user you can skip this altogether, unless you ran into a problem with the end user method above and need to use the JTAG interface to recover.

The boards can always be programmed via the JTAG interface, which requires the following hardware and software:

1. A JTAG programming cable, with standard Xilinx JTAG 14-pin 2mm connector
   • Digilent JTAG-HS3 (recommended)
   • Digilent XUP-USB-JTAG -- a bit older and more expensive
2. A computer with JTAG programming software
   • Xilinx Vivado (recommended) -- you can install the full Vivado software (Vivado ML Edition), or just the Vivado Lab Edition, which is "a compact, and standalone product targeted for use in the lab environments ... [that] requires no certificate or activation license key"
   • Xilinx ISE WebPACK tool (free) -- this is the older generation of Xilinx tools
   • OpenOCD (open source) -- binaries are available for Linux, Mac OS and Windows
     • Ubuntu: sudo apt install openocd
   • Digilent Adept2 Software (free) -- CMD/GUI tools that are available for Linux and Windows

The firmware files can be found in the GitHub mechatronics-firmware Releases. For this programming procedure, you should download the appropriate .bit and .mcs files:

• FPGA1394V1-QLA.* for FPGA V1 (no Ethernet connector), formerly called FPGA1394-QLA.*
• FPGA1394V2-QLA.* for FPGA V2 (one Ethernet connector), formerly called FPGA1394Eth-QLA.*

Steps to program board:

1. Download .bit and .mcs files (see above)
2. Connect the JTAG programming cable between your PC and the FPGA board
3. Connect a FireWire or Ethernet cable from your PC to the FPGA board
4. Apply power to the FPGA board
5. Use your JTAG programming software to program the FPGA using the .bit file
   • For Xilinx Vivado, choose "Open Hardware Manager", followed by "Open target", "Auto Connect"
6. Once the FPGA is programmed, do not turn off power; you should be able to access it via FireWire or Ethernet (there is no need to remove the JTAG cable)
7. On the PC, run pgm1394 specifying the FPGA board id (rotary switch on board), as described above for end users; this will use the .mcs file that you downloaded
8. If programming successful, remove power from FPGA board and remove JTAG cable