FPGA Reprogramming Guide

This guide covers the basics of loading FPGA bitstreams on Red Pitaya boards. Learn how to load pre-built FPGA projects, upload custom designs, verify configuration, and revert to factory settings.

See also

Advanced Topics:

• FPGA Boot Loading Configuration - Make your FPGA load automatically at boot

• Advanced FPGA Loading - Custom bitstreams, device trees, practical workflows, and FAQ

• Device Tree - Device tree configuration for custom hardware

• Signal Mapping - Hardware signal connections and pinout

Overview

Understanding FPGA Loading Methods

Red Pitaya uses different FPGA loading mechanisms depending on the OS version:

OS Version	Method	Key Features
1.04 or older	Direct /dev/xdevcfg access	Simple but no device tree management
2.00 to 2.05-37	fpgautil command	Linux FPGA Manager framework
2.07-43 or newer	overlay.sh script	Automated device tree handling, verification

Note

Starting with OS 2.00, Red Pitaya adopted the Linux FPGA Manager framework, which provides better integration with the kernel and enables device tree overlay support.

When to Use This Guide

Use this guide when you need to:

• Load a custom FPGA design you created

• Switch between different pre-built FPGA projects

• Test FPGA modifications during development

• Verify FPGA configuration

• Revert to factory FPGA settings

For advanced topics like boot loading, custom device trees, and partial reconfiguration, see the Advanced FPGA Loading guide.

Prerequisites

Hardware and Access

• Red Pitaya board powered and connected to the local network

• SSH access to the Red Pitaya device

File Requirements

Depending on your use case, you’ll need:

For OS 2.00 or newer:

• Binary bitstream file (.bit.bin)

• Device tree overlay file (.dtbo) - optional for custom peripherals (see Advanced FPGA Loading)

For OS 1.04 or older:

• FPGA bitstream file (.bit)

Command Line Notation

Throughout this guide:

• Commands with “redpitaya>” prefix - Execute inside Red Pitaya Linux OS after establishing an SSH connection

• Commands without the prefix - Execute in your computer’s local terminal or command prompt

Quick Start

For experienced users who just need the commands:

OS 2.07-43 or newerOS 2.00 to 2.05-37OS 1.04 or older

# Upload bitstream
scp red_pitaya_top.bit.bin root@rp-xxxxxx.local:/root

# Load FPGA
ssh root@rp-xxxxxx.local
redpitaya> fpgautil -b /root/red_pitaya_top.bit.bin

# Or load pre-built project
redpitaya> /opt/redpitaya/sbin/overlay.sh v0.94 v0.94

Preparing FPGA Files

Converting .bit to .bit.bin

If you have a .bit file from Vivado, convert it to .bit.bin format for OS 2.00+.

Note

This conversion is only needed for Red Pitaya OS 2.00 or newer. OS 1.04 uses .bit files directly.

Navigate to .bit File Location

Open your terminal and go to the directory containing your bitstream:

cd <Path/to/RedPitaya/repository>/prj/<project_name>/project/redpitaya.runs/impl_1

Note

On Windows, change forward slashes to backward slashes in paths.

Create .bif File and Generate .bit.bin

The bootgen tool converts the bitstream using a .bif (Boot Image Format) configuration file.

LinuxWindows (Vivado TCL Console)

echo -n "all:{ red_pitaya_top.bit }" > red_pitaya_top.bif
bootgen -image red_pitaya_top.bif -arch zynq -process_bitstream bin -o red_pitaya_top.bit.bin -w

Tip

The difference between Linux and Windows is in the echo command:

• Linux: Use echo -n to avoid newline characters

• Windows: Standard echo without -n flag

Uploading Files to Red Pitaya

Transfer Bitstream via SCP

Use the scp command to copy files from your computer to Red Pitaya:

For OS 1.04 or older (.bit file):

scp red_pitaya_top.bit root@rp-xxxxxx.local:/root

For OS 2.00 or newer (.bit.bin file):

scp red_pitaya_top.bit.bin root@rp-xxxxxx.local:/root

Tip

For graphical file transfer on Windows, use WinSCP or FileZilla.

Verify File Upload

Connect via SSH and check the files:

redpitaya> cd
redpitaya> ls -lh

You should see your uploaded files in the /root directory.

Loading FPGA

Choose the method appropriate for your Red Pitaya OS version.

OS 2.07-43 or Newer (Recommended)

For OS 2.07+, you can use either fpgautil (for bitstream only) or overlay.sh (for bitstream + device tree).

Loading Pre-Built FPGA Projects

Red Pitaya includes pre-built FPGA images. Load them directly by name:

# Load default v0.94 project
redpitaya> /opt/redpitaya/sbin/overlay.sh v0.94

# Load streaming application
redpitaya> /opt/redpitaya/sbin/overlay.sh stream_app

# Load logic analyzer
redpitaya> /opt/redpitaya/sbin/overlay.sh logic

Note

overlay.sh reads the Red Pitaya board profile and then loads the matching files from /opt/redpitaya/fpga/<model>/<project>/. This is why the same command name works across different board models.

Loading Custom Bitstream

For simple FPGA loading without device tree changes:

# Load bitstream only (keeps current device tree)
redpitaya> fpgautil -b /root/red_pitaya_top.bit.bin

For advanced custom configurations with device trees, see Advanced FPGA Loading.

OS 2.00 to 2.05-37 (fpgautil Method)

Starting with OS 2.00, Red Pitaya adopted the Linux FPGA Manager framework. Use the fpgautil command to load bitstreams.

Loading FPGA Bitstream

1. Ensure the .bit.bin file is uploaded to Red Pitaya

2. Load using fpgautil:

   redpitaya> fpgautil -b red_pitaya_top.bit.bin
   

Features:

• Uses Linux FPGA Manager framework

• Validates bitstream compatibility

• Reports loading status

OS 1.04 or Older (Legacy Method)

This method uses direct access to the /dev/xdevcfg device for FPGA configuration.

Loading FPGA Bitstream

1. Ensure the .bit file is uploaded to Red Pitaya

2. Load the bitstream:

   redpitaya> cat red_pitaya_top.bit > /dev/xdevcfg
   

The FPGA is immediately reconfigured with your design.

Limitations:

• No device tree management

• No automatic verification

Verification and Troubleshooting

Confirming FPGA Configuration

There are several ways to confirm that the FPGA has been successfully reprogrammed.

Method 1: Check Status Files (OS 2.07+)

The overlay script creates verification files:

Check loaded project identifier:

redpitaya> cat /tmp/loaded_fpga.inf

Example outputs:

v0.94                      # Standard project
v0.94_my_project           # Custom bitstream
v0.94_my_project_dtbo      # Custom bitstream + device tree

Check detailed loading information:

redpitaya> cat /tmp/update_fpga.txt

Example output:

Commit a1b2c3d4
FPGA md5sum: d41d8cd98f00b204e9800998ecf8427e  /opt/redpitaya/fpga/Z10/v0.94/fpga.bit.bin
Tue Oct 24 10:30:45 UTC 2025

Method 2: Check FPGA Manager State

Verify the FPGA Manager successfully loaded the configuration:

redpitaya> cat /sys/class/fpga_manager/fpga0/state

Expected output: operating

Other possible states:

• unknown - FPGA Manager not initialized

• write init - Starting configuration

• write - Writing bitstream

• write complete - Bitstream written successfully

• write error - Configuration failed

Method 3: Check Custom Register

If your FPGA design includes an ID register, verify it directly:

redpitaya> /opt/redpitaya/bin/monitor 0x40300050

The command should return your expected register value (e.g., 0xfeedbacc from the Adding a custom component tutorial).

Method 4: Test LED Patterns

For designs that control LEDs, observe the 8 yellow LEDs on the board to verify your custom pattern.

Common Issues and Solutions

Error: “BIN FILE loading through FPGA manager failed”

sh: 1: echo: echo: I/O error
BIN FILE loading through FPGA manager failed

Possible causes and solutions:

