4.2.2.5. Build Red Pitaya OS
4.2.2.5.1. Overview
Executable scripts from debian
directory:
script |
description |
---|---|
|
full SD card image build procedure (creates and formats partitions) |
|
update existing SD card image with new |
|
run FSCK on SD card image partitions (for images created from used DS cards) |
|
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 bootstrap, locale, apt configuration, timezone, fake HW clock) |
|
Debian bootstrap (experimental, WEB applications are not working) |
|
tools for compiling software |
|
HW support for ZYNQ chip (U-Boot, I2C, EEPROM, dtc, IIO, NE10?, GPIO, groups with HW access rights) |
|
systemd-networkd based wired/wireless network configuration and required tools (hostAP, supplicant) |
|
libraries required by ecosystem applications (boost, jpeg, json), install and enable services |
|
Jupyter with NumPy and SciPy |
|
The script builds cmake of the required version to build the ecosystem |
|
Configures the watchdog service |
|
X-server and XFCE |
The overlay
directory contains configuration files which are individually installed onto the OS by scripts.
4.2.2.5.2. Bootstrapping
A short list of SD card image contents:
Debian/Ubuntu OS (Ext4 partition): - base operating system files - additional operating system applications and libraries - systemd services - most network configuration files - Jupyter work space
Ecosystem (Fat32 partition):
Bare metal: -
boot.bin
file containing FSBL, FPGA bitstream, U-Boot - Linux kernel image, device tree files - alternative FPGA bitstreams and corresponding device tree overlaysUser 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:
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 aredpitaya_OS_*.tar.gz
file, to be used in thechroot
environment.Build the
ecosystem_*.zip
inside thechroot
environment.Combine
redpitaya_OS_*.img
withecosystem_*.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.
4.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
4.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.
4.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
4.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
4.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
4.2.2.5.4. Debian Usage
4.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 notebbok for Python development |
|
SCPI server, is disabled by default, since it conflicts with WEB applications |
|
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
4.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