FPGA Boot Loading Configuration

This guide covers methods to make your custom FPGA load automatically at Red Pitaya boot. By default, FPGA configuration persists only until the device is powered off, reset, or a new FPGA image is loaded.

See also

Prerequisites:

Before setting up boot loading, you need a working FPGA bitstream. See:


Understanding Persistence

FPGA Configuration Lifecycle

By default, FPGA configuration persists until one of these events occurs:

  1. Device is powered off or reset

  2. A new FPGA image is loaded (web applications, interface reload)

  3. FPGA configuration is changed through software

This section covers methods to make your custom FPGA load automatically at boot.

When to Use Boot Loading

Set up automatic boot loading when you:

  • Deploy a production system with custom FPGA

  • Want the same FPGA to load after every power cycle

  • Need consistent hardware configuration at startup

  • Run headless systems without manual intervention

  • Develop appliances with fixed FPGA functionality


Method 2: Using systemd Service (Alternative)

For advanced users who prefer systemd services, you can create a custom service that runs at boot. This method provides more control over service dependencies and startup order.

Note

The startup.sh method (Method 1) is simpler and recommended for most users. Use systemd services only if you need advanced features like service dependencies, restart policies, or logging.

When to Use systemd

Use systemd services when you need:

  • Fine-grained control over startup order

  • Service dependencies (start after network, etc.)

  • Automatic restart on failure

  • Advanced logging and monitoring

  • Integration with other systemd services

  • Service-level resource limits


Create systemd Service

Step 1: Create service file

redpitaya> rw
redpitaya> nano /etc/systemd/system/custom-fpga.service

Step 2: Add service configuration

[Unit]
Description=Load Custom FPGA at Boot
After=network.target

[Service]
Type=oneshot
ExecStart=/opt/redpitaya/sbin/overlay.sh v0.94 my_project
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

Step 3: Enable and start the service

redpitaya> systemctl daemon-reload
redpitaya> systemctl enable custom-fpga.service
redpitaya> systemctl start custom-fpga.service
redpitaya> ro

Step 4: Verify service status

redpitaya> systemctl status custom-fpga.service

To Disable

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

Method 3: Using /etc/profile.d (Login Method)

This method loads the FPGA when users log in via SSH. Not recommended for boot loading because:

  • Only runs when someone logs in (not at system boot)

  • Runs at every SSH login (can cause delays)

  • Can interfere with automated scripts

Use this method only if you specifically want FPGA loading triggered by user login rather than system boot.

Note

Since Red Pitaya automatically logs in the root user on boot, this method effectively runs at boot time for default setups. However, it still executes on every login.


Setup Procedure

Step 1: Create startup script

redpitaya> rw
redpitaya> nano /etc/profile.d/custom_fpga.sh

Step 2: Add load command

#!/bin/bash
/opt/redpitaya/sbin/overlay.sh v0.94 my_project

Step 3: Make executable

redpitaya> chmod +x /etc/profile.d/custom_fpga.sh
redpitaya> ro

Warning

This method runs at every login, not just at boot. This can cause:

  • FPGA reloading during active sessions

  • Login delays

  • Repeated initialization

Use Method 1 (startup.sh) instead for boot loading.


Method 4: Replace Default FPGA Image (Advanced)

This method overwrites the default Red Pitaya FPGA image with your custom one, making it the system default.

Warning

  • This modifies system files. Keep backups!

  • Only works for OS 2.00 or newer

  • Applications expecting v0.94 behavior will use your custom FPGA

  • Use Method 1 unless you specifically need system-wide replacement

When to Use This Method

Replace the default FPGA when:

  • You want all Red Pitaya applications to use your custom FPGA

  • The standard v0.94 project is never needed

  • You need system-wide FPGA replacement

  • Your custom FPGA maintains v0.94 register compatibility

Important

After using this method, commands like overlay.sh v0.94 will load your custom FPGA instead of the factory default.


Replacement Script

This script safely replaces the default FPGA with automatic backup:

Step 1: Create the script

redpitaya> nano /root/replace_fpga.sh

Step 2: Add script content

#!/bin/bash

BITSTREAM=$1
MODEL=$(/opt/redpitaya/bin/monitor -f)
PROJ=v0.94

# Enable read-write privileges
mount -o rw,remount /opt/redpitaya

