Link Search Menu Expand Document

Building Bela Images

GSoC’2022 |


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.


Table of Contents

  1. Introduction
  2. Documentation
  3. Contributions
  4. Further Implementation
  5. Conclusion
  6. Helpful Links


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:

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
     cd ./omap-image-builder
  • Generate: Debian root file system

Debian Bullseye 11.5

   ./ -c

Archive will be under ./deploy/

  • Finalize: Bela specific version:

     sudo ./ --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.


Debian – Packages

Introductory notes

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

Debian 11: (bullseye):

deb [arch=armhf] bullseye main
#deb-src [arch=armhf] bullseye main
Package lists

These are the Bela required packages that are up in

bela-customizationsBela customizations
bela-seasocksSimple, small, C++ embeddable webserver with WebSockets support
hvcchvcc compiler for Pure Data patches - python3
libxenomai1-v3.0Shared libraries for Xenomai
libxenomai-v3.0-devHeaders and static libraries for Xenomai
xenomai-v3.0-kernel-sourceSources of the Xenomai 2.x kernel
xenomai-v3.0-runtimeXenomai runtime utilities


Bootloader: U-Boot

Cape device tree overlays (src):

Debian package: bb-cape-overlays


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


4 more capes can be loaded via:


Plus one custom cape:

U-Boot /boot/uEnv.txt configuration


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/

Just tweak it here:

   ###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}

Load With:

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/ script and custom xenomai kernel and all other Bela required packages are installed through /configs/

Bela Customizations

The bela-customizations debian package ships these ( 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.

  • 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…
  • 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:
  • fstab, hosts these files are generated when we run 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…

 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

DHCP /etc/dhcp/dhcpd.conf

Bela using dhcp to set usb0/usb1…

    subnet netmask {

    subnet netmask {

In Bullsye, the exact same setup is done through systemd-network.. with: bb-usb-gadget package

Bela Gadget

This should be tweaked in an option in: as it auto loads the gadget driver.

[Unit] USB gadgets


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


Achieved Milestones

  • Debian package updated/packaged Bela dependencies
  • Packages are up in apt package manager and
  • 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.

Pull Requests

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

Add seasocks, xenomai debian packages configuration [PR #60]Closed
Add debian package configuration of bela customizations [PR #61]Merged
Add debian package configuration of hvcc [PR #62]Merged
Add xenomai (stable/v3.0.x) debian packages configuration [PR #63]Closed
bela-customizations: cleanup and add bb-start-acm-ncm-rndis-old-gadget [PR #64]Merged
Update packages list of Bela in configs [PR #199]Closed
bela-bullseye-image-build [PR #200]Merged
figured out what packages failed to install and made necessary changes [PR #201]Merged
modify bela-bullseye chroot script [PR #202]Merged
update to python3 version of hvcc compiler [PR #205]Merged
bela boot [#208]Merged
some more bela specific changes [#209]Merged
source to build the ti-linux-xenomai-4.14.y kernel debian package with bela configured config [PR #53]Merged

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.


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.

Back to top

All content licensed under CC BY-SA 4.0 license unless otherwise stated.

Copyright © 2022 Kurva Prashanth.