HackerBox 0088: FPGA Lab

Welcome to HackerBox 0088. We will explore Field Programable Gate Array (FPGA) technology and hardware description languages (HDL) such as Verilog. Configure an open source tool chain to synthesize FPGA projects. Assemble the HackerBox FPGA Lab Kit. Experiment with FPGA logic, memories, state machines, and soft processor cores. Integrate FPGA output ports, input ports, analog to digital conversion, display drivers, and other peripheral devices.

HackerBox is the original monthly subscription box for electronics, computer technology, and hacker culture. Each HackerBox is a discovery box, which means all members await and enjoy a new surprise each month. Tech, toys, knowledge, and fun. It's like having a hacker convention, your birthday, and the first day of school - every month - right in your mailbox.

There is a wealth of information for current and prospective members in the HackerBoxes FAQ. Almost all of the non-technical support emails that we receive are already answered there, so we'd really appreciate it if you can take a few minutes to read the FAQ.

This Instructable contains information for getting started with HackerBox 0088. The full box contents are listed on the product page for HackerBox 0088 where the box is also available for purchase while supplies last. If you would like to automatically receive a HackerBox like this right in your mailbox each month, you can subscribe at HackerBoxes.com and join the party. Subscribers save at least $15 every month and get each new HackerBox shipped immediately off of the production line.

A soldering iron, solder, and basic assembly tools are generally needed to work on the monthly HackerBox. A computer for running software tools is also required. Have a look at the HackerBox Workshops for basic tools and a wide array of introductory activities and experiments.

The most import thing you will need is a sense of adventure, hacker spirit, patience, and curiosity. Building and experimenting with electronics, while very rewarding, can be tricky, challenging, and even frustrating at times. The goal is progress, not perfection. When you persist and enjoy the adventure, a great deal of satisfaction can be derived from this hobby. Take each step slowly, mind the details, and don't be afraid to ask for help.

WEAR SAFETY GLASSES WHEN SOLDERING, WHEN TRIMMING WIRE LEADS, OR WHEN CUTTING, DRILLING, ETC.

A field-programmable gate array (FPGA) is an integrated circuit designed to be configured by a customer or a designer after manufacturing – hence the term field-programmable. The FPGA configuration is generally specified using a hardware description language (HDL), similar to that used for an application-specific integrated circuit (ASIC). Circuit diagrams were previously used to specify the configuration, but this is increasingly rare due to the advent of electronic design automation tools. (Wikipedia)

FPGAs contain an array of programmable logic blocks, and a hierarchy of reconfigurable interconnects allowing blocks to be wired together. Logic blocks can be configured to perform complex combinational functions, or act as simple logic gates like AND and XOR. In most FPGAs, logic blocks also include memory elements, which may be simple flip-flops or more complete blocks of memory.

While the Digi-Key video references a Lattice iCEstick evaluation kit, the general notions behind FPGAs apply equally to the Tang Nano FPGA kit that we'll be using here.

Check out Recommended FPGA Sites from Project F.

A hardware description language is a specialized computer language used to describe the structure and behavior of electronic circuits, and most commonly, digital logic circuits. (Wikipedia) An HDL is not "run" on hardware the way a software programming language is. A software program is usually executed on hardware such as a microprocessor. Instead an HDL is used to specify what an actual piece of hardware is and how it operates.

An HDL description can be used for analysis and simulation of an electronic circuit. The description can also be synthesized into a netlist specifying physical electronic components and how they are connected together. The netlist can then be place-and-routed to produce the set of masks to create an integrated circuit (IC chip). In the case of an FPGA, instead of masks, a bitstream is generated to configure connection within the FPGA.

A hardware description language looks much like a programming language such as C or ALGOL; it is a textual description consisting of expressions, statements and control structures. One important difference between most programming languages and HDLs is that HDLs explicitly include the notion of time.

The two most widely used and well-supported HDL varieties, used in industry, are Verilog and VHDL.

Verilog, the HDL we'll be using in here, is standardized as IEEE 1364. Verilog is widely used in both the design and verification of digital circuits.

Verilog Quick Reference

We suggest working through the setup and LED counter demo in this step before soldering pins onto, or connecting anything to, the FPGA module. Simply use the USB-C cable.

The Tang Nano 9K development board is based on the Gowin GW1NR-9 LittleBee FPGA chip. The development board also integrates USB-C, HDMI, microSD, and six LEDs. The FPGA itself features 8640 LUT4 (four-input look up table) blocks, 6480 FlipFlops, 608K Flash, and 64M SDRAM. The 8640 LUT4 units can be used to synthesize a variety of complex logic circuits. There are even enough logic blocks to build a complete PicoRV RISC-V soft core.

Setting up development tools for FPGAs has traditionally been a long and expensive proposition. Luckily, things keep getting better and better. It is still not trivial, so grab a coffee, breathe deep, and take your time. We suggest starting with the online lesson from Lushay Labs entitled, Tang Nano 9K: Getting Setup. The lesson will guide you through configuring an open source toolchain and works through a first Verilog example counter.v.

Once your counter.v project is working, it is time to celebrate. Seriously. That was a huge step. It might feel like you just typed in a little program, but remember HDL is not program code... You actually just created hardware!

The HackerBox FPGA Lab supports experimenting and prototyping with various aspects of FPGAs by connecting inputs, outputs, peripheral interfaces, and more. The interconnection header points allow these activities to be performed using standard jumper wires.

Kit Contents

• Exclusive HackerBox FPGA Lab PCB
• 128x64 OLED 0.96 inch Display (SSD1306 Driver with SPI)
• 8x8 LED Matrix (1088AS)
• ADS1115 16bit Analog to Digital Module
• Eight Bit DIP Switch
• PS/2 Jack - 6 Pin mini DIN
• 100K Potentiometer
• Four Tactile Momentary Button
• SMD Resistors (120R, 1K, 2K, 10K)
• Header Pins and Sockets

Assembly Notes

RESISTORS: Start by placing the SMD resistors on the back of the board. Resistors are not polarized and can be oriented in either direction. There are two 120 ohm resistors (marked "121"), two 2K resistors (marked "202"), and eight 1K resistors (marked "102"). Place these according to the PCB markings. There are also twelve 10K resistors (marked "103") that do not need to be populated. You can place them, but they are not strictly necessary, so feel free to leave them off. We will discuss these (unnecessary) 10K resistors in a later step.

TOP SIDE COMPONENTS: Aside from the SMD resistors, all of the other components are placed on the top side of the FPGA Lab PCB. Look at the main image (scroll way up) to see an assembled kit showing where the components go. Most of the placement is fairly obvious from the image, but here are some important points that may be less obvious...

LED MATRIX: The 8x8 LED Matrix must be orientated in a specific direction. There is a tiny "1" marking next to one of the pins on the back of the matrix. This needs to match to to "pin 1" as marked on the PCB silkscreen. To double check, when the matrix is in this correct orientation, the "1088AS" part number stamped on the matrix should be facing the FPGA module (downward, not upward).

RED HEADER PIN STRIPS: From the image of the assembled kit, we can see that the three red header strips need to be divided into 12 sections. Start by cutting the longest strips (24 pins) first and working down to the strip of three pins. (greedy algorithm). These red header points are used to connect various elements of the FPGA Lab PCB while experimenting or prototyping with the FPGA.

FPGA MODULE HEADERS: The black male header strips that came in the plastic box with the FPGA module should be used for the FPGA module since they are already the correct length. The two long black female header strips can be cut down to match the length of the male FPGA headers to form a pluggable socket for the FPGA module.

A trick for cutting the female headers is to carefully cut into the middle of the next socket hole beyond the last one required. The pin inside that cut socket hole will fall out once that hole is cut open. This will leave the required number of header socket holes undamaged with their pins intact.

To align the headers for soldering, many like to insert the headers (two male and two female) between the FPGA and the PCB as they will be in their final application. The four rows of solder points (two on top and two on the bottom) can then be soldered. Take care not to let too much solder wick in from the PCB side (bottom) as this can bond the male header inside the female header which obviously defeats the point of created a pluggable socket.

OPTIONAL PMOD HEADERS: The two 2x6 headers (PMOD1 and PMOD 2) are not populated.

Post Assembly Test

After assembly, but before re-programming the FPGA module, power the module backup. The last demo (counter.v) should still operate perfectly. If it does not, cut the power and search for short circuits.

Use 16 jumper wires to connect the 8x8 LED matrix to the FPGA as shown in the drawing.

Download the github repository. Open the sweep8x8 example folder and use the Verilog and constraint files within to configure the FPGA.

OUTPUT DISPLAY

Leave the 8x8 LED matrix attached as it was in the last step.

DIP SWITCH

Connect the header above the 8bit DIP switch to the red pins of the FPGA Lab like so:

HDR --- Lab PCB
COM     3V3
bit1    29
bit2    30
bit3    33
bit4    34
bit5    40
bit6    53
bit7    54
bit8    55
PD      N.C.

The eight numbered I/O pins connect to the 24 pin header just under the FPGA module.

The COM (common) pin can be connected to the six pin 3V3 header just under the OLED module. The COM pin is connected to the "ON" side of each switch by PCB traces. Accordingly, each switch is wired to go high (+3.3V) when switched "ON". Assuming the 10K pulldown resistors are unpopulated, the PD (pulldown) pin is not used, and can be left unconnected. We do not need the pulldown resistors or the PD pin since the input pins to the FPGA have pulldowns activated in the constraint file.

Alternatively, we can populate the 10K pulldown resistors and connect the PD pin to GND and then we would not need to set the pulldown mode active in the constraint file.

Using the 10K resistors on the PCB or activating the pulldowns within the FPGA both accomplish the same result. That is, when a switch is "OFF" the corresponding input to the FPGA is low (pulled down to 0V).

BUTTONS

Next, connect the header above the four buttons like so:

HDR --- Lab PCB
COM     3V3
SW1     56
SW2     57
SW3     68
SW4     69
PD      N.C.

As with the DIP Switch, the COM (common) pin connects to one side of each button so the signal to the FPGA goes high (+3.3V) when the button is pressed. Either populating the 10K pulldown resistors on the PCB or activating the pulldowns within the FPGA both accomplish keeping the button signals to the FPGA low (0V) when the corresponding button is not pressed.

CONFIGURE THE FPGA

From the same github repo as the last step, open the switchlatch example folder. Note the "PULL_MODE=DOWN" designations in the constraint file. Use the Verilog and constraint files in the switchlatch folder to configure the FPGA.

OPERATION

Pressing the buttons will latch the DIP switch settings into registers mapped to a corresponding row of the 8x8 LED Matrix.

Imagine having to store ("deposit") code and data into a computer using switch settings like this. In fact, early electronic computers (like the Altair 8800) would leverage a front panel to input and display the machine's internal registers and memory. Front panels usually consisted of indicator lights, toggle switches, and push buttons. (Wikipedia)

OPTIONAL KEYBOARD

A PS/2 type keyboard interface is provided via a four pin header [GND, CLK, DAT, 5V]. The GND and 5V pins must be jumper wired to the corresponding pins of the FPGA. The 5V rail is required to power the keyboard. The two 120 ohm and two 2K resistors on the Lab PCB shift the clock and data signals into the 3.3V range that can be read into the FPGA. Let this Verilog PS/2 Keyboard example motivate your experimentation. However, we have not yet tested it with the FPGA Lab hardware.

Using seven jumper wires, connect the 128x64 OLED display to the Lab PCB, like so:

OLED ------ Lab PCB
GND         GND
VCC (VDD)   3V3
D0 (SCK)    27
D1 (SDA)    26
RES         25
DC          39
CS          36

GND and 3V3 can be connected to the six pin power headers just under the OLED module.

For the five FPGA pins, it might be helpful to use longer jumper wires, or add on five male-female jumper wires as "extensions" to the provided female jumper wires to span the longer distance between the FPGA and the OLED header at the top of the Lab PCB.

These pins are specified because they are used in Lushay Labs lesson Tang Nano 9K: OLED Screen 101. However, you can change the constraints to use others pins (in the 3.3V banks) if you wish.

Download Lushay Labs' github repository which includes several example projects (including counter.v that we used earlier). Four of the examples: screen, screen_txt, screen_data, lfsr demonstrate use of the OLED display with the FPGA.

FPGAs generally do not support analog I/Os, so let's attach the ADS1115 analog to digital converter (ADC) module like so:

ADC --- Lab PCB
A3      N.C.
A2      N.C.
A1      GND
A0      Potentiometer Center Pin
ALERT   N.C.
ADDR    3V3
SDA     31   (PCB is incorrectly labeled as "SCL")
SCL     32   (PCB is incorrectly labeled as "SDA")
GND     GND
VCC     3V3

Also connect the left pin of the potentiometer header to 3V3 and the right pin to GND. This configuration allows the potentiometer to act as a variable voltage divider with its output feeding the A0 input to the ADC.

Note that the PCB markings on the ADC header have the SDA and SCL pins reversed. Connect the one next to the GND pin to FPGA pin 32, and the one next to the ADDR pin to FPGA pin 31 as shown in the table above.

Use the example project ads1115_adc (from the Lushay Labs repo) to demonstrate operation of the ADC with output to the OLED display. There is also an online lesson corresponding to the project. Appreciate there is no microcontroller or processor code involved in this example.

A CPU (central processing unit) is the electronic circuitry that executes instructions comprising a computer program. The CPU performs basic arithmetic, logic, controlling, and input/output (I/O) operations specified by the instructions in the program. Most modern CPUs are implemented as integrated circuit (IC) chip microprocessors. (Wikipedia)

As discussed earlier, HDL code is not executed on a CPU because it isn't program code. Instead, HDL code describes how to create (synthesize) hardware. So while HDL code doesn't "run" on a CPU, HDL code can be used to create a CPU. Because a CPU is hardware.

As background, consider Ben Eater's breadboard computer project. Ben built an 8-bit computer from scratch on breadboards using only simple logic gates. Obviously, those logic gates can be wired together inside an FPGA instead of using breadboards.

Lushay Labs has a beautiful lesson entitled Tang Nano 9K: Our First CPU.

Sipeed provides a RISC-V CPU with HDMI (updated files here) based on the PicoRV32 project.

The Pmod interface (peripheral module interface) is an open standard defined by Digilent for connecting peripheral modules to FPGA and microcontroller development boards. (Wikipedia)

The two Pmod headers (PMOD1 and PMOD 2) on the FPGA Lab PCB are not populated for this kit. Using them will require female right angle 2x6 pin headers with 0.1 inch pin pitch similar to this one available from Digi-Key.

The blue template pinout in the image is from the Digilnet Specification Document. The two black pinouts show how those pins map onto the two headers of the FPGA Lab PCB. The numbered pins of the black headers designate the I/O pin connections to the FPGA. Note that the I/O pins in PMOD2 support 3.3V logic, while most of the I/O pins in PMOD1 map into "Bank 3" of the FPGA which operates at 1.8V logic.

A variety of PMOD modules can be browsed from Digi-Key under Evaluation Boards - Expansion Boards, Daughter Cards. Select the "Pmod" entry under the "Series" search filter parameter.

We hope you are enjoying this month's HackerBox adventure into electronics, computer technology, and hacker culture. Reach out and share your success in the comments below or other social media. Also, remember that you can email support@hackerboxes.com anytime if you have a question or need some help.

What's Next? Join the party and live the HackLife. Get a cool box of hackable gear delivered right to your mailbox each month and enjoy a generous member discount. Surf over to HackerBoxes.com right now to sign up for your monthly HackerBox subscription.

Please consider sharing this free Instructable with others who may be interested in learning about these subjects. We really appreciate your support and "word of mouth advertising" is the most powerful marketing!