Build Red Pitaya ecosystem

This guide explains how to build the Red Pitaya ecosystem, which includes FPGA bitstreams, Linux kernel, boot files, API libraries, SCPI server, and web applications.

Introduction

What is the ecosystem

The Red Pitaya ecosystem comprises all software and hardware components required for the Red Pitaya to function:

• FPGA bitstreams - Hardware logic designs for different applications

• Boot components - FSBL, U-Boot, and boot scripts

• Linux kernel - Operating system kernel and device tree files

• User-space components - API libraries, SCPI server, and web applications

• Development tools - Utilities and examples

The ecosystem is packaged as a ecosystem_*.zip file that can be deployed to the FAT32 partition of an SD card.

Ecosystem directory structure

The Red Pitaya source code is organized across multiple directories:

Directory	Contents
rp-api	API source code for librp.so, librp2.so, librp-gpio.so, librp-i2c.so, librp-spi.so, etc.
apps-free	WEB applications for the old (pre-2.00) environment (also with controller modules & GUI clients)
apps-tools	WEB interface home page and system management applications
Bazaar	Nginx server with dependencies, Bazaar module & application controller module loader
fpga	FPGA design (RTL, bench, simulation, and synthesis scripts) - SystemVerilog based [1]
OS	GNU/Linux operating system components
patches	Patches applied to the official Linux OS
scpi-server	SCPI server
Test	Command line utilities (acquire, generate, etc.) and tests
Examples	Examples in different programming languages for working with peripherals
build_scripts	Scripts for building an ecosystem and preparing images for memory cards

[1]

The FPGA design is located in the GitHub: RedPitaya-FPGA repository and will be cloned into the fpga/ subdirectory during the build process.

Prerequisites

Host system requirements

Red Pitaya ecosystem must be built on a Linux host system.

Red Pitaya ecosystem version	Host platform OS
Ecosystem 2.0 and higher	Ubuntu 22.04 LTS or higher
Ecosystem 1.04	Ubuntu 18.04 LTS or higher

For additional OS build requirements, refer to the OS build requirements section.

Required software packages

Install the following packages on your Ubuntu host system.

Basic development tools

# Generic dependencies
sudo apt-get install make curl xz-utils git cmake

# U-Boot build dependencies
sudo apt-get install libssl-dev device-tree-compiler u-boot-tools

# Secure chroot
sudo apt-get install schroot

# QEMU for ARM emulation
sudo apt-get install qemu qemu-user qemu-user-static

# 32-bit libraries
sudo apt-get install lib32z1 lib32ncurses5 libbz2-1.0:i386 lib32stdc++6

Python 3 and build tools

Python 3.10 or higher is required for building some ecosystem components.

sudo apt-get install python3 python3-pip
sudo pip3 install --upgrade pip
sudo pip3 install meson
sudo apt-get install ninja-build

Note

The Meson build system is optional and primarily used during development on x86 PCs.

Xilinx Vivado and SDK

The build process requires AMD Xilinx Vivado and SDK (bare metal toolchain).

Required versions

Red Pitaya ecosystem version	FPGA development tools
Ecosystem 2.0 and higher	Vivado 2020.1 and SDK 2019.1
Ecosystem 1.04	Vivado 2020.1 and SDK 2019.1

Warning

The Vivado and SDK versions are critical. Different versions are not compatible with each other. Ensure you install the exact versions listed above.

Note

Future Red Pitaya OS releases will migrate to Vitis. Currently, Vivado and SDK are still required.

Installation requirements

1. Follow the installation instructions in the Creating a Vivado SDK/Vitis project and Installation of Vivado sections

2. Install both Vivado and SDK - During the Vivado installation, ensure the SDK (bare metal toolchain) is also selected

3. Use default installation paths - Both tools should preferably be installed in their default locations (/opt/Xilinx/)

4. Create gmake symbolic link - Vivado requires gmake, which does not exist on Ubuntu:

   sudo ln -s /usr/bin/make /usr/bin/gmake
   

Virtual machine installation (optional)

If running Vivado from a virtual machine with installation on a host shared folder:

1. Use VirtualBox - VMware has a bug in VMware-tools for Ubuntu guests that prevents proper mounting of shared filesystems

2. Install Ubuntu without encryption - Encrypted installations block some Red Pitaya build procedures

3. Configure shared folders:

   • Open VirtualBox settings for your Ubuntu VM

   • Navigate to Shared Folders

   • Add the Xilinx installation directory from the host (typically /opt/)

   • Enable the “Auto-mount” option

