2.4. Prepare SD card

In this section you will find instrucitons on how to install the Red Pitaya OS on an SD card.

2.4.1. Quick installation instructions

The following steps will guide you through the process of installing the Red Pitaya OS on an SD card.

1. Select the latest Red Pitaya OS version image and download it.

   

2. Use a disk image writing tool (for example, Balena Etcher) to write the image onto the SD card. Instructions are available for various operating systems:

   • Windows.

   • Linux.

   • macOS.

3. Insert the SD card into the Red Pitaya.

   

4. Connect the power supply and ethernet cable and check the status LED sequence during boot.

   If you spot any unexpected behaviour, please check the FAQ troubleshooting section.

5. Connect to the board via the web interface. For more information check the quick start instructions.

6. When updating between major software releases (for example, from 1.04 to 2.00), reset the calibration parameters to Factory Default (or recalibrate your Red Pitaya).

Note

To see all options for updating the OS, please refer to the Update Red Pitaya OS section.

2.4.2. OS Versions

The OS versions are listed from newest to oldest. Each listed OS version consists of an image download link (to download the OS image) and a changelog link (listing the major changes in the OS).

Latest 2.00 OS

Note

One OS to rule them all. The 2.00 OS versions work on all Red Pitaya board models.

RedPitaya OS 2.0:

• Latest Beta (2.05-37) - CHANGELOG (MD5 (extracted): ad55cb45cf92bf8e40e3901f24a677ba).

• Latest Stable (2.04-35) - CHANGELOG (MD5 (extracted): d3d59bca29421987550289fce29b87b5).

Note

When updating the OS to 2.00 version from 1.04 or older (or downgrading from 2.00 to 1.04 or older), a factory reset of calibration parameters must be performed. Please open the Red Pitaya’s web interface and head to System => Calibration => Manual DC calibration. Click on Reset, select Factory, and confirm the reset. For more details on calibration, please see the Calibration application.

Note

If you have problems running the 2.00 version of the OS and you updated from the 1.04 or older OS image, please check this GitHub solution. For all other problems please contact the support team.

1.04 OS

The 1.04 OS versions are board model specific. Please download only versions compatible with your board type.

Here is a video on how to identify the Red Pitaya board model and install 1.04 or older OS to the SD card.

STEMlab 125-14 & STEMlab 125-10:

• 1.04-28 - CHANGELOG (MD5 (zipped): 92e14e68d27e63568fb87954239e9fb0).

• 1.04-18 - CHANGELOG (MD5 (zipped): f6cde9b3264a12372873d039535e58d5).

STEMlab 125-14 (SECONDARY/SLAVE board) (not recommended - use 2.00 version instead):

• 1.04-06 - CHANGELOG (MD5 (zipped): ef928d3014d806539e4360e59b7f6a99).

STEMlab 125-14-Z7020:

• 1.04-14 - CHANGELOG (MD5 (zipped): c740aab5d7b374924f19171e1edd3161).

• 1.04-10 - CHANGELOG (MD5 (zipped): 3770f34e954674b0423db33ed8a3471d).

STEMlab 125-14 4-Input (not recommended - use 2.00 version instead):

• 1.04-03 - CHANGELOG (MD5 (zipped): 414c1e7572ec116657a356f3ee2000ac).

SDRlab 122-16:

• 1.04-15 - CHANGELOG (MD5 (zipped): ba9f8be2f19630b42ee7b56bdd1d4392).

• 1.04-11 - CHANGELOG (MD5 (zipped): 634cf27555d4ae8900c92833afc1ddb9).

SIGNALlab 250-12:

• 1.04-30 - CHANGELOG (MD5 (zipped): 2acb0579dbf67a40828a9b60a59be9e8).

• 1.04-27 - CHANGELOG (MD5 (zipped): 40601a42fb06cf23f43aefe15d042a01).

Older OS versions

All older OS versions that are in our database are available in our archive:

• Red Pitaya archive - some images may require separate ecosystem and Linux OS installation. Check the nightly build installation instructions.

Note

Impossible. Perhaps the archives are incomplete.

