Skip to content

HowTo FuPy on Icebreaker and TinyFPGA BX

Jump to bottom Edit New page
William D. Jones edited this page Nov 8, 2018 · 4 revisions

Icebreaker and TinyFPGA BX Setup

Introduction

This how-to guide is for people who want to get started running MicroPython on a Icebreaker iCE40UP5k or TinyFPGA BX 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)
  • An Icebreaker board or
  • A TinyFPGA BX board
  • A micro USB cable to connect the Icebreaker/TinyFPGA BX to your laptop

This guide will show you how to;

  • Configure the FPGA to run a "Soft CPU"
  • Create an combined FPGA bitstream and Micropython image
  • Use the MicroPython REPL from your laptop

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

All shell commands in this guide use bash

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
CPU=lm32             # Soft CPU architecture
CPU_VARIANT=minimal  # Use a resource-constrained variant to make up5k happy    
PLATFORM=icebreaker  # Target platform Icebreaker, or PLATFORM=tinyfpga_bx for TinyFPGA BX
FIRMWARE=micropython
TARGET=base
export CPU CPU_VARIANT PLATFORM TARGET FIRMWARE

# 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).

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

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