Getting Started With the Cu

Justin Rajewski

In this tutorial we will setup all the software needed to work with the Alchitry Cu.

Installing iCEcube2

The first step to setting up your environment is to install iCEcube2. iCEcube2 is a program provided by Lattice (the manufacture of the FPGA on the Cu) that is used to build your projects. It holds all the secret sauce that converts your text into an FPGA configuration file (bin file).

Head over to Lattice's website and download the latest version of iCEcube2 here.

The download links are at the bottom of the page.

You will need to create an account to download the software and create a (free) license file for it.

Getting a License

Before launching the installer, you should get a license file.

Head over to Lattice's license page here.

You will need your MAC address to generate the file.

On Windows, open the command prompt and type in the following.

ipconfig /all

It is labeled as Physical Address.

On Ubuntu 18.10, you can find your MAC in Settings->Network->Wired (or Wireless)->Gear Icon. It's labeled as Hardware Address under the Details tab. 

Alternatively, you can find it with the following command.

ip link show

The MAC address format on Linux is colon separated but Lattice wants dashes so swap them after you copy paste it.

They will email you a license file for that MAC address.

You will need to download this file and put it somewhere safe. iCEcube2 will require that it stays where you put it.

Launching the Installer


You should be able to extract file you downloaded and simply double click to run it.


If you are using Ubuntu you will need to install a bunch of 32bit packages to be able to run the software. You can run the following command to do this.

sudo apt-get install libxext6:i386 libsm6:i386 libxi-dev:i386 libxrandr-dev:i386 libxcursor-dev:i386 libxinerama-dev:i386 libfreetype6:i386 libfontconfig:i386 libglib2.0-0:i386 libstdc++6:i386

On Ubuntu 18.10, the version of libpng that is available is libpng16 but iCEcube2 looks for libpng12. You can download the .deb package here.

Most Linux systems don't use the old eth0 naming convention for your network interface anymore. However, the licensing system of iCEcube2 does.

You can make Ubuntu name your network interface eth0 by creating a udev rule.

Run the following command to open a text editor.

sudo gedit /etc/udev/rules.d/10-net-naming.rules

The paste the following line in. You will need to change the fake MAC address aa:bb:cc:dd:ee:ff to your actual MAC address you found earlier. Save the file and close the editor.

SUBSYSTEM=="net", ACTION=="add", ATTR{address}=="aa:bb:cc:dd:ee:ff", NAME="eth0"

You will need to reboot for this to take effect.

On Linux you don't need root permissions if you are installing it somewhere you already have write permissions. I usually install mine to /opt/lattice/icecube2 which I have setup to be owned by me. By default, it tries to install it to your home directory.

You should now be able to run the installer.


The installer itself is pretty straight forward. 

Just run through pointing it to where you want it installed and your license file you downloaded.

Alchitry Labs or Alchitry Loader

Now is decision time. You have a few options for developing for the Cu. The first, and recommended, option is to download Alchitry Labs.

Alchitry Labs supports both Lucid and Verilog. It also has some very handy features like a library of built in components, real-time error checking for Lucid, real-time syntax checking for Verilog, support for Alchitry Constraints so you don't need to look at the schematics to define pinouts, and single click builds.

Your second option is to download the Alchitry Loader.

This is a very basic program that will transfer the .bin file you generate on your own to the Cu (or Au). This is what you should use if you want to use iCEcube2 directly to build your projects. This also opens up all the Lattice supported build methods including VHDL.

You can't use Lucid directly with iCEcube2.

Lucid is a language we developed that is similar to Verilog but can significantly reduce the lines of code required for the same design and makes the easy "gotchas" of Verilog impossible. We highly recommend this for hobbyists/beginners.

Next Steps

From here you can follow either the Lucid or Verilog tutorials.