Building Bela Images

GSoC’2022 | BeagleBoard.org

The project idea was to Improve the maintainability of the Bela Image development by adding the functionalities of the Bela Image builder repo to the BeagleBoard Image builder repo.

About

• Student Name: Kurva Prashanth
• Mentors: Giulio Moro, Vedant Paranjape, Vaishnav Achath
• GSoC Entry link: Program Project Page
• Wiki: Building Bela Images
• Blog Link: Building Bela Images
  

Table of Contents

1. Introduction
   • Why Bela Image has been built again?
   • Project Preview
   • Brief Overview of Bela Image
2. Documentation
   • Debian – Packages
   • omap-image-builder
   • Bela Software
   • Writings
3. Contributions
   • Achieved Milestones
   • Git Repositories
   • Pull Requests
4. Further Implementation
5. Conclusion
6. Helpful Links

Introduction

Bela is an open hardware and software platform for creating beautiful interaction with sensors, sound and it is designed for artists, musicians, researchers and makers, Bela brings the power of ultra-low latency interactive audio and sensors to digital systems.

Bela Platform uses the Bela software which is a customised Debian distribution including a custom xenomai kernel, minimal clutter, and custom systemd configurations and It takes advantage of features of the BeagleBone computers and can achieve extremely fast audio and sensor processing times.

Why Bela Image has been built again?

The Bela Image development repo is heavily based and which was initially inspired by Beagleboard Image-builder scripts. Currently, the Beagle board Image development repo diverged greatly from a common functionalities of building Images.

And, there is an requirement to “rebase” the functionalities of the Bela Image builder repo to the Beagleboard Image builder one. As the two codebases are drastically different and need to rebuild the Bela Image and add the features of the Bela Image builder repo (xenomai kernel building scripts along with a bunch of Bela core) to Beagleboard Image builder repo.

Now, after the specific changes the Bela Image development is following more closely with the Beagleboard Image development and as a result from now the Bela Image will be updated more often and it minimized further development effort.

Project Preview

The main goal is to Improve the maintainability of the Bela Image development by adding the functionalities of the Bela Image builder repo to the BeagleBoard Image builder repo.

Note: This project isn’t rewrite omap-image-builder with bela changes, it’s merge bela changes into omap-image-builder.

Bela Image builds with RobertCNelson/omap-image-builder scripts, These are the same build scripts that were used to generate the official BeagleBoard Images, found here: https://beagleboard.org/latest-images

Bela - Build-Script Instructions

These scripts are tested on Debian x86 machine.

A typical workflow to build a Bela Image would look like:

• Download RobertCNelson/omap-image-builder

   git clone https://github.com/RobertCNelson/omap-image-builder
   cd ./omap-image-builder
  

• Generate: Debian root file system

Debian Bullseye 11.5

   ./RootStock-NG.sh -c bela.io-debian-bullseye-v4.14-ti-xenomai-armhf

Archive will be under ./deploy/

• Finalize: Bela specific version:

   sudo ./setup_sdcard.sh --img-4gb bela-image --dtb beaglebone --distro-bootloader --enable-cape-universal --enable-load-bela-overlay
  

After the script finishes running, we will have an image file generated.

Brief Overview of Bela Image

• Image uses Debian 11 (Bullseye) with the ti-linux-xenomai-bela-4.14.y and Xenomai v3.0.13
• Image have the default root user with no password.
• On the first boot, the image will expand to fill the eMMC or SD card.
• Root login over ssh is enabled.
• The hostname is set to the name of board it’s for as Bela
• Loads Bela IDE over browser, bela.local
• Uses Robert Nelson’s Beaglebone image-builder scripts to build image.

Documentation

Debian – Packages

Introductory notes

Debian package updated/packaged the dependencies of Bela and pushed to apt packager manager at https://rcn-ee.com that used in omap-image-builder along with mainline Debian apt package manager.

Debian 11: (bullseye): http://repos.rcn-ee.com/debian/

deb [arch=armhf] http://repos.rcn-ee.com/debian/ bullseye main
#deb-src [arch=armhf] http://repos.rcn-ee.com/debian/ bullseye main

