Chapter 1. Basics
1.0 Introduction
When you buy BeagleBone Black, pretty much everything you need to get going comes with it. You can just plug it into the USB of a host computer, and it works. The goal of this chapter is to show what you can do with your Bone, right out of the box. It has enough information to carry through the next three chapters on sensors (Chapter 2), displays (Chapter 3), and motors (Chapter 4).
1.1 Picking Your Beagle
Solution
For someone new to the BeagleBoard.org boards, the BeagleBone Black is the obvious choice. It’s the newest and cheapest (~$55 USD) of the inexpensive Bones, and there are nearly a quarter-million units out there. Many of the recipes in this book will work on the other Beagles, too, but the Black is where to begin. If you already have BeagleBone Black, you can move on to the next recipe. If you have another Beagle, your mileage may vary.
Discussion
If you already have a BeagleBoard and it isn’t a Black, read on to see what it can do.
Note
There is a high-end line and a low-end line for BeagleBoard.org boards. The BeagleBoards are the higher-end boards, with strongest appeal to advanced Linux hackers looking for affordable solutions with digital signal processors (DSPs) and features that can improve display performance. The BeagleBones are the lower-end boards, with strongest appeal to everyday “makers” of things, including lots of low-level I/O, but they still have reasonable display performance.
The Original BeagleBoard
The original BeagleBoard (Figure 1-1) came out in July 2008.
Figure 1-1. The original BeagleBoard
The original BeagleBoard used the very first ARM Cortex-A8 processor, starting at 600 MHz with 256 MB of RAM. The clock frequency was then increased to 720 MHz. Figure 1-2 shows more details of its original features.
Figure 1-2. Details of the original BeagleBoard
There are many in the field, and they are still being sold, but the newer Bones are a better starting point.
BeagleBoard-xM
The BeagleBoard-xM (Figure 1-3) began shipping August 2010.
Figure 1-3. The BeagleBoard-xM
The xM brings with it a faster ARM processor running at 1 GHz, twice the RAM as the original at 512 MB, and four USB ports. Figure 1-4 shows additional features. The xM sells for $150 USD.
Figure 1-4. Details of the BeagleBoard-xM
The xM is a good choice if you want to use the BeagleBoard as a small workstation. You can plug in a USB keyboard, mouse, and an HDMI display. Add a 5 V power supply, and you are ready to run without the need of a host computer.
BeagleBone White
The original BeagleBone appeared in October 2011. Shown in Figure 1-5, it’s white (thus the name BeagleBone White), and it sells for $90 USD. It dropped back to 256 MB RAM and 720 MHz clock, but it can fit in an Altoids tin.
Figure 1-5. The original BeagleBone, known as the White
The BeagleBone also adds two 46-pin expansion headers (shown in Figure 1-6) and the ability to add capes (Chapter 9).
Figure 1-6. Details of the BeagleBone White
The White can run the same software images off the same SD cards as the Black does, so everything presented in this book will also run on the White.
BeagleBone Black
April 2013 saw the introduction of BeagleBone Black (shown in Figure 1-7), which is the real focus of the recipes in this book.
Figure 1-7. The BeagleBone Black
The Black initially reduced the price by half, to $45 USD, bumped the RAM back to 512 MB, and pushed the clock to 1 GHz. It also added 2 GB of onboard flash memory. Rev C of the board increased the onboard flash to 4 GB and raised the price to $55 USD. All this, and, again, it still fits in an Altoids tin.
Figure 1-8 provides more details on the BeagleBone Black.
Figure 1-8. Details of the BeagleBone Black
This book focuses on BeagleBone Black (simply called the Bone here), so more details will follow.
BeagleBoard-X15
At the time of this writing (late 2014/early 2015), the newest addition to the orginal BeagleBoard lineup has not yet had any official details announced. However, due to the open development nature of BeagleBoard.org, many potential details of BeagleBoard-X15 have been discussed in public mailing lists and blog posts, such as the post on the cnx-software blog. The concept is to have support in the mainline u-boot and Linux kernel projects ahead of public hardware availability. The BeagleBoard wiki provides the current state of development. Figure 1-9 shows an image of the current prerelease development board.
Figure 1-9. The BeagleBoard-X15
The current prerelease board measures 4ʺ x 4.2ʺ, is based on a Texas Instruments dual-core ARM Cortex-A15 processor running at 1.5 GHZ, and features 2 GB of DDR3L memory. It includes an estimated 157 general-purpose input/output (GPIO) pins and interfaces for audio I/O, simultaneous LCD and HDMI video output, PCIe, eSATA, USB3, and dual-gigabit Ethernet. Additional processing elements include dual TI C66x DSPs, dual ARM Cortex-M4s, dual PRU-ICSS subsystems, and multiple image/graphics processing engines.
BeagleBoard-X15 is going to be an amazing machine, but it will be a fair bit more expensive and complicated. Starting with BeagleBone Black and moving up to BeagleBoard-X15 when you’ve identified a clear need for its power is a good approach.
1.2 Getting Started, Out of the Box
Solution
Fortunately, you have all you need to get running: your Bone and a USB cable. Plug the USB cable into your host computer (Mac, Windows, or Linux) and plug the mini-USB connector side into the USB connector near the Ethernet connector on the Bone, as shown in Figure 1-10.
Figure 1-10. Plugging BeagleBone Black into a USB port
The four blue USER LEDs will begin to blink, and in 10 or 15 seconds, you’ll see a new USB drive appear on your host computer. Figure 1-11 shows how it will appear on a Windows host, and Linux and Mac hosts will look similar. The Bone acting like a USB drive and the files you see are located on the Bone.
Figure 1-11. The Bone appears as a USB drive
Open the drive and open START.htm using Google Chrome or Firefox (Figure 1-12).
Tip
Some users have reported problems when using Internet Explorer with the web pages served up by the Bone, so make sure to use Chrome or Firefox.
Figure 1-12. Open START.htm
Follow the instructions (Figure 1-13) for installing the USB drivers for your host computer’s operating system (OS).
Figure 1-13. Install the USB drivers
On your host, browse to http://192.168.7.2 (Figure 1-14).
Figure 1-14. Open http://192.168.7.2 on your host computer
You are now ready to explore your Bone. Look around. There’s lots of information on the page.
Tip
The green banner at the top of the page means the browser is talking to the Bone, and code on the page can be edited and run on the Bone. Try scrolling down to the code in “BoneScript interactive guide” and running it. Then try editing the code and running it again. Take five minutes and try it! Watch out, though, because you can’t save your edits. You need Cloud9 for that, as discussed next.
Also be sure to browse to http://192.168.7.2:3000 from your host computer (Figure 1-15).
Figure 1-15. Cloud9
Here, you’ll find Cloud9, a web-based integrated development environment (IDE) that lets you edit and run code on your Bone! See Recipe 1.6 for more details.
Note
Cloud9 can have different themes. If you see a white background, you can match the cookbook’s figures by clicking on the Main Theme drop-down menu and selecting Cloud9 Classic Dark Theme.
Warning
Make sure you turn off your Bone properly. It’s best to run the halt command:
bone# halt The system is going down for system halt NOW! (pts/0)
This will ensure that the Bone shuts down correctly. If you just pull the power, it’s possible that open files won’t close properly and might become corrupt.
Discussion
The rest of this book goes into the details behind this quick out-of-the-box demo. Explore your Bone and then start exploring the book.
1.3 Verifying You Have the Latest Version of the OS on Your Bone
Solution
This book uses Debian, the Linux distribution that currently ships on the Bone. However this book is based on a newer version (2014-11-11 image) than what is shipping at the time of this writing. You can see which version your Bone is running by following the instructions in Recipe 1.2 to open the USB drive that comes from the Bone, as shown in Figure 1-12. But instead of opening START.html, open ID.txt (shown with the dashed arrow in Figure 1-12). You’ll see something like Figure 1-16, in which 2014-11-11 is the date of the image.
Figure 1-16. Contents of ID.txt
Discussion
If you don’t find ID.txt on your drive, or if the date given isn’t 2014-11-11 or newer, you may need to update your image, as described in Recipe 1.10.
Note
Many of the following examples in this chapter and Chapter 2, Chapter 3, and Chapter 4 may run fine on an older image. Try it and see. If you run into problems, see Recipe 1.10 to update your Bone’s OS version.
1.4 Running the BoneScript API Tutorials
Solution
Plug your board into the USB of your host computer and browse to http://192.168.7.2/Support/bone101/ using Google Chrome or Firefox (as shown in Recipe 1.2). In the left column, click the BoneScript title, which will take you to http://192.168.7.2/Support/BoneScript/ (Figure 1-17).
Figure 1-17. The BoneScript API examples page
Tip
Explore the various demonstrations of the BoneScript API. The BoneScript examples page lists several places to learn more about JavaScript and BoneScript (Figure 1-17).
If the banner is green, the examples are live. Clicking the “run” button will make them run on your Bone.
Tip
Here’s yet another place to explore. In the left column of Figure 1-17, click the function names. Take five minutes and see what you can find.
Warning
You can edit the JavaScript on the BoneScript API examples page, but you can’t save it for later. If you want to edit and save it for later, fire up Cloud9 (Recipe 1.6) and look in the examples folder.
Discussion
The JavaScript BoneScript API tutorials use Socket.IO to create a connection between your browser and your Bone. The editor running in these tutorials gives you the ability to edit the examples quickly and try out new code snippets, but it doesn’t provide the ability to save.
Visit the BONE101 GitHub page and select the “Fork me on GitHub” link (Figure 1-18) to learn more about how these tutorials are implemented and how you can embed similar functionality into your own web pages.
Figure 1-18. Bone101 GitHub page
1.5 Wiring a Breadboard
Solution
Many of the projects in this book involve interfacing things to the Bone. Some plug in directly, like the USB port. Others need to be wired. If it’s simple, you might be able to plug the wires directly into the P8 or P9 headers. Nevertheless, many require a breadboard for the fastest and simplest wiring.
To make this recipe, you will need:
-
Breadboard and jumper wires (see “Prototyping Equipment”)
Figure 1-19 shows a breadboard wired to the Bone. All the diagrams in this book assume that the ground pin (P9_1 on the Bone) is wired to the negative rail and 3.3 V (P9_3) is wired to the positive rail.
Figure 1-19. Breadboard wired to BeagleBone Black
Discussion
There are many good tutorials online about wiring breadboards. (See How to Use a Breadboard [http://bit.ly/1NJMFom] and Breadboard Basics for Absolute Beginners [http://bit.ly/1FaPB9M/], for example). The key thing to know is which holes are attached to which. Figure 1-20 gives a clear illustration of the connections.
Figure 1-20. Breadboard hole connections
The rails, or buses, are the pairs of columns of holes that run up and down on the left and right side of the board. All the holes in one column are electrically wired together. Therefore, attaching ground to the rightmost column makes ground available everywhere on that column. Likewise with attaching 3.3 V to the next column over, it’s easily wired from anywhere up and down that column.
In the middle, groups of five holes are wired from left to right, as shown in Figure 1-20. For example, Figure 1-21 shows a pushbutton switch plugged into four holes.
Figure 1-21. Diagram for wiring a pushbutton
The lower-right pin of the pushbutton is connected to a hole of the breadboard that is electrically connected to the four holes to the right of it. The rightmost hole of that group is wired to the plus column; therefore, it attaches the pushbutton to the 3.3 V on the Bone. The upper-right pin of the pushbutton is electrically connected to the four holes to the right of it; the rightmost pin is wired to GPIO pin P9_42 on the Bone.
If you’re careful when wiring to keep the wires flat on the board, it’s easy to understand and debug a moderately complex circuit.
Warning
By default, many of the Bone’s GPIO pins are configured as inputs, such as we would want in this circuit. Later, we’ll show you that they can be configured as outputs, and thus you should take care to avoid shorting an output pin. If the switches were connected as shown in Figure 1-21 and the GPIO pins were configured as outputs, having the buttons active would cause the GPIO pin to be shorted to 3.3 V. If the pin were outputting a low or 0, it would try to sink all the current it could to make the pin go low. The result is that the pin would burn out.
Note
In addition to the GPIO pins being able to be either inputs or outputs, there are also internal pull-up and pull-down resistors on the Bone’s GPIO pins. It is necessary to use the pull-down mode of the GPIO pins for this circuit to work predictably. Otherwise, when the switches are open, the input pins are not connected electrically and will be in an unknown state.
1.6 Editing Code Using the Cloud9 IDE
Solution
Plug your Bone into a host computer via the USB cable. Open a browser (either Google Chrome or FireFox will work) on your host computer (as shown in Recipe 1.2). After the Bone has booted up, browse to http://192.168.7.2:3000 on your host. You will see something like Figure 1-15.
Click the examples folder on the left and then double-click blinkled.js. You can now edit the file. If you would like to edit files in your home directory, on the left of the Cloud9 screen, go to the Preferences wheel in the Workspace browser and select Add Home to Favorites (Figure 1-22). Now, your home directory will show up in the Workspace file tree.
Figure 1-22. Making your home folder appear in Cloud9
Note
If you edit line 13 of the blinkled.js file (setInterval(toggle, 1000);), changing 1000 to 500, you must save the file before running it for the change to take effect. The blue LED next to the Ethernet port on your Bone will flash roughly twice as fast.
Figure 1-22 shows /root has been added under FAVORITES.
Note
The cloud9 folder that appears under FILE SYSTEM is located in /var/lib/cloud9 on your Bone.
Discussion
The Bone comes with a nice web-based IDE called Cloud9. You can learn all about it at the Cloud9 website, although it’s easy enough to use that you can just dive in and begin using it.
Warning
By default, the Bone’s operating system runs the Cloud9 IDE as the root user. In Linux, this is a special account that has privileges to perform many operations often excluded to normal user accounts. These operations include accessing various hardware features and contents of various files, along with the ability to modify the on-board flash contents. This was done to make many tasks simpler to complete, but caution should be used before editing system files you don’t understand. The good news is that you can always read Recipe 1.13 to learn how to restore the onboard flash to the factory contents.
You can find out more about the root account on the Linux Documentation Project System Administrator’s guide’s entry on accounts and Debian’s wiki entry on the root user.
1.7 Running JavaScript Applications from the Cloud9 IDE
Solution
Cloud9 has a bash command window built in at the bottom of the window. You can run your code from this window. To do so, add #!/usr/bin/env node at the top of the file that you want to run and save.
At the bottom of the Cloud9 window are a series of tabs (Figure 1-23).
Click the bash tab (it should be the leftmost tab). Here, you have a command prompt. In my case, it’s root@yoder-debian-bone:/var/lib/cloud9#. Yours will be slighly different, but it should end with a #.
Figure 1-23. Cloud9 debugger
Change to the directory that contains your file, make it executable, and then run it:
root@bone:/var/lib/cloud9# cd examples root@bone:/var/lib/cloud9/examples# chmod +x blinkled.js root@bone:/var/lib/cloud9/examples# ./blinkled.js
The cd is the change directory command. After you cd, you are in a new directory, and the prompt reflects that change. The chmod command changes the mode of the file. The +x indicates that you want to add execute permission.
You need to use the chmod +x command only once. Finally, ./blinkled.js instructs the JavaScript to run. You will need to press ^C (Ctrl-C) to stop your program.
Discussion
The Debian distribution we are using comes with two users: root and debian. The bash command window for Cloud9 runs as root; you can tell this by looking at the last character of the prompt. If it’s a #, as shown here, you are running as root. If it’s a $, you are running as a normal user (debian).
Note
In this book, we assume that you are running as root.
Warning
root is also known as the superuser. Running as root, you can access most everything on the Bone. This is both good and bad. If you know what you are doing, you can easily interact with all of the hardware. But, if you don’t know what you are doing, you can really mess things up. If you follow our examples carefully, you shouldn’t have any problems.
Warning
Initially, the root password isn’t set, so anyone can log in without a password. This may be OK if your Bone is never connected to the network, but it’s better practice to set a password:
bone# passwd Enter new UNIX password: Retype new UNIX password: passwd: password updated successfully
For security, the password you type won’t be displayed.
1.8 Running Applications Automatically
Solution
This is an easy one. In Cloud9, notice the folder called autorun (Figure 1-24). Place any BoneScript files you want to run at boot time in this folder. The script will begin execution immediately and will stop execution when you remove the file from this folder.
Figure 1-24. Making applications autorun at boot-up time
You can drag and drop the script into the autorun folder using the Cloud9 IDE workspace view, or you can move it using the bash prompt:
bone# mv myApp.js autorun
Discussion
Your script will start running as soon as you copy it to the folder and will run every time you boot up the Bone. In fact, it will run as soon as you put it in the folder, and if you change the file, it will restart with the current contents.
This solution currently works with Node.js applications, Python scripts, and .ino Arduino sketches (files ending in .js, .py, or .ino, respectively). You can check the BoneScript GitHub repository to see if any other types have been added.
1.9 Finding the Latest Version of the OS for Your Bone
Solution
Note
At the time they were written, these instructions were up-to-date. Go to http://beagleboard.org/latest-images for the latest instructions.
On your host computer, open a browser and go to http://rcn-ee.net/deb/testing/. This shows you a list of dates of the most recent Debian images (Figure 1-25).
Figure 1-25. Latest Debian images
Clicking a date will show you several variations for that particular date. Figure 1-26 shows the results of clicking 2014-11-11.
Figure 1-26. Latest Debian images for a given date
Clicking lxde-4gb/ shows a list of 4 GB images (Figure 1-27).
Figure 1-27. Latest 4 GB Debian images for a given date
These are the images you want to use if you are flashing a Rev C BeagleBone Black onboard flash, or flashing a 4 GB or bigger miscroSD card. The image beginning with bone-debian-7.7-lxde is used for programming the microSD card. The one beginning with BBB-eMMC-flasher-deb is for programming the onboard flash memory.
Discussion
There are a number of images posted on this site. The subdirectory names, such as lxde-4gb, might change with time and might take some investigating to learn what they mean. In this case, a simple Google search reveals that lxde is the Lightweight X11 Desktop Environment. The -4gb means it’s a 4 GB image. The other lxde has 2 GB images, which are needed for the pre-Rev C BeagleBone Blacks, because their onboard flash is only 2 GB. The lxqt has images that use the next generation of the Lightweight Desktop Environment. These images are for a newer release of Debian.
Warning
You can try running a newer release, but things might not work exactly as described in this text. See Recipe 5.15 for information about the Debian release system.
The images suggested here are big installations with many important applications already included. If you want an image with almost nothing included, try console (Figure 1-26). The images in this folder are very minimal, with very few programs installed (for example, Cloud9 and BoneScript are missing), but they have enough to boot up and run. Notice that they are about one-tenth the size of the complete installs.
1.10 Running the Latest Version of the OS on Your Bone
Solution
This solution is to flash an external microSD card and run the Bone from it. If you boot the Bone with a microSD card inserted with a valid boot image, it will boot from the microSD card. If you boot without the microSD card installed, it will boot from the onboard flash.
Tip
If you want to reflash the onboard flash memory, see Recipe 1.13.
Note
I instruct my students to use the microSD for booting. I suggest they keep an extra microSD flashed with the current OS. If they mess up the one on the Bone, it takes only a moment to swap in the extra microSD, boot up, and continue running. If they are running off the onboard flash, it will take much longer to reflash and boot from it.
Windows
If you are using a host computer running Windows, go to http://rcn-ee.net/deb/testing/2014-11-11/lxde-4gb/, and download bone-debian-7.7-lxde-4gb-armhf-2014-11-11-4gb.img.xz. It’s more than 500 MB, so be sure to have a fast Internet connection. Then go to http://beagleboard.org/getting-started#update and follow the instructions there to install the image you downloaded.
Linux
If you are running a Linux host, plug a 4 GB byte or bigger microSD card into a reader on your host and run Disks.
Select the microSD Drive and unmount (Figure 1-28) any partitions that have mounted. Note the path to the device (shown with an arrow in Figure 1-28) at the top of the Disks window. In my case, it’s /dev/sdb. We’ll use this path in a moment.
Figure 1-28. Unmounting the microSD card via the Disks application
Run the following command to download the 2014-11-11 image (be sure that you have a fast Internet connection; it’s more than 500 MB in size):
host$ wget http://rcn-ee.net/deb/testing/2014-11-11/lxde-4gb/\ bone-debian-7.7-lxde-4gb-armhf-2014-11-11-4gb.img.xz
This will copy the disk image to the current directory the command was run from to your host computer. This will take a couple minutes on a fast connection.
The downloaded file is compressed. Uncompress it by using the following command:
host$ unxz bone-debian-7.7-lxde-4gb-armhf-2014-11-11-4gb.img.xz
After a minute or so, the compressed .imgxz file will be replaced by the uncompressed .img file. Then write it to the microSD card by using the following command, substituting your device path noted earlier (/dev/sdb, in my case) for the device path given in the dd command:
host$ sudo dd if=bone-debian-7.7-lxde-4gb-armhf-2014-11-11-4gb.img \
of=/dev/sdb bs=8M
The dd command takes 5 to 10 minutes.
Warning
This operation will wipe out everything on the microSD card. It might be worth plugging in your card, noting the path, removing the card, noting it has disappeared, and then plugging it in again and checking the path. You can really mess up your host if you have selected the wrong disk and used the wrong path. Be careful.
Note
When formatting SD cards, you often need to be sure to have a bootable partition. Because you are completly rewriting the card, it doesn’t matter how the card is configured before writing. The dd command writes everything the way it needs to be.
When you have your microSD card flashed, put it in the Bone and power it up. The USB drive and other devices should appear as before. Open Cloud9 (Recipe 1.6) and, in the bash tab, enter:
root@beaglebone:/var/lib/cloud9# df -h Filesystem Size Used Avail Use% Mounted on rootfs 3.2G 2.0G 1.0G 29% / udev 10M 0 10M 0% /dev tmpfs 100M 676K 99M 1% /run /dev/mmcblk0p2 7.2G 2.0G 5.0G 29% / tmpfs 249M 0 249M 0% /dev/shm tmpfs 249M 0 249M 0% /sys/fs/cgroup tmpfs 5.0M 0 5.0M 0% /run/lock tmpfs 100M 0 100M 0% /run/user /dev/mmcblk0p1 96M 62M 35M 65% /media/BEAGLEBONE /dev/mmcblk1p2 1.8G 290M 1.4G 18% /media/rootfs /dev/mmcblk1p1 16M 520K 16M 4% /media/BEAGLEBONE_
This prints out how much of the disk is free. The first line is the one we’re interested in. If the Size is much smaller than the size of your microSD card, you’ll need to resize your partition. Just enter the following:
root@beaglebone:/var/lib/cloud9# cd /opt/scripts/tools/ root@beaglebone:/opt/scripts/tools# ./grow_partition.sh root@beaglebone:/opt/scripts/tools# reboot root@beaglebone:/var/lib/cloud9# df -h Filesystem Size Used Avail Use% Mounted on rootfs 7.2G 2.0G 5.0G 29% / udev 10M 0 10M 0% /dev tmpfs 100M 676K 99M 1% /run /dev/mmcblk0p2 7.2G 2.0G 5.0G 29% / tmpfs 249M 0 249M 0% /dev/shm tmpfs 249M 0 249M 0% /sys/fs/cgroup tmpfs 5.0M 0 5.0M 0% /run/lock tmpfs 100M 0 100M 0% /run/user /dev/mmcblk0p1 96M 62M 35M 65% /media/BEAGLEBONE /dev/mmcblk1p2 1.8G 290M 1.4G 18% /media/rootfs /dev/mmcblk1p1 16M 520K 16M 4% /media/BEAGLEBONE_
This clever script will figure out how big the partition can be and grow it to that size. A reboot is necessary.
Here, I started by putting a 4 GB image on an 8 GB microSD card. Initially, only 3.2 GB were usable. After growing the partition, most of the card (7.2 GB) is available.
Mac
If you are running from a Mac host, the steps are fairly similar to running on a Linux host, except that you won’t be able to view the Linux partition on the created microSD card.
Begin by plugging a 4 GB or bigger microSD card into a reader on your host and then run Disk Utility. Select the disk and click Info. In Figure 1-29, you can see the Disk Identifier is disk1s1.
Figure 1-29. Examining the microSD card via the Disk Utility application
The important part of the Disk Identifier is the number immediately following disk (a 1 in Figure 1-29). We’ll use this identifier to overwrite the microSD contents.
From your Mac’s Terminal, run the following command to download the 2014-11-11 image (again, be sure that you have a fast Internet connection, because it’s more than 500 MB):
mac$ curl -O http://rcn-ee.net/deb/testing/2014-11-11/lxde-4gb/\ bone-debian-7.7-lxde-4gb-armhf-2014-11-11-4gb.img.xz
You’ll need to have the xz utility installed (download from The Tukaani Project [http://tukaani.org/xz/]). Uncompress the image by using the following command (this will take a minute or so):
mac$ unxz bone-debian-7.7-lxde-4gb-armhf-2014-11-11-4gb.img.xz
Then write it to the microSD card, substituting your device path noted earlier (/dev/rdisk1, in my case) for the device path given in the dd command:
mac$ sudo dd if=bone-debian-7.7-lxde-4gb-armhf-2014-11-11-4gb.img of=/dev/rdisk1
You’ll need to type in your password. The dd command takes 5 to 10 minutes.
Warning
This operation will wipe out everything on the microSD card. It might be worth plugging in your card, noting the path, removing the card, noting it has disappeared, and then plugging it in again and checking the path. You can really mess up your host if you have selected the wrong disk and used the wrong path. Be careful.
Note
Note that I used rdisk1 rather than disk1. According to the eLinux wiki, doing so will speed up writing quite a bit.
Discussion
BeagleBone Black can run its OS from the onboard flash memory (2 GB on older Blacks and 4 GB on the new Rev Cs) or from a microSD card. The 2 GB is a bit small, so I advise my students to use a 4 GB or bigger microSD card. If you want to use the onboard flash, see Recipe 1.13.
1.11 Updating the OS on Your Bone
Problem
You’ve installed the latest version of Debian on your Bone (Recipe 1.10), and you want to be sure it’s up-to-date.
Solution
Ensure that your Bone is on the network and then run the following command on the Bone:
bone# apt-get update bone# apt-get upgrade
If there are any new updates, they will be installed.
Note
If you get the error The following signatures were invalid: KEYEXPIRED 1418840246, see eLinux support page for advice on how to fix it.
Discussion
After you have a current image running on the Bone, it’s not at all difficult to keep it upgraded.
1.12 Backing Up the Onboard Flash
Solution
The eLinux page on BeagleBone Black Extracting eMMC contents provides some simple steps for copying the contents of the onboard flash to a file on a microSD card:
-
Get a 4 GB or larger microSD card that is FAT formatted.
-
If you create a FAT-formatted microSD card, you must edit the partition and ensure that it is a bootable partition.
-
Download beagleboneblack-save-emmc.zip and uncompress and copy the contents onto your microSD card.
-
Eject the microSD card from your computer, insert it into the powered-off BeagleBone Black, and apply power to your board.
-
You’ll notice
USER0(the LED closest to the S1 button in the corner) will (after about 20 seconds) begin to blink steadily, rather than the double-pulse “heartbeat” pattern that is typical when your BeagleBone Black is running the standard Linux kernel configuration. -
It will run for a bit under 10 minutes and then
USER0will stay on steady. That’s your cue to remove power, remove the microSD card, and put it back into your computer. -
You will see a file called BeagleBoneBlack-eMMC-image-XXXXX.img, where XXXXX is a set of random numbers. Save this file to use for restoring your image later.
Note
Because the date won’t be set on your board, you might want to adjust the date on the file to remember when you made it. For storage on your computer, these images will typically compress very well, so use your favorite compression tool.
Tip
The eLinux wiki is the definitive place for the BeagleBoard.org community to share information about the Beagles. Spend some time looking around for other helpful information.
Discussion
The beagleboneblack-save-emmc.zip file contains just enough of a Linux operating system to know how to copy an image from the onboard flash to a file. The code that does the work is in autorun.sh, which is shown in Example 1-1.
Example 1-1. Code for copying from onboard flash to microSD card
#!/bin/sh echo timer > /sys/class/leds/beaglebone\:green\:usr0/trigger dd if=/dev/mmcblk1 of=/mnt/BeagleBoneBlack-eMMC-image-$RANDOM.img bs=10M sync echo default-on > /sys/class/leds/beaglebone\:green\:usr0/trigger
The first echo changes the USER0 LED to flash a different pattern to show the copy is being made. The dd command then copies the onboard flash image from input file (if) /dev/mmcblk1 to an output file (of) on the microSD card called /mnt/BeagleBoneBlack-eMMC-image-$RANDOM.img. /dev/mmcblk1 is where the entire onboard flash appears as a raw image and dd just copies it.
The final echo turns the USER0 LED on to notify you that the copying is over.
You can use the same microSD card to copy an .img file back to the onboard flash. Just edit the autorun.sh file to include Example 1-2. This code is largely the same as Example 1-1, except it reverses the direction of the dd command.
Example 1-2. Restore .img file back to the onboard flash
#!/bin/sh echo timer > /sys/class/leds/beaglebone\:green\:usr0/trigger dd if=/mnt/BeagleBoneBlack-eMMC-image-XXXXX.img of=/dev/mmcblk1 bs=10M sync echo default-on > /sys/class/leds/beaglebone\:green\:usr0/trigger
To copy the saved image back, eject the microSD card from your computer, insert it into the powered-off Bone, and apply power. Remember, because you are programming the onboard flash, you will need to use an external 5 V power supply. The Bone will boot up from the microSD card and write the backup files to the onboard flash.
1.13 Updating the Onboard Flash
Solution
Note
At the time of this writing, these instructions were up-to-date. Go to http://beagleboard.org/latest-images for the latest instructions.
If you want to use the onboard flash, you need to repeat the steps in Recipe 1.10, substituting BBB-eMMC-flasher-debian-7.7-lxde-4gb-armhf-2014-11-11-4gb.img.xz for lxde-4gb/bone-debian-7.7-lxde-4gb-armhf-2014-11-11-4gb.img.xz.
That is, download, uncompress, and copy to a microSD card by using the following commands:
host$ wget http://rcn-ee.net/deb/testing/2014-11-11/\
BBB-eMMC-flasher-debian-7.7-lxde-4gb-armhf-2014-11-11-4gb.img.xz
host$ unxz BBB-eMMC-flasher-debian-7.7-lxde-4gb-armhf-2014-11-11-4gb.img.xz
host$ sudo dd if=BBB-eMMC-flasher-debian-7.7-lxde-4gb-armhf-2014-11-11-4gb.img \
of=/dev/sdb bs=8M
Again, you’ll put the microSD card in the Bone and boot. However, there is one important difference: you must be powered from an external 5 V source. The flashing process requires more current than what typically can be pulled from USB.
Warning
If you write the onboard flash, be sure to power the Bone from an external 5 V source. The USB might not supply enough current.
When you boot from the microSD card, it will copy the image to the onboard flash. When all four USER LEDs turn off (in some versions, they all turn on), you can power down the Bone and remove the microSD card. The next time you power up, the Bone will boot from the onboard flash.
Get BeagleBone Cookbook now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.
