Quick start
Examples on how to go from scratch to the Blinky LED on different FPGA boards in a few minutes!
- Install the dependencies
sudo apt install python3 python3-pip
Apio needs Python 3.9 or Higher. Check the python version:
$ python3 --version
Python 3.10.12
- Install apio:
sudo pip3 install -U apio
- Install all the available apio packages
apio install -a
- Enable the drivers for this board:
apio drivers --ftdi-enable
- Download the Blinky example for the Alhambra-II FPGA board:
apio examples -d Alhambra-II/Blinky
- Enter the example folder
cd Alhambra-II/Blinky
- Synthesize and upload the bitstream to the board
apio upload
The LED7 is blinking!!
- Enable the drivers for this board:
apio drivers --ftdi-enable
- Download the Blinky example for the NandLand Go-Board FPGA board:
apio examples -d go-board/Blinky
- Enter the example folder
cd go-board/Blinky/
- Synthesize and upload the bitstream to the board
apio upload
The LED1 is blinking!!
- Enable the drivers for this board:
apio drivers --serial-enable
- Give permission for accessing the serial port. Execute these two commands:
sudo usermod -a -G dialout $USER
exec su -l $USER
- Install the tinyprog programmer. It is a python application that can be installed with pip (an apio package is not necesary)
sudo pip3 install tinyprog
- Connect the board to USB port, turn it into bootloader mode, and check whether it is being detected as an USB device with VID:PID equal to 1d50:6130. There are boards that report different identifiers (e.g. 1209:2100). If you have this case with your board, update the bootloader with:
tinyprog --update-bootloader
- Download the Blinky example for the TinyFPGA-BX board:
apio examples -d TinyFPGA-BX/Blinky
- Enter the example folder
cd TinyFPGA-BX/Blinky/
-
Make sure the Board is in boot mode: Press the Button. The LED will be flashing
-
Synthesize and upload the bitstream to the board
apio upload
The LED is blinking!! It is blinking in a different way than previously when it was in the boot mode
- Enable the drivers for this board:
apio drivers --ftdi-enable
- Download the Blinky example for the IceBreaker FPGA board:
apio examples -d iCEBreaker/Blinky/
- Enter the example folder
cd iCEBreaker/Blinky/
- Synthesize and upload the bitstream to the board
apio upload
The LED G (Green) is blinking!!
- Enable the drivers for this board:
apio drivers --serial-enable
- Give permission for accessing the serial port. Execute these two commands:
sudo usermod -a -G dialout $USER
exec su -l $USER
- Install the blackiceprog programmer. It is a python application that can be installed with pip (an apio package is not necesary)
sudo pip3 install blackiceprog
- Download the Blinky example for the Mystorm Blackice board:
apio examples -d blackice/Blinky
- Enter the example folder
cd blackice/Blinky/
- Synthesize and upload the bitstream to the board
apio upload
The blue LED (LED1) is blinking!!
-
Note: This example is for ULX3S-12F. Nevertheless all these steps can be applied to the other models just by changing the 12F sufix for 85F or 45F
-
Enable the drivers for this board:
apio drivers --ftdi-enable
- Download the Blinky example for the ULX3S-12F FPGA board:
apio examples -d ulx3s-12f/Blinky
- Enter the example folder
cd ulx3s-12f/Blinky
- Synthesize and upload the bitstream to the board
apio upload
The LED7 (Blue) is blinking!!
- Enable the drivers for this board:
apio drivers --ftdi-enable
- Download the Blinky example for the fomu FPGA board:
apio examples -d fomu/Blinky
- Enter the example folder
cd fomu/Blinky
- Check that the fomu is in booloader mode
When the fomu is connected the first time, it is in boot mode. The RBG led will fade in and out, in a cyan color
- Synthesize and upload the bitstream to the board
apio upload
The RGB LED should be changing its color!!
- Enable the drivers for this board:
apio drivers --ftdi-enable
- Download the Blinky example for the iCESugar 1.5 FPGA board:
apio examples -d iCESugar_1_5/Blinky
- Enter the example folder
cd iCESugar_1_5/Blinky
- Synthesize and upload the bitstream to the board
apio upload
The RGB LED should be changing its color!!
- Install python3.9 or higher from here: https://www.python.org/downloads/. Download the installer, execute it. Check the Add Python 3.9 to PATH checkbox. Click on Install Now
- Open the command prompt
All the following commands should be typed in the windows command prompt:
- Install apio:
pip install apio
- Install all the available apio packages
apio install -a
-
Plug the Alhambra-II board to the PC
-
Install the drivers for this board. Execute this command as an Administrator
apio drivers --ftdi-enable
It will execute the Zadig driver installation. Select the Alhambra-II-(Interface 0) option on the top and then click on Replace Driver
When finished close the Zadig Windows
-
Unplug the Alhambra II board and Plug it again
-
Download the Blinky example for the Alhambra-II FPGA board:
apio examples -d Alhambra-II/Blinky
- Enter the example folder
cd Alhambra-II/Blinky
- Synthesize and upload the bitstream to the board
apio upload
The LED7 is blinking!!
- Enable the drivers for this board:
apio drivers --ftdi-enable
It will execute the Zadig driver installation. Select the RS232-HS(Interface 0) option on the top. Select the libusbK driver and then click on Replace Driver
When finished close the Zadig Windows
-
Unplug the NandLand Go-board and Plug it again
-
Download the Blinky example for the NandLand Go-Board FPGA board:
apio examples -d go-board/Blinky
- Enter the example folder
cd go-board/Blinky/
- Synthesize and upload the bitstream to the board
apio upload
The LED1 is blinking!!
- Enable the drivers for this board:
apio drivers --serial-enable
It will execute the application for installing the drivers. Once it is done, just click on the Done button. It is very likely that the drivers have been already installed by windows when the board was plugged
- Check that the drivers are ok. Execute this command:
apio system --lsserial
You should get an output similar to this (the COM3 may vary):
Number of Serial devices found: [{'port': 'COM3', 'description': 'Dispositivo serie USB (COM3)', 'hwid': 'USB VID:PID=1D50:6130 SER= LOCATION=1-1'}]
COM3
Description: Dispositivo serie USB (COM3)
Hardware info: USB VID:PID=1D50:6130 SER= LOCATION=1-1
- Install the tinyprog programmer. It is a python application that can be installed with pip (an apio package is not necesary)
pip install tinyprog
- Download the Blinky example for the TinyFPGA-BX board:
apio examples -d TinyFPGA-BX/Blinky
- Enter the example folder
cd TinyFPGA-BX/Blinky/
-
Make sure the Board is in boot mode: Press the Button. The LED will be flashing
-
Synthesize and upload the bitstream to the board
apio upload
The LED is blinking!! It is blinking in a different way than previously when it was in the boot mode
-
Plug the IceBreaker board to the PC
-
Install the drivers for this board:
apio drivers --ftdi-enable
It will execute the Zadig driver installation. Select the icebreaker-(Interface 0) option on the top and then click on Replace Driver
When finished close the Zadig Windows
-
Unplug the Icebreaker board and Plug it again
-
Download the Blinky example for the icebreaker FPGA board:
apio examples -d iCEBreaker\Blinky
- Enter the example folder
cd iCEBreaker\Blinky
- Synthesize and upload the bitstream to the board
apio upload
The LED G (Green) is blinking!!
The LED7 is blinking!!
- Enable the drivers for this board: Connect the board and execute this command
apio drivers --serial-enable
It will execute the application for installing the drivers. Once it is done, just click on the Done button. It is very likely that the drivers have been already installed by windows when the board was plugged
- Check that the drivers are ok. Execute this command:
apio system --lsserial
You should get an output similar to this (the COM5 may vary):
Number of Serial devices found: [{'port': 'COM5', 'description': 'Dispositivo serie USB (COM5)', 'hwid': 'USB VID:PID=0483:5740 SER=00000000001A LOCATION=1-1'}]
COM5
Description: Dispositivo serie USB (COM5)
Hardware info: USB VID:PID=0483:5740 SER=00000000001A LOCATION=1-1
- Install the blackiceprog programmer
pip install -U apio[blackiceprog]
- Download the Blinky example for the Mystorm Blackice board:
apio examples -d blackice/Blinky
- Enter the example folder
cd blackice/Blinky/
- Synthesize and upload the bitstream to the board
apio upload
The blue LED (LED1) is blinking!!
-
Note: This example is for ULX3S-12F. Nevertheless all these steps can be applied to the other models just by changing the 12F sufix for 85F or 45F
-
Enable the drivers for this board:
apio drivers --serial-enable
It will execute the application for installing the drivers. Once it is done, just click on the Done button. It is very likely that the drivers have been already installed by windows when the board was plugged
- Check that the drivers are ok. Execute this command:
apio system --lsserial
You should get an output similar to this (the COMx number may vary):
Number of Serial devices found: [{'port': 'COM12', 'description': 'USB Serial Port (COM12)', 'hwid': 'USB VID:PID=0403:6015 SER=K00102A'}]
COM12
Description: USB Serial Port (COM12)
Hardware info: USB VID:PID=0403:6015 SER=K00102A
- Download the Blinky example for the ULX3S-12F board:
apio examples -d ulx3s-12f\blinky
- Enter the example folder
cd ulx3s-12f\blinky
- Synthesize and upload the bitstream to the board
apio upload
The blue LED (LED7) is blinking!!
NOTE: If you get the error Cannot find JTAG cable, please check this troubleshooting section for ulx3s on Windows 10
- You do not need to install any driver if you are in Windows 10 or later. For checking that the board is detected, plug it and execute this command:
apio raw "dfu-util -l"
- Download the Blinky example for the fomu FPGA board:
apio examples -d fomu/Blinky
- Enter the example folder
cd fomu/Blinky
- Synthesize and upload the bitstream to the board
apio upload
The RGB LED should be blinking!!
- Install homebrew. Just open the macOS Terminal and paste this command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"
- Check that homebrew has been correctly installed. Type this command:
% brew --version
Homebrew 2.5.11
- Install python3. Execute the following commands:
(You need python 3.9 or Higher!)
% brew update
and
% brew install python
- Check that you have python3 and pip3 installed. Open a terminal and execute the following commands:
% python3 --version
Python 3.8.2
% pip3 --version
pip 19.2.3 from /Library/Developer/CommandLineTools/Library/Frameworks/Python3.framework/Versions/3.8/lib/python3.8/site-packages/pip (python 3.8)
- Install apio:
sudo pip3 install apio
- Install all the available apio packages
apio install -a
- Enable the drivers for this board:
apio drivers --ftdi-enable
- Download the Blinky example for the Alhambra-II FPGA board:
apio examples -d Alhambra-II/Blinky
- Enter the example folder
cd Alhambra-II/Blinky
- Synthesize and upload the bitstream to the board
apio upload
The LED7 is blinking!!
- icesugar (Windows/Mac)
- fomu
- icestick
- icezum Alhambra
- Lattice HX8k Breakout board
- Lattice UP5K Breakout board
- Operating System: MACos
Once apio is installed, the workflow is rather easy:
- Edit the verilog files using your favorite IDE
- Synthesize and upload the bitstream just by executing the command:
apio upload
- Error message:
WinError 740 - The requested operation requires elevation
- Solution:
You have to run the command apio drivers --ftdi-enable as an Administrator. The windows command line (cmd) is executed as a normal user (no privileges). In order to execute it as an administrator search for "cmd" and click on the "Run as Administrator" area. The you can run the command with no errors
- Error messages:
Cannot find JTAG cable
scons: *** [upload] Error 1
- Solution:
If you have been using another FPGA board with apio it is likely that you already have installed the libusbK drivers. In order to make ulx3s works in Windows with apio, you should uninstall that driver and uses the standard ftdi drivers that windows 10 install by default. Follow these steps:
- Uninstall the libusbK driver. Follow the instructions given on this link: https://github.com/kost/fujprog#change-ulx3s-driver-to-ftdi
- Unplug the ulx3s board, for 30 seconds
- Plug it again. Windows 10 will install automatically the standar FTDI driver
- Thanks to Antonio Pascual for his help on testing apio in MacOS
- Thanks to Sergio Cuenta for the Troubleshooting for the ULX3S board
- Thanks to Wm (FPGAwars group thread)
