Building BuildRoot for BeagleBone Black

February 12, 2025 BeagleBone Tutorial

I purchased my first Beaglebone Black in 2017 and, coming from a PIC microcontroller background, was amazed at all the things it can do. And so I started documenting everything I learned about it which is essentially what became teachmemicro.com.

Eight years later a project on my job required using an AM335x CPU. They didn’t send me the actual hardware which sucked. But guess what device contains the same CPU?

So this post will be about how I run BuildRoot on my BeagleBone Black and will also serve as a short introduction to Embedded Linux.

Contents

What is BuildRoot

BuildRoot is a tool that simplifies the creation of a Linux system, especially for embedded devices. It can build a filesystem, kernel, and bootloader, ready to be flashed and used by, for example, a BeagleBone Black. It’s very easy to use as it provides a menu interface where several options can be enabled or disabled. The whole BuildRoot process is too long to cover here but I will give the minimum steps that I did to get it running.

Downloading Buildroot

First off, you’ll need a host Linux PC. If you don’t have one, use VirtualBox and install an Ubuntu OS. I am using Ubuntu 16.04 without a GUI:

Distributor ID: Ubuntu
Description:    Ubuntu 16.04.7 LTS
Release:        16.04
Codename:       xenial

apt update
apt install -y git build-essential bison flex libncurses5-dev gcc g++ xz-utils unzip bc

Then, download the buildroot package:

git clone https://git.buildroot.net/buildroot
cd buildroot

Buildroot is meant to be used for a variety of embedded devices. Furthermore, it gives options on which Linux Kernel version to use, filesystem formats, packages, etc. It would be great if this were not your first rodeo with embedded Linux. The simplest approach would be to load the provided configuration for BeagleBone which ensures it builds an appropriate kernel and root filesystem:make beaglebone_defconfig

Customize Buildroot

I mentioned that Buildroot allows you to customize your Linux installation. It can be done by editing the config files or by simply running

make menuconfig

This opens up the Buildroot configuration window:

Since we already loaded the default Beaglebone configuration, we only have little work to do here. For example, you can go to System Configuration to change your system banner or hostname, etc.:

Or, you can add more apps in Target packages:

There is one important update though. If you did add more packages, the default filesystem size might not be enough. Go to Filesystem images -> exact size. Change the root filesystem size from 60M to 200M like this:

After that, go to <Save>, the <Exit>.

Building the Image

If you’re like me who logged in as root, run this first:

export FORCE_UNSAFE_CONFIGURE=1

It’s generally discouraged to use root when building apps so the command above bypasses that.

Now, start the build process:

make

Make sure you’re still inside the buildroot folder!

This process can take a while depending on your system’s performance. Once complete, the generated files are stored in the output/images directory.

Notice that buildroot also provides the device tree blobs for different beaglebone boards. We will need five files from here: the first state bootloader MLO, the second stage bootloader u-boot, the Beaglebone black device tree blob, the kernel, and the root filesystem.

Preparing the microSD Card

If you’re using VirtualBox, make sure to enable USB for your virtual machine via Settings > USB > Enable USB Controller. Then when your virtual machine is powered up, go to Devices > USB then select your microSD card.

To identify your SD card, use:

lsblk

This will list your external drives. SD Cards are usually at /dev/sdb or /dev/sdc. Mine is at /dev/sdc. Make sure to identify the correct drive by checking the disk size.

Now, we need two partitions for the SD card, one for the bootloader and kernel and one for the filesystem. You can use fdisk for this:

fdisk /dev/sdc

Then issue the command (o) to create a new partition table.

Then add a new boot partition using command (n). Make it primary, specify the size (about 100MB should be enough), and type (c) to make it FAT32.

Next, add another root partition using command (n). Make it primary, use the rest of the space of the SD card, and (83) to make it ext4.

Then format the partitions:

mkfs.vfat /dev/sdc1
Mkfs.ext4 /dev/sdc2

Flashing the Buildroot Image

Now that we have our SD card prepared, it’s time to move the buildroot output images. First off, mount the partitions:

mkdir -p /mnt/boot /mnt/root
mount /dev/sdc1 /mnt/boot
mount /dev/sdc2 /mnt/root

Then copy the bootloader files:

cp output/images/MLO /mnt/boot/
cp output/images/u-boot.img /mnt/boot/

Then copy the kernel, device tree blob and root filesystem:

cp output/images/zImage /mnt/boot/
cp output/images/am335x-boneblack.dtb /mnt/boot/
cp -r output/images/rootfs.tar /mnt/root/

Go to the mount point, extract the root filesystem and them remove the archive after:

cd /mnt/root && sudo tar -xf rootfs.tar && sudo rm rootfs.tar

To safely remove the SD card, unmount it first:

cd /root/
umount /mnt/boot /mnt/root

Boot BeagleBone Black, Now With Buildroot!

Insert the SD card into the BeagleBone Black. Apply power to it using the USB port or the 5V DC jack. You will notice that the user LEDs will do the usual patterns.

Now if something went wrong or the LEDs are not doing the patterns, you can’t SSH into the BBB. But you can connect a USB-TTL device to the BBB.

For Linux, use screen to view the debug messages:

screen /dev/ttyUSB0 115200

For Windows, use Putty and select the USB-TTL device’s COM port.

Here’s what my Putty screen looks like when everything is set up correctly:

If you want to SSH into this setup, just type root as login then just leave the password empty.

Conclusion

You have successfully built and deployed a Buildroot-based Linux system onto a BeagleBone Black. You can now customize it further by adding software packages, configuring networking, and optimizing performance.