Clone wiki

roseline / Tutorial 1 - Booting the QoT Stack


The BeagleBone Black uses a bootloader called U-Boot, which can be configured to boot Linux off the internal memory (eMMC), external flash memory (MicroSD) or a wired network. Since the board is shipped without a MicroSD card, it follows that by default it boots of eMMC. Flashing the eMMC is quite tricky, plus it makes for a good fall-back system, so we will use a MicroSD card.

The BeagleBone Black will only boot off a MicroSD if it is partitioned correctly. You will need a 4GB+ MicroSD card, which you are willing to format. You will create and populate three partitions:

  1. A primary, bootable 64MB W95 FAT16 partition that accommodates the U-Boot application, boot instructions, and potentially a kernel / device tree.
  2. A primary 2GB EXT4 partition, which will accommodate the root file system.
  3. A primary EXT4 partition with the remaining bytes available, which will store user data.

STEP 1 : Insert MicroSD card and determine its device handle (very important)

Insert the MicroSD card into your Host PC and create the partitions. Please note that fdisk is a partitioning tool, and if you do not specify the correct device, you run the risk of formatting the incorrect drive. So, please use tail -f /var/log/syslog before inserting the card to see which device handle (/dev/sd?) is assigned by udev when the card is inserted into your PC.

STEP 2 : Format the MicroSD card using fdisk

The application fdisk should already be installed. Type this to check:

sudo apt-get install fdisk

Then run the following:

  1. Start fdisk to partition the SD card: sudo fdisk /dev/sd?
  2. Type o. This will clear out any partitions on the drive.
  3. Type p to list partitions. There should be no partitions left.
  4. Type n, then p for primary, 1 for the first partition on the drive, enter to accept the default first sector, then +64M to set the size to 64MB.
  5. Type t to change the partition type, then e to set it to W95 FAT16 (LBA).
  6. Type a, then 1 to set the bootable flag on the first partition.
  7. Type n, then p for primary, 2 for the second partition on the drive, and +2GB to set the size to 2GB.
  8. Type n, then p for primary, 3 for the third partition on the drive, and enter to select the remaining bytes on the drive.
  9. Write the partition table and exit by typing w.
  10. Initialise the filesystem for partition 1: mkfs.vfat -F 16 /dev/sd?1 -l boot
  11. Initialise the filesystem for partition 2: mkfs.ext4 /dev/sd?2 -l rootfs
  12. Initialise the filesystem for partition 3: mkfs.ext4 /dev/sd?3 -l user

STEP 3 : Copy the files to the MicroSD card

Copy the bootloader (MLO, u-boot.img), bootloader instructions (uEnv.txt), kernel (zImage) and compiled device tree (am335x-boneblack.dtb) to the auto-mounted boot partition:

sudo cp -R <roseline>/kernel/bootloader/* /media/<username>/bootloader

Copy the root filesystem to the auto-mounted rootfs partition. Note that it is essential to specify the -p flag, as this preserves the permissions on all of the files:

sudo tar xjfp <roseline>/kernel/rootfs/rootfs.tar.bz2 -C /media/<username>/rootfs

STEP 4 : Safely remove MicroSD card and boot the BeagleBone Black

Close the terminal window and safely remove the MicroSD card. Once it has been safely unmounted from the computer, remove it and insert it into the BeagleBone Black.

  • The blue LEDs should incrementally brighten until all five are lit.
  • The blue LEDs will then all turn off for a moment.
  • The blue LEDs will then flicker, indicating that the system has booted.
  • The blue LEDs will turn off when the system has fully booted.

Common issues

If your platform does not boot, try and repeat the MicroSD card preparation process. If the problem persists you may find it helpful to acquire an FTDI Programming Cable.

First, make sure your Linux username is added to the dialout group in Linux:

sudo usermod -a -G dialout <username>

Log in and out to activate this new permission.

Then, plug the FTDI cable into the powered-off board as follows:


Then, plug the FTDI cable into your host PC. If you are working with a virtual Ubuntu installation (VMWare / VirtualBox) then you may need to configure the device to be "seen" by the guest operating system. Just follow the prompts given to you by the virtual machine.

Now, open a terminal and run minicom:

minicom -s

Select the port to /dev/ttyUSB0, baud to 115200 and hardware flow control to off. Press escape twice after configuring to fall back to the minicom command line.

Now, if you power on the BeagleBone Black you should see a stream of bootloader debug information printed to your screen. This will allow you to diagnose the reason for your boot issues. After booting, you will be able to log in through the serial console. However, we recommend working over ssh, as there are certain keystrokes that are not accepted by the serial console (like the arrows or delete key).