How to…

Install the toolchain

  1. Install Python 2.7
  2. Launch the toolchain installation process

Go to Tools > Toolchain > Install. Be patient for the toolchain installation.



When the toolchain is installed, the menu option changes to Tools > Toolchain > Update. Also, the toolchain can be restored to default in Tools > Toolchain > Reset default.

Update the toolchain

  1. Connect to the Internet
  2. Launch the toolchain updating process
Go to Tools > Toolchain > Update. Be patient for the toolchain update.

Install the drivers

  1. Install the toolchain (required for Windows)
  2. Enable the FTDI drivers
Go to Tools > Drivers > Enable. Each OS has a different process. This configuration requires administration privileges.


In Windows, an external application (Zadig) is launched to replace the existing FTDI driver of the Interface 0 by libusbK.


In MacOS this operation requires Internet connection to allow Homebrew to install libffi and libftdi packages.


To revert the drivers configuration go to Tools > Drivers > Disable

Create a project

  1. Create a new project

    Go to Edit > New. A new window will be opened.


  1. Add blocks

There are different types of blocks:

  1. Input/Output blocks

    Click on Basic > Input or Basic > Output, write the block’s name and press OK or Enter.

    These blocks can be configured as virtual (green). Then, the FPGA pin selector won’t be shown.

    Also, it can be configured as buses using the [x:y] notation (x is the most significant bit).


  1. Constant blocks

    Click on Basic > Constant, write the block’s name and press OK or Enter.

    These blocks can be configures as local. Then, this parameter won’t be exported.


  1. Code blocks

    Click on Basic > Code, add the code ports. Port names are separated by a comma. E.g.: a, b.


    This block contains a text editor to write your module in verilog code. Module header and footer are not required.


  1. Info blocks

    Click on Basic > Info.

    This block contains a text editor to add comments about the project.


    It can be converted into a Readonly text block by editing the block (double-click).



  1. Bit blocks

    Click on Bit > 0 or Bit > 1.

    These blocks are low and high logic drivers.


  1. Logic blocks

    Go to the Logic menu and select a block. This menu contains Gates, Combinational blocks and Sequential blocks.


  1. Setup blocks

    Click on Setup > Pull up or Setup > Tri-state.

    The Pull up block must be connected to input ports in order to configure a pull up in the FPGA.


In this example we are going to implement an AND logic gate with its input/output pins connected to the FPGA I/O.


  1. Connect the blocks

  1. Select your board

    Go to Select > Board and select IceZUM Alhambra, Kéfir I iCE40-HX4K, Nandland Go board, iCE40-HX8K Breakout Board, iCEstick Evaluation Kit or icoBOARD 1.0.


  1. Set FPGA I/O pins

    Select all Input/Output blocks’ pins.


  1. Save the project

    Go to Edit > Save as and select the project name, for example myProject.

    It will be saved as an .ice file.


Show the FPGA resources

Go to View > FPGA resources


Upload a bitstream

  1. Open a project

    Go to Edit > Open… and select an .ice file.

  2. Verify the project

    Go to Tools > Verify.

    This option checks the generated verilog code using apio verify.


  3. Build the project

    Go to Tools > Build.

    This option generates a bitstream using apio build.


  4. Upload the project

    Connect your FPGA board and press Tools > Upload. This option uses apio upload.


Create a block

  1. Open a project

    Go to Edit > Open project and select an .ice file. It is recommended to set all the I/O ports non-FPGA ports (green) to create a block.

  1. Verify the project

    Go to Tools > Verify.

  1. Add the project information

    Go to Edit > Preferences > Project information.


  1. Save the project

    Go to Edit > Save.


Add a project as block

  1. Open or create a new project

  1. Import the custom block

    Go to Edit > Add as block… and select an .ice file.



  2. Examine the custom block

    Complex blocks can be examined by double clicking the block.


Add a collection

Go to Tools > Collections > Add and select a collection package (ZIP file).

Select a collection

Go to Select > Collections. Select a collection. The first item is the “Default” collection that is the one stored in the application.

View the selected collection info

Go to View > Collection info. A new window will appear with the file content.

Create a collection package

  1. Create one or more collections

You can use the icm cli tool to create and update a collection.

├── blocks
│   ├── category1
│   │   ├──
│   │   └── subcategory1
│   │       ├──
│   │       └──
│   └── category2
│       └──
├── examples
│   ├──
│   ├──
│   └──
├── locale
│   ├── en
│   │   └── en.po
│   ├── es_ES
│   │   └── es_ES.po
│   └── translation.js
├── package.json
  1. ZIP all your collections

Create a ZIP file with all your created collections at the main level.
├── Collections 1
│   └── ...
└── Collections 2
    └── ...


The file package.json must exists, and also the blocks directory and/or the examples directory. The locale directory is optional. More information in the Default collection.

Include a list file

If your code block contains a list file(s), for example:

$readmemh("rom.list", rom);
  1. Save the ice project
  2. Copy the list file(s) in the project directory
  3. Build and upload the project

Also you can include explicitly a list file in the header of a code block:

// @include rom.list

Include a verilog (header) file

If your code block includes a verilog (header) file(s), for example:

// @include lib.vh
// @include math.v

`include "lib.vh"
  1. Save the ice project
  2. Copy the verilog (header) file(s) in the project’s directory
  3. Build and upload the project

View the board rules

Go to View > Board rules


Disable the board rules

Go to Edit > Preferences > Board rules > Disable



Configure a remote host

I you want to use a RPi, eg pi@, or another computer from Icestudio as a client, first configure the host:

  1. Copy your SSH public key into the server
$ ssh-keygen
$ ssh-copy-id -i .ssh/ pi@
  1. Install apio in the server
$ ssh pi@
$ sudo pip install -U apio
$ apio install --all
$ apio drivers --enable  # For FTDI devices
  1. Enter the host name in Icestudio, Edit > Remote hostname


  2. Now, Verify, Build and Upload tools will run in the selected host

Close the application

Go to File > Quit or click the application’s close button. If there are unsaved changes an alert will appear to confirm or cancel the action: