Examples and Tutorials

This is a collection of examples and tutorial code to learn how to use features on the BeagleBone Black.  The code has been tested on Angstrom 3.8 and Ubuntu 12.04 LTS.  It is released as is under the GPL license. I have also put together how to login to your BBB and some useful commands to transfer code to and from your BeagleBone.  We will start with this because you will need to do this for all of the examples.  I will be primarily working in Linux (Ubuntu 12.04 to be specific), but I will try to also post Windows equivalents as often as possible. Sorry MAC users no dice.

Quick Notation Notes

  1. Code: Commands that look like this ssh root@192.168.7.2 are Linux command line commands and are meant to be typed exactly as shown

Methods to Login to your BBB
Keep in mind these are only a few methods for those who don’t know how to start. There are an almost endless number of other ways to do this. Also if you are using Angstrom or another OS that supports a GUI then you can connect a monitor, mouse, and keyboard and skip this.

  • USB – This uses the USB mini connection on the board to connect.
    • Linux
      • Plug the USB cable into your computer.
      • Wait for the board to initialize.  The leds should have gone all solid and be blinking.
      • Open terminal window.
      • type ssh root@192.168.7.2
      • It will prompt for a password but there isn’t one by default so just press enter
      • You should now be logged into the board home directory.
    • Windows 7
      • Plug the USB cable into your computer.
      • Wait for the board to initialize.  If this is the first time wait for the driver to load.  The leds should have gone all solid and be blinking.  Windows will also prompt a successful driver message the first time.
      • Use your favorite ssh client.  If you don’t have one I suggest Putty or Tera Term.
      • Now configure it to ssh to 192.168.7.2 on port 22
      • It will then prompt for password but there isn’t one by default so just press enter.
      • You should  now be logged into the home directory.
  • Ethernet – This method assumes you are connected to the internet and using +5V barrel connector
    • Linux
      • Install Avahi with the command sudo apt-get install avahi-daemon
      • Connect the board and wait a few seconds for it to boot.
      • Run Avahi Zeroconf Browser.
      • Find the SSH Connection for Beaglebone and click.
      • This will give you the IP address of the board so simply SSH into the board like you normally would.
    • Windows
    • Router
      • If you have a router connecting your devices simply login to the router and get the IP.
      • SSH to the board and you are off and running again.

File Transfer Commands
As with the login methods this is one of many ways. Feel free to comment with other ways you have used for the good of everyone.

  • SCP from the BBB to your Computer
    • Send a single file
      • Open terminal window
      • Generically the command looks like this                                                                         scp user@IPAddress:/directory/filename.file /directory/
      • The first part after scp is the login information and file location on the BBB, the second part is where on the computer you want to copy it too
      • Example: scp root@192.168.7.2:/home/root/test.txt /home/
    • Send a directory
      • You can also recursively send an entire directory to sync folders
      • scp -rp user@IPAddress:/directory/ /home/directory
      • Same concept as before but now we specify the directory we want to recursively copy
      • Example: scp root@192.168.7.2:/home/root/Code/ /home/gavin/Code
  • SCP from your Computer to Beaglebone
    • Same concept but in reverse
    • send a file: scp /home/filename.file user@IPAddress:/directory
    • send a directory: scp -rp /directory/ user@IPAddress:/directory
    • Example:                                                                                                                               scp /home/gavin/test.txt root@192.168.7.2:/home/root/Desktop/
    • Example:                                                                                                                               scp -rp /home/gavin/Code/ root@192.168.7.2:/home/root/Code/

Example 0 – Blinking A User LED
This example is your “Hello World” for the BBB. This will show how to use file operations to change the state of one of the onboard user leds. It also uses the time.h header to develop a function that pauses for a specified number of seconds. A function to pause less than a second will be shown later.

Instructions
1a. Download Example 0 code (you have your choice of .tar or .zip) here and SCP the code or another method to get it on your board.
1b. Use svn: svn checkout https://repos.anl-external.org/repos/redac/BeagleBoneBlack/Examples/
2. Open a terminal window
3. Extract the code and navigate to the folder location: tar -xvf filename.tar filename
4. type make
5. type ./blinkusr to run the program

Example 1 – Blinking A GPIO Pin
This expands on the previous example by now blinking and led that is connected to one of the GPIO pins. For this example, wiring an led with a 1K resistor to GPIO1_13 which is P8_11 on the headers. Remember if you want to use a larger resistor to keep I/O drive current under 4 or 6 mA depending on the pin and 8 mA sink current a transistor can be added to switch the additional current.

Instructions
1a. Download Example 1 code (you have your choice of .tar or .zip) here and SCP the code or another method to get it on your board.
1b. Use svn: svn checkout https://repos.anl-external.org/repos/redac/BeagleBoneBlack/Examples/
2. Open a terminal window
3. Extract the code and navigate to the folder location: tar -xvf filename.tar filename
4. type make
5. type ./blinkled to run the program

