Getting Started

The TinyFPGA BX boards use Lattice Semiconductor’s iCE40 FPGAs. There are a number of existing software and hardware tools available as well as documentation from Lattice for these FPGAs. This guide will help get you started with the BX board, the tools, and documentation available for the FPGA chips themselves.

Hardware

For this guide you will need a TinyFPGA BX board and a micro USB cable.

Software

You will need to install the latest development environment and other support tools for the iCE40 FPGAs and the BX board. The TinyFPGA BX is supported by open source tools. These instructions should work for all platforms.

1. Install Python

Tools for the TinyFPGA BX require Python. If you don’t already have Python installed, follow the directions below. Linux users should already have Python installed.

Linux

Most Linux distributions install Python by default. If not, install Python using your distribution’s package manager.

Windows

  1. Download and run the Windows Python Installer.
  2. Important: Check the “Add Python 3.6 to PATH” checkbox.
  3. Click on “Install Now”
  4. When Python has finished installing, click “Close”.

MacOS

  1. Download and run the MacOS Python Installer.
  2. Follow the instructions from the installer.

2. Install APIO and tinyprog

APIO is tool that makes it very easy to run the open source FPGA toolchain and program the design onto the FPGA board.

To install APIO and tinyprog, open up a terminal and run the following commands:

pip install apio==0.4.0b5 tinyprog
apio install system scons icestorm iverilog
apio drivers --serial-enable

These commands install APIO, tinyprog, as well as all of the necessary tools to actually program the FPGA.

On Unix systems, you may need to add yourself to the dialout group in order for your user to be able to access serial ports. You can do that by running:

sudo usermod -a -G dialout $USER

Connect your TinyFPGA BX board(s) and make sure the bootloader is up to date by running the following command:

tinyprog --update-bootloader

This command will check for bootloader updates for all of the connected boards. This is important to do to ensure your boards have the latest bootloaders with any known bugs fixed.

3. Download and install Atom.

Atom is an open source text editor and IDE that is very extensible. The authors of APIO have created the APIO-IDE plugin that enables APIO to be used from within Atom.

  1. Download and run the Atom Installer. When the installer finishes it should launch Atom.
  2. Go to “File” and click on “Settings”.
  3. Click on the “Install” tab.
  4. Type in “apio-ide” in the “Search Packages” text box and click “Packages”.
  5. Install “apio-ide”. Click yes for any dependencies. Ignore any warnings about the APIO version.

First Project Tutorial

Once you have all of your hardware and software ready you can get started developing some digital logic. This first project won’t go into all the details of designing and implementing digital logic circuits in general, but it will guide you through the specifics of setting up a simple project, writing verilog, and programming the board with the project.

1. Connect USB cable

Connect a micro USB cable to the TinyFPGA board. Use a quality cable to minimize programming issues. The power LED should light up when the board is connected. The boot LED should pulse on and off to indicate the bootloader is active.

2. Copy the template project from the TinyFPGA BX Repository

Copy the apio_template directory to a new directory and rename it blink_project.

3. Open your newly copied template project

Open up Atom. From the “File” menu select “Open Folder…”. In the newly opened file chooser, navigate to the “blink_project” directory you just created and click “Select Folder”.

4. Program the FPGA board

From the “Apio” menu, select “Upload”. The project will automatically be built and uploaded to the TinyFPGA BX board.

5. Verify the design works on the board as intended

If everything is working as it should, you should see the user LED on the board blinking a “SOS” in morse code.

If you see the LEDs blinking congratulations! You’ve successfully programmed your open hardware FPGA board with open source tools. If you are familiar with Verilog and digital design you are ready to implement more complicated designs on your board(s).

Tips

Bootloader Behavior

The bootloader behaves differently depending on what is connected to the USB port:

  • If the board is connected to a USB host, the bootloader will stay active. It will wait to be programmed by tinyprog. You can manually exit the bootloader and load the user image from the onboard SPI flash by running tinyprog -b.
  • If the board is connected to a dumb power supply, the bootloader will timeout after one second and load the existing user image from the onboard SPI flash.

Pressing the reset button will always return the board to the bootloader, but it will only stay in the bootloader if its plugged into a USB host.

Updating the Bootloader

The following incantation will update tinyprog if there is a new version available, and check for updates for the bootloaders on all connected TinyFPGA BX boards. tinyprog will give you the option to automatically update the bootloader if an update is available for your board(s). It will list any release notes as well.

pip install --upgrade --no-cache-dir tinyprog
tinyprog --update-bootloader

Extra Resources