# Check if backup already exists
if [ ! -f "/opt/redpitaya/fpga/$MODEL/$PROJ/fpga_orig.bit.bin" ]; then
    # Create backup of original fpga.bit.bin
    cp "/opt/redpitaya/fpga/$MODEL/$PROJ/fpga.bit.bin" \
       "/opt/redpitaya/fpga/$MODEL/$PROJ/fpga_orig.bit.bin"
fi

if [ $# -eq 0 ]; then
    # Restore original file
    cp -f "/opt/redpitaya/fpga/$MODEL/$PROJ/fpga_orig.bit.bin" \
          "/opt/redpitaya/fpga/$MODEL/$PROJ/fpga.bit.bin"
    conf="Restored original fpga.bit.bin"
else
    # Replace with custom image
    cp -f "$(realpath $1)" \
          "/opt/redpitaya/fpga/$MODEL/$PROJ/fpga.bit.bin"
    conf="fpga.bit.bin overwritten with $BITSTREAM"
fi

mount -o ro,remount /opt/redpitaya
echo "$conf"

Step 3: Make executable

redpitaya> chmod +x /root/replace_fpga.sh

Step 4: Replace default FPGA

redpitaya> ./replace_fpga.sh /root/red_pitaya_top.bit.bin

Step 5: Reboot to activate

redpitaya> reboot

To Restore Original FPGA

# 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.


Deprecated Methods

Using /etc/rc.local (Deprecated)

Warning

This method is deprecated in newer Linux distributions (Ubuntu 18.04+) and may not work on recent Red Pitaya OS versions. The rc.local service is no longer enabled by default in systemd-based systems.

Use Method 1 (startup.sh) or Method 2 (systemd service) instead.

For older systems where rc.local is still available, you can add commands to /etc/rc.local:

Step 1: Check if rc.local exists and is enabled

redpitaya> systemctl status rc-local.service

If the service is not found or is disabled, use Method 1 or Method 2 instead.

Step 2: Edit rc.local (if available)

redpitaya> rw
redpitaya> nano /etc/rc.local

Step 3: Add load command before exit 0

#!/bin/bash
/opt/redpitaya/sbin/overlay.sh v0.94 my_project
exit 0

Step 4: Make executable

redpitaya> chmod +x /etc/rc.local
redpitaya> ro

Step 5: Test by rebooting

redpitaya> reboot

Comparison of Methods

Method

Pros

Cons

startup.sh script

Recommended, Red Pitaya standard, simple, runs once at boot, easy to manage

Requires file editing

systemd service

Clean, manageable, advanced control, service dependencies

More complex, requires systemd knowledge

/etc/profile.d

Easy to add/remove

Only loads on login (not boot), runs at every login

Replace default

System-wide, affects all applications

Modifies system files, harder to revert

/etc/rc.local (deprecated)

Simple, single file

Deprecated, not available on newer systems

Recommendation: Use startup.sh script (Method 1) for most use cases. Use systemd service (Method 2) only if you need advanced service control features.


Troubleshooting Boot Loading

FPGA Not Loading at Boot

Check startup.sh syntax:

redpitaya> cat /opt/redpitaya/sbin/startup.sh
# Look for your FPGA loading command

Test the command manually:

# Try running the command directly
redpitaya> /opt/redpitaya/sbin/overlay.sh v0.94 my_project

# Check for errors
echo $?

Check file permissions:

redpitaya> ls -l /opt/redpitaya/sbin/startup.sh
# Should be executable

View boot logs:

redpitaya> journalctl -b | grep -i fpga
redpitaya> dmesg | grep -i fpga

Service Won’t Start (systemd)

Check service status:

redpitaya> systemctl status custom-fpga.service

View service logs:

redpitaya> journalctl -u custom-fpga.service

Verify service file syntax:

redpitaya> systemctl cat custom-fpga.service

Reload systemd configuration:

redpitaya> systemctl daemon-reload

Wrong FPGA Loads at Boot

Check loaded FPGA:

redpitaya> cat /tmp/loaded_fpga.inf

Check startup.sh for conflicts:

redpitaya> grep overlay.sh /opt/redpitaya/sbin/startup.sh
# Look for multiple FPGA loading commands

Check for multiple services:

redpitaya> systemctl list-units | grep fpga