beagleboard url beaglebone in hand

Getting started with your new BeagleBone

This is the quick-start guide. Before looking for any additional help, please read:

This document is supplied with the revision A3 BeagleBone. It is highly recommended to view the on-line version of this document with updates available at beagleboard.org/static/beaglebone/a3/README.htm.

Table of contents

Before you begin, update to the newest demo image

Some version and debug information is stored in a dynamically produced file on this partition called info.txt, which if you are familiar with buidling Angstrom, will let you know when this image was built and with what source.

The latest pre-built version of this Angstrom Cloud9 IDE demo image is available from:

Please visit there now to download the latest version. The BeagleBoard101 presentation will provide you with some guidance on writing the demo image to a microSD card if you aren't already a Linux user. You can also find help on the IRC live chat.

If you are planning on using a different microSD card image, please look for support from the supplier of that image. Some images available at the time of this release include (not supported by BeagleBoard.org):

Some software already running on your BeagleBone

The Angstrom Distribution image provided with your BeagleBone includes a large amount of software already running as you are reading this document. It is also possible to install many more pre-built packages from the on-line repository feed using the 'opkg' tool.

Some of the running programs include web servers and other Internet servers that give you access to the board, even if you don't have a display, mouse and keyboard connected to it.

Here is a list of some of the running servers:

  • ssh (port 22) - for access to a shell
  • bone101 (port 80) - small server written in node.js serving up an intro presentation
  • GateOne (port 443) - access to a shell through Firefox or Chrome
  • Cloud9 IDE (port 3000) - text editor and debugger for node.js applications through Firefox, Chrome or Safari

Note: Future releases will include the TI Matrix application launcher.

Decision time: Ethernet or single-cable USB based development?

The most recommended path from here for someone experienced in managing their local network and performing remote logins via ssh is to go get a recommended 5V power adapter and connect your BeagleBone via an Ethernet to your LAN. Your BeagleBone will automatically start web services to which you can connect, so you can avoid installing USB drivers until you want to perform some lower-level debug. Use Bonjour, the IP address in info.txt or your router's DHCP log to discover the IP address of your board and browse to it.

Further, right now, the clock speed of the BeagleBone is determined by if the power source is USB or the 5V adapter at initial boot. It will be 500MHz if the power source is USB and 720MHz if the power source is an adapter.

If you aren't interested in using the USB interfaces and your network connection is all setup, you can jump ahead to navigating to your BeagleBone's web interface. Otherwise, please continue...

Getting your host machine USB drivers setup

This BeagleBone demo image exposes five (5) different USB device types to your host machine:

  • SMSC USB hub - a dedicated 2-port hub on your BeagleBone
  • FTDI USB-to-JTAG interface - first port on a dedicated USB interface chip
  • FTDI USB-to-serial interface - second port on a dedicated USB interface chip
  • Linux mass storage class interface - the Linux distribution running on your BeagleBone supports emulating a mass storage device (flash drive) and will share the first partition on the microSD card
  • Linux USB-to-Ethernet interface - the Linux distribution running on your BeagleBone supports emulating a USB-to-Ethernet device such that you can access your BeagleBone with networking protocols, such as web browsing

Advanced note: On this revision A3 board, the VID/PID were chosen to match the TI XDS100v2 (0x0403/0xA6D0). On future revisions when we've given the authors of CCS the chance to update their software, the generic FTDI VID/PID (0x0403/0x6010) will be used to simplify installation of drivers for systems already having those drivers.

Neither the SMSC USB hub nor Linux mass storage class interface will require any driver installation on your host machine as drivers for those are completely standard in all major operating systems.

OpenOCD is an application that provides JTAG-based debugging on all three operating systems, but support for the BeagleBone USB-to-JTAG interface is still a work in progress. Please visit the OpenOCD Homepage to learn more about the project, join the mailing list and help us to add support for the BeagleBone.

Otherwise, support varies across Windows, Mac OSX or Linux.

  • Windows:
  • Mac OS X:
    • Save and open FTDI_Ser.dmg, double-click "FTDI_Serial.pkg" and to install the USB-to-serial drivers. For additional information, visit FTDI's Virtual COM Port Drivers page.
    • For the USB-to-Ethernet interface, the drivers are likely built into your system, so no additional work is required. For older OS X systems, you can look at the driver the folks over at Bug Labs have produced for their excellent modular development platform that you might use: Start_Guide_Mac_OS_X_10.5
  • Linux:
    • For a quick start, simply load the USB-to-serial driver with the following command: 
      sudo modprobe ftdi_sio vendor=0x0403 product=0xa6d0
      To make the BeagleBone show up upon every reboot, add a udev rule. Here is an example /etc/udev/rules.d/73-beaglebone.rules: 
      ACTION=="add", SUBSYSTEM=="usb", ENV{DEVTYPE}=="usb_interface", \
        ATTRS{idVendor}=="0403", ATTRS{idProduct}=="a6d0", \
        DRIVER=="", RUN+="/sbin/modprobe -b ftdi_sio"

ACTION=="add", SUBSYSTEM=="drivers", \
        ENV{DEVPATH}=="/bus/usb-serial/drivers/ftdi_sio", \
        ATTR{new_id}="0403 a6d0"

