Tool to generate the golden image to be flashed on the Raspberry Pi. It cross-compiles a cut-down Linux system with a few packages using buildroot.
- A linux host with git, gcc, g++, make, unzip, subversion and device-tree-compiler installed is needed (WSL works too)
- Configure the top-level variables in
build.sh - To start the image build, run
./build.sh - To force a rebuild (in case packages or files were reconfigured), run
./build.sh clean all - On first run, the build can take up to an hour, depending on computing power
- Final images will appear in the
img/folder click_emmc.imgis the raw eMMC file that can be flashed using rpiboot with a Compute Module IO boardclick_golden.imgis the golden image that includes the usbboot bootloader for VNC2L. This is the golden image to be uplinked to the BCT bus.- The default root password is
lasercom. CLICK SSH keys can also be used to log in using SSH without a password when in debug mode.
build.shis the main script that executes buildroot. It has a variableCLICK_FSW_VERSIONdefining which flight software version to bundle, andBOOT_WITH_PPPwhich can be used to generate an image that boots in debugging mode with PPP/SSH running.config_buildroot.txtcontains buildroot config flags. Defines how to build the system, which Linux kernel git commit to use (BR2_LINUX_KERNEL_CUSTOM_TARBALL_LOCATION), which packages to include in the system (BR2_PACKAGE_xxx), and some other basic configuration. Can be modified to add more software packages if needed.config_kernel.txtcontains Linux kernel config flags. Defines which kernel modules are bundled with the kernel image and which are built as external modules. Mostly disables a lot of unneeded kernel features and drivers to make the image smaller. Should not need changing.config_rpi.txtis the config for the RPi bootloader. Sets a static GPU clock to fix SPI frequency and configures the SPI using the device tree overlay from the SPI driver.extra/contains definitions for custom/uncommon packages that are not included in buildroot by default, such as the custom flight software, Matrix Vision libraries, and the png2jpeg tool. Each folder inextra/package/has makefiles that define how the package is downloaded, built and installed to the image. More uncommon software packages can be defined here.overlay/is a custom tree of files that are added directly to the OS partition by buildroot. These include some system config files and OS services and the FPGALink libraries.post_build.shis a script that is automatically executed after buldroot is done with all package compilation. It does some OS configuration before the OS is packaged.post_image.shis a script that is automatically executed after buldroot packages the OS. It creates the images with all the partitions, which can be directly flashed onto the RPi.
The final image (~19 MB) contains three partitions:
- boot (~3 MB), a FAT-16 filesystem with the bootloader files and the (compressed) kernel image.
- OS (~16 MB), a SquashFS compressed read-only filesystem that contains all the other OS files and packages, including the "golden" CLICK flight software files.
- RW (3.7 GB), an empty EXT4 read-write filesystem that is created on first boot. The image only contains its partition table entry, not any data.
The way the OS handles the filesystems is explained below:
- The OS is configured to only use the root user account.
- The original root user files, including the golden CLICK FSW, are stored read-only at
/usr/local/fsw. - On first boot, the read-write EXT4 filesystem is created and mounted on
/mnt, see fs-initialize.service and mnt.mount. - Next, an overlay filesystem is automatically mounted on
/root. The overlay filesystem will mirror all the read-only files from/usr/local/fsw, but allow overwriting them within/root, see root.mount. However, all the changes are actually kept behind the scenes on/mnt/overlay(this is invisible to the user). This allows making changes to the original root user files and the CLICK FSW without needing changes on the read-only filesystem. - All manual file modifications or new data storing should be done directly on
/root. The/mntdirectory should not be written to by the user. - Finally, the OS binds
/mnt/journalto/var/log/journalto enable persistent journal archiving, see var-log-journal.mount.
Emergency fallback handling:
- If something malfunctions and the read-write FSW (
/root/busfolder) is not accessible after boot, the EXT4 filesystem will be re-generated automatically using the fs-initialize.service. This will restore the system to the golden image state. - If even the EXT4 filesystem generation fails for some reason, the OS will bind
/usr/local/fswdirectly to/root, see fs-fallback.service. This will allow the system to operate at least in a read-only mode using the golden image software.
If the EXT4 filesystem is operational, journal logs from each boot are archived in /mnt/journal. Systemd creates a folder with the name of the current boot ID that contains the system and user logs.
To help identify which ID is from which boot (since we don't know the time during boot), id-save.service appends the current ID to /mnt/journal/id.txt on each boot.
The logs can then be viewed on ground or through SSH via journalctl --file <boot_id>/system.journal.