OS images not in our archive have been lost to the sands of time. If you are looking for a specific OS or ecosystem that is missing from the archives, we suggest you ask the community on the Red Pitaya forum. There is a chance someone has it lying around on the disk.

For manual ecosystem upgrade please refer to Manual ecosystem upgrade.

Nightly Builds

The nightly builds are snapshots of the development activity for upcoming Red Pitaya OS releases and include the newest features and bug fixes scheduled for the official releases. These builds are made available to make it easier for users to test their setup for potential issues with an upcoming release or to test new features and provide feedback on improving them before they are released as a Beta OS or Stable version. We have decided to release the nightly builds to ensure that our codebase stays healthy and to shorten the time to fix some of the reported issues or implement some new features reported as suggestions for improvement. As these builds are snapshots of the latest code, odds are you will encounter more issues compared to stable releases. Please report any issues to support@redpitaya.com so that our developers can review them and make any needed fixes.

Nightly Builds ecosystem:

• Red Pitaya downloads - NIGHTLY CHANGELOG.

The instructions for installing the Nightly Builds are available in the Nightly build installation guide below.

Note

These OS versions may be unstable and may cause misconfigurations or measurement data loss. We recommend that you use them solely for testing purposes, or you have reported a bug or requested a feature and our technical staff has instructed you to proceed.

2.4.3. Installation instructions for Windows, Linux and MacOS

Here you can find the installation instructions for vairous computer OS systems.

For all OS versions, the installation process is the same. The only difference is the tool used to write the image onto the SD card. Deleting the existing partitions on the SD card beforehand can help with the installation process and avoid potential limited space issues.

Windows

1. Insert the SD card into your PC or SD card reader.

   

2. If necessary delete the existing partitions on the SD card using the Computer manager or Disk management tool.

   

3. Download balenaEtcher and install it.

4. Open the newly installed Balena Etcher application.

   

5. Under Flash from file select the downloaded Red Pitaya image file (Balena Etcher accepts both zipped and unzipped files).

   

6. Under Select target choose the drive letter of the SD card. Balena Etcher will only show you external drives.

   

   Note

   Balena Etcher will only show you external drives, but please be careful to select the correct drive if you have multiple cards or USBs plugged into your computer. If you choose the wrong one, you risk erasing data from the selected drive. You can easily see the drive letter (for example, E:) by looking in the left column of Windows Explorer.

   

7. When you click Flash the computer will prompt you to allow the operation. Click yes and wait for the flashing and validation to be completed.

   

8. Close Balena Etcher.

   

Linux

Note

You can also use balenaEtcher on Linux and macOS. Instructions are under Windows section.

Ubuntu using Image Writer

1. Right-click on the extracted SD card image and select Open With > Disk Image Writer.

   

   Context menu

   

   Select tool dialog

2. In the Restore Disk Image window, select your SD card in the Destination pull-down menu. Be careful to select the correct device; use the size for orientation (for example, a 16 GB SD card).

   

   Select drive dialog

3. You will be asked to confirm your choice and enter a password. Additional dialog windows will again show the selected destination drive. Take the opportunity to reconsider whether you chose the right device.

Command line

Note

Please note that the use of the dd tool can overwrite any partition of your machine. If you specify the wrong device in the instructions below, you could delete your primary Linux partition. Please be careful.

1. Insert the SD card into your PC or SD card reader.

   

2. Open the terminal and check the available disks with df -h. Our SD card is 16 GB. It is named /dev/sdx and divided into two partitions, /dev/sdx1 and /dev/sdx2. The drive mounted at / is your main drive. Be careful not to use it.

   $ df -h
   Filesystem       Size  Used   Avail  Use%  Mounted on
   /dev/sdx1        118M   27M     92M   23%  /media/somebody/CAD5-1E3D
   /dev/sdx2       15.9G 1013M   15.8G   33%  /media/somebody/7b2d3ba8-95ed-4bf4-bd67-eb52fe65df55
   

3. Unmount all SD card partitions with umount /dev/sdxN (make sure you replace N with the right numbers).

   $ sudo umount /dev/sdx1 /dev/sdx2
   