Example 2 – Reading Button Input
The next logically step after learning to output a signal is to learn how to read an input signal. This example will show you how to read the state of a button. The internal pullup/pulldown resistors are not used here so you will need to wire in your button into GPIO1_15 or P8_15 with that in mind.

Instructions
1a. Download Example 2 code (you have your choice of .tar or .zip) here and SCP the code or another method to get it on your board.
1b. Use svn: svn checkout https://repos.anl-external.org/repos/redac/BeagleBoneBlack/Examples/
2. Open a terminal window
3. Extract the code and navigate to the folder location: tar -xvf filename.tar filename
4. type make
5. type ./digin to run the program

Example 3 – Connecting Input to Output
There isn’t anything new concepts in this example. This is meant to demonstrate how to connect the two previous concepts. You will see how to connect a button to an led and program will read in the button state and output it to the led. This will start to show you how to close the loop between inputs and outputs. This also uses the same wiring configuration as the previous examples with led on P8_11 and a button on P8_15.

Instructions
1a. Download Example 3 code (you have your choice of .tar or .zip) here and SCP the code or another method to get it on your board.
1b. Use svn: svn checkout https://repos.anl-external.org/repos/redac/BeagleBoneBlack/Examples/
2. Open a terminal window
3. Extract the code and navigate to the folder location: tar -xvf filename.tar filename
4. type make
5. type ./in2out to run the program

Example 4 – PWM
Pulse Width Modulation (PWM) is a very common and very useful feature of many microprocessors. A quick google search will provide you with a mind blowing amount of information regarding its uses and concepts for those that don’t already know. For this example I will assume you are already familiar with why you want to use PWM. The pwm modules are mux with other features so they are available on specific pins. We are going to use the one on P8_13. It is also important to note that this program looks for a directory call ~/bone_capemgr.*/. The star value will change so if the code doesn’t work make sure you look up your number and change the corresponding one in the program to match. In future examples, I will show you how to avoid this but lets keep in simple for now.

Instructions
1a. Download Example 4 code (you have your choice of .tar or .zip) here and SCP the code or another method to get it on your board.
1b. Use svn: svn checkout https://repos.anl-external.org/repos/redac/BeagleBoneBlack/Examples/
2. Open a terminal window
3. Extract the code and navigate to the folder location: tar -xvf filename.tar filename
4. type make
5. type ./pwm to run the program

Example 5 – Reading ADC
Up to this point you now have some sound fundamentals in the digital world, but the world is analog so it will be important to be able to read an Analog to Digital Converter (ADC). NOTE: you can only apply 1.8V to the onboard ADC or you WILL damage the chip and void the warranty so you will be out a board…DON’T DO THAT! Now you are sufficient scared lets hook up a couple of potentiometers to analog channels 0 and 1 located on pins P9_39 and P9_40 respectively. Connect one side to the VADC on P9_32, one side to GND, and the wiper to the analog channels. This will make sure you don’t exceed 1.8V.

Instructions
1a. Download Example 5 code (you have your choice of .tar or .zip) here and SCP the code or another method to get it on your board.
1b. Use svn: svn checkout https://repos.anl-external.org/repos/redac/BeagleBoneBlack/Examples/
2. Open a terminal window
3. Extract the code and navigate to the folder location: tar -xvf filename.tar filename
4. type make
5. type ./analogin to run the program

Example 6 – UART
Now it is time to dive into the serial protocols so you can interface sensors and all sorts of other goodies. UART is widely used in serial communication still and this program will send some basic bytes through the UART 4 port. The easiest way to see this working is to hook up an oscilloscope to the pin and watch the output. If you don’t have that connect a usb to serial converter to the pin and open up a terminal window. The character should stream into the window.

Instructions
**Follow the same procedure as the previous examples.
CODE: TAR ZIP

Example 7 – SPI
Next up is the Serial Peripheral Interface. This is found in A/D converters and a huge variety of other sensors. As with the previous example an oscilloscope or logic analyzer is the easiest way to see this working.

Instructions
**Follow the same procedure as the previous examples.
CODE: TAR ZIP

Example 8 – I2C
Inter Integrated Circuit is the another very popular serial protocol for connecting a large number of devices by only using two I/O pins. Again the logic analyzer or scope is the best way to see this one work.

Instructions
**Follow the same procedure.
CODE: TAR ZIP

Example 9 – LCD 4-bit Interface
This program demonstrates how to interface to a 2×16 lcd in 4-bit mode. This also uses the libBBB library.

Same Instructions
CODE: TAR ZIP

Example 10 – PRU Programs
This program builds on the examples provided by TI for the PRU. It demonstrates simple I/O control using the PRU by blinking a led.

Same Instructions
CODE: TAR ZIP

Example 11 – “Interrupts”
I got tired of looking for ways to do basic interrupts and the internet suggesting polling. This is not using the low latency interrupts at the kernel level which is why it is in quotation marks. For basic buttons and interrupts that do not require very low latency, this method uses signals and child processes to make an interrupt generator and handler. Give a try if you really don’t want your application to poll.

Same Instructions
CODE: TAR ZIP