Skip to main content

Official WebFPGA Command-line Utility

Project description


PyPI version

Python migration is complete! This repository is feature-complete with the web IDE.

Welcome to the official command-line utility for WebFPGA compatible devices. If you are unfamiliar with WebFPGA, please checkout the homepage ( or our Kickstarter (

This utility provides access to the official backend for Verilog synthesis. It also provides flashing capability for the official WebFPGA family of boards ( You are free to use bitstreams sourced from our tools, Lattice's iCECube, or IceStorm. They should all work.


$ pip install webfpga

$ webfpga --help
Usage: webfpga [OPTIONS] COMMAND [ARGS]...

  --version  Show the version and exit.
  --help     Show this message and exit.

  flash    Flash the first connected WebFPGA device
  setbits  Set the CPU->FPGA communication bits
  synth    Synthesize one or more input Verilog files and save the bitstream


The utility is fairly simply to use once installed. Simply synthesize one or more Verilog source files to produce a bitstream. Then, feed that bitstream into webfpga flash to load the binary onto your local device. E.g. webfpga synth input.v -o bitstream.bin && webfpga flash bitstream.bin. By default, webfpga synth will save the bitstream as bitstream.bin, but you can use -o to specify a different filename.

$ curl -O
$ webfpga synth WF_blinky.v
WebFPGA CLI v0.3

Connecting to remote synthesis engine...
200 {"status":"ok"} 

Attempting synthesis (saving to bitstream.bin)...
  - WF_blinky.v

... verbose output omitted ...

purging build directory...
synthesis complete!

$ webfpga flash bitstream.bin
ryan@mu2 ~/cli $ ./webfpga flash bitstream.bin 
WebFPGA CLI v0.3

Opening USB device...

Preparing device for flashing...
AT: Hi
APR: 000921
Found programmer.
Checking for FPGA module and its flash configuration...
APWE: wren

Erasing device...

Flashing device...
AMWD: 0  3e  0  3e

IceStorm Example.

If you would like to produce logic with Yosys, IceStorm, and friends — then please check out webfpga_icestorm_examples. Once you have produced a bitstream, simply run webfpga flash bitstream.bin.

What is a compressed bitstream?

FPGA bitstreams are typically full of contiguous zeroes. Therefore, compression on the host and decompression in the device's firmware makes perfect sense. Flashing speeds are about 20x faster when using compressed bitstreams.

Right now, the device's firmware expects compressed bitstreams. WebFPGA doesn't support uncompressed, raw bitstreams (such as ones outputted from iCECube/IceStorm tools.) These compressed bitstreams are chunked into sub-64-byte chunks that fit into standard USB control transfer frames.

But don't fret! Our flashing utility automatically detects uncompressed bitstreams and transparently compresses them before transferring them. Bitstreams that originate from the official WebFPGA backend arrive pre-compressed.

Deploying to PyPI

$ ./ sdist
$ twine check dist/*
$ twine upload dist/*

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

webfpga-0.4.1.tar.gz (12.8 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page