4. Write the image onto the SD card with the following command. Replace the red_pitaya_image_file.img with the name of the unzipped Red Pitaya SD Card Image and replace /dev/device_name with the path to the SD card.

   $ sudo dd bs=1M if=red_pitaya_image_file.img of=/dev/device_name
   

5. Wait until the process has finished.

macOS

Note

You can also use balenaEtcher on Linux and macOS. Instructions are under Windows section.

Using ApplePi-Baker

1. Insert the SD card into your PC or SD card reader.

   

2. Download ApplePi-Baker. Direct link:

   • ApplePi-Baker-v2.2.3.dmg.

   • ApplePi-Baker-1.9.9.dmg.

3. Click on ApplePi-Baker icon, then click Open in order to run it.

   

4. Drag and drop ApplePi-Baker for installation.

   

5. Enter your admin password and click OK.

   

6. Select the SD card drive. This can be recognised by the size of the card, which is 16 GB.

   

7. Select the Red Pitaya OS image file.

   

8. It’s coffee time. The application will show you the estimated time for accomplishment.

   

9. When the operation is finished, the status will change to idle.

   

Command line

1. Insert the SD card into your PC or SD card reader.

   

2. Click cmd + space, type Disk Utility into the search box and press enter. From the menu, select your SD card and click on the Erase button (be careful not to delete your disk!).

   

3. Click cmd + space, then enter cd into the Terminal. Then type cd Desktop and press enter once more.

4. Unmount the partition so that you will be able to overwrite the disk. Type diskutil list into the Terminal and press enter. This will show you the list of all memory devices.

   

5. Unmount with: diskutil UnmountDisk /dev/diskn (insert the number n of your disk correctly!)

   

6. Type: sudo dd bs=1m if=path_of_your_image.img of=/dev/rdiskn. Remember to replace n with the number that you noted before. Notice that there is a letter r in front of the disk name, use that as well!.

   

7. Type in your password and wait a few minutes for the image to be written.

8. When the image is written, type: diskutil eject /dev/diskn and press enter.

9. Safely eject the SD card.

2.4.4. Red Pitaya OS partitions

The Red Pitaya OS image on the SD card contains two partitions. As of OS 2.05-37, the partitions are as follows:

1. The 1 GB FAT contains the ecosystem:

   • Boot files: FSBL, FPGA images, U-Boot, Linux kernel;

   • Red Pitaya API libraries and header files;

   • Red Pitaya web applications, scripts, tools;

   • Customized Nginx web server.

2. The ~8 GB Ext4 contains the OS:

   • Ubuntu/Debian OS,

   • various libraries,

   • network setup customization,

   • systemd services customization.

Most of Red Pitaya’s source code translates into the ecosystem. Therefore, it is updated more often to accomodate new features and bug fixes. The newer the ecosystem, the larger the FAT partitions (the earlies Red Pitaya OS images have around 128 MB FAT partitions). The Linux OS is updated less frequently.

Note

Genereally, the newer the ecosystem, the larger the FAT partition size. You can find all available Red Pitaya OS images and Ecosystem zip files on our Red Pitaya archive.

Note

A list of new features, bug fixes, and known bugs for each Red Pitaya release can be found in our CHANGELOG.

2.4.5. Manual ecosystem upgrade

Instead of writing the whole SD card image, it is possible to upgrade only the ecosystem. A manual upgrade allows you to fix a corrupted SD card image (if only the FAT partition is corrupted) or to install older, newer, or custom ecosystem zip files compatible with the current Linux version.

1. Download a zip file from our Red Pitaya archive.

2. Insert the SD card into the card reader.

   Note

   Do not format the SD card as this will also delete the Linux OS partition.

3. Delete all files from the FAT partition. Use Shift + Delete to avoid placing files into the trash bin on the same partition.

4. Extract the ecosystem zip file contents onto the now empty partition.

If you wish to keep wireless settings, skip deleting the next files:

• wpa_supplicant.conf.

• hostapd.conf.

2.4.6. Nightly build installation guide

Note

