Build and deploy Yocto Linux on the Beaglebone Black

This post will show you how to build and deploy the Yocto Linux distribution on the Beaglebone Black. Since the latest Yocto 1.6 “daisy” release, there is an official board support package for the Beaglebone. Therefore, the build process will be pretty straight-forward.

Prerequisites

On an Ubuntu 12.04, you will need at least the following packages

~$ sudo apt-get install chrpath gawk diffstat texinfo g++

Download the latest Yocto release branch “daisy”

~$ mkdir yocto
~$ cd yocto
~/yocto$ git clone -b daisy git://git.yoctoproject.org/poky.git

Building

~/yocto$ cd poky

A proper build environment is initialized with the oe-init-build-env script. This script needs to be source’d. This can be done with the source command or shorter, with the dot operator. Furthermore, we need to supply a name for the build environment root folder as an argument to the oe-init-build-env script. In this example, we will be using “build”, but you can choose any name you like.

user@host:~/yocto/poky$ source oe-init-build-env build
# or alternatively
user@host:~/yocto/poky$ . oe-init-build-env build

A new folder “build” will be generated, and also your shell automatically switches to this folder (which can be a bit confusing at first).

We are now ready to configure our Yocto distribution. This is mainly done with the help of two configuration files, namely conf/local.conf and conf/bblayers.conf. Prior to Yocto 1.6, an external meta layer (such as “meta-ti”) had to be downloaded and included in the conf/bblayers.conf file. However, since the Beaglebone is now an official build target, we only need to modify conf/local.conf for now.

user@host:~/yocto/poky/build$ vim conf/local.conf

In the above configuration file, we need to set the MACHINE variable to “beaglebone”. To do so, you can simply uncomment the line

#MACHINE ?= "beaglebone"

… so that it reads

MACHINE ?= "beaglebone"

The “?=” and “??=” signs are conditional assignments, and will only set the MACHINE variable if it has not been assigned already. Therefore, the subsequent line “MACHINE ??= qemux86”, which is used to set the default machine type, will have no effect. However, if you want to be 100% sure, you may also delete said line 🙂

We are now ready to start a build

user@host:~/yocto/poky/build$ bitbake core-image-base

If you get an error similar to …

The program 'bitbake' is currently not installed. You can install it by typing:
sudo apt-get install bitbake

… then you have probably switched terminals, and the build environment is not initialized in your current shell. In that case, simply re-run the oe-init-build-env script with the same build folder as an argument. If the build folder already exists, it will not be over-written or deleted, and your changes to the conf/local.conf file will be preserved.

When trying to build core-image-base, we received the following error messages.

user@host:~/yocto/poky/build$ bitbake core-image-base
ERROR:  OE-core's config sanity checker detected a potential misconfiguration.
    Either fix the cause of this error or at your own risk disable the checker (see sanity.conf).
    Following is the list of potential problems / advisories:

    Failed to fetch test data from the network. Please ensure your network is configured correctly.

ERROR: Execution of event handler 'check_sanity_eventhandler' failed
ERROR: Command execution failed: Exited with 1

Summary: There were 3 ERROR messages shown, returning a non-zero exit code.

If you get the same error, you should obviously check your internet connection first, but chances are, that you are indeed online – you are reading this blog after all 🙂 – and the test data is currently not available. To disable the network test data download, we need to empty the variable CONNECTIVTY_CHECK_URIS. This could be done in the file yocto/poky/meta-yocto-conf/distro/poky.conf. A better approach however is adding this variable to our local configuration under conf/local.conf so that it reads:

CONNECTIVITY_CHECK_URIS = ""
# ..

Deploying

Building Yocto will take quite a while, but if everything succeeded, you will get binary output images under yocto/poky/build/tmp/deploy/images/beaglebone
The most important ones are:

• MLO-beaglebone
  The second stage bootloader (the first stage bootloader is implemented in ROM code on the AM335x chip and can not be altered in software)
• u-boot-beaglebone.img
  The third stage u-boot bootloader (the “main” bootloader)
• uImage
  The Linux kernel image (uImage is a special format used with u-boot bootloader)
• core-image-base-begalebone.tar.bz2
  This archive contains the root file system.

To deploy the system, we will need to prepare an SD-card. The SD-card partition layout should be:

#First partition
type: FAT32
size: around 30MB (that is way too much, but most SD-cards are 4GB+ anyways)
label: BOOT
flags: boot

#Second partition
type: ext4
size: around 200MB, or rest of SD-card
label: ROOT

Use any program you like for partitioning. Just make sure you know where the SD-card is mounted (you don’t want to accidentally swipe your computer’s hard disc). To see all mounted disk drives, use the command “lsblk”.

~$ lsblk
NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
sda      8:0    0 238.5G  0 disk 
├─sda1   8:1    0 222.5G  0 part /
├─sda2   8:2    0     1K  0 part 
└─sda5   8:5    0    16G  0 part [SWAP]
sdb      8:16   0 931.5G  0 disk 
├─sdb1   8:17   0 919.8G  0 part 
├─sdb2   8:18   0     1K  0 part 
└─sdb5   8:21   0  11.7G  0 part 
sdc      8:48   1   3.7G  0 disk 
├─sdc1   8:49   1    33M  0 part 
├─sdc2   8:50   1   512M  0 part 
└─sdc3   8:51   1   3.2G  0 part
# In this case, the SD-card has a size of 3.7G and is mounted as /dev/sdc

