BeagleBone Black Cookbook: Over 60 recipes and solutions for inventors, makers, and budding engineers to create projects using the BeagleBone Black

Here's what you need:

Perform the following steps:

Power down: Before proceeding, remove all cables and power (USB, Ethernet, DC cord, HDMI, and so on).

Perform the following steps:

If the planets are aligned and the drivers are installed properly, you will see the following at the top of the browser window:

Your board is connected! BeagleBone Black rev 0A5C S/N xxxxxxxxxxxx running BoneScript 1.2.3 at 192.168.7.2.

At this point, you're ready to fly; at least at low altitude. With a co-pilot…on an emulator.

Running your board with an HDMI monitor is the default method to use your BBB.

There's no obligation to use only an HDMI display on BeagleBone Black. For example, with the right HDMI to VGA converter cable, you can actually attach a standard VGA monitor to the BBB. Compatible converters can be found at http://elinux.org/Beagleboard:BeagleBone_Black_Accessories#HDMI_Adapters.

You may also develop an embedded prototype device that only needs a small LCD and no HDMI. Here's one recipe for a scenario using a 3.5-inch screen from Circuitco (http://elinux.org/CircuitCo:BeagleBone_LCD3) that I've used in my own projects. The display is in the category of add-ons to the BBB called capes, which are akin to the shields on an Arduino board. Capes are typically robust daughterboards and, unfortunately, tend to be much more expensive than Arduino add-ons.

CircuitCo LCD3 cape

Perform the following steps:

For more information on the following topics, refer to the respective websites:

Ensure that your BeagleBone Black is set up and running in the manner described in the Introduction section. (Note that here, we will show the two different methods of running the board: powered via USB and powered via 5V).

Congratulations! You've just sent your first command to BeagleBone Black (and it wasn't Hello World). But we're getting ahead of ourselves. Commands are for the next section.

Let's take a quick look at the various parts of what LXTerminal shows us. Firstly, we know that Linux likes to keep the current user name at the front and center, in this case debian. This way, you always have a quick reference point to know whether you are a root user, which gives you total control over the system, or just another user with limited privileges.

Then comes the address of the device you're working on: beaglebone. You can actually customize the name, but we will save that for the appendix. Lastly, consider the $ sign, which denotes that you're logged in as a regular user. If you were a root user, the symbol would be the # sign. You will learn more about users and root users in a later section.

Of course, we assume that if you intend to use some command line interface (CLI) commands, you have to have your command shell window open and gain root access:

sudo

Using sudo as part of your command syntax is a requirement that often bedevils new Linux users. It is important to understand that many Linux commands demand what are known as "superuser" privileges, which grant you total control over the board and its software. Having full admin rights within a command prevents any casual user from coming along and destroying your hard work, by design or accident.

The "open sesame" of Debian Linux, the magic sudo command (pronounced "soo-doo"), means "Super User do x-command" when dissected. If you don't append your command at the beginning with sudo, your mkdir command, for example, will return a "bad command" error.

sudo -i and root

Adding the -i option (the sudo -i command) provides even more control over the environment: the root user access. When running commands as a root user, there are ample opportunities to completely mangle your system, so exercise extreme caution in its use.

However, not all commands require superuser privileges. For instance, when you're really just poking around the system and not modifying files, directories, or the system itself, sudo isn't necessary.

You should keep in mind several things when working with the command line:

Conventions

Early in the book, we will frequently use the entire line from the command line, including the user name, address, symbols connoting user type, directory, and so on. So, for example, you will see a line that looks similar to the following:

debian@beagle_bone:~$ mkdir

However, as we become more familiar with the shell, we will mostly shorten the command instruction to only include the command itself:

~$ mkdir

Alternatively, you will see a slight variation on the preceding command when we refer to a root user. Note the # sign in place of the $ sign in the following command:

~# mkdir

Now, let's move on to the commands. A super-duper subset of commands, anyway. We've organized them into System navigational commands, Device and system insight, and Modify content/data commands.

To move from one directory to another, there are numerous variations on how to do it.

Perform the following steps:

In addition to the preceding commands, you should be familiar with the four special directory symbols:

This stands for print working directory, a means to show the user where in the system they are currently working or the absolute path relative to the current directory.

Use the following command to show your current directory:

debian@beaglebone:~$ pwd
/home/Debian

Looking for a file? One way to search for it is with the find function. Just be sure to add the -name option so that the output shows the directory location. Add sudo as well so that you do not get directory access errors.

Use the following command to find a file:

$ sudo find / -name <filename>

The ls command lists the contents of your current directory.

Use the following command to see the list of contents in the current directory:

debian@beaglebone:~$ ls
Desktop

At the moment, the only thing you will see is the Desktop directory. As we continue adding content in subsequent chapters, there will be more that would be seen upon using ls.

Adding the -lah option at the end of the command gives more detailed information on the files, as follows:

debian@beaglebone:~$ ls -lah
total 112K
drwxr-xr-x 19 debian debian 4.0K May  4 23:37 .
drwxr-xr-x  3 root   root   4.0K May  5 00:05 ..
-rw-------  1 debian debian   55 May  4 23:37 .Xauthority
-rw-------  1 debian debian 2.4K May  5 01:41 .bash_history
-rw-r--r--  1 debian debian  220 Jan  1  2015 .bash_logout
-rw-r--r--  1 debian debian 3.4K Jan  1  2015 .bashrc
drwxr-xr-x  6 debian debian 4.0K Mar  8  2015 .cache
drwxr-xr-x  9 debian debian 4.0K Mar  4 23:51 .config
drwx------  3 debian debian 4.0K Mar  4 23:37 .dbus
-rw-r--r--  1 debian debian   35 Mar  4 23:37 .dmrc
drwxr-xr-x  2 debian debian 4.0K Mar  8  2015 .fontconfig
drwxr-xr-x 24 debian debian 4.0K Mar  8  2015 .gimp-2.8
drwx------  3 debian debian 4.0K Mar  8  2015 .local

The options in the command now reveal a variety of things about the file: their permission status (column 1), owner and group (columns 3 and 4), file sizes (column 5) , and modification date (column 6). The l option outputs in the list form, adding the a forces the command to show any hidden files, and the h option turns it all into a human readable format.

This captures and lists all USB devices currently connected to the BBB while showing basic information about the device.

Use the following command to find out about the USB devices connected:

debian@beaglebone:~$ lsusb
Bus 001 Device 002: ID 0d8c:013c C-Media Electronics, Inc. CM108 Audio Controller
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

Where lusb leaves off, this command lists more detailed information about any device connected to the BBB. Note the difference in output for the same USB audio device (C-media) shown in our preceding recipe using lsusb.

Use the following command to get information about connected devices:

debian@beaglebone:~$ cat /proc/bus/input/devices

I: Bus=0000 Vendor=0000 Product=0000 Version=0000
N: Name="tps65217_pwr_but"
P: Phys=
S: Sysfs=/devices/ocp.3/44e0b000.i2c/i2c-0/0-0024/input/input0
U: Uniq=
H: Handlers=kbd event0
B: PROP=0
B: EV=3
B: KEY=100000 0 0 0

I: Bus=0003 Vendor=0d8c Product=013c Version=0100
N: Name="C-Media Electronics Inc.       USB PnP Sound Device"
P: Phys=usb-musb-hdrc.1.auto-1/input3
S: Sysfs=/devices/ocp.3/47400000.usb/musb-hdrc.1.auto/usb1/1-1/1-1:1.3/input/input1
U: Uniq=
H: Handlers=kbd event1
B: PROP=0
B: EV=13
B: KEY=78 0 e0000 0 0 0
B: MSC=10

The stem of this command is cat, which is one of the most popular commands to quickly read files without writing or modifying them:

$  cat file4

You can try it with any file to see how the screen output looks.

You can find out which version and distribution of Linux you are running through several methods.

To find out your version of Linux, use the following command:

debian@beaglebone:~$ lsb_release -a

The screen output will look similar to this:

No LSB modules are available.
Distributor ID: Debian
Description: Debian GNU/Linux 7.6 (wheezy)
Release: 7.6
Codename: wheezy

The preceding command is a good complement to the more typical way we determine the actual kernel version, which is as follows:

$ uname -r
3.8.13-boneXX

In Linux, applications are referred to as processes, and each is given a unique ID number or PID. The ps (that is, process status) command provides information about the currently running tasks or processes. The output includes the PIDs.

