Make Lattice iCEcube2 work on Ubuntu 20.04 and program the iCEstick FPGA board

This tutorial shows how to install the Lattice iCEcube2 FPGA design software on Ubuntu 20.04. Instead of the Lattice Diamond Programmer, we will use the alternative programmer from Project IceStorm that works flawlessly on Ubuntu Linux.

The Lattice iCEcube2 FPGA design software only works on Red Hat-based Linux distributions out of the box. Fortunately, we can make it run perfectly on Ubuntu Linux by installing dependencies and making a few changes to our system.

Finally, we will install a command-line tool for programming the Lattice iCE40 FPGA with the bitstream.

Installing iCEcube2 on Ubuntu Linux

First, you need to download the iCEcube2 installer from Lattice. You will need to create an account to do that. Click the link and scroll to the bottom to download the Linux version of the software!

iCEcube2 Design Software

After placing the downloaded tarball file in your home directory, copy-paste the commands from the below recipe to install and make it work on Ubuntu Linux.

The recipe

The listing below shows all the commands I entered in the video for installing iCEcube2 on Ubuntu 20.04.

# Step 1: Update your system
sudo apt update
sudo apt upgrade
 
# Step 2: Install 32-bit dependencies
sudo apt install gcc-10-base:i386 libc6:i386 libcrypt1:i386 \
    libgcc-s1:i386 libidn2-0:i386 libunistring2:i386 \
    zlib1g:i386 libxext6:i386 libsm6:i386 libxi6:i386 \
    libxrender1:i386 libxrandr2:i386 libxfixes3:i386 \
    libxcursor1:i386 libxinerama1:i386 libfreetype6:i386 \
    libfontconfig1:i386 libglib2.0-0 lib32stdc++6 libglib2.0-0:i386
 
# Step 3: Install 32-bit libpng12 with modified paths
wget vhdlwhiz.com/wp-content/uploads/2020/05/\
libpng12-0_1.2.54-1ubuntu1b_i386.deb
sudo dpkg -i libpng12-0_1.2.54-1ubuntu1b_i386.deb
 
# Update 2020-08-10:
#   See Peter Uran's comment on this blog post for an
#   alternative method of changing the network interface name
#   vhdlwhiz.com/lattice-icecube2-ubuntu-20-04-icestick#comment-73154
#
# Step 4a: Make a backup of the GRUB config
sudo cp /etc/default/grub /etc/default/grub_original
 
# Step 4b: Change the default network name from "ens33" to "eth0"
OLD_STRING='GRUB_CMDLINE_LINUX=\"find_'
NEW_STRING='GRUB_CMDLINE_LINUX=\"net.ifnames=0 biosdevname=0 find_'
sudo sed -i "s/$OLD_STRING/$NEW_STRING/g" /etc/default/grub
 
# Step 4c: Check the changes (compare to my diff below this listing)
diff /etc/default/grub /etc/default/grub_original
 
# Step 4d: Update the GRUB config and reboot
sudo update-grub
sudo reboot
 
# Step 4e: Check that the network name is now "eth0"
ip link show
 
# Step 5: Unpack and install Lattice iCEcube2
cd
tar zxf ./iCEcube2setup_Sep_12_2017_1708.tgz
chmod +x iCEcube2setup_Sep_12_2017_1708
./iCEcube2setup_Sep_12_2017_1708
 
# Step 6a: Replace #!/bin/sh shebang with #!/bin/bash recursively
find ~/lscc/iCEcube2.2017.08/synpbase/bin/ \
    -type f -exec sed -i '1s/#\!\/bin\/sh/#\!\/bin\/bash/g' {} \;
 
# Step 6b: Replace some occurrences of /bin/sh with /bin/bash
find ~/lscc/iCEcube2.2017.08/synpbase/lib/ \
    -type f -exec sed -i 's/\/bin\/sh /\/bin\/bash /g' {} \;
find ~/lscc/iCEcube2.2017.08/synpbase/lib/ \
    -type f -exec sed -i "s/'\/bin\/sh'/'\/bin\/bash'/g" {} \;
 
# Step 7: Start iCEcube2
~/lscc/iCEcube2.2017.08/iCEcube2

Diff between grub and grub_original

11c11
< GRUB_CMDLINE_LINUX="net.ifnames=0 biosdevname=0 find_preseed=/preseed.cfg auto noprompt priority=critical locale=en_US"
---
> GRUB_CMDLINE_LINUX="find_preseed=/preseed.cfg auto noprompt priority=critical locale=en_US"

iCEcube2 license request

To request a free license for iCEcube2, you need to find the MAC address of your network adapter. Issue the command “ip link show” and note down the 12-digit hex value, as shown below.