Nightly builds are released several times a week and contain the latest features and bug fixes. The nightly builds are not as thoroughly tested as the official releases, so they may contain bugs.

As mentioned in the Red Pitaya OS partitions chapter, each Red Pitaya OS consists of two separate files:

• Linux OS - red_pitaya_OS-beta_<Linux OS version>.img.zip - which contains Ubuntu OS, Red Pitaya libraries, etc.

• Ecosystem - ecosystem-<Linux OS version>-<Nightly Build ecosystem number>-<ID>.zip - Red Pitaya Web APIs

The official Red Pitaya OS releases have both the Linux OS and the ecosystem combined into one image file. For new feature development it is easier to have the two separated, so the nightly builds are released as two separate files.

Red Pitaya OS	OS release date	Nightly Build versions	Linux OS version
2.00-18	26.7.2023	up to NB 141	2.00
2.00-22	4.10.2023	up to NB 160	2.01
2.00-23	5.10.2023	up to NB 162	2.01
2.00-30	11.1.2024	up to NB 215	2.03
2.04-35	15.3.2024	up to NB 258	2.04
2.05-37	7.8.2024	up to NB 345	2.05
IN DEV		346 and later	2.06 and newer

1. Download the .zip containing the Nightly Build Ecosystem (usually the highest number available).

   • Nightly build ecosystems are named ecosystem-<Linux OS version>-<Nightly build ecosystem number>-<ID>.zip.

2. Go to the RedPitaya/downloads page and download the latest Linux OS

   • Linux OS versions are named red_pitaya_OS-beta_<Linux OS version>.img.zip.

   Note

   Make sure the Linux OS version is the same as the one listed in the ecosystem name

   Note

   Please note that Official Red Pitaya OS != Red Pitaya Linux OS

3. Write the Linux OS to the SD card using the BalenaEtcher. As the BalenaEtcher will automatically close the connection between the SD and the computer at the end of the installation process, reinsert the SD card into the computer.

4. Extract the ecosystem from the .zip directly to the SD card (if possible without first extracting it to a folder on the computer).

5. Insert the SD card into the Red Pitaya and power it on.

Please read this section carefully

When unpacking the ecosystem, some files may be overwritten because the FAT file system is not case-sensitive. Files such as CONNMARK.h and connmark.h will appear to the search system to be the same file, so you will be prompted to choose which file to keep. Choose from the following options (depending on the byte size of the files):

File name	File byte size	Prompt overwrite?
ipt_ttl.h	375	No
ipt_ECN.h	901	Yes
ip6t_HL.h	408	Yes
xt_MARK.h	184	Yes
xt_DSCP.h	697	Yes
xt_tcpmss.h	235	No
xt_RATEEST.h	859	No
xt_CONNMARK.h	901	No

Note

Please note that the file names are approximate.

As a general rule, always choose the smaller file unless the difference in size is more than 200 bytes. (For example, if you are asked to choose between file sizes of 199 bytes and 901 bytes, choose 901. If the choice is between 235 bytes and 253 bytes, choose 235 (the smaller size)).

• This will also happen if you first extract to a folder, but you may not be informed of the change (it happens automatically).

• There may be other file combinations that work, this is one that works for us.

• This is a problem with the FAT file system, which is not case-sensitive, so files like “connmark.h” and “CONNMARK.h” are interpreted as the same file.

• If you use a different combination of files, you may not be able to connect to Red Pitaya.

Updating nighlty build ecosystem

To update just the nightly build ecosystem, you can use the Ecosystem update utility.

2.4.7. Resize file system

When we record an image to a flash card of any size, we get sections of the file system that are 4 GB in size. In order to increase the available free space, you need to run the following script:

root@rp-f03dee:~# /opt/redpitaya/sbin/resize.sh

When the script is finished, the system will ask you to reboot your Red Pitaya. If everything is done correctly, the system will start with an increased disk size. This can be checked with the following command:

root@rp-f03dee:~# df -h

Note

If the file system size has not changed, try running the command manually:

root@rp-f03dee:~# sudo resize2fs /dev/mmcblk0p2