4. Install VirtualBox guest additions:

   sudo apt-get install virtualbox-guest-dkms
   

5. Access shared folder - After rebooting, the Xilinx shared folder will be accessible under /media/sf_Xilinx (requires root privileges)

Red Pitaya source code

Clone the repository

Navigate to your preferred development directory and clone the repository:

git clone https://github.com/RedPitaya/RedPitaya.git
cd RedPitaya

The choice of specific branches or tags depends on your requirements.

Configure environment

Set the LC_ALL environment variable to C (required for locale-sensitive build tools):

echo $LC_ALL

If the command returns an empty line, set it:

export LC_ALL=C

To make this permanent, add the line to your ~/.bashrc file.

Warning

Building the ecosystem on an encrypted home directory is not supported, as schroot cannot access encrypted directories. Create a separate non-encrypted directory (e.g., /home/ecosystem_build) for building.

Understanding the Build Process

Build environment architecture

The Red Pitaya build process uses multiple environments:

• Local machine (x86) - FPGA bitstreams and Linux kernel are compiled here using cross-compilers

• Chroot environment (ARM) - User-space applications (API, SCPI server, web apps) are compiled in an emulated ARM environment

The build scripts automatically switch between these environments as needed.

Important notes

Before proceeding, understand these key points:

1. Not a standard Linux build - The build uses a Red Pitaya virtual ARM environment via schroot, not a regular cross-compilation setup

2. Ubuntu host required - The build must run on Ubuntu (native or VM). Windows, macOS, and WSL are not supported

3. Automatic environment switching - The build scripts handle switching between x86 and ARM environments automatically. Example of automatic switching:

   make -f Makefile.x86
   
   schroot -c red-pitaya-ubuntu <<- EOL_CHROOT
   make -f Makefile CROSS_COMPILE="" REVISION=$GIT_COMMIT_SHORT
   EOL_CHROOT
   
   make -f Makefile.x86 zip
   

4. Disk space requirements - Ensure at least 10 GB of free disk space for source code and compilation

Building the Ecosystem

The full build process creates a complete ecosystem package that can be deployed to Red Pitaya hardware.

Prepare the build environment

Step 1: Load build settings

The settings.sh script configures environment variables for Vivado and SDK. Edit this file if you used non-default installation paths:

source settings.sh

Step 2: Create download cache (optional)

Create a cache directory to store downloaded source tarballs (speeds up subsequent builds):

mkdir -p dl
export DL=$PWD/dl

Step 3: Download ARM Ubuntu environment

Download the pre-built ARM Ubuntu root environment from the Red Pitaya download server.

Ecosystem 2.00 and higherEcosystem 1.04

wget https://downloads.redpitaya.com/downloads/LinuxOS/redpitaya_OS_17-31-47_20-Mar-2025.tar.gz
sudo chown root:root redpitaya_OS_17-31-47_20-Mar-2025.tar.gz
sudo chmod 664 redpitaya_OS_17-31-47_20-Mar-2025.tar.gz

Note

Alternatively, you can create your own root environment by following the OS image build instructions.

Step 4: Configure schroot

Create the schroot configuration file: /etc/schroot/chroot.d/red-pitaya-ubuntu.conf

Replace placeholders with:

• Absolute path to the downloaded tarball

• Comma-separated list of users who should have build access

Ecosystem 2.00 and higherEcosystem 1.04

[red-pitaya-ubuntu]
description=Red Pitaya Debian/Ubuntu OS image
type=file
file=/absolute/path/to/redpitaya_OS_17-31-47_20-Mar-2025.tar.gz
users=your-username
root-users=your-username
root-groups=root
profile=desktop
personality=linux
preserve-environment=true

Full build procedure

Ecosystem 2.00 and higherEcosystem 1.04

Option 1: Automated build script

Build for all board models:

cd build_scripts
sudo ./build_OS.sh

Option 2: Manual build

Build step-by-step:

make -f Makefile.x86
schroot -c red-pitaya-ubuntu <<- EOL_CHROOT
make
EOL_CHROOT
make -f Makefile.x86 zip

Interactive ARM shell

To get an interactive ARM shell for debugging:

schroot -c red-pitaya-ubuntu

Note

Unlike Ecosystem 1.04, version 2.0 and higher builds for all board models simultaneously. Board-specific differences only affect FPGA bitstream compilation.

Partial Rebuild

You can rebuild individual components without rebuilding the entire ecosystem.

Available components

Ecosystem 1.04Ecosystem 2.00 and higher

