BeagleBoardBeginners

This is the "community" beginners guide for TI's ARM based OMAP3 Beagle Board. For "official" beginners guide see My Beagle Board Out of the box experience. If something doesn't work or isn't covered in these guides, please feel free to ask at IRC or mailing list. But before you ask there, make sure you read the FAQs.

So I got this little board, what do I do now?

=Types of BeagleBoard= There are two major types of BeagleBoard currently in existence- the original BeagleBoard and the BeagleBoard-xM. The xM was released rather recently. Consequentially, much of the online documentation that will come up on Google searches for "BeagleBoard" refers to the original version, and not the xM. Typically, the word "BeagleBoard", when used alone without modifiers, refers specifically to the original BeagleBoard and not to the BeagleBoard xM. Major differences between the two are:


 * 1. They have different inputs, so they require different peripherals, and


 * 2. The original BeagleBoard has flash NAND memory, while the BeagleBoard xM does not, so the micro SD card used to boot the xM must contain 3 files... MLO, u-boot.bin, and uImage. Original BeagleBoards have u-boot loaded on the NAND flash memory.

BB xM also has several subversions: including Rev A, Rev B, and Rev C. Each of these are slightly different, so make a note of which revision you have.

=Finding all the right hardware=

Original BeagleBoard
Links to the recommended collection of peripherals can be found on the bottom of BeagleBoard.org/hardware, but a slightly more detailed comprehensive shopping list can be found on the Beagle Board Shopping List.

BeagleBoard xM
This website has a list of required cables for xM and as well as a guide to getting the Angstrom, Android, and Ubuntu OSs running on the xM, which require slightly different processes than to do the same thing on the original BB.

Differences between requirements of the original BeagleBoard and the BeagleBoard xM
Be sure to buy at least one additional SD card. Currently, the BeagleBoard xM is shipped with a micro SD card included that has an Angstrom demo loaded on it. The demo features the Midori web browser and a full GUI desktop. Additionally, all of the USB ports work with no additional setup. The demo Angstrom OS is surprisingly fast, even though it might sound like it has a lot of stuff on it. On the demo image everything is set up correctly for the version of BeagleBoard that you bought. Writing your own SD card (even when using a prebuilt image) can lead to a surprising number of difficulties, partly due to the many different revisions of BeagleBoard which exist. It is best if you can simply keep the original card unchanged, and do your experiments on other ones. Be wary of thinking that you can simply back up the information on your desktop machine. While it is certainly possible to back up this information, some difficulties can arise since the card needs to be formatted a certain way Also, it's easy to accidentally only partially partial copy the root filesystem files off of the SD card onto your desktop machine because of the varying permissions which the different files have.

=Getting Started=

Original BeagleBoard
First of all you might want to check it for possible defects. To do so, connect a 5-pin Mini-USB cable to the board and to a computer at the other end. If everything's all right you should see one LED light up and, after a short while, two more LEDs coming up too. Also, if you connect some speakers or headphones to the audio output you should hear a burst noise when starting the board. (you won't hear a noise on Rev.C boards, ). For a more complete validiation of the rev. C hardware, see

