I learned about a new FOSS project a few weeks ago: apio. It's stated mission is:

Experimental open source micro-ecosystem for open FPGAs. Based on platformio. Apio is a multiplatform toolbox, with static pre-built packages, project configuration tools and easy commands to verify, synthesize, simulate and upload your verilog designs.

That sounded pretty good to me. It was easy to install on my RPi3:

pip install apio

That just installs the apio "shell". In order to get all the synthesis, simulation, and board tools, I used the command:

apio install --all

That automatically downloads and installs some system utilities, the Icestorm FPGA toolchain, the iverilog simulator, and some design examples for several types of iCE40 FPGA boards. Once that was completed, I could check to see what boards were supported:

pi@raspberrypi:~ $ apio boards --list

Supported boards:

--------------------------------------------------------------------------------
Board         FPGA                 Type  Size  Pack
--------------------------------------------------------------------------------
icoboard      iCE40-HX8K-CT256     hx    8k    ct256
icezum        iCE40-HX1K-TQ144     hx    1k    tq144
icestick      iCE40-HX1K-TQ144     hx    1k    tq144
go-board      iCE40-HX1K-VQ100     hx    1k    vq100
iCE40-HX8K    iCE40-HX8K-CT256     hx    8k    ct256

Use `apio init --board <boardname>` for creating a new apio proyect for that board

What!?!? No CAT Board in the list!?! I needed to fix that situation. I poked around in the apio Python code and found a likely file at apio/resources/boards.json. Inside that file, I pretty much copied the existing entry for the icoboard with a few modifications:

  "Cat-board": {
    "fpga": "iCE40-HX8K-CT256",
    "prog": "litterbox",
    "check": {
      "arch": "linux_armv7l"
    }
  }

The only thing I changed (besides the board identifier) was the "prog" entry to list the litterbox utility that uploads bitstreams from the RPi3 to the FPGA on the CAT Board.

I also had to modify the following section of the SConstruct file in the same directory:

# -- Upload the bitstream into FPGA
upload_cmd = ''
if PROG == 'ftdi':
    upload_cmd = 'iceprog{0} -d i:0x0403:0x6010:{1} $SOURCE'.format(
        EXT, DEVICE)
elif PROG == 'gpio':
    # Icoboard + RPI2: sram
    upload_cmd = 'export WIRINGPI_GPIOMEM=1; icoprog -p < $SOURCE'
elif PROG == 'litterbox':
    # Cat Board + RPI2,3
    upload_cmd = 'sudo litterbox -c $SOURCE'

This just adds the command for uploading a bitstream using the litterbox utility.

Finally, after a little more poking around, I found the apio/managers/scons.py file and added the following code to its upload function:

        # -- Litterbox
        elif programmer == 'litterbox':
            # Cat Board + RPI2,3
            # Device argument is ignored
            if device and device != -1:
                click.secho(
                    'Info: ignore device argument {0}'.format(device),
                    fg='yellow')
            # Check architecture
            arch = self.resources.boards[board]['check']['arch']
            current_arch = util.get_systype()
            if arch != current_arch:
                # Incorrect architecture
                click.secho(
                    'Error: incorrect architecture: RPI2 or RPI3 required',
                    fg='red')
                return 1

This does a sanity check to make sure the upload process for the CAT Board is occurring on an RPi2 or RPi3.

Now when I regenerate the board list, I can see the CAT Board:

pi@raspberrypi:~ $ apio boards --list

Supported boards:

--------------------------------------------------------------------------------
Board         FPGA                 Type  Size  Pack
--------------------------------------------------------------------------------
icoboard      iCE40-HX8K-CT256     hx    8k    ct256
icezum        iCE40-HX1K-TQ144     hx    1k    tq144
Cat-board     iCE40-HX8K-CT256     hx    8k    ct256
icestick      iCE40-HX1K-TQ144     hx    1k    tq144
go-board      iCE40-HX1K-VQ100     hx    1k    vq100
iCE40-HX8K    iCE40-HX8K-CT256     hx    8k    ct256

Use `apio init --board <boardname>` for creating a new apio proyect for that board

Once my modifications were complete, I went into the directory for the LED blinker and used the following command to indicate that this design was intended for the CAT Board:

apio init --board Cat-board

This creates an apio.ini file with a single line of text indicating the board type:

{"board": "Cat-board"}

From there, it's an easy step to compile the design and upload it to the CAT-board:

apio upload

If the bitstream in the directory is missing or out of date, apio will rebuild the design using the Icestorm tools. Then it uploads the bitstream to the CAT Board using the litterbox utility. After that, the LED starts blinking. Success!

The apio tool makes it really easy to install and apply the iCE40 FPGA tools. Also, the authors have added my modifications so apio now supports the CAT Board right out of the box.