Lab 1: Setup

Abstract

In this lab, you will learn how to install and use everything needed to get your WebFPGA working. There are two main ways to program your board. The first one is using WebFPGA’s online IDE; if you plan to be constantly flashing the board while connected to the internet, then you only need to complete Part 1. If you will be programming your board offline, there is an offline command line interface option in Part 2.

Web IDE (Part 1)

To access the online IDE go to https://beta.webfpga.io/dashboard while using Google Chrome or any Chromium based browser.

In this dashboard you will see a large number of tools you can use. Now we will walk through the steps you need to take to flash your board with its first program:

First we need to make sure that the board is connected to our IDE.

Once we load the IDE in a browser we should get a pop up like in Figure 2 asking to connect the device. If you have not connected your device to your PC’s USB port now is a good time to. If you don’t see the pop up, click on Connect Device on the left hand side toolbar, if you still don’t see your device go to your browsers security settings and allow WebUSB. Click on Cascadia WebUSB FPGA Programmer and click on connect.

If you are running on Linux you will need to allow access to USB devices. Do this by traveling to the following directory: /etc/udev/rules.d and create a text file called 60-webfpga.rules. In this file insert the following text: SUBSYSTEM=="usb", ATTR{idVendor}=="16d0", ATTR{idProduct}=="0e6c", TAG+="uaccess". If you are denied access, try doing this through the terminal and using the keyword sudo.

Now choose an online example to load onto your device. The example code will automatically load onto your screen. In this example I will choose blinky.v

Click on Run Synthesis to synthesize the code on your screen. The terminal to the right will output synthesis data that is useful to know the amount of flip flops, registers, etc that are being synthesized.

Once the IDE terminal says “Ready to flash” you can do so by clicking on Flash Device. Now you should notice your board running the program.

You are finally done with the online solution for programming your board. If you would like to program your board offline, continue with this lab, if not, you can skip to section 3.

_______________________________________________________________

Offline CLI (Part 2)

If you would like to flash a program to your WebFPGA while you are not connected to the internet, there are a couple of extra steps you need to take. In this section we will look at some CLI tools you would need.

Operating System

For these CLI tools to work you will need to use a Debian operating system like Linux or Ubuntu. If you have access to a Linux machine that would be preferred. If not, you could use a Ubuntu Virtual machine

WebFPGA CLI

Now that you are running on a Debian OS we can download and install the webFPGA CLI that they offer. Here are the steps to get started.

First, clone the webfpga CLI repository here https://github.com/webfpga/cli

Once you have it in a directory run $pip install webfpga

Be sure you have pip installed ($sudo apt python3-pip)

Test that it installed correctly by running $webfpga --help (Sometimes you might have to restart your PC to get the commands fully working)

Now we have to allow webFPGA access to the PC’s USB to flash the WebFPGA. Do this by traveling to the following directory: /etc/udev/rules.d and create a text file called 60-webfpga.rules. In this file insert the following text: SUBSYSTEM=="usb", ATTR{idVendor}=="16d0", ATTR{idProduct}=="0e6c", TAG+="uaccess".

If you are denied access, try doing this through the terminal and using the keyword sudo.

Now that we have successfully installed the WebFPGA CLI we can try out an example. Go to the WebFPGA online IDE (https://beta.webfpga.io/dashboard) and download one of their example Verilog codes and place it in the directory.

Now synthesize the code by running $webfpga synth filenamehere.v. You will notice a new file in your directory called bitstream.bin, this is the bitstream of the Verilog code you just synthesized. Now you can flash it to your board by running $webfpga flash bitstream.bin.

If you observe the terminal, you can notice that this CLI still uses the internet to synthesize Verilog by connecting to WebFPGA’s synthesis servers. Because of this we will download our own synthesis engine. To achieve a fully online implementation we will have to take one extra step.

Icestorm Synthesizer

Icestorm is an open source toolchain that allows various different types of FPGAs to be flashed and provides their own synthesis engine. To get a base understanding of how this works, watch the first 14 minutes of this lecture by one of the developers of Icestorm (https://www.youtube.com/watch?v=s7fNTF8nd8A&list=LL&index=3&t=0s) Please watch this lecture before continuing with this lab. Luckily, Icestorm supports supports the FPGA on the WebFPGA. The developers of WebFPGA have made a video showing that it works (https://www.youtube.com/watch?v=GwvMhctskyo).

There is a GitHub repository linked in the video that explains the entire installation of Icestorm (https://github.com/nesl/ice40_examples). Follow these steps below:

Follow the instructions from the Icestorm GitHub to install the Icestorm toolchain, Arachne-PNR, NextPNR, and Yosys
Once all Icestorm tools are installed we need to download the pinmap and makefile for our specific board. These can be downloaded from the WebFPGA Icestorm example GitHib here (https://github.com/webfpga/webfpga_icestorm_examples)

Now you are ready to test it. Like in the lecture video, place the pinmap, makefile, and Verilog file (you can choose whichever example .v file from WebFPGA) in a directory.

Open the makefile and go over it to make sure everything is correct
Make sure that FILE = “your file name here”.v

Finally run this command to flash the synthesized code using a WebFPGA command from the makefile. $make flash

If this command does not work for you, open the makefile and look at the section under flash: You might need to change that to webfpga flash build/”your file name here”.bin

Conclusion

Congratulations! You are now ready to use your board for the following labs. If you have any trouble or doubts about this process, WebFPGA has a support forum(https://forum.webfpga.com/) that is very helpful and might already have the answer to your questions. The developers also urge users to email them with any questions.