BeagleBoard xM
xM is shipped with a micro SD card containing a demo operating system. To test if it works just click the included micro SD card into the slot, plug in a wired ethernet cable, a USB mouse, a USB keyboard, a DVI-D monitor, and THEN plug in the 5V barrel power cable. (It is important to plug in the power last, because plugging in the monitor while it is powered up can cause damage. Applying power should make it boot up, first showing the BeagleBoard logo in the top of the screen, then an Angstrom loading splash screen, then to a screen saying "Automatic login", and if you do nothing, you should soon be dragging desktop icons around and surfing the Web with Midori.

=Setting up serial connection between your desktop machine and the BeagleBoard=

(This section refers specifically to the original BeagleBoard)

Connect a serial (COM port) cable (known as the AT/Everex Cable) to the 10-pin header on the board: it's next to the power input. Actually, pin number 10 is not used on either end of the cable, so if you have an AT/Everex Cable with a plug in the hole for Pin 10, you can use needle-nose pliers to break off pin 10 on the Beagle Board. Or you could drill out the plug. I used a hot needle for this purpose and it worked. The advantage to breaking off the pin on the BeagleBoard is that now your cable is keyed, and can't be plugged in backwards. For additional information on IDC to DB9 pin connections see FAQ Serial Connection.

Now you need a Null-Modem DB9 male-male serial cable (that you can also buy from Digikey).

=First interaction with the board=

Connect the serial cable to the COM port in the beagleboard, and connect the other end to the COM port in the computer.

Super Easy Way Using GNU Screen
As root or sudo do: "screen /dev/ttyS0 115200"

Tedious Old-Fashioned Way Using Minicom
Run minicom setup as root from the host computer:

$ sudo minicom -s You'll get a screen as follows: +-[configuration]--+ | Filenames and paths     | | File transfer protocols | | Serial port setup       | | Modem and dialing       | | Screen and keyboard     | | Save setup as dfl       | | Save setup as.. |                                                   | Exit                     | | Exit from Minicom       | +--+

Select Serial port setup:

+---+      | A -    Serial Device      : /dev/ttyS1                                | | B - Lockfile Location    : /var/lock                                 | | C -  Callin Program      :                                           | | D - Callout Program      :                                           | | E -   Bps/Par/Bits       : 9600 8N1                                  | | F - Hardware Flow Control : Yes                                      | | G - Software Flow Control : No                                       | |                                                                      |       |    Change which setting? |      +---+               | Screen and keyboard      | | Save setup as dfl       | | Save setup as.. |                                                   | Exit                     | | Exit from Minicom       | +--+

Now press E to change those settings:

+---[Comm Parameters]+ +---|                                       |--+       | A -    Serial | Current: 115200 8N1                    |              | | B - Lockfile L|                                       |              | | C -  Callin P|   Speed          Parity          Data  |              | | D - Callout P|                                        |              | | E -   Bps/Par| A: 300           L: None         S: 5  |              | | F - Hardware F| B: 1200         M: Even         T: 6  |              | | G - Software F| C: 2400         N: Odd          U: 7  |              | |              | D: 4800          O: Mark         V: 8  |              | |   Change whic| E: 9600          P: Space              |              | +---| F: 19200                     Stopbits |--+ | Screen| G: 38400                        W: 1  | | Save s| H: 57600                        X: 2  | | Save s| I: 115200       Q: 8-N-1              | | Exit | J: 230400        R: 7-E-1              | | Exit f|                                       | +---|                                       |                                      | Choice, or  to exit? |                                     ++

You should get 115200 8N1, press keys I, L, V and W. When you're done, press Enter.

Now in the previous screen, press F to set Hardware Flow Control to Off. You should have this now:

+---+      | A -    Serial Device      : /dev/ttyS1                                | | B - Lockfile Location    : /var/lock                                 | | C -  Callin Program      :                                           | | D - Callout Program      :                                           | | E -   Bps/Par/Bits       : 115200 8N1                                | | F - Hardware Flow Control : No                                       | | G - Software Flow Control : No                                       | |                                                                      |       |    Change which setting? |      +---+               | Screen and keyboard      | | Save setup as dfl       | | Save setup as.. |                                                   | Exit                     | | Exit from Minicom       | +--+                                       Press Enter to leave this screen, select Save setup as dfl and finally select Exit from Minicom.

Now run minicom as root:

$ sudo minicom

You should get the following screen:

Welcome to minicom 2.2 OPTIONS: Compiled on Sep 8 2008, 17:03:34. Port /dev/ttyS0 Press CTRL-A Z for help on special keys Texas Instruments X-Loader 1.41 Starting OS Bootloader...                                                    U-Boot 1.3.3 (Jul 10 2008 - 16:33:09) OMAP3530-GP rev 2, CPU-OPP2 L3-165MHz OMAP3 Beagle Board + LPDDR/NAND DRAM: 128 MB                            NAND:  256 MiB In:   serial Out:  serial Err:  serial Audio Tone on Speakers ... complete OMAP3 beagleboard.org #

If you don't, check the serial port. You'll have to go back to the config (minicom -s) and get to this screen:

+---+      | A -    Serial Device      : /dev/ttyS1                                | | B - Lockfile Location    : /var/lock                                 | | C -  Callin Program      :                                           | | D - Callout Program      :                                           | | E -   Bps/Par/Bits       : 115200 8N1                                | | F - Hardware Flow Control : No                                       | | G - Software Flow Control : No                                       | |                                                                      |       |    Change which setting? |      +---+               | Screen and keyboard      | | Save setup as dfl       | | Save setup as.. |                                                   | Exit                     | | Exit from Minicom       | +--+

Now press A and change /dev/ttyS1 for /dev/ttyS0, or 2 or 3, depending on which port you have it connected. In my case it was 0. If you use a usb to serial adapter it is probably /dev/ttyUSB0 or perhaps /dev/ttyUSB1.

If you still don't get the beagleboard shell, try using other serial terminal program like GtkTerm.

Now we got the beagleboard shell! Congratulations!

First command we wanna try is "help":

OMAP3 beagleboard.org # help

If you get some output, you're happy!

If at some point you cannot enter text any more, verify that you have turned off flow control (F and G should be set to No). Also if after a reboot you do not see anything exit (ctrl-A q) and restart minicom

=SD card setup=

(For a BeagleBoard xM specific step-by-step guide to setting up your SD card and installing Angstrom, click here.)

Now we want to use an SD card to install some GNU/Linux distro in it and get more space for our stuff. You can use either an SD or SDHC card. In the latter case of course take care that your PC card reader also supports SDHC. You should know that you are not dealing with an x86 processor, this is a completely different architecture called ARM, so don't even try to install a normal distro here.

Since the steps for getting this to work are already written down in the wikis, I'll copy the information, pointing out some extra things you should take care of.

First of all, we want to set up the SD card to be used as a boot disk, let's plug it into our PC card reader and see what the wiki page says:

MMC boot format

In order to create a bootable SD/MMC card under Linux compatible with OMAP3 boot ROM, you have to set a special geometry in the partition table. There are two ways of doing this, with a script or, through the fdisk "Expert mode".

Formatting the SD card via the mkcard.txt script

 * 1) Download mkcard.txt from here.
 * 2)  x, Where x is the letter of the card.  You can find this by inserting your card and then running  .  You should see the messages about the device being mounted in the log.  Mine mounts as sdc.
 * 1)  x, Where x is the letter of the card.  You can find this by inserting your card and then running  .  You should see the messages about the device being mounted in the log.  Mine mounts as sdc.

