Toby Schneider edited this page May 26, 2016 · 7 revisions

This walk-through teaches you how to set up Debian Wheezy on an embedded ARM computer, the BeagleBone Black (or BBB).


This wiki entry uses a few conventions:

  • Commands intended to be typed into the host will be formatted as such:

    # host
    ls *
  • Commands intended to be typed into the BBB over serial console (picocom) or SSH will be formatted as such:

    # bbb
    ls *
  • Commands that are to be typed into a chroot environment on the host representing the BBB will be formatted:

    # bbb-chroot
    ls *
  • Where no directive is given, # host is assumed.

  • Sometimes, I'll use zile instead of emacs since the basic commands are the same and zile is much smaller. You can always use nano, vi, etc. instead wherever I have zile.

  • I like picocom for connecting to the serial console terminal, as it's very easy to configure (one line). You are, of course, welcome to use minicom or kermit if you prefer.

Other useful websites

Hardware you need

  • A computer, the host, capable of running Debian. Using a virtual machine is discouraged, especially if this is your first time.
  • A BeagleBone Black single board computer and the supplied USB cable.
  • A micro-SDHC card. I'm using a Transcend 32GB card, which is large enough for most uses (64GB cards are also available).
  • An SDHC reader (some SD readers do not read SDHC cards).

Software we will install

Setup: Host

I'm using Ubuntu 12.04 as the host machine distribution. You need to use a new Debian or Debian-derivative (Ubuntu, Mint, etc.) as your host. Older versions of multistrap seem to broken, such as the one packaged with Ubuntu 10.04. If necessary, you can safely manually install a newer multistrap because it has minimal dependencies.

Required packages:

sudo apt-get install multistrap qemu-user-static picocom

Partition the SD Card

I will walk through one way of formatting the SD card. Further details of formatting the SD card for the BBB are available on Robert Nelson's post:

You will need two primary partitions (you can probably have more if you want):

  1. a 64 MB fat32 (vfat) partition for the bootloaders and kernel. (I'm calling this "boot"). Set "Align to Cylinder" not "MiB".
  2. an ext4 partition for the filesystem ("/") that uses the remaining space on the card. (I'm calling this "rootfs").

The easiest way to get started is to use gparted for partition editing, which you can get with

sudo apt-get install gparted

The SD card is usually seems to usually be /dev/mmcblk0, so I'll assume that's what it is here.

sudo gparted
  1. Locate the SD card /dev/mmcblk0
  2. Unmount and delete any existing partitions (be sure you have the SD card, not another drive!)
  3. Add the two partitions mentioned above.
  4. Set the "boot" flag on the fat32 partition.

When you're done, the SD card should look something like this:

When you're done, close gparted and let the SD card partitions automount by removing the card and reinserting it. Alternatively you can mount on the command line with mount.

Copy the BBB Bootloader and Kernel

Download the relevant boot files:

The copying order matters!

sudo cp MLO /media/boot
sudo cp u-boot.img /media/boot
sudo cp *.zImage /media/boot/zImage
sudo cp uEnv.txt /media/boot
sudo mkdir -p /media/boot/dtbs/
sudo tar xfov *-dtbs.tar.gz -C /media/boot/dtbs/
sudo mkdir -p /media/rootfs/lib/firmware
sudo tar xfv *-firmware.tar.gz -C /media/rootfs/lib/firmware/
sudo tar xfv *-modules.tar.gz -C /media/rootfs/

Obtain a root filesystem

Create a Debian root filesystem on the host

We will use multistrap to create a bootable Debian root armhf filesystem on the host that we can later copy to the BBB.

  1. Pick a folder to work from, e.g. ~/bbb.

  2. Make a directory to hold the root fileystem:

    # host
    cd ~/bbb
    mkdir rootfs
  3. Create a file called beaglebone-wheezy-hf.conf in ~/bbb and put in the following:

    # same as --tidy-up option if set to true
    # same as --no-auth option if set to true
    # keyring packages listed in each debootstrap will
    # still be installed.
    # whether to add the /suite to be explicit about where apt
    # needs to look for packages. Default is false.
    # extract all downloaded archives (default is true)
    # the order of sections is not important.
    # the debootstrap option determines which repository
    # is used to calculate the list of Priority: required packages.
    packages=apt zile adduser makedev less isc-dhcp-client netbase ifupdown iproute net-tools iputils-ping openssh-server sudo picocom minicom build-essential wget curl locales gnu-fdisk traceroute socat zip unzip nano m4 psmisc rsync lsof vim cpufrequtils aptitude iperf module-init-tools udev rsyslog pps-tools

    These packages will be installed on the new root filesystem that we will later copy to the SD card. Feel free to add/remove packages to suit your needs; however, you can always use apt-get later to add/remove the packages listed here. Debian packages are listed here:

  4. Create the root filesystem in the directory given in beaglebone-wheezy-hf.conf:

    # host
    sudo multistrap -f beaglebone-wheezy-hf.conf
  5. Copy the QEMU ARM emulator into the new root filesystem so that it is on the path once we chroot to ~/bbb/rootfs:

    # host
    sudo cp /usr/bin/qemu-arm-static ~/bbb/rootfs/usr/bin/
  6. Mount the real /dev in the chroot to give it access to /dev/random, etc. Then, run bash in the root ~/bbb/rootfs as it will be seen by the BBB when we're all done:

    # host
    sudo mount -o bind /dev ~/bbb/rootfs/dev
    sudo chroot ~/bbb/rootfs /bin/bash
  7. Finish setting up packages:

    # bbb-chroot
    dpkg --configure -a
    • Answer "no" when asked if you want to use "dash" as "/bin/sh".
    • I choose UTC for the time zone (13, then 33). You can use what you want here, though.
  8. Set the root user password

    # bbb-chroot
  9. Add a user and (if desired) give it sudo permissions

    # bbb-chroot
    adduser gobysoft
    printf "gobysoft       ALL=(ALL) ALL" >> /etc/sudoers
  10. Configure locales for your language(s). I'm assuming you're US English (en_US.UTF-8); if not, choose other locales.

    # bbb-chroot
    dpkg-reconfigure locales

    (138 is en_US.UTF-8, probably set this to default)

  11. Add the filesystems ( to fstab

    # bbb-chroot
    zile /etc/fstab
    # /etc/fstab: static file system information.
    # <file system> <mount point>   <type>  <options>       <dump>  <pass>
    proc            /proc           proc    defaults        0       0
    /dev/mmcblk0p2   /           auto   errors=remount-ro   0       1
    /dev/mmcblk0p1   /boot/uboot auto   defaults            0       2

    Then for now, manually mount the proc filesystem: :

    mount proc
  12. Add a DNS server (Google is a decent choice)

    # bbb-chroot
    printf "nameserver" > /etc/resolv.conf
  13. Add a sane static network (if you need DHCP install the isc-dhcp-client package using apt-get))

    # bbb-chroot
    zile /etc/network/interfaces
    auto lo
    iface lo inet loopback
    auto eth0
    iface eth0 inet dhcp
  14. Restart networking to apply the new interface eth0

    # bbb-chroot
    /etc/init.d/networking restart

    You might get an error here depending on the status of eth0 on the host. Try pinging something to see if that works anyway: :

    # bbb-chroot

    If it doesn't, make sure the host's networking is working.

  15. Update the apt repositories

    # bbb-chroot
    apt-get update
  16. Give the computer a name

    # bbb-chroot
    printf "seapup" > /etc/hostname
    printf "   seapup\n" >> /etc/hosts
  17. Add a tty (console) on the appropriate serial port

    # bbb-chroot
    printf "T0:23:respawn:/sbin/getty -L ttyO0 115200 vt102\n" >> /etc/inittab
  18. Do anything else you want to do in the chroot environment, such as installing Goby: InstallFromSource. Your host computer (even running QEMU) is likely much faster than the BBB itself.

  19. Unmount proc and dev

    • umount proc
    • umount dev
  20. Type "exit" or Ctrl-D from the chroot'd bash.

Copy over the root filesystem and boot the BBB

  1. Copy over the files to the SD card (recursive, preserving permissions and showing progress):

    # host
    cd ~/bbb/rootfs
    sudo rsync -aP . /media/rootfs/

    In the future, if you make changes to the rootfs on the host computer that you can to propagate to the SD card, simply run this command again. Run it with source and destination reversed to update the host computer rootfs if you make changes directly on the SD card.

  2. Unmount the SD card partitions:

    # host
    sudo umount /media/boot
    sudo umount /media/rootfs
  3. Remove the SD card from the host and insert into the BBB.

  4. Power on the BBB (either through the 5V supply or the supplied USB cable).

  5. SSH in or use the serial console and login using "gobysoft" and the password you gave when creating that user.

Compiling C and C++ code for the BBB

There are several approaches to compiling for the BBB:

  1. Native compilation on the board itself:

    • Pros: Easy to setup
    • Cons: Slow, requires access to the BBB.
    • How to use: Simply sudo apt-get install build-essential on the BBB and go from there.
  2. "Native" emulated compilation on the chroot using QEMU (Note, this can be used to compile Debian packages using pbuilder-dist, which makes dependency resolution a breeze.)

    • Pros: Relatively easy to setup, probably faster than native, doesn't require access to the BBB.
    • Cons: Slower than full speed cross-compilation
    • How to use: chroot in the filesystem on the host, then sudo apt-get install build-essential. For building Debian packages, see (you'll be using pbuilder-dist wheezy armhf ...).
  3. Cross-compiling on the host system (which should probably be a Debian Wheezy machine to avoid dependency problems with Ubuntu versions of these packages).

    • Pros: Fast, doesn't require access to the BBB.

    • Cons: Can be cumbersome to setup for projects with significant dependencies (but xapt has gone a long way to help with this).

    • How to use: Get the cross-compilers from

      1. Add to /etc/apt/sources.list (unstable is not a typo here, it appears that as of this writing that the Emdebian folks haven't switched to calling Wheezy stable):

        deb unstable main
      2. sudo apt-get install emdebian-archive-keyring

      3. sudo apt-get update


      sudo apt-get install gcc-4.7-arm-linux-gnueabihf xapt
      sudo xapt -a armhf -m libstdc++6-4.6-dev
      sudo apt-get install g++-4.7-arm-linux-gnueabihf
      1. Compile your code using the appropriate cross compiler, e.g.

        /usr/bin/arm-linux-gnueabihf-g++-4.7 hello.cpp -o hello-cc
      2. If you need dependencies, install them with xapt. E.g.,

        sudo xapt -a armhf -m libboost-date-time-dev
        /usr/bin/arm-linux-gnueabihf-g++-4.7 date-time-test.cpp -o date-time -L /usr/arm-linux-gnueabihf/lib/ -lboost_date_time

The referenced codes are hello.cpp:

#include <iostream>

int main()
   std::cout << "Hello world!" << std::endl;


and date-time-test.cpp

#include <iostream>
#include <boost/date_time.hpp>

int main()
  std::cout << to_simple_string(boost::posix_time::second_clock::universal_time()) << std::endl;

Compile and install libvpx (VP8 video codec library)

The VP8 video codec library is already available in the main Debian repository. Run

sudo apt-get install libvpx-dev

to get the development headers and library. See also and

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.