Package lists

These are the Bela required packages that are up in https://rcn-ee.com

omap-image-builder

Bootloader: U-Boot

Cape device tree overlays (src): https://github.com/beagleboard/bb.org-overlays/

Debian package: bb-cape-overlays

uboot_overlay_addr0=/lib/firmware/<file0>.dtbo
uboot_overlay_addr1=/lib/firmware/<file1>.dtbo
uboot_overlay_addr2=/lib/firmware/<file2>.dtbo
uboot_overlay_addr3=/lib/firmware/<file3>.dtbo

If for some reason we need to disable the auto-loading of any of ^ those, use the option that matches addrX:

disable_uboot_overlay_addr0=1
disable_uboot_overlay_addr1=1
disable_uboot_overlay_addr2=1
disable_uboot_overlay_addr3=1

4 more capes can be loaded via:

uboot_overlay_addr4=/lib/firmware/<file4>.dtbo
uboot_overlay_addr5=/lib/firmware/<file5>.dtbo
uboot_overlay_addr6=/lib/firmware/<file6>.dtbo
uboot_overlay_addr7=/lib/firmware/<file7>.dtbo

Plus one custom cape:

dtb_overlay=/lib/firmware/<file8>.dtbo  

U-Boot /boot/uEnv.txt configuration

/boot/uEnv.txt:

In Bela Image build used this configuration to load Bela Overlay, Use Distro Bootloader, and Cape Universal Enable

--distro-bootloader --enable-cape-universal --enable-load-bela-overlay 

Enable and Load Custom Device Tree Overlay

In omap-image-builder/tools/setup_sdcard.sh

Just tweak it here: https://github.com/RobertCNelson/omap-image-builder/blob/f9b6785eca8c275dc665012efef06141400c5846/tools/setup_sdcard.sh#L1289

   ###Todo: make this more generic so you can specify any overlay...
       if [ "x${load_custom_overlay}" = "xenable" ] ; then
              echo "###" >> ${wfile}
              echo "dtb_overlay=PB-HACKADAY-2021.dtbo" >> ${wfile}
               echo "" >> ${wfile}
       fi

Load With: https://github.com/RobertCNelson/omap-image-builder/blob/f9b6785eca8c275dc665012efef06141400c5846/tools/setup_sdcard.sh#L2102

--enable-load-custom-overlay)
	load_custom_overlay="enable"
	;;

Populating rootfs and Boot Partition

Boot Partition

Rootfs Partition

Bela Software

Bela Core

seasocks, am335x_pru_package, Bela IDE, prudebug, rtdm_pruss_irq, hvcc are installed through /target/chroot/bela.io-bullseye.sh script and custom xenomai kernel and all other Bela required packages are installed through /configs/bela.io-debian-bullseye-v4.14-ti-xenomai-armhf.conf

Bela Customizations