Once run, your card should be formatted.

Formatting the SD card via fdisk "Expert mode"
First, lets clear the partition table:

================================================================================ $ sudo fdisk /dev/sdb Command (m for help): o Building a new DOS disklabel. Changes will remain in memory only, until you decide to write them. After that, of course, the previous content won't be recoverable. Warning: invalid flag 0x0000 of partition table 4 will be corrected by w(rite) ================================================================================

Print card info:

================================================================================ Command (m for help): p Disk /dev/sdb: 128 MB, 128450560 bytes .... ================================================================================

Note card size in bytes. Needed later below.

Then go into "Expert mode":

================================================================================ Command (m for help): x ================================================================================

Now we want to set the geometry to 255 heads, 63 sectors and calculate the number of cylinders required for the particular SD/MMC card:

================================================================================ Expert command (m for help): h Number of heads (1-256, default 4): 255 Expert command (m for help): s Number of sectors (1-63, default 62): 63 Warning: setting sector offset for DOS compatiblity ================================================================================

NOTE: Be especially careful in the next step. First calculate the number of cylinders as follows:


 * B = Card size in bytes (you got it before, in the second step when you printed the info out)
 * C = Number of cylinders

C=B/255/63/512

When you get the number, you round it DOWN. Thus, if you got 108.8 you'll be using 108 cylinders.

================================================================================ Expert command (m for help): c Number of cylinders (1-1048576, default 1011): 15 ================================================================================

In this case 128MB card is used (reported as 128450560 bytes by fdisk above), thus 128450560 / 255 / 63 / 512 = 15.6 rounded down to 15 cylinders. Numbers there are 255 heads, 63 sectors, 512 bytes per sector.

So far so good, now we wanna create two partitions. One for the boot image, one for our distro. Let's check what another wiki page has to say about it:

Linux boot disk format

Create the FAT32 partition for booting and transferring files from Windows. Mark it as bootable.