The following components can be built separately:

• FPGA and device tree

• U-Boot

• Linux kernel

• API

• SCPI server

• Free applications

Setup build environment

Ecosystem 1.04Ecosystem 2.00 and higher

Configure Vivado and SDK for cross-compilation:

source settings.sh

On some systems (including Ubuntu 18.04), Vivado’s library setup can conflict with system libraries. Disable Vivado library overrides if needed:

export LD_LIBRARY_PATH=""

Package the ecosystem

Ecosystem 2.00 and higherEcosystem 1.04

After building components, package them into a zip archive:

make -f Makefile.x86 zip

Build FPGA bitstream and device tree

Ecosystem 2.00 and higherEcosystem 1.04

Each FPGA version uses device tree overlays. Build for specific board models:

make -f Makefile.x86 fpga MODEL=Z10
make -f Makefile.x86 fpga MODEL=Z20
make -f Makefile.x86 fpga MODEL=Z20_125
make -f Makefile.x86 fpga MODEL=Z20_125_4CH
make -f Makefile.x86 fpga MODEL=Z20_250_12

For detailed instructions, see building the FPGA.

Note

Build only the models you need to speed up the build process.

Build U-Boot

Ecosystem 2.00 and higherEcosystem 1.04

Build U-Boot binary and boot scripts:

make -f Makefile.x86 boot

This downloads the Xilinx U-Boot source from GitHub, applies Red Pitaya patches (from patches/ directory), and builds.

Note

Two versions of boot.bin are created:

• One for boards with 512 MB RAM

• One for boards with 1 GB RAM

Two versions of Linux kernel boot scripts are also created.

Note

The device tree for U-Boot is built using files from the dts_uboot/ folder, defining minimum peripheral requirements for board startup.

Build Linux kernel and device tree binaries

Ecosystem 2.00 and higherEcosystem 1.04

Build the Linux kernel and device tree:

make -f Makefile.x86 linux
make -f Makefile.x86 devicetree

This downloads the Xilinx Linux kernel source from GitHub, applies Red Pitaya patches (from patches/ directory), and builds.

Note

Device tree builds require FPGA projects to be built first, as dtb and dts files are based on FPGA barebone projects.

Build boot file

Ecosystem 2.00 and higherEcosystem 1.04

Build user-space applications

Ecosystem 2.00 and higherEcosystem 1.04

Build individual components in the ARM chroot environment:

schroot -c red-pitaya-ubuntu <<- EOL_CHROOT
make api
make nginx
make scpi
make sdr
make bode
make monitor
make generator
make acquire
make calib
make daisy_tool
make spectrum
make led_control
make ecosystem
make updater
make main_menu
make scpi_manager
make streaming_manager
make calib_app
make network_manager
make jupyter_manager
EOL_CHROOT

Note

Some components have dependencies on each other. Use make all to build everything at once.

Component-Specific Information

The following sections provide additional details for specific components.

API library

Build the Red Pitaya API library:

schroot -c red-pitaya-ubuntu <<- EOL_CHROOT
make api
EOL_CHROOT

Output files:

• Library: api/lib/librp.so

• Header file: api/includes/redpitaya/rp.h

Install to Red Pitaya:

scp build/api/lib/*.so root@192.168.0.100:/opt/redpitaya/lib/

Replace 192.168.0.100 with your Red Pitaya’s IP address (or use the .local address).

U-Boot EEPROM configuration

U-Boot variables are stored in EEPROM but are not read automatically during boot. Default constant values are used if EEPROM is not read.

To update and recalculate variable values from EEPROM:

i2c dev 0
# Offset 0x1800 + 0x4 (crc32)
eeprom read  0 0x50 0 0x1804 0x400
env import -b 0 0x400 hw_rev serial ethaddr

SCPI server

Build the SCPI server:

schroot -c red-pitaya-ubuntu <<- EOL_CHROOT
make scpi
EOL_CHROOT

Output file: scpi-server/scpi-server

Install to Red Pitaya:

scp scpi-server/scpi-server root@192.168.0.100:/opt/redpitaya/bin/

Replace 192.168.0.100 with your Red Pitaya’s IP address (or use the .local address).

Note

Red Pitaya uses a customized SCPI parser with optimized functions for Red Pitaya hardware.

For more information, see the SCPI server README.

Legacy web applications

To build applications from the apps-free directory, follow the instructions in the repository.

Warning

Applications in apps-free were developed for Ecosystem 1.04 and earlier. They require modification to work with Ecosystem 2.00 and higher.