This command takes a snapshot of your board. You can run the command unadulterated and with no options, as follows:

$ ps

But the output is a thin gruel:

debian@beaglebone:~$ ps
PID    TTY    TIME    CMD
1623    pts/0    00:00:00    bash
2035    pts/0    00:00:00    ps

So, it is often better to modify the output in order to get more insight into the running processes and display this information in a more orderly fashion, as in the following command:

$ ps aux

The following is the output:

The aux series of options complement the basic command by doing the following:

This command takes it a bit further than the ps command as it dynamically updates not only the processes running but also the CPU resources used by the processes. The status is continuous and in real time.

Use this command line:

$ top

The output is as follows:

The top command is adequate and one that you will hear most Linux users call upon, but there is now a much lovelier, easier way to read a package—htop. Let's install it and compare it to top with the following command:

$ sudo apt-get install htop

Now, the output will be as follows:

As you can see, it has an output that is much cleaner and easier to read.

The typical way to force quit—or kill—an application is to use the kill command and combine it with the process ID (PID), which you can derive from any of the preceding recipes to capture process information. Let's take a look at the basic method.

Use the following command to kill processes:

$ kill <process_id>

Here's a real example, which would force quit the top process shown in our prior recipe:

$ kill 4569

When you know the name of a process, you can use the pkill command, which operates on the process name instead, as follows:

$ pkill -9 gdb

Naturally, there is yet another way to skin the cat while killing a process. For example, you may discover that there are several processes associated with one application, and killing them one by one gets a bit slippery. Instead, use killall and kiss them goodbye:

$ killall chromium

As you already know, every time you boot up your device, a ton of messages quickly scrolls past on the screen. Unless you wear a blue leotard with a red cape and possess exceptionally fast eyes, you likely will not catch all these pearls of ASCII wisdom. Yet, these messages can be extremely useful at times, particularly when you need to troubleshoot a system problem.

The dmesg command is used as follows:

$ dmesg

Typically, the output looks similar to this:

[    0.000000] Booting Linux on physical CPU 0x0
[    0.000000] Initializing cgroup subsys cpu
[    0.000000] Linux version 3.8.13-bone47 (root@imx6q-wandboard-2gb-0) (gcc version 4.6.3 (Debian 4.6.3-14) ) #1 SMP Fri Apr 11 01:36:09 UTC 2014
[    0.000000] CPU: ARMv7 Processor [413fc082] revision 2 (ARMv7), cr=50c5387d
[    0.000000] CPU: PIPT / VIPT nonaliasing data cache, VIPT aliasing instruction cache
[    0.000000] Machine: Generic AM33XX (Flattened Device Tree), model: TI AM335x BeagleBone
[    0.000000] Memory policy: ECC disabled, Data cache writeback
[    0.000000] On node 0 totalpages: 130816
[    0.000000] free_area_init_node: node 0, pgdat c0824280, node_mem_map c089f000

The list goes on and on as your machine is full of activity! So, limiting dmesg to output smaller chunks of information with a command option is primarily the course followed. In this case, we want to show the last ten events on the system, so we will use the following:

$ dmesg | tail

Alternatively, we can use the less option, which allows us to advance forward in the list more methodically, as follows:

$ dmesg | less

This command outputs information on your board's available disk space and displays it in human readable format.

Use the following command to find out the disk space:

debian@beaglebone:~$ df -h
Filesystem      Size  Used Avail Use% Mounted on
rootfs          7.2G  1.6G  5.4G  22% /
udev             10M     0   10M   0% /dev
tmpfs           100M  824K   99M   1% /run
/dev/mmcblk0p2  7.2G  1.6G  5.4G  22% /
tmpfs           249M     0  249M   0% /dev/shm
tmpfs           249M     0  249M   0% /sys/fs/cgroup
tmpfs           100M     0  100M   0% /run/user
tmpfs           5.0M     0  5.0M   0% /run/lock
/dev/mmcblk0p1   96M   71M   25M  75% /boot/uboot
/dev/mmcblk1p2  1.7G  1.7G     0 100% /media/rootfs
/dev/mmcblk1p1   96M   11M   86M  11% /media/boot

This lists all the network devices with network information. You will commonly find yourself using this command on the BBB when you need to troubleshoot a problem or set up network connections.

