Skip to content

HowTo FuPy on iCE40 Boards

Jump to bottom Edit New page
Tim 'mithro' Ansell edited this page Nov 13, 2018 · 21 revisions

FuPy on iCE40 Boards

Introduction

This how-to guide is for people who want to get started running MicroPython on a iCE40 based development board using FμPy.

The process for booting either board is extremely similar, so this guide combines the two.

By the end of this guide you will have a MicroPython REPL running on the board's FPGA using a Soft CPU.

You will need:

  • A laptop running Linux, or a Linux VM (Ubuntu 16.04 LTS is well tested)
  • A USB cable to connect the FPGA board to your laptop

This guide will show you how to;

This guide uses Ewen McNeill's corresponding wiki page for the Arty A7 as a basis.

All shell commands in this guide use bash

Supported Boards

Tier 1

Tier 1 boards can be used without any physical modification to the board and provide a great experience.

Icebreaker

The icebreaker is an ideal board to play with FuPy. It has the iCE40UP5K, user buttons + LEDs and a serial UART.

You will need;

  • A micro USB cable to connect the Icebreaker to your laptop.

Tier 2

Tier 2 boards can be used without any physical modification but have some type of limiting factor that prevents an awesome experience.

iCE40-HX8K Breakout Board

The HX8K only has limited RAM for MicroPython.

You will need;

  • A mini USB cable to connect the TinyFPGA BX to your laptop.

Tier 3

Tier 3 boards require extra components or modification to the board to be used.

TinyFPGA BX

The TinyFPGA BX has the USB pins directly connected to the FPGA. This means special functionality is required inside the FPGA design for the USB connection to operate. At this time, this functionality has not been integrated into the LiteX-BuildEnv environment thus you will require a seperate UART interface to see the MicroPython prompt.

You will need;

Hardware Modification Needed

You will need to connect the USB UART to the following pins;

XXXX

iCE40 UltraPlus Breakout Board

You will need;

Hardware Modification Needed

You will need to do the following;

  • Solder the pin headers onto the PMOD socket.
  • Connect the Pmod USBUART Interface to the bottom row of the PMOD socket.

Configure USB Connection

First we need to configure how we connect with the device by creating some rules for udev:

git clone https://github.com/timvideos/HDMI2USB-mode-switch.git
cd HDMI2USB-mode-switch/udev
make install
make reload

Next we ensure that your user has permission to access the relevant device files:

sudo adduser $USER video
sudo adduser $USER dialout       # or 'uucp' group on some Linux distros
sudo reboot

(if you do not want to reboot it is sufficient to log your user out, and back in again; use id to check that your user is in the correct groups, particularly dialout or uucp).

Download the Build Environment

Next we download and setup the build environment. This environment contains the tools that we need to build the gateware + firmware and load them onto the FPGA.

git clone https://github.com/timvideos/litex-buildenv.git
cd litex-buildenv/

# Build targets
export CPU=lm32             # Soft CPU architecture
export CPU_VARIANT=minimal  # Use a resource-constrained variant to make up5k happy
export PLATFORM=icebreaker  # Target platform Icebreaker, or PLATFORM=tinyfpga_bx for TinyFPGA BX
export FIRMWARE=micropython
export TARGET=base

# Download dependencies for the build environment
./scripts/download-env.sh

Enter the build environment

Once the download is done (several minutes) you can enter your build environment. You will need to do this every time you use the litex build tools (eg, in a new terminal window or a new login). The environment variable settings are the same as above (substituting PLATFORM=tinyfpga_bx if you are using that board).

export CPU=lm32
export CPU_VARIANT=minimal
export PLATFORM=icebreaker
export TARGET=base
export FIRMWARE=micropython

source scripts/enter-env.sh

Compiling the Gateware and BIOS

Both the Icebreaker and TinyFPGA BX boards use a fully open source flow to build the FPGA gateware. The tools are:

For this tutorial, we will be building our own gateware. The download-env.sh script will have downloaded the above tools for you. To make the gateware, run the following from the root of litex-buildenv (_assuming you have already entered the build environment as described above):

make gateware

The above command will compile a set of base C libraries, a BIOS, and then generate the FPGA bitstream. After this command is finished, we still need to compile Micropython. However, first we should test whether the gateware and soft-CPU function properly.

Loading the gateware onto the Icebreaker

While some platforms on litex-buildenv support loading the gateware (along with a BIOS embedded into the BRAM) into volatile memory for testing, on the Icebreaker and TinyFPGA BX, the gateware and the BIOS must be written to SPI flash.

To flash the gateware and the BIOS at once, use the following command:

make gateware-flash

On Icebreaker, the output will be sent through the USB serial console. Currently TinyFPGA BX requires an external UART. TX should be connected to Pin 1 and RX to Pin 2 (as labeled on the TinyFPGA BX silkscreen). Either way, once the output pauses in the serial console, hit the enter key, you should see a BIOS> prompt. Type help and enter for a list of commands to test the BIOS out.

Building and running MicroPython (FμPy)

Next we will build the MicroPython firmware and load it onto the soft CPU:

./scripts/build-micropython.sh
make image-flash

You can also use make image to just create the combined gateware, BIOS, and micropython image that will be programmed onto the SPI flash of either board. In this case, the output image will be available under:

  • build/icebreaker_base_lm32.minimal/image-gateware+bios+micropython.bin for Icebreaker, and
  • build/tinyfpga_bx_base_lm32.minimal/image-gateware+bios+micropython.bin for TinyFPGA BX

Once the image has been flash to the boards using make image-flash or otherwise, the BIOS should detect a valid image and should start booting MicroPython. After approximately 20 seconds (we are running a program from SPI flash on a CPU with no cache, after all) you should reach a MicroPython REPL:

Booting from serial...
Press Q or ESC to abort boot completely.
sL5DdSMmkekro
Timeout
Booting from flash...

        __   _ __      _  __
       / /  (_) /____ | |/_/
      / /__/ / __/ -_)>  <
     /____/_/\__/\__/_/|_|
 SoC BIOS / CPU: LM32 /  12MHz
(c) Copyright 2012-2018 Enjoy-Digital
(c) Copyright 2007-2018 M-Labs Limited
Built Nov  8 2018 01:55:19

BIOS CRC passed (1055eedc)
Booting from serial...
Press Q or ESC to abort boot completely.
sL5DdSMmkekro
Timeout
Booting from flash...
Executing booted program at 0x20028008
MicroPython v1.9.4-533-g7b0c4384b on 2018-11-08; litex with lm32
>>>

Try running the following program and see if you can get an LED to blink! Type one line at a time at the REPL, as sometimes serial chars can arrive too fast on these boards:

import litex

l = litex.LED(1)

while True:
    l.on()
    l.off()
Add a custom footer
Clone this wiki locally