3.2.2.5. Build Red Pitaya OS

3.2.2.5.1. Overview

Executable scripts from debian directory:

script

description

image.sh

full SD card image build procedure (creates and formats partitions)

image-update.sh

update existing SD card image with new ecosystem_*.zip

image-fsck.sh

run FSCK on SD card image partitions (for images created from used DS cards)

image-clean.sh

deprecated

Scripts to be used in a chroot environment only:

Note

If this scripts are executed on the host OS directly, they can cause serious damage.

script

description

ubuntu.sh

Ubuntu bootstrap, locale, apt configuration, timezone, fake HW clock)

debian.sh

Debian bootstrap (experimental, WEB applications are not working)

tools.sh

tools for compiling software

zynq.sh

HW support for ZYNQ chip (U-Boot, I2C, EEPROM, dtc, IIO, NE10?, GPIO, groups with HW access rights)

network.sh

systemd-networkd based wired/wireless network configuration and required tools (hostAP, supplicant)

redpitaya.sh

libraries required by ecosystem applications (boost, jpeg, json), install and enable services

jupyter.sh

Jupyter with NumPy and SciPy

cmake3.21.sh

The script builds cmake of the required version to build the ecosystem

watchdog.sh

Configures the watchdog service

tft.sh

X-server and XFCE

The overlay directory contains configuration files which are individually installed onto the OS by scripts.

3.2.2.5.2. Bootstrapping

A short list of SD card image contents:

  1. Debian/Ubuntu OS (Ext4 partition): - base operating system files - additional operating system applications and libraries - systemd services - most network configuration files - Jupyter work space

  2. Ecosystem (Fat32 partition):

    1. Bare metal: - boot.bin file containing FSBL, FPGA bitstream, U-Boot - Linux kernel image, device tree files - alternative FPGA bitstreams and corresponding device tree overlays

    2. User space - Bazaar server (Nginx) and WEB applications - Red Pitaya API library - SCPI server

To build a functional OS image the ecosystem is required, since without the boot.bin and the Linux kernel, the system will not start. And to build the ecosystem the OS image is required, since the user space applications are built inside a chroot environment with an emulated ARM CPU.

Therefore the procedure for the first build is as follows:

  1. Build the OS image without the ecosystem. This will create a redpitaya_OS_*.img SD card image, but without the ecosystem and therefore non functional. It will also create a redpitaya_OS_*.tar.gz file, to be used in the chroot environment.

  2. Build the ecosystem_*.zip inside the chroot environment.

  3. Combine redpitaya_OS_*.img with ecosystem_*.zip using:

    OS/debian/image-update.sh redpitaya_OS_*.img ecosystem_*.zip

After finishing the bootstrapping procedure, either the ecosystem or the OS image can be built as needed. The more common procedure would be to build a new ecosystem using an existing chroot environment, and then replace the ecosystem in an existing SD card image with the new one. The build procedure for a new SD card OS image can now be done in one step. If an existing ecosystem_*.zip file is present in the project root while building the OS image, it will be integrated and the result will be a fully functional SD card image.

3.2.2.5.3. Dependencies

Ubuntu 2022.04 was used to build Debian/Ubuntu SD card images for Red Pitaya.

The next two packages need to be installed on the host PC:

$ sudo apt-get install debootstrap qemu-user-static

3.2.2.5.3.1. Ubuntu bootstrap

The next steps should be executed in the root directory of the Red Pitaya Git repository.

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

Run the next command to build the OS image. Root or sudo privileges are needed. The code should be executed as the root user, otherwise some configuration files will be placed into the wrong users home directory.

Note

Before you execute next step, the Ecosystem <ecosystem> must be built.

$ sudo bash
# OS/debian/image.sh
# exit

image.sh will create an SD card image with a name containing the current date and time. Two partitions are created a 512MB FAT32 partition for the ecosystem and a slightly less then 8GB Ext4 partition.

image.sh will call ubuntu.sh which installs the base system and some additional packages. It also configures APT (Debian packaging system), locales, hostname, timezone, file system table, U-boot and users (access to UART console).

ubuntu.sh also executes network.sh which creates a systemd-networkd based wired and wireless network setup. And it executes redpitaya.sh which installs additional Debian packages (mostly libraries) needed by Red Pitaya applications. redpitaya.sh also extracts ecosystem*.zip (if one exists in the current directory) into the FAT partition.

Optionally (code can be commented out) ubuntu.sh also executes jupyter.sh and tft.sh which provide additional functionality.

3.2.2.5.3.2. Red Pitaya ecosystem update

In case an ecosystem*.zip file was not available for the previous step, it can be extracted later to the FAT partition (128MB) of the SD card. In addition to Red Pitaya tools, this ecosystem_*.zip file contains a boot image (containing FPGA code), a boot script (u-boot.scr) and the Linux kernel.

A script image-update.sh is provided for updating an existing image to a newer ecosystem_*.zip file without making modifications to the ext4 partition.

The script should be run with the image and ecosystem files as arguments:

# ./OS/debian/image-update.sh redpitaya_OS_*.img ecosystem-*.zip

Now you can burn a micro SD card (sized 8GB) e.g.,

# dd bs=4M if=redpitaya_OS_*.img of=/dev/mmcblk0

3.2.2.5.3.3. File system check

If the image creation involved multiple steps performed by the user, for example some installation/setup procedure performed on a live Red Pitaya, there is a possibility a file system might be corrupted. The image-fsck.sh script performs a file system check without changing anything.

Use this script on an image before releasing it.

# ./OS/debian/image-fsck.sh redpitaya_OS_*.img

3.2.2.5.3.4. Reducing image size

Note

This steps should only be performed on a live Red Pitaya board. If executed on the host OS, they can and will cause problems.

A cleanup can be performed to reduce the image size. Various things can be done to reduce the image size:

  • remove unused software (this could be software which was needed to compile applications)

  • remove unused source files (remove source repositories used to compile applications)

  • remove temporary files

  • zero out empty space on the partition

The next code only removes APT temporary files and zeros out the file system empty space.

$ apt-get clean
$ cat /dev/zero > zero.file
$ sync
$ rm -f zero.file
$ history -c

3.2.2.5.4. Debian Usage

3.2.2.5.4.1. Systemd

Systemd is used as the init system and services are used to start/stop Red Pitaya applications/servers. Service files are located in OS/debian/overlay/etc/systemd/system/*.service.

service

description

jupyter

Jupyter notebbok for Python development

redpitaya_scpi

SCPI server, is disabled by default, since it conflicts with WEB applications

redpitaya_nginx

Nginx based server, serving WEB based applications

To start/stop a service, do one of the following:

$ systemctl start service_name
$ systemctl stop service_name

To enable/disable a service, so to determine if it will start at powerup, do one of the following:

$ systemctl enable service_name
$ systemctl disable service_name

To see the status of a specific service run:

$ systemctl

3.2.2.5.4.1.1. Debugging

$ systemd-analyze plot > /opt/redpitaya/www/apps/systemd-plot.svg
$ systemd-analyze dot | dot -Tsvg > /opt/redpitaya/www/apps/systemd-dot.svg