1. Bitstream incompatible with board model

   Check your Red Pitaya model and verify build flags:

   redpitaya> /opt/redpitaya/bin/monitor -f
   

   Rebuild FPGA with correct model flags (MODEL=Z10, MODEL=Z20, etc.)

2. Corrupted bitstream file

   Verify file integrity:

   redpitaya> ls -lh /root/red_pitaya_top.bit.bin
   redpitaya> md5sum /root/red_pitaya_top.bit.bin
   

   Re-generate and re-upload the file if sizes don’t match (~2-4 MB typical)

3. Wrong file path or filename

   Ensure exact filename:

   redpitaya> ls /opt/my_project/
   # Must show: fpga.bit.bin (case-sensitive!)
   

4. Incorrect .bit to .bit.bin conversion

   Verify bootgen command completed without errors and retry conversion

Error: “Device tree overlay not found”

For standard device tree:

Check that base project exists:

redpitaya> MODEL=$(/opt/redpitaya/bin/monitor -f)
redpitaya> ls /opt/redpitaya/fpga/$MODEL/v0.94/fpga.dtbo

For custom device tree:

Ensure file exists and has correct name:

redpitaya> ls /opt/my_project/fpga.dtbo

FPGA Loads But Applications Don’t Work

Possible causes:

1. Device tree mismatch - FPGA hardware doesn’t match device tree description

   • Regenerate device tree from Vivado (see Device Tree)

   • Verify register addresses match your FPGA design

   • Check that peripheral names and properties are correct

2. Custom peripherals not accessible

   Test register access:

   # Try reading a register (use your address)
   redpitaya> /opt/redpitaya/bin/monitor 0x40000000
   

   If reads return 0 or fail, check device tree memory regions

3. Incorrect clock configuration

   • Verify PL clocks are enabled in FPGA design

   • Check clock frequencies match device tree specifications

   • Ensure AXI clock domains are correctly configured

For more troubleshooting guidance, see the comprehensive FAQ in Advanced FPGA Loading.

Reverting to Factory FPGA

If you want to return to the official Red Pitaya FPGA, use these methods.

Method 1: Reload Factory FPGA (Simple)

For OS 2.00 or newer, simply load the default project:

OS 2.07+ (overlay.sh)OS 2.00-2.05 (fpgautil)

redpitaya> /opt/redpitaya/sbin/overlay.sh v0.94 v0.94

Or restart your Red Pitaya:

redpitaya> reboot

Note

This works unless you’ve configured boot loading (see FPGA Boot Loading Configuration) or replaced the default FPGA image.

Method 2: Disable Boot Loading

If you set up automatic FPGA loading at boot, disable it:

For startup.sh method:

redpitaya> rw
redpitaya> nano /opt/redpitaya/sbin/startup.sh
# Comment out or remove your FPGA loading line
redpitaya> ro
redpitaya> reboot

For systemd service:

redpitaya> rw
redpitaya> systemctl disable custom-fpga.service
redpitaya> systemctl stop custom-fpga.service
redpitaya> ro
redpitaya> reboot

See FPGA Boot Loading Configuration for complete boot loading management.

Method 3: Restore Replaced FPGA Image

If you used the replacement script to overwrite system files (advanced method):

# Run the replacement script without parameters
redpitaya> /root/replace_fpga.sh

# Reboot to activate
redpitaya> reboot

This restores the backup created when you first replaced the default image.

Method 4: Manual Revert (OS 1.04)

For OS 1.04, reboot to reload the factory FPGA:

redpitaya> reboot

The factory FPGA loads automatically at boot on OS 1.04.

Related Documentation

FPGA Documentation:

• FPGA Boot Loading Configuration - Make FPGA load automatically at boot

• Advanced FPGA Loading - Advanced loading scenarios, workflows, and FAQ

• Device Tree - Device tree configuration for custom hardware

• Signal Mapping - Hardware signal connections and pinout

Developer Guides:

• Red Pitaya FPGA Developer Guide - FPGA development overview

• Adding a custom component - FPGA tutorial

• C++ and Python API - Software interface

Application Examples:

• Red Pitaya GitHub repository - Example designs

• Red Pitaya forum - Community projects