ACTION=="add", KERNEL=="ttyUSB*", \
	ATTRS{interface}=="BeagleBone", \
        ATTRS{bInterfaceNumber}=="00", \
	SYMLINK+="beaglebone-jtag"

ACTION=="add", KERNEL=="ttyUSB*", \
	ATTRS{interface}=="BeagleBone", \
        ATTRS{bInterfaceNumber}=="01", \
	SYMLINK+="beaglebone-serial"
      Run the following to load the new udev rules: 
      sudo udevadm control --reload-rules
    • Code Composer Studio v5 (CCSv5) is a TI provided Eclipse-based integrated development environment that enables you to debug and develop C/C++ applications for your BeagleBone. CCSv5 provides debug support in Linux over the USB-to-JTAG interface. See the CCSv5 wiki page for download and installation information.

Connect to your BeagleBone's serial console

Connecing to the serial port will give you access to the bootloader shell, kernel boot logs, a login prompt and the Linux shell. The username is 'root' and the password is not set. If the board is already booted, a quick press of <Enter> should bring up a new login prompt.

  • Windows
    • Launch HyperTerminal (Start -> All Programs -> Accessories -> Communications -> HyperTerminal)
    • Give the name 'BeagleBone' and press <Enter>
    • Select the last (newest) COM port and press <Enter>
    • Choose '115200' Bits per second, '8' Data bits, 'None' Parity, '1' Stop Bits, 'None' Flow control and press <Enter>
  • Mac OS X

    To open the serial terminal from within Terminal.app, use the following command: 

    screen /dev/tty.usb*B 115200

  • Linux

    To open the serial terminal from the shell prompt, use the following command: 

    screen /dev/beaglebone-serial 115200
    Type CTRL-A \ to exit screen.

Launch USB-to-Ethernet interface

At boot-up, the processor on your BeagleBone is running a USB storage "gadget" driver that served you up this file. For this software build, you need to swap the storage gadget for a USB-to-Ethernet gadget when you are ready to establish an IP connection over your USB cable.

  • From your PC, eject the BEAGLE_BONE USB drive. The USB Ethernet gadget will automatically start.

    Note #1: It has been observed in Windows that it may actually take a couple of minutes for the driver to load on occasion.

    Note #2: It has been observed in Windows that you may be prompted to locate the 'linux.inf' file. If you installed the driver properly, you should be able to find it under c:\windows\system32\drvstore\linux_...

  • Configure the adapter that appears for DHCP.
  • The adapter should be given the IP address 192.168.7.1.

At this point, you should have an IP connection either over Ethernet or over your USB cable. The links below assume you are using your USB cable, which should be providing fixed IP addresses.

The Linux distribution running on your BeagleBone is configured to start a handful of web servers upon boot. This is the easiest way to get explore and program your BeagleBone if you are not already experienced with Linux.

Note: Please note that many of the tools do not support Internet Explorer. It is recommended you use recent versions of Chrome or Firefox.

Note #2: Some VPNs may interfere with your local network connection to your BeagleBone. Please consult your VPN guide.

  • BeagleBone 101 presentation - http://192.168.7.2

    This application is largely self explanatory. The source can be edited using the Cloud9 IDE. The application is 'bone101.js'.

  • GateOne - https://192.168.7.2

    For documentation, please visit the on-line GateOne Documentation.

    Note: This installation might be a bit slow, but we are actively working on improving this with the author.

  • Cloud9 IDE - http://192.168.7.2:3000

    This development environment supports direct execution of JavaScript via Node.JS. Visit nodejs.org for information on programming in Node.JS.

    The IDE is pre-populated with the source and demos of the BoneScript project.

    Notes: BoneScript is in an early alpha phase and is expected to be at a point suitable for building applications by Summer 2012. There is currently no autorun features for the applications loaded into Cloud9 IDE, but that is one feature planned to be enabled.

Examine the rest of the hardware design

The latest hardware docs are on-line, but a local copy at the time of image creation is provided here for your convenience.

Known issues

  • System
    • Move FTDI PID from 0xa6d0 to 0x6010 PID (to happen on Rev A4 boards)
    • Mount time for USB-to-Ethernet may take a couple of minutes under Windows
  • Kernel
    • Need completed ADC support with IIO framework
    • Need completed CAN drivers
    • Need improved PWM support
    • Need device tree support and run-time configuration with daughterboards
    • Need improved USB and USB DMA support
    • Need improved SD performance
  • SD card image
    • Add Java
    • Need simplified IP discovery
    • Need improved GateOne performance
    • Need to consider ConnMan tethering for USB-based IP
    • 'top' refresh rate can sometimes be crazy fast
    • Restore automounting of hotplugged media
    • Restore Matrix and add application entries for GateOne and Cloud9 IDE
  • Documentation
    • Need daughterboard building guide
    • Add graphics and/or videos where appropriate
    • Need full description of /sys entries
    • Basic information on apps for each major interface type, ie. I2C, SPI, etc.
    • Need to highlight daughterboard ("cape") EEPROM spec
  • Cloud9 IDE and BoneScript
    • Inclusion of node-fibers such that delays don't hog the CPU
    • Arduino-like automatic execution of installed apps
    • Dynamic web conent example with board status and streaming data
    • Optimal utilization of the PRU and performance improvements
    • Extensive improvements to the BoneScript API
    • Need examples on programming in C through the Cloud9 IDE interface
    • Include npm and several node modules