================================================================================ Expert command (m for help): r Command (m for help): n Command action e  extended p  primary partition (1-4) p Partition number (1-4): 1 First cylinder (1-245, default 1): (press Enter) Using default value 1 Last cylinder or +size or +sizeM or +sizeK (1-245, default 245): +50 Command (m for help): t Selected partition 1 Hex code (type L to list codes): c Changed system type of partition 1 to c (W95 FAT32 (LBA)) Command (m for help): a Partition number (1-4): 1 ================================================================================

Create the Linux partition for the root file system.

================================================================================ Command (m for help): n Command action e  extended p  primary partition (1-4) p Partition number (1-4): 2 First cylinder (52-245, default 52): (press Enter) Using default value 52 Last cylinder or +size or +sizeM or +sizeK (52-245, default 245):(press Enter) Using default value 245 ================================================================================

Print and save the new partition records.

================================================================================ Command (m for help): p Disk /dev/sdc: 2021 MB, 2021654528 bytes 255 heads, 63 sectors/track, 245 cylinders Units = cylinders of 16065 * 512 = 8225280 bytes Device Boot     Start         End      Blocks   Id  System /dev/sdc1  *           1          51      409626    c  W95 FAT32 (LBA) /dev/sdc2             52         245     1558305   83  Linux Command (m for help): w The partition table has been altered! Calling ioctl to re-read partition table. WARNING: Re-reading the partition table failed with error 16: Device or resource busy. The kernel still uses the old table. The new table will be used at the next reboot. WARNING: If you have created or modified any DOS 6.x partitions, please see the fdisk manual page for additional information. Syncing disks. ================================================================================

Now we got both partitions, next step is formatting them.

NOTE: If the partitions (/dev/sdc1 and /dev/sdc2) does not exist, you should unplug the card and plug it back in. Linux will now be able to detect the new partitions.

================================================================================ $ sudo mkfs.msdos -F 32 /dev/sdc1 -n LABEL mkfs.msdos 2.11 (12 Mar 2005) $ sudo mkfs.ext3 /dev/sdc2 mke2fs 1.40-WIP (14-Nov-2006) Filesystem label= OS type: Linux Block size=4096 (log=2) Fragment size=4096 (log=2) 195072 inodes, 389576 blocks 19478 blocks (5.00%) reserved for the super user First data block=0 Maximum filesystem blocks=402653184 12 block groups 32768 blocks per group, 32768 fragments per group 16256 inodes per group Superblock backups stored on blocks: 32768, 98304, 163840, 229376, 294912 Writing inode tables: done Creating journal (8192 blocks): done Writing superblocks and filesystem accounting information: ================================================================================

All done!

NOTE: For convenience, you can add the -L option to the mkfs.ext3 command to assign a volume label to the new ext3 filesystem. If you do that, the new (automatic) mount point under /media when you insert that SD card into some Linux hosts will be based on that label. If there's no label, the new mount point will most likely be a long hex string, so assigning a label makes manual mounting on the host more convenient.

NOTE: XorA created a script to automate SD card formatting

=Writing the Ångström image into the SDcard and finally booting GNU/Linux=

Now we have these two partitions. In the first one we're going to write the Linux boot image and other stuff, while in the other one we're going to write our Ångström root filesystem.

First of all, let's download the files we're going to need from:

Ångström demo images

Get the latest Ångström demo image (Angstrom-Beagleboard-demo-image......), MLO, u-boot.bin and uImage. Additionally, download the modules (modules-2.6.X-rX-beagleboard.tgz) file that correspond with the kernel version you download. Without these module files some peripherals, such as webcams, will not function.

For certain images (such as the images generated by the Narcissus build system), no separate uImage exists. You can find the uImage in the /boot directory of the root filesystem. Just copy the uImage-x.xx... to the vfat partition and rename it.

Now you must copy MLO, u-boot.bin and uImage into the first partition (the FAT32 one) of your SD card. Do it in this strict order, since MLO must be in the first sectors of the card.

Mount both partitions somewhere -- I'll assume they're mounted in /mnt/sda1 and /mnt/sda2, respectively.