Use the following command to explore network configuration:

$ ifconfig

The output is as follows:

This command helps you create a directory (folder) where you want to work or place files.

Use the following command to make a new directory:

debian@beaglebone:~$ mkdir test

Now is a good time to check your work with the ls command, as follows:

debian@beaglebone:~$ ls
Desktop  test

As the name implies, this command removes a file or directory that you designate.

Removing a file is very simple. You just need to type out the following:

$ rm file1

Adding the -i option is good practice, especially for beginners, as it prompts you to confirm the file's removal as follows:

$ rm -ir file1
rm: remove regular file `file1'?

To remove directories, there are principally two commands you can use. Firstly, when you have an empty directory, the command is similar to the following:

$ rmdir dir1

However, rmdir works only if the directory is empty. If you want to remove a directory with all its contents, you can use rm with the -r option. This option tells rm to remove a directory recursively, as in the following command:

$ rmdir -r dir1

Running this command gives you control over grabbing and downloading files from web servers via HTTP, HTTPS, and FTP. Unlike the experience of downloading a file in a web browser, wget is noninteractive. This means that you don't have to be logged on for the command to complete its task, which is potentially a great time-saver with large file downloads.

In order to download files, you can use a command such as the following:

$ wget http://

This will download the Major Tom page at www.hudsonwerks.com into your current directory and create a file named index.html. Next, perform the following steps:

Where do we put the new tarballs, packages, and so on? It is good practice to create a directory called /home/username/Packages/. This is where you can put tarballs, their extracted files, compiled code, backups of replaced files, and installation scripts. For this, you can use the following command:

$ mkdir /home/username/Packages/
$ wget -P /home/debian/packages <download-url>

Working with files in the .tar (tarball) format, a type of archived file, is common in Linux. The various options that come with the tar command will considerably ease your management of the files that are not archived.

Use the following command to open a tar file:

$ tar -zxvf file_name.tar.gz

Before actually running the command, let's understand a bit about the options:

Other file types include .xz, which is the actual file type we downloaded previously using wget—wget-1.15.tar.xz. So, here are the essential recipe steps:

The flip side of unarchiving is archiving. Here's how you can create a tar file:

$ tar -cvf file.tar inputfile1 inputfile2

Replace inputfile1 and inputfile2 with the files and/or directories that you want to combine. You can use any name in the place of file.tar; you should keep the .tar extension, though.

You may occasionally run into errors while opening tarballs (or other gzip files). If so, one troubleshooting tip is to ensure that the file is actually a zipped archive with the following command:

$ file filename

This will show the file type and size; if it's not an archive, you can't run the tar command on it.

This command removes partial packages from the system.

Use the following command to clean up files:

$ sudo apt-get autoclean

These commands completely get rid of packages and dependencies.

Use the following command to get rid of packages and dependencies:

$ sudo apt-get purge packagename

Alternatively, you can use the following command:

$ sudo apt-get remove  --purge packagename

It is a bad idea to pull the plug on your board to turn it off. Doing so can often lead to a corrupted SD card or mangled files. Instead, here's how you power down your board gracefully.

If you want to shut down the BBB and reboot it, the following command will be useful:

sudo shutdown -r now

However, if you simply want to shut down the system and power down completely, then either of the following two options will do the trick:

sudo shutdown -h now

You can alternatively use the following command:

sudo poweroff

You will find some of the best one-page cheat sheet references for Linux commands. Print them out and post them in an honored place!

When you're using nano, take note of all the options at the bottom of the screen: Exit, Get Help, Read File, and so on. You access these functions with the keyboard shortcuts shown next to each option. Beware that these shortcuts actually may change their function or mode when you navigate to another screen or choose an option. So, remember what the bottom menu says before assuming that the shortcut you just used remains in the same mode.

In the main (default) window, here's a quick rundown on the most commonly used functions and their shortcuts:

I recommend using Ctrl + G periodically when you're just beginning as a reminder for the additional functions available, many of which are powerful and useful. Overall, you will find that even a simple Linux-based text editor such as nano comes loaded with features that most Wintel/Mac desktop versions don't typically include.

This function can be performed through the following steps:

We lost our work, but it was only one line of text. We would now have popped back into the command line, and we will have another go; this time, we need a few more steps:

You've now made a very exciting .txt file that you can go back and read whenever you want. Okay, that wasn't terribly challenging. But don't worry; we will be adding more complexity as we proceed in upcoming chapters.

For those who find nano a bit Spartan in functionality and prefer a more powerful editor, vim is a popular choice. Although challenging to learn at first, you may find it to be a more rewarding and flexible choice as a tool. Learn how to use it at http://www.openvim.com/tutorial.html.

If you have direct access to your network's router, using the Ethernet connection is pretty much Plug and Play on the BBB.

Here's what you need for this recipe:

Perform the following steps for Ethernet connectivity:

Since its original release in the spring of 2013, Wi-Fi on the BBB has been a bit of an Achilles Heel for the platform. Compared to the typical experience with Raspberry Pi, you could pull out your hair getting Wi-Fi to work on the BBB. If you were happy using Angstrom only for your projects, you were in luck as this distribution was (mostly) solid, given that several USB minidongles on the market worked well.

However, on Debian and Ubuntu, unless you did not mind using larger dongles with protruding antennae, connections were flaky. Alternatively, you could invest a chunk of time writing custom drivers. So much for out-of-the-box portability.

Fast forward to the (mostly) good news. With the three different Wi-Fi dongles that we tested on the current shipping version of Debian 7 Wheezy for the BBB (using 3.8.13-bone71) and on Debian 8 Jessie, we largely got positive results. The bad news? With the exception of using Debian Jessie, not all dongles were recognized by the BBB without some configuration. However, it is fairly easy to set up the hardware, and you also may get lucky with the dongle you have in your kit and get immediate connectivity.

The following are the prerequisites for Wi-Fi connectivity:

We will divide this recipe into three different setup methods as some dongles are happy with one method while others prefer the second one. We will also include the setup for Debian 8.0 (Jessie) as this distribution has greatly improved and simplified the process.

Some of the setup instructions are derived from http://elinux.org/BBBWiFiConfigs.

The micro USB dongle models

The universe of low-cost Wi-Fi dongles available on the market is fairly large, the following table being a very small subset. The mini dongles we used in these recipes have been historically problematic with the BBB but are now more reliable with the current Debian distribution. Your best results, however, may be with a standard-sized (nonmicro) dongle that also comes accompanied by an antenna.

The following table shows the tested and working models of micro USB dongles for our recipes. Note that the first three models use Method Two for setup and the last two use Method Three. All dongles are priced around USD $10.00-12.00:

Method one: Graphical desktop application

In lieu of the command line, the current distribution of Debian 7 (3.8.13-bone71, Wheezy) includes a handy graphical tool—Wicd Network Manager—to set up Wi-Fi. This recipe is quite simple:

Although the preceding steps are straightforward, you might find that your dongle will not work with this recipe or that you are using a different version of the kernel and easy connectivity eludes you. If so, here are other recipes to get connected.

Method Two: command line option 1

Consult the table at the beginning of this section for the tested models that use Method Two. Note that they all use the same RTL8188CUS chipset. This means that you will likely be able to use other dongles with the following steps as long as they use the aforementioned chipset. Now to the steps:

Method Three: command line option 2

Consult the table for the tested models that use the following steps. The main difference between these steps and the previous recipe is that the drivers in these dongles require a different interface—a wireless supplicant—with the BBB to function properly. Before starting the steps, be sure to remove any Wi-Fi dongles you may have inserted into the USB hub:

Method Four: Debian Jessie

Using Jessie is the easiest and fastest route to a reliable Wi-Fi connection. Here is how to do this:

Some users report that the board can interfere with a Wi-Fi dongle's USB signal. So, if you do not get a reliable connection, position your powered USB device containing the Wi-Fi dongle a few feet away from the BBB.

Take a look at a list of other compatible dongles here at http://elinux.org/Beagleboard:BeagleBoneBlack#WIFI_Adapters.

Use the following steps to install packages:

Let's do a real package, though, one that we will be using in a later chapter. For our recipes focused on debugging in Chapter 3, Physical Computing Recipes Using JavaScript, the BoneScript Library, and Python, we will use a tool called gdb, also known as GNU Debugger, which is a standard tool in the Linux arsenal thus:

$ sudo apt-get update
$ sudo apt-get upgrade
$ sudo apt-get install gdb

Once you've installed the pretty package on your BBB, it's useful—and often interesting—to take a peek inside. So, another apt-get variant gives you some interesting insight:

$ sudo apt-cache show package-name

In our case, this would be as follows:

$ sudo apt-cache show gdb
Package: gdb
Version: 7.4.1+dfsg-0.1
Installed-Size: 5192
Maintainer: Hector Oron <zumbi@debian.org>
Architecture: armhf
Depends: libc6 (>= 2.13-28), libexpat1 (>= 2.0.1), libgcc1 (>= 1:4.4.0), libncurses5 (>= 5.5-5~), libpython2.7 (>= 2.7), libreadline6 (>= 6.0), libtinfo5, zlib1g (>= 1:1.2.0), gdbserver
Suggests: gdb-doc
Description-en: The GNU Debugger
 GDB is a source-level debugger, capable of breaking programs at
 any specific line, displaying variable values, and determining
 where errors occurred. Currently, gdb supports C, C++, D,
 Objective-C, Fortran, Java, OpenCL C, Pascal, assembly, Modula-2,
 and Ada. A must-have for any serious programmer.
Homepage: http://www.gnu.org/s/gdb/
Description-md5: 8132571fab028a898d029eecd88e571e

To list all installed packages, enter:

dpkg --list

Alternatively, you can use this command:

dpkg --list | less

You can also run the following command:

dpkg --list | grep -i 'http'

Note the grep option as part of the command string. One of the most popular commands on Linux, grep is a powerful search mechanism to find a particular file, a directory, a pattern or chunk of code.

Using SSH (secure shell) on a desktop PC or other client will give you control over your BBB across a network. Here is the recipe.

On your BBB:

On your PC/Mac/Linux box:

Congratulations! You've now gained control over your BBB using the command line from another box.

So, are you still not entirely comfortable with the command line and want access to some of the GUI-based tools? Or, do you need to test and control using an actual GUI? Or, perhaps, is your app not running properly from only the command line? Then, it's time for VNC.

Virtual Network Computing (VNC) allows remote access to a device that's running an X session or windows/GUI-based system from a remote device or client machine. With the current Debian distribution, running VNC is easier than ever as the BBB arrives preloaded with the relevant package, the TightVNC server. On your client box, you need to install a remote viewer.

For your client box, download and install one of the following remote viewer applications:

Once again, we're cooking up a recipe from a Mac perspective, so VNC Viewer it will be.

As noted, the BBB now comes with the remote server installed, so the only new installation required is the one for your client box. For this, perform the following steps:

You will now be logged in to your BBB, be able to see the desktop, and have full control over the device using the mouse on your client box.

Although your board comes preloaded with a shipping version of Debian 7, you certainly want to understand how to replace it or update it when necessary. Here, we will discuss the recipe to flash the OS to your internal solid-state drive along with how to update to Debian 8.

As of the writing of this book, Debian 8 (Jessie) is still considered a testing option, whereas Debian 7 (Wheezy) is the official shipping firmware OS for the BBB. Additionally, you will notice "LXQt" as part of the URL download link. LXQt is a lightweight Qt variant of LXDE, the Lightweight Desktop Environment. Qt is a toolset to build cross platform applications that you can use on Mac OS X, Windows, and Linux. It uses the C++ programming language and has a nice GUI builder, so it is a popular choice for many open source-centric developers.

You will need the following:

The following steps are used to flash the OS to your internal drive:

Good practice to manage your system OS and files includes having enough room to add more packages, being able to clone your eMMC, and backing up your code image.

In this section, you will learn the recipes to load the OS and boot from a microSD card. Much of the process is similar to how we flash the eMMC internal drive; however, it is important to take note of the differences.

You will need the following:

Perform the following steps:

Sometimes, you want to stick with what you have already installed as it runs fine and does the job. But more often than not, you want the latest and greatest kernel, including updating to Debian 8.0, aka Debian Jessie. The following steps show you how:

Compare the preceding screen output with the version you wrote down in Step 2 of this recipe. You should, hopefully, see the new version kernel goodness.

If you know a specific version you want, you can also update or modify your kernel with an alternative method using a series of command-line steps: