Requirements

For this workshop you will need;

  1. The Fomu workshop files - see Required Files section.

  2. The Fomu toolchain - see Required Software section.

  3. A Fomu board - see Required Hardware section.

  4. Set up drivers - see Required Drivers section.

Note

If you are at a workshop, please install the tools first and then get the hardware from your presenter.

Warning

Your Fomu should be running Foboot v2.0.3 or newer.

You can see what version you are running by typing dfu-util -l like so;

dfu-util -l

If your Fomu is running an version older than v2.0.3 follow the Updating the Fomu Bootloader section.

Required Files

You will need the Workshop files. They are located in the fomu-workshop Github repository. You can download master.zip or clone it from git:

git clone --recurse-submodules https://github.com/im-tomu/fomu-workshop.git

Note

If you’re attending a workshop that provides USB drives, these files may be available on the USB drive under the Workshop directory.

Required Software

Fomu requires specialized software. This software is provided for Linux x86/64, macOS, and Windows, via Fomu Toolchain.

Debian packages are also available for Raspberry Pi.

If you’re taking this workshop as a class, the toolchains are provided on the USB disk.

To install the software, extract it somewhere on your computer, then open up a terminal window and add that directory to your PATH:

export PATH=[path-to-toolchain]/bin:$PATH
export PATH=[path-to-toolchain]/bin:$PATH

If you use PowerShell as your terminal;

If you use cmd.exe as your terminal;

PATH=[path-to-toolchain]\bin;%PATH%

To confirm installation, run the yosys command and confirm you get the following output;

$ yosys

 /----------------------------------------------------------------------------\
 |                                                                            |
 |  yosys -- Yosys Open SYnthesis Suite                                       |
 |                                                                            |
 |  Copyright (C) 2012 - 2018  Clifford Wolf <[email protected]>           |
 |                                                                            |
 |  Permission to use, copy, modify, and/or distribute this software for any  |
 |  purpose with or without fee is hereby granted, provided that the above    |
 |  copyright notice and this permission notice appear in all copies.         |
 |                                                                            |
 |  THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES  |
 |  WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF          |
 |  MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR   |
 |  ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES    |
 |  WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN     |
 |  ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF   |
 |  OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.            |
 |                                                                            |
 \----------------------------------------------------------------------------/

 Yosys 78b30bbb1102047585d1a2eac89b1c7f5ca7344e (Fomu build) (git sha1 41d9173, gcc 5.5.0-12ubuntu1~14.04 -fPIC -Os)

yosys>

Ensure it says (Fomu build). Type exit to quit yosys.

Note

The Fomu Toolchain consists of the following tools;

Tool

Purpose

yosys

Verilog synthesis

nextpnr-ice40

FPGA place-and-route

icestorm

FPGA bitstream packing

riscv toolchain

Compile code for a RISC-V softcore

dfu-util

Load a bitstream or code onto Fomu

python

Convert Migen/Litex code to Verilog

wishbone-utils

Interact with Fomu over USB

serial console

Interact with Python over a virtual console

Required Hardware

For this workshop, you will need a Fomu board.

Aside from that, you need a computer with a USB port that can run the Required Software.

You should not need any special drivers, though on Linux you may need sudo access, or special udev rules to grant permission to use the USB device from a non-privileged account.

This workshop may be competed with any model of Fomu, though there are some parts that require you to identify which model you have. See the Which Fomu do I have? section.

Which Fomu do I have?

Hacker

Production

String

hacker

pvt

Bash Command

export FOMU_REV=hacker

export FOMU_REV=pvt

Front

Hacker Hardware Front without case

Production Hardware Front without case

Back

Hacker Hardware Back without case

Production Hardware Back without case

In Case

Hacker Hardware Back with case

Production Hardware Back with case

Parts

Hacker Hardware Annotated Diagram

Production Hardware Annotated Diagram

Color

dark blue

cyan / light blue

Bootloader

Fomu Hacker running DFU Bootloader vX.X.X

Fomu PVT running DFU Bootloader vX.X.X

Description

These are the original design and cut corners to make it easier to manufacture. If you received one directly from Tim before 36C3, you probably have one of these. Hacker boards have white silkscreen on the back.

If you ordered a Fomu from Crowd Supply, this is the model you’ll receive. It is small, and fits in a USB port. There is no silkscreen on it. This model of Fomu has a large silver crystal oscillator that is the tallest component on the board.

Schematic

schematic-hacker.pdf

schematic-pvt.pdf

Received at

From Tim at 35C3, CCCamp19, HackADay Supercon 2019

At RISC-V Summit 2019, 36C3, Crowdsupply, Mouser

Buy more

End of Life

CrowdSupply,

Note

There are also Fomu EVT boards which were shipped to early backers of the Fomu crowd funding campaign. This model of Fomu is about the size of a credit card. It should have the text “Fomu EVT3” written across it in white silkscreen. If you have a different EVT board such as EVT2 or EVT1, they should work also.

Required Drivers

On most systems the Fomu board does not need any special drivers.

  • On Windows 10 or newer you do not need to install anything.

  • On Windows systems earlier than Windows 10 you will need to Installing Zadig Drivers.

  • On MacOS X you do not need to install any drivers.

  • On Linux you do not need to install any drivers, however you may need sudo access unless you Setup udev rules to grant permission to use the USB device from a non-privileged account.

Setup udev rules

Warning

This set up is for Linux only.

Setting up these udev rules grant permissions to use the USB device from a non-privileged account.

In Linux, try running dfu-util -l, and if you get an error message like the following you should add a udev rule as to give your user permission to the usb device.

dfu-util -l

Steps to set up udev rule

  1. Add your user to the plugdev group

    sudo groupadd plugdev
    sudo usermod -a -G plugdev $USER
    
  2. Check you are in the plugdev group with id $USER

    id $USER
    
  3. You will need to log out and log in again in order to be a member of the plugdev group.

    Warning

    You must log out and then log in again for the group addition to take affect.

  4. Check you are in the plugdev group with groups

    groups | grep plugdev
    
  5. Create a file named /etc/udev/rules.d/99-fomu.rules and add the following:

    SUBSYSTEM=="usb", ATTRS{idVendor}=="1209", ATTRS{idProduct}=="5bf0", MODE="0664", GROUP="plugdev"
    
  6. Reload the udev-rules using the following:

    sudo udevadm control --reload-rules
    sudo udevadm trigger
    

Installing Zadig Drivers

Warning

This set up is only needed for Windows system earlier than Windows 10.

  1. Download Zadig.

  2. Open Zadig.

  3. Under Options, select “List All Devices”.

  4. In the dropdown, select your Fomu and in the field right of the green arrow choose the WinUSB driver and hit Upgrade Driver.

    Setup of ZADEG for Updating USBport driver on WIN7