$ cp MLO /mnt/sda1 $ cp u-boot.bin /mnt/sda1 $ cp uImage /mnt/sda1

Now let's copy the root filesystem into the other partition (the ext3 one):

$ sudo cp Angstrom-Beagleboard-demo-image..... /mnt/sda2

and untar it. (IMPORTANT: You must untar directly onto the SD card. Do not untar somewhere else and then copy to the SD):

$ cd /mnt/sda2 $ sudo tar -jxvf Angstrom-Beagleboard-demo-image....

(If you get "permission denied" errors while copying or untarring it to the SD Card then issue that command using 'sudo' e.g "sudo cp Angstrom-Beagleboard-demo-image..... /mnt/sda2")

Once that's done, delete the tarball:

$ sudo rm Angstrom-Beagleboard-demo-image....

If you downloaded the modules-2.6.X-rX-beagleboard.tgz modules file you'll need to copy and untar it:

$ sudo cp modules-2.6.X-rX-beagleboard.tgz /mnt/sda2 $ sudo tar -xvf modules-2.6.X-rX-beagleboard.tgz

Again delete the module tarball:

$ sudo rm modules-2.6.X-rX-beagleboard.tgz

and unmount both partitions.

$ sudo umount /mnt/sda1 $ sudo umount /mnt/sda2

Setting up the boot args
If you are running a Beagle xM you can skip this section

If you are running a current version of U-boot you can skip to the next section. The newer versions have bootargs and bootcmd set to the correct values. Note the newest version requires kernel parameters to be passed to the g_ether module:


 * 1) setenv bootargs 'console=ttyO2,115200n8 root=/dev/mmcblk0p2 rw rootwait g_ether.host_addr=16:0F:15:5A:E1:21  g_ether.dev_addr=16:0F:15:5A:E1:20'

Ok, we're almost done. Now we need to tell our BeagleBoard that we want it to boot from the SD card. Let's go back to our almost-forgotten minicom shell:

OMAP3 beagleboard.org # The commands to set it up for booting from SD are:


 * 1) setenv bootargs 'console=ttyO2,115200n8 root=/dev/mmcblk0p2 rw rootwait'
 * 2) setenv bootcmd 'mmc init;fatload mmc 0 80300000 uImage;bootm 80300000'

You might also want to configure your screen resolution at this time.

Now we want to save these variables into the NAND Flash so we don't have to type them in every time we reboot:


 * 1) saveenv

And, YES, we're done.

Wire up your Beagle and power it up
Connect the BeagleBoard to a screen using a DVI cable and press the RESET button while holding down the USER button. Now you've got to be PATIENT, first boot takes a looooong time.

gcohler has also provided a write-up on getting Angstrom running.

=Connect with your beagleboard using VNC and ethernet over USB= The Angstrom demo image for the beagleboard comes with USB networking support. The only thing you have to do is to enable it by issuing the following commands on your beagleboard via the terminal. Note: you can use your own MAC and IP addresses, but maintain consistency.

Optional if g_ether module not compiled into older kernels :


 * 1) cd /lib/modules/2.6.29-omap1/kernel/drivers/usb/gadget
 * 2) modprobe g_ether host_addr=16:0F:15:5A:E1:21 dev_addr=16:0F:15:5A:E1:20

Configure networking

nameserver 192.168.1.1 Ctrl + D #
 * 1) ifconfig usb0 192.168.0.202 netmask 255.255.255.0
 * 2) route add default gw 192.168.0.200
 * 3) cat >> /etc/resolv.conf

The beagleboard will now show up as Auto usb0 on Ubuntu. You can add it automatically by making some udev rules.

As a precaution, first enable packet forwarding in your computer:

Uncomment the line  net.ipv4.ip_forward=1, to enable forwarding of packets. To check that the change has been made and routing is enabled
 * 1) sudo vi /etc/sysctl.conf
 * 1) sudo sysctl -p
 * 2) sudo cat /proc/sys/net/ipv4/ip_forward

Now create /etc/udev/ruled.d/80-beagleboard.rules