jonas@ubuntu:~$ ip link show
1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc fq_codel state UP mode DEFAULT group default qlen 1000
    link/ether 00:0d:29:2f:0a:ae brd ff:ff:ff:ff:ff:ff

When you have the MAC address, you can use the Lattice iCEcube2 license request form *. You will have to create a Lattice account to access this page. Make sure to replace the ‘:’ characters in your MAC address with ‘-‘ before you paste it in the license request form.

* Update 2024: Lattice iCEcube2 now costs money.

Place the license file somewhere on your filesystem. For example, in the iCEcube2 installation directory ~/lscc/. Finally, start the license manager by using the command below and specify the license file.

~/lscc/iCEcube2.2017.08/LicenseSetup

After you close the license manager, you can start iCEcube2, as explained in Step 7.

Troubleshooting

No such file or directory

bash: ./iCEcube2setup_Sep_12_2017_1708: No such file or directory

If you try to run the iCEcube2 installer on a standard Ubuntu installation, you are likely to see the error message shown above.

The problem is that iCEcube2 depends on 32-bit libraries that are not available on Ubuntu by default. The solution is to install the 32-bit dependencies, as shown in Step 2 and 3.

Missing libpng12.so.0 file

./iCEcube2setup_Sep_12_2017_1708: error while loading shared libraries: libpng12.so.0: cannot open shared object file: No such file or directory

The iCEcube2 installer depends on the 32-bit version of the libpng12-0 package. Without the libpng12.so.0 file on your system, the iCEcube2 installer exits with the error message shown above.

Unfortunately, that package doesn’t work out of the box in Ubuntu 20.04 for reasons explained in this Ask Ubuntu answer. The author of the linked answer record was kind enough to provide a modified version of the package that works on newer versions of Ubuntu.

You can download it from the VHDLwhiz server by using the link below.

libpng12-0_1.2.54-1ubuntu1b_i386.deb

If you are concerned about installing the unknown package on your system, I recommend that you compare it to the original file from the Ubuntu server. Unpack both packages and compare the md5sums of all files to verify that the only difference is the install paths.

License checkout failed: Cannot find license file

Error: License checkout failed. Use LM_LICENSE_FILE to use a different license file Feature: LSC_ICECUBE2_A Filename: /usr/local/flexlm/licenses/license.dat

You have to specify a license file. Run the license manager, as shown earlier in this article.

License checkout failed: hostid of this system does not match the hostid

Invalid host.
 The hostid of this system does not match the hostid
 specified in the license file.
...
FLEXnet Licensing error:-9,57.  System Error: 19 "(null)"

If you are getting this error message when starting iCEcube2 despite having specified the license file, it’s probably because your network device is different from “eth0”. You can find the name in Ubuntu by using the “ip link info” command.

The iCEcube2 license is “node-locked” to the MAC address of your network adapter. Unfortunately, the “eth0” network name is hardcoded in the iCEcube2 installer. With the default network name on Ubuntu 20.04 being different, probably “ens33”, this is a problem.

One way to fix this is by changing the network name back to “eth0”. Refer to Step 4 in the recipe to solve this.

Script syntax errors during synthesis

/home/jonas/lscc/iCEcube2.2017.08/synpbase/bin/synplify_pro: 321: /home/jonas/lscc/iCEcube2.2017.08/synpbase/bin/config/execute: Syntax error: "(" unexpected (expecting ";;")

These errors may appear when you start a synthesis after opening iCEcube2 successfully. The problem is that /bin/sh is different on Ubuntu than on Red Hat.

The solution is to replace the /bin/sh shebang with /bin/bash in all the scripts, as explained in this thread on the DigiKey forum. Refer to Step 6 in my recipe to do this from the command line.

Lattice Diamond Programmer alternative

The Lattice Diamond Programmer Standalone software is a GUI tool for programming the FPGA with bitstreams that you generate in iCEcube2. It’s difficult to get it working on Ubuntu because it depends on an outdated version of libusb.

Fortunately, there’s a better and easier tool that you can use if you are working with the Lattice iCE40 FPGA. Install the Project IceStorm package on Ubuntu by issuing the following command:

sudo apt install fpga-icestorm

After installing the fpga-icestorm package, programming the FPGA is as simple as shown below. Plug the Lattice FPGA board into the USB port and call the iceprog command with the bitfile as an argument:

iceprog seg7/impl/seg7_Implmnt/sbt/outputs/bitmap/top_bitmap.bin

Install the free version of ModelSim on Ubuntu

To complete the VHDL and FPGA development environment on your Ubuntu box, you may want to check out this tutorial:

How to make ModelSim from Quartus Prime Lite work on Ubuntu 20.04

With iCEcube2, ModelSim, and Project IceStorm installed, you can do VHDLwhiz’ beginner Fast-Track course and the advanced Dot Matrix course on your Ubuntu box!