ECELabs software

ECELabs, Purdue ECE teaching labs

A Python driver that lets a Raspberry Pi set and read an FPGA's pins through eight I2C expanders. The lab's station web apps run on top of it.

2023 to 2024I wrote the I2C driver layer

The problem

In ECE 270, students learn to use an FPGA and logic gates and to write SystemVerilog. Each lab station ran as a small hardware server. Web apps on its Raspberry Pi 4B let one student at a time check out an iCE40-⁠HX8K FPGA board, press its 20 push buttons and read back its LEDs and seven-segment displays.

My carrier boards put the FPGA’s pins behind eight MCP23017 I2C expanders, so the Pi needed a driver to reach them. The older station code called gpiozero and pigpio, two libraries that drive the Pi’s own pins.

How it works

I wrote the driver layer under the station’s web apps, in Python. Three modules sit between the lab’s web apps and the eight expanders: setupIO.py sets the pins up, readwriteIO.py reads and writes them, and FuncTrans.py lets the older station code call them.

I also wrote a guide to building the open-source iCE40 toolchain on an Ubuntu computer that talks to each station’s Pi. Click a block to see what each part does and why.

One lab station, block by block. Blocks: Student web page; Lab web server; Writer web app (push buttons); Reader web app (displays, check-out); FuncTrans (shims for old calls); readwriteIO (block reads and writes); setupIO (pin directions); 8 × MCP23017 (0x20 to 0x27); iCE40-HX8K FPGA; FPGA toolchain (Ubuntu computer). Student web page to and from Lab web server; Lab web server to Writer web app, POST; Reader web app to Lab web server, GET; Writer web app to FuncTrans, LED(n).on(); FuncTrans to readwriteIO, write_bit; readwriteIO to Reader web app, read_all; readwriteIO to and from 8 × MCP23017, I2C bus 1, 400 kHz; setupIO to 8 × MCP23017; 8 × MCP23017 to and from iCE40-HX8K FPGA, 103 FPGA I/Os; FPGA toolchain to iCE40-HX8K FPGA, bitstream.

Click a labeled block to see what it does and why.

One station, block by block

A student's clicks reach the FPGA through the lab's web apps, my three driver modules and the expanders. Click a block to see what it does and why.

In this layer

  • readwriteIO The module that reads and writes the expanders' pins over the Pi's I2C bus 1.
  • FuncTrans Shims that mimic the gpiozero and pigpio calls of the older station code, so that code could move onto the expanders.
  • setupIO Sets the direction and polarity of all eight expanders, at addresses 0x20 to 0x27 on the Pi's I2C bus 1.
  • 8 × MCP23017 Eight MCP23017 I2C expanders on my carrier boards give the Pi about 103 FPGA pins.
  • Writer web app The lab's web app for the push buttons, built on CherryPy, a Python web framework. I deployed it on each station's Pi.
  • Reader web app The lab's web app for the displays, also on CherryPy, which I deployed beside the writer.
  • FPGA toolchain A guide I wrote to building the open-source iCE40 toolchain on an Ubuntu computer, which loads the bitstream into the FPGA board over its FTDI USB link.

readwriteIO: the pins, in blocks

The module that reads and writes the expanders' pins over the Pi's I2C bus 1.

I chose block transfers over one register at a time, because a block moves both 8-⁠bit ports of a chip in one I2C package.

Two writes, six reads

My code calls it “efficient since it sends only 1 i2c package”. write_bitstr_fast sets all 20 buttons in two writes, and read_all fetches every LED and digit in six reads.

Testing it, August 2023

WriteTest.py writes two button patterns 4 ms apart. ReadTest.py, in a second terminal, polls read_all until each expected pattern appears and prints how long it took. The expected values depend on the FPGA design loaded for the test.

The driver's two fast paths

Blocks: write_bitstr_fast (20-character button string); read_all (LED, RGB, LEFT, RIGHT, SS0 to SS7); 0x20, 0x21 (MCP23017, outputs); 0x22 to 0x27 (MCP23017, inputs); iCE40-HX8K FPGA.

  • write_bitstr_fast to 0x20, 0x21: 2 block writes.
  • 0x20, 0x21 to iCE40-HX8K FPGA: PB[0:19].
  • iCE40-HX8K FPGA to 0x22 to 0x27: RGB LED, LED rows, SS0 to SS7.
  • 0x22 to 0x27 to read_all: 6 block reads.

What I wrote: write_bitstr_fast, read_all.

The pin map as first written, in August 2023: two expanders drive the FPGA's push-button inputs and six read its outputs. A block transfer covers both ports of a chip in one I2C package, so a full update takes two writes and six reads.

FuncTrans: the old calls, kept

Shims that mimic the gpiozero and pigpio calls of the older station code, so that code could move onto the expanders.

I chose them over rewriting the station code: in their own note, they “make implementation onto the current setup easier”.

What it cost

Certainty: the same note says they “haven't been fully tested (about 80% done)”.

How a call reaches the bus

A call such as LED(n).on() becomes one write_bit in readwriteIO, which reads the port, changes one pin and writes it back.

setupIO: setting the expanders up

Sets the direction and polarity of all eight expanders, at addresses 0x20 to 0x27 on the Pi's I2C bus 1.

January 2024

I changed setupIO.py, readwriteIO.py and FuncTrans.py “to match new FPGA PCB”. Two of expander 0x20's port B lines, PB[20] and HWCLK, became inputs, and so did 0x21's port A.

The expanders, and who masters them

Eight MCP23017 I2C expanders on my carrier boards give the Pi about 103 FPGA pins.

I chose the Pi's own I2C bus over an FTDI chip, because my README records the FTDI route at “<100Hz read/write”, with the advice “not to use the FTDI chip”.

The FTDI test, July 2023

readspeed.py read one expander port through an FT4232H in a tight loop, and printed “Unexpected” whenever a value was not the last plus one.

Why the Pi is the I2C master

Blocks: Test script (pyftdi); FTDI chip (FT4232H); I2C driver layer (Pi 4B, smbus); MCP23017 expanders.

  • Test script to FTDI chip (dashed).
  • FTDI chip to and from MCP23017 expanders: <100 Hz read/write (dashed).
  • I2C driver layer to and from MCP23017 expanders: I2C bus 1.

What I wrote: I2C driver layer.

The dashed path was tried first. My README gives its rate as "<100Hz read/write" and says not to use the FTDI chip, so the driver runs on the Pi's own I2C bus.

Writer web app: the push buttons

The lab's web app for the push buttons, built on CherryPy, a Python web framework. I deployed it on each station's Pi.

A POST of a 20-character switches string sets the FPGA's push buttons, one FuncTrans call per character; an x leaves that button alone.

Reader web app: displays and check-out

The lab's web app for the displays, also on CherryPy, which I deployed beside the writer.

A thread calls read_all every 1 ms, and each GET returns the LEDs and displays.

Check-out

It also runs the check-⁠out queue: one student at a time holds the board, and the others wait in line.

The FPGA toolchain guide

A guide I wrote to building the open-source iCE40 toolchain on an Ubuntu computer, which loads the bitstream into the FPGA board over its FTDI USB link.

What it covers

It builds Yosys, nextpnr and IceStorm from source, then gives a script that synthesizes a design, places and routes it, packs the bitstream and loads it.

The FPGA toolchain I documented

Blocks: Yosys (synth_ice40), in Ubuntu computer; nextpnr-ice40 (--hx8k --package ct256), in Ubuntu computer; icepack (writes the bitstream), in Ubuntu computer; iceprog (loads the bitstream), in Ubuntu computer; iCE40-HX8K board.

  • Yosys to nextpnr-ice40.
  • nextpnr-ice40 to icepack.
  • icepack to iceprog: out.bin.
  • iceprog to iCE40-HX8K board: FTDI USB.
The flow from my install guide. Yosys, nextpnr and IceStorm are built from source on the Ubuntu computer.

The point of all this is a short loop: write SystemVerilog, program the FPGA, press its buttons and read its LEDs and displays. Here is that loop in miniature, in your browser. Pick an example, program the board, then press the buttons.

buttons.sv14 lines
// Buttons to LEDs. Buttons 0 to 7 light the
// right bank of LEDs, 8 to F the left bank.
// W, X and Y mix the RGB LED.
module top (
  input  logic [19:0] PB,
  output logic [7:0]  LEFT, RIGHT,
  output logic        RED, GREEN, BLUE
);
  assign RIGHT = PB[7:0];
  assign LEFT  = PB[15:8];
  assign RED   = PB[16];  // W
  assign GREEN = PB[17];  // X
  assign BLUE  = PB[18];  // Y
endmodule

Buttons. The simplest design: wires. Press 0 to F for the LEDs, or W, X and Y for the RGB LED.

The board is blank. Press Program, or P, to load Buttons.

An illustration I made for this page, not the lab's interface. Each example is SystemVerilog compiled with Yosys when the site is built and run in your browser on a drawing of the ECE 270 breakout I designed. The port names are those of the lab's pin file. With focus on the board, the keys 0 to 9, A to F and W to Z press its buttons; its “?” lists the other keys.

Design decisions

Three choices shaped the driver, and each is in its block above: block transfers in readwriteIO, the Pi as bus master in the expanders, and the shims in FuncTrans.

Bring-⁠up

I wrote two test scripts in August 2023 and changed the driver in January 2024 “to match new FPGA PCB”. Both are in the readwriteIO and setupIO blocks; a July 2023 test of the FTDI route is under the expanders.

Results

No timing result is on record. ReadTest.py prints a pass time, but no run was saved, so the speed of the Pi path is not measured. The 400 kHz in my README is the bus clock setting.

The station set-⁠up script of January 2024 installs my driver under the reader and writer web apps on each station’s Pi, across the lab’s 40 to 50 stations. I first uploaded the driver for the v1.2 carrier; the I2C carrier page shows v2, a board of the same family.

Credit

The CherryPy web apps are the lab’s station software; I deployed them. I wrote the I2C driver layer under them and the toolchain guide.