KERNEL=="usb[0-9]*", DRIVERS=="cdc_ether", ACTION=="add", RUN+="/usr/local/sbin/beagleboard-usb-add.sh %k"
 * 1) This file causes programs to be run on device insertion.
 * 2) See udev(7) for syntax.
 * 3) http://www.reactivated.net/writing_udev_rules.html#example-netif
 * 1) For newer kernels, e.g. in Ubuntu 11.04, use DRIVERS=="cdc_eem" instead of DRIVERS=="cdc_ether"

Next create /usr/local/sbin/beagleboard-usb-add.sh

( busNum=$( printf %.2d $( expr match "$1" "usb\([0-9]*\)") ) ip link set "$1" address 16:0F:15:5A:E1:21:$busNum &> /dev/null iptables -A POSTROUTING -t nat -j MASQUERADE -s 192.168.0.0/24 echo 1 > /proc/sys/net/ipv4/ip_forward iptables -P FORWARD ACCEPT ) & exit 0
 * 1) !/bin/sh

Finally run "chmod +x /usr/local/sbin/beagleboard-usb-add.sh" to make it executable and now you can use network-manager with mac specific settings to automatically connect to the beagleboard.


 * Plug your beagle into your computer's usb port.
 * Note the mac address from "ifconfig usb0"
 * Right-click the network manager icon in the panel.
 * Click "Edit Connections..."
 * Delete the "Auto usb0" entry.
 * Add a new connection named 'beagleboard'
 * Enter the mac address from above.
 * Click the "IPv4 Settings" tab.
 * Change "Method" to "Manual"
 * Add an address of 192.168.0.200, 255.255.255.0 (address and netmask respectively).
 * Click "Ok"
 * Enter your system password (if prompted) to allow changing of this system setting.

You can now connect to your beagleboard using any VNC viewer and you should be able to access the internet from your beagleboard.

Note: if your beagleboard can't resolve external URLs (#ping elinux.org) you might need to replace the resolv.conf settings with those from your host. From Ubuntu: # scp /etc/resolv.conf root@192.168.0.202:/etc/resolv.conf root@192.168.0.202's password: [ENTER] Note: if you fail to ping host or beagle and is on revision C4 you might want to try adding 'g_ether.use_eem=0' as a boot argument (See BeagleBoardBeginners)

=Development with Ångström=

If you want to get started building Ångström yourself, take a look at OpenEmbedded on Beagle.

=Important USB Cable Information=

The BeagleBoard has a 5-pin USB OTG Mini-AB Female connector on the board. This allows the Beagle to operate as either a peripheral attached to a host computer (e.g. a PC) or as a host computer itself with peripherals attached.

To operate the Beagle as a peripheral, just use any USB A-male to Mini-B-male cable and you're good to go. Plus, you will not need a power brick for the Beagle as the Host PC will be able to power the board through the A to Mini-B cable.

To operate the Beagle as an OTG Host, you need a special cable -- plus you will need a power brick to power the Beagle, because it is now the host and must supply power to the peripherals. The key is that the cable needs to have a USB Mini-A-male (NOT a Mini-B) to connect to the Beagle. If you have cables with USB male mini connectors, the overwhelming chance is that they are Mini-B. While both Mini-A and Mini-B fit in the Mini-AB connector on the BeagleBoard, there is an internal wiring difference in the Mini-A and Mini-B connectors that allows the BeagleBoard to sense the type; Mini-A have pin 4 connected to GND, whereas Mini-B leave the pin unconnected.

One source for a USB Standard A-female to Mini-A-male Adapter is Serial I/O. This can be used for connecting e.g. a USB hub to the Beagle.

If you're using a USB hub, be sure it's a self-powered one. That means it should have a power input which you can connect to a power socket. The BeagleBoard by itself cannot power multiple USB devices and if you hook up too many it goes into a continuous disconnect/reconnect cycle.

=Further reading=

Main BeagleBoard resources are:


 * TI maintained BeagleBoard home and Google wiki for BeagleBoard
 * Community maintained eLinux wiki (see wiki article overview for a list of existing articles)

Other BeagleBoard usage instructions:
 * Free Electrons embedded Linux training labs on the BeagleBoard

=Thanks to=


 * _vlad
 * jkridner
 * ds2

And the rest of the people in the #beagle IRC channel, if you cannot go through some of the steps, don't hesitate to ask there, there's always somebody willing to help you!

Written by Nabax