You can now use gparted for instance to partition your SD-card. Make sure you also set the “boot” flag on the first partition.

~$ sudo apt-get install gparted
~$ sudo gparted

After partitioning is completed, we are ready to copy the files to the SD-card:

~$ cd yocto/poky/build/tmp/deploy/images/beaglebone
~$ cp MLO-beaglebone /media/user/BOOT/MLO
~$ cp u-boot-beaglebone.img /media/user/BOOT/u-boot.img
~$ sudo tar -xvf core-image-base-beaglebone.tar.bz2 -C /media/user/ROOT/

You might wonder why we do not copy the Linux kernel image to the boot partition. The reason for this is that the uImage is already included in the root file system under /boot. This uImage will then be loaded directly from the root partition at location /boot/uImage.
You can double check this with the strings tool:

strings u-boot-beaglebone.img | grep loaduimage
loaduimage=load mmc ${bootpart} ${loadaddr} ${bootdir}/${bootfile}
strings u-boot-beaglebone.img | grep bootpart
bootpart=0:2
# device 0 is the external SD-card, and the second partition is our root partition with the /boot folder
strings u-boot-beaglebone.img | grep bootdir
bootdir=/boot
strings u-boot-beaglebone.img | grep bootfile
bootfile=uImage

Booting

Connect to your Beaglebone with a serial adapter, and a serial terminal program such as minicom. Insert the SD-card, hit the reset button on the Beaglebone and observe the output on the serial console.

The Beaglebone Black has an internal eMMC disk and also an external SD-card reader. Therefore, there may be some confusion to which bootloader and root file system gets booted. For the sake of simplicity, the official instructions suggest to delete the on-board eMMC disk with the following command within u-boot:

# mmc dev 1
# mmc erase 0 512

However, the mmc command was not available on our prebuilt image on the Beaglebone Black revision B6, but there are other ways to disable the eMMC image. One way is to start the Beaglebone normally, without any SD-card inserted. This should bring up the factory shipped Angstrom image. You can then mount the internal eMMC and wipe all data. Alternatively, you can also just rename the internal MLO file to MLO.disabled or similar, which has the same effect. From then on, the MLO and u-boot.img bootloaders will be pulled from the SD-card instead of the internal eMMC. If you ever want to return to the factory setting, there are special eMMC “flasher” images which you can put on an SD-card to automatically flash the internal eMMC image.

# Start the prebuilt Angstrom image (no SD-card inserted!)
root@beaglebone:~# mkdir internal
root@beaglebone:~# mount -t vfat /dev/mmcblk0p1 internal/
root@beaglebone:~# ls internal/
App           Drivers       LICENSE.txt   README.md     autorun.inf   uEnv.txt
Docs          ID.txt        MLO           START.htm     u-boot.img
root@beaglebone:~# mv internal/MLO internal/MLO.disabled
root@beaglebone:~# umount internal

Now reboot your Beaglebone with the SD-card inserted, and watch the output on the serial console. The build time (May 17 2014 – 17:15:48 in this case) should be visible at the start of MLO/SPL and u-boot bootloader:

U-Boot SPL 2013.07 (May 18 2014 - 17:15:48)
musb-hdrc: ConfigData=0xde (UTMI-8, dyn FIFOs, HB-ISO Rx, HB-ISO Tx, SoftConn)
...
reading u-boot.img
U-Boot 2013.07 (May 18 2014 - 17:15:48)
...

Furthermore, you should get to a login prompt. The user name will be root without password.

Poky (Yocto Project Reference Distro) 1.6 beaglebone /dev/ttyO0
beaglebone login: root
root@beaglebone:~#

Configuring

In this example, we will also add an SSH server (dropbear) and busybox’s integrated webserver.
To add the SSH server, we need to include dropbear package. This is done by modifying our conf/local.conf configuration file. Use any text editor you like and add the following line:

CORE_IMAGE_EXTRA_INSTALL += "dropbear"

By the way, you can show a list of available recipes with:

bitbake-layers show-recipes

Furthermore, to start the graphical configuration menu for busybox:

bitbake -c menuconfig busybox

Navigate to the Networking section and enable httpd by hitting space bar. Another cool feature which you might want to enable is the server option “-l” for netcat or nc. When you are done, press ESC repeatedly and save the changes.

You may need to force busybox to recompile:

bitbake -f -c compile busybox

To change the Linux kernel configuration, use the following command:

bitbake -c menuconfig virtual/kernel

Then re-build and deploy the image:

bitbake core-image-base
# Insert SD-card and clear contents
sudo rm -rf /media/user/ROOT/*
# Deploy to SD-card
sudo tar -xvf tmp/deploy/images/beaglebone/core-image-base-beaglebone.tar.bz2 -C /media/user/ROOT/