The bela-customizations debian package ships these (https://github.com/BelaPlatform/bela-image-builder/tree/master/misc/rootfs) files as it is to bela image.

Initialized a repo for bela-customizations and copied the /misc/rootfs of bela-image-builder repo in it and used this repo as source for packaging.

Removed

• dhcp.conf cause bela-customizations package failed to install due to ‘/etc/dhcp/dhcpd.conf’, which is also in package isc-dhcp-server and better file, this has dhcp enabled…, that exact same setup is done thru systemd-network.. with: bb-usb-gadget package… https://github.com/rcn-ee/repos/blob/master/bb-usb-gadgets/suite/bullseye/debian/usb0-DHCP.network
• securetty In Debian Bullseye, the runtime that use to use etc/securetty no longer uses that file.. it was completely removed as a legacy option.. Reference: https://www.debian.org/lts/security/2021/dla-2596
• fstab, hosts these files are generated when we run setup_sdcard.sh of omap-image-builder
• interfaces systemd-network uses a new inteface..
• wpa_supplicant.conf will find it already pre-installed..

Changes that need to be done

Bela Bootloader

This still need to be converted… bela_bootloader.sh

 echo "log: dd if=/mnt/boot/MLO of=${DEVICE} seek=${dd_spl_uboot_seek} bs=${dd_spl_uboot_bs}"
 dd if=/mnt/boot/MLO of=${DEVICE} seek=${dd_spl_uboot_seek} bs=${dd_spl_uboot_bs}
 echo "log: dd if=/mnt/boot/u-boot.img of=${DEVICE} seek=${dd_uboot_seek} bs=${dd_uboot_bs}"
 dd if=/mnt/boot/u-boot.img of=${DEVICE} seek=${dd_uboot_seek} bs=${dd_uboot_bs}

This should just call and depend on debian package bb-u-boot-am335x-evm

 /opt/u-boot/bb-u-boot-am335x-evm/install-mmcblk1.sh

DHCP /etc/dhcp/dhcpd.conf

Bela using dhcp to set usb0/usb1… https://github.com/rcn-ee/repos/blob/master/bela-customizations/suite/bullseye/debian/dhcpd.conf#L40-L46

    subnet 192.168.7.0 netmask 255.255.255.0 {
        range 192.168.7.1;
    }

    subnet 192.168.6.0 netmask 255.255.255.0 {

In Bullsye, the exact same setup is done through systemd-network.. with: bb-usb-gadget package https://github.com/rcn-ee/repos/blob/master/bb-usb-gadgets/suite/bullseye/debian/usb0-DHCP.network

Bela Gadget

This should be tweaked https://github.com/BelaPlatform/bela-image-builder/blob/master/misc/rootfs/opt/Bela/bela_gadget.sh in an option in: https://github.com/rcn-ee/repos/blob/master/bb-usb-gadgets/suite/bullseye/debian/bb-start-acm-ncm-rndis-old-gadget as it auto loads the gadget driver.

[Unit]
Description=BeagleBoard.org USB gadgets
After=usb-gadget.target
ConditionFileIsExecutable=/usr/bin/bb-start-usb-gadgets

Writings

I maintained weekly log my progress throughout the program. For the most part it has my work progress for the week and for the issue documented.

Weekly Progress

How-To Guides

Project Notes

Weekly Meeting Minutes

Contributions

Achieved Milestones

• Debian package updated/packaged Bela dependencies
• Packages are up in https://rcn-ee.com apt package manager and https://github.com/rcn-ee/repos
• Built Bela Image with Beaglebone image-builder scripts
• From now the Bela Image will be updated more often with BeagleBone Images

  Git Repositories

Common software that is on or used for building bela image.

• rcn-ee/repos - Debian package configuration
• RobertCNelson/omap-image-builder - Image builder
• RobertCNelson/ti-linux-kernel-dev - ti-linux-xenomai-bela-4.14.y
• Kurva Prashanth/bela-customizations - Source for bela-customizations debian package

Pull Requests

In the following table, I present the pull requests (PRs) I created during the GSoC program.

rcn-ee/repos

RobertCNelson/omap-image-builder

RobertCNelson/ti-linux-kernel-dev

Further Implementation

There are a few things that I would like to implement after GSoC:

• Evaluate and Optimise boot times
• Debian Package remaining Bela Core
  • rtdm_pruss_irq
  • Bela IDE
  • prudebug
• Improvise bela-customizations package.

Conclusion

The goals that were proposed have been completed to the best of my abilities except evaluating and optimizing boot times. currently the built image which shows that it can be build and work with BeagleBone Image builder scripts and I will be working on improving these things after suggestion in the upcoming weeks to make Bela Image into a more complete platform.

I am thankful to Mentors, BeagleBoard and Bela for providing me this opportunity to work on this project during the summer, which helped me learn a lot. Before i was just using the new capabilities provided by the community, with this experience now i’m capable enough to contribute to the FOSS projects and moreover this experience sofar helped me to demystify technology and established that anyone can develop custom OS distibution.

Helpful Links

• Original GSoC Project idea
• https://github.com/BelaPlatform
• https://bela.io
• https://github.com/beagleboard/image-builder
• https://github.com/BelaPlatform/bela-image-builder