[Updated Jan 25: Correction! There is a 1.8V voltage source on the Beaglebone: Port 9 Pin 32.  Thanks to Koen Kooi for the info.  I've updated the text with this information]

This article is my second explaining the fundamentals of coding with the Beaglebone. In the first article I explained some of the mysteries of pin muxing, and gave an example of a very simple usage of a digital pin. This time, I’ll use an analog sensor and serial I/O (just O, actually), to create a time and temperature LCD display.

I have to admit that I’m far from an expert – I’m basically writing about this stuff as I figure it out.

The Beaglebone will hopefully prove to be a ground-breaking product, introducing a lot of electronics hobbyists to embedded Linux programming. Unfortunately, at this point there isn’t much in the way of embedded Linux development tools or tutorials that is geared to newcomers. This should change by the summer of 2012, as bonescript expands and more Beaglebone-based projects pop up on blogs and sites like Instructables. Until then, it will be one baby step at a time…

Analog Input

The first rule of analog input with the Beaglebone is:
NOTE: Maximum voltage is 1.8V. Do not exceed this voltage. Voltage dividers
should be used for voltages higher than 1.8V.

So sayeth the Beaglebone System Reference Manual (Emphasis theirs. )

I haven’t experimented with what happens if you go above 1.8V, but since they’ve made the warning red and underlined, I’m pretty sure it would not go well.
This limitation is a problem, since:

• There is no pin on the Beaglebone that provides a 1.8V source
  [Correction Jan 25 - as pointed out in the comments, there is a pin that provides 1.8V, Port 9 pin 32 (labelled VDD_ADC in the Beaglebone System Reference Manual).    So you can ignore the stuff about voltage dividers and level converters below if you are using an analog sensor that can operate on 1.8V, like a potentiometer.]
• Many analog sensors require a minimum voltage greater than 1.8V

So, until someone has a better idea, voltage dividers will be an important part of any Beaglebone analog circuit.

The second most important thing to know about the Beaglebone’s analog input is that the software support seems to be a work-in-progress. The approach I’m taken is based on a brief blog post by one of the maintainers of the Beaglebone Angstrom demo images. His remarks would suggest that they have a better plan that is under development. As far as I know, the approach taken here is an Angstrom kernel modification that won’t work at all on a Ubuntu image with the vanilla Ubuntu kernel.

Back to the issue of 1.8 max voltage. You have a couple of options in your design:

• Added Jan 25: Use Port 9 Pin 32 as your voltage source, if your analog sensor can work on 1.8V
• Use a couple of high precision resistors that can knock 3.3V or 5V down to exactly 1.8V
• Use a couple of garden variety resistors to knock the voltage below 1.8V, then modify your software to adjust for the difference

Being lazy, I’m going with the latter approach. Being very lazy, I’m not even bothering to hook up the resistors – as shown in the screenshot below, I’m using a tiny breakout board to do the work.

Specifically, this is a Sparkfun Logic Level Converter – BOB-08745. You’ll see this part recommended quite often in Beagleboard/Beaglebone circles, since it is an inexpensive solution that can handle a range of voltages, and supports 2-way conversion (necessary for I2C).

For the purpose of analog input I’m not using the board as intended – I’m taking advantage of a semi-documented hack. The RX pins on this board just use a voltage divider: the voltage going into the “HV” pins comes out as half the amount from the LV pins. The circuit for this, taken from the BOB-08745 schematic, is shown below.

If you don’t have a BOB-08745, you can just use a couple of 10K resistors.

Before actually using this type of circuit, measure what voltage you get from the LV end of the voltage divider if the HV end is connected directly to 3.3V. If it isn’t below 1.8V, figure out what’s wrong before you hook it up to the Beaglebone. (Red and underlined, remember?) Don’t worry if the reading isn’t exactly 50% – we will calibrate the software to handle the variance.

The 2 analog sensors I’m using are a 10K potentiometer and an analog thermistor (temperature sensor), the Microchip MCP9700A.

As you can see from the photos, the connections are:

- Potentiometer and MCP9700A:

• Input pin to 3.3V (which connects to pins 3 or 4 of Port 9 on the Beaglebone),
• Ground pin to ground (connects to pins 1 or 2 of Port 9 of the Beaglebone),
• Output pin to one of the RXI pins on the Sparkfun level converter (or to the HV pin on the voltage divider circuit)
• Added Jan 25: An alternative for the potentiometer is to connect the input pin to Port 9 Pin 32 (VDD_ADC)., and the output pin directly to the Beaglebone AIN0 pin (pin 39 on Port 9)

- Sparkfun level converter:

• HV to 3.3V
• HV GND and LV GND to Ground
• LV RXO for the potentiometer to the Beaglebone AIN0 pin (pin 39 on Port 9, or the outside pin of the 4th row from the “bottom” – the end opposite the Ethernet port)
• LV RXO for the MCP9700A to the Beaglebone AIN1 pin (pin 40 on Port 9, or the inside pin of the 4th row)

Note that the LV pin on the level converter isn’t used, since we are just interested in the voltage divider.

The definitive guide to the Beaglebone pin connections is the System Reference Manual. For this project we are just using Port 9, so you can refer to the table below:

Testing Analog Input

Remember all that stuff about pin muxing from the first article? You can forget about it for analog in.

As you can see by looking at Table 12 of the Beaglebone System Reference Manual (part of which is shown below), the mux table for all of the analog in pins (AIN1 to AIN6) is empty: the pins can only be used for analog in.

There actually are entries for these pins in the file system, /sys/kernel/debug/omap_mux, but they have the correct setting by default, and as far as I can tell the Mode setting has no effect on the pins. (The Python code I wrote sets them anyway, but that’s admittedly more out of ignorance than caution.)

So, we can proceed directly to using the pins.

Let’s start with the potentiometer on analog 0 (pin 39 of Port 9). To get the current reading from the pot, enter the following (yes, it’s ain1 for analog 0 – go figure):

root@beaglebone:~# cat /sys/devices/platform/tsc/ain1
 1807

A number should be displayed. Turn the pot all the way up and repeat. You’ll see the maximum value.

For me, it’s 3779. Or 3775. Or 3776. It drifts around a little. Go figure.

The analog input pins on the Beaglebone are 10-bit, so the maximum possible value is 4096. This represents a value of 1.8V. At 3779, it’s reading 3779/4096 * 1.8V, or 1.66V, which is about what you would expect with a 10K/10K voltage divider with 3.3V input.

Now, check the MCP7200A thermometer on analog 1 (again, the analog index is off by 1, so it’s ain2):

root@beaglebone:~# cat /sys/devices/platform/tsc/ain2
 826

You should get a relatively low value: if it’s above 1000, either you are in hell or your thermistor isn’t hooked up correctly.

The formula for converting this reading to a temperature is:

(milliVolts – 500) / 10

The 826 reading I got is 826/4096 * 1.8V, or 362 mV.

Is it cold in here, or is it just me?

It’s just me. The voltage divider knocked the reading from the MCP7200A down by about half, or the actual reading is 362 * 2, or 724 mV. The temperature reading is therefore (724 – 500) / 10, or 22.4. (No, that isn’t cold, it’s just metric).

Actually, neither the MCP9700A nor this approach is very accurate. The MCP7200A’s datasheet says it’ typical accuracy is to within 1 degree C . There isn’t anything we can do to improve that, but we can make our calculation more accurate by allowing for slight variances of the resistors in our voltage divider.

To see what effect the voltage divider is having, temporarily hook the input to 3.3V instead of the MCP9700A’s output pin. Then check the value of /sys/devices/platform/tsc/ain2 again.

And again. And again.

I get 3765. And 3762. And 3759.

Given that each 10mV is a degree, that jumping about is a real problem. We’ll plug the average (call it 3762) into the code, then average a bunch of readings to get the temperature, approximately.

Serial I/O

The Beaglebone has 6 serial UARTs. One of those, UART0, is connected to the USB port, but that leaves us with 5 to play with. This is quite a step up from the Arduino’s single UART, or the Netduino’s 2 UARTs.

All of these are 3.3V UARTs. This is a problem if you’re communicating with a 5V device, but only when receiving data. Some 3.3 microcontrollers, like the Netduino’s, have “5V tolerant” pins, so they can communicate directly with 5V serial devices. But, for the Beaglebone:

NOTE: Do not connect 5V logic level signals to these pins or the board will be
damaged.

So sayeth the Beaglebone System Reference Manual.

I assume this means that connecting an UART RX pin directly to the TX pin of a 5V serial device is a bad idea. I did it for awhile, and my Beaglebone lived to tell the tale, but maybe I got lucky.

Were we receiving data from the Serial LCD, then a level converter would be required, like the Sparkfun BOB-08745 described earlier. (Actually a second level converter would be needed, since we would be going between 3.3Vand 5, not 3.3 and 1.8ish.)

However, it will be serial TX only for this project, and all 5V serial devices that I’ve come across handle 3.3V on the RX pin without problems.

In the demo Angstrom image, the pins are not enabled for UART by default. Yup, time for the black art of pin muxing again.

Working with UART1’s mux mode is relatively straightforward. UART1 is the Mode 0 usage for the pin, and as you may recall from my first article, the pin name used in the file system are taken from the Mode 0 usage. To check the current settings:

root@beaglebone:~# cat /sys/kernel/debug/omap_mux/uart1_rxd
 name: uart1_rxd.(null) (0x44e10980/0x980 = 0x0037), b NA, t NA
 mode: OMAP_PIN_OUTPUT | OMAP_MUX_MODE7
 signals: uart1_rxd | mmc1_sdwp | d_can1_tx | NA | NA | NA | NA | NA

 root@beaglebone:~# cat /sys/kernel/debug/omap_mux/uart1_txd
 name: uart1_txd.(null) (0x44e10984/0x984 = 0x0037), b NA, t NA
 mode: OMAP_PIN_OUTPUT | OMAP_MUX_MODE7
 signals: uart1_txd | mmc2_sdwp | d_can1_rx | NA | NA | NA | NA | NA

As you can see, both are set to 0×37 by default in the Angstrom demo image. This setting means they are in Mode 7 (as the 2nd line of the output confirms) and that the Receive feature is enabled for both pins.

Let’s briefly take a closer look at the meaning of these mux pins. In my last article I explained the Mode settings, but not the other bits. The full list of the bit settings can be found in Table 9-58 of the AM335x Technical Reference Manual – you can find a link to it here. I’ll save you the trouble of searching for the table in that 4500-page behemoth:

The 2 UART pins currently have a mux setting of 0×37, or 0011 0111. So:

• The slow slew rate is selected – this might concern me if I knew what it meant.
• The Receiver is enabled – we want that for the RX pin, not so much for the TX pin
• The pullup/pulldown is set to pullup – not a concern for serial communication
• The pullup/pulldown is enabled
• The 3 mode bits are all on, to indicate mode 7

We want to set both pins to Mode 0, and we also want the receiver disabled on the TX pin:

root@beaglebone:~# echo 20 > /sys/kernel/debug/omap_mux/uart1_rxd

 root@beaglebone:~# cat /sys/kernel/debug/omap_mux/uart1_rxd
 name: uart1_rxd.uart1_rxd (0x44e10980/0x980 = 0x0020), b NA, t NA
 mode: OMAP_PIN_OUTPUT | OMAP_MUX_MODE0
 signals: uart1_rxd | mmc1_sdwp | d_can1_tx | NA | NA | NA | NA | NA

 root@beaglebone:~# echo 0 > /sys/kernel/debug/omap_mux/uart1_txd

 root@beaglebone:~# cat /sys/kernel/debug/omap_mux/uart1_txd
 name: uart1_txd.uart1_txd (0x44e10984/0x984 = 0x0000), b NA, t NA
 mode: OMAP_PIN_OUTPUT | OMAP_MUX_MODE0
 signals: uart1_txd | mmc2_sdwp | d_can1_rx | NA | NA | NA | NA | NA

Having said all that, I’m actually going to use UART2 for this project.

UART2 is a little trickier, since its pins have other names in the file system. Looking at Table 11 of the Beaglebone System Reference Manual, we see that UART2_TXD is pin 21, and UART2_RXD is pin 22. Table 12 (below) tells us that pin 21’s Mode 0 usage (and therefore the name used in the file system) is spi0_d0, and that UART2_RXD is the Mode 1 usage. For Pin 22, it’s spi0_sclk, and we also want to change it to Mode 1.

Here are the commands for checking the current settings, and changing the settings to use UART2:

root@beaglebone:~# cat /sys/kernel/debug/omap_mux/spi0_d0
 name: spi0_d0.(null) (0x44e10954/0x954 = 0x0037), b NA, t NA
 mode: OMAP_PIN_OUTPUT | OMAP_MUX_MODE7
 signals: spi0_d0 | NA | NA | NA | NA | NA | NA | NA

 root@beaglebone:~# echo 1 > /sys/kernel/debug/omap_mux/spi0_d0

 root@beaglebone:~# cat /sys/kernel/debug/omap_mux/spi0_d0
 name: spi0_d0.(null) (0x44e10954/0x954 = 0x0001), b NA, t NA
 mode: OMAP_PIN_OUTPUT | OMAP_MUX_MODE1
 signals: spi0_d0 | NA | NA | NA | NA | NA | NA | NA

 root@beaglebone:~# cat /sys/kernel/debug/omap_mux/spi0_sclk
 name: spi0_sclk.(null) (0x44e10950/0x950 = 0x0037), b NA, t NA
 mode: OMAP_PIN_OUTPUT | OMAP_MUX_MODE7
 signals: spi0_sclk | NA | NA | NA | NA | NA | NA | NA

 root@beaglebone:~# echo 21 > /sys/kernel/debug/omap_mux/spi0_sclk

 root@beaglebone:~# cat /sys/kernel/debug/omap_mux/spi0_sclk
 name: spi0_sclk.(null) (0x44e10950/0x950 = 0x0021), b NA, t NA
 mode: OMAP_PIN_OUTPUT | OMAP_MUX_MODE1
 signals: spi0_sclk | NA | NA | NA | NA | NA | NA | NA

A Python Time and Temperature Display for the Beaglebone

I’ve written some Python code to try out the analog and serial pins of the Beaglebone. It gets the temperature from the MCP9700A, and uses the potentiometer to set the backlight of the LCD.

You can download the Python program from my Google Code project page: it’s just a single file, serdisplay.py.

From the Beaglebone command line, you can download the Python program as follows:

root@beaglebone:~# wget http://gigamega-micro.googlecode.com/files/gpiotester.py

I’ve tested the code with the Sparkfun Serial Enabled LCD Kit, the Sparkfun Serial Enabled Backpack. I’ve also coded support for Matrix Orbital serial LCDs, but haven’t tested that yet.

The code uses one Python library that isn’t included in the Angstrom demo image, python-serial. To install it:

root@beaglebone:~# opkg install python-serial

There is no configuration file or command line parameters yet, so any changes to the default settings (the Sparkfun Serial LCD Backpack and a 4-row 20-column LCD) should be made to the code near the top of the program:

# -------------- configurable settings ---------
# settings for UART1
 #DISPLAYPORT = '/dev/ttyO1'
 #RX_MUX = 'uart1_rxd'
 #TX_MUX = 'uart1_txd'
 #MUX_MODE = 0
# settings for UART2
 DISPLAYPORT = '/dev/ttyO2'
 RX_MUX = 'spi0_sclk'
 TX_MUX = 'spi0_d0'
 MUX_MODE = 1
# settings for Serial LCD
 DISPLAY_TYPE = 'SPARKFUN_KIT'
 #DISPLAY_TYPE = 'MATRIX_ORBITAL'
 #DISPLAY_TYPE = 'SPARKFUN'
# settings for analog voltage conversion
 MAX_ANALOG = 3762 # approx 4096 * (1.65/1.8), since voltage divider gives me max of 1.65
 # -- actual values of 3762 based on measurements
# settings for display updates
 TIME_UPDATE_INTERVAL = 1 # every second
 TIME_DISPLAY_ROW = 1
 TEMPERATURE_DISPLAY_ROW = 2
 LCD_NUM_ROWS = 4
 LCD_NUM_COLS = 20
# determines whether debug info is written to the console
 Debug = True
# ---------------------------------------------------------

Then, just run the program as root:

root@beaglebone:~# python serdisplay.py

To stop the program, press Ctrl-Z to put it in the background, then kill the background job:

root@beaglebone:~# kill %1

If you want to keep the program running all the time, I’d recommend using the GNU Screen utility:

root@beaglebone:~# screen
<Press enter when prompted>
root@beaglebone:~# python serdisplay.py

To return to the main command command prompt (leaving the Python program running in the background) press Ctrl-A D.  To go back to the Screen session at any time in the future:

root@beaglebone:~# screen –r –d

For troubleshooting, any error messages are written to serdisplay.log in the same directory as serdisplay.py.

Programmer’s Show And Tell

Since the focus of this article is the Beaglebone, not Python, I’ll just point out some Beaglebone-specific parts of the code.

The code which initializes the UART for the serial display is:

DISPLAYPORT = '/dev/ttyO2'
 RX_MUX = 'spi0_sclk'
 TX_MUX = 'spi0_d0'
 MUX_MODE = 1
 BAUDRATE = 9600
 TIMEOUT = 3 # serial port timeout is 3 seconds - only used when reading from display
# MUX settings
 RECEIVE_ENABLE = 32
. . .
open('/sys/kernel/debug/omap_mux/' + RX_MUX, 'wb').write("%X" % (RECEIVE_ENABLE + MUX_MODE))
 # set the TX pin for Mode 0
 open('/sys/kernel/debug/omap_mux/' + TX_MUX, 'wb').write("%X" % MUX_MODE)
 serDisplay = serial.Serial(DISPLAYPORT, BAUDRATE, timeout=TIMEOUT)

There are Linux character devices assigned to the BeagleBone UARTs: UART1 is /dev/ttyO1, UART2 is /dev/ttyO2, and so on.

From the point of view of the Python program, the Beaglebone’s UART behaves like any other serial port. The code I wrote would work unchanged (aside from the /dev name) when communicating with an XBee, or through a USB-based virtual COM port.

Analog input is a little more finicky. The code which reads the analog value is:

def readAnalog(pinIndex):
 try:
    # add 1 to pin index to get analog pin sys filename
    reading = open("/sys/devices/platform/tsc/ain" + str(pinIndex + 1), "r").read()

    # sometimes string has trailing nulls - delete them
    val = int(re.sub(r'[^\d]+', '', reading))
    return val
 except:
    log.exception('Error in readAnalog')

As indicated by the comments, I found that the value read through the file system was sometimes corrupted: it contained nulls, usually after the value, but occasionally imbedded within the value. I’m not sure if this is a Python-specific thing, or other code would also encounter the problem. In Python, you can strip out the null (and any other non-numeric) values using a regular expression:

val = int(re.sub(r'[^\d]+', '', reading))

From time to time, the attempt to read the analog value will throw an exception.  So, it’s best to use a try/except handler like the one above.

One other problem is that the analog value tends to jump around by about 5 points from one reading to the next, even when it should be constant (e.g. from the potentiometer). I adjusted for this by using an average reading for the temperature, and by ignoring potentiometer readings (i.e. LCD brightness settings) that are within 20 of the last setting.

Don’t forget that the analog value is from 0-4096 – 16 times more sensitive than on the Arduino —  so allow for a greater range of readings.

Wrapping Up

Based on my testing of the code in this project, I’ve found that the Beaglebone’s UARTs are quite reliable and pretty easy to use.  Serial communications should be a relatively easy and trouble-free addition to any Beaglebone project.

Analog in, on the other hand,  has room for improvement.

The approach I used for reading analog input in is good enough for things that don’t require precise accuracy, like the potentiometer or a light meter.  The readings returned by the MCP9700A thermistor are not as stable as they should be.

Fortunately, analog is not the only game in town when it comes to temperature readings, so I plan to experiment with some I2C sensors in the future.

[Updated Jan 22 - various improvements to the Python sample code at the end of the article]

In November, Texas Instruments, Digi-Key and the other members of Beagleboard.org, the Beaglebone.  This is a simpler, more hobbyist-friendly little brother to the Beagleboard (which I’ve written about in past articles).

Compared to the Beagleboards, the Beaglebone is considerably less expensive ($90), provides access to all of its pins, is pin-compatible with 3.3V sensors and devices (aside from analog in, which is still 1.8V), and provides a more friendly “out of the box” experience.  As with the Arduino, the only thing you need to get started is a USB cable.

As a developer, my most pleasant surprise with the Beaglebone was the inclusion of an entry-level IDE and scripting language: the Cloud9 IDE configured to run node.js and bonescript.

With the Beagleboards, there was no “out of the box” IDE.  There were plenty of options for developing with the Beagleboard – Texas Instrument’s Code Composer Studio, Eclipse, or the command-line GCC tools being the most prominent – but all had a fairly steep learning curve just to do something basic, like blink an LED.

One of the most slippery patches on that learning curve is figuring out how to convince the Linux kernel to let your code access the pins.  It’s nowhere near as simple as Arduino’s “digitalwrite(13, HIGH)” – or, at least, it wasn’t until bonescript came along.  Although bonescript is still in its very early stages, there is enough meat on it to give the embedded Linux newbie a friendly introduction to coding.

The Circuit

The circuit is your garden-variety LED configuration:

• an LED
• a resistor (680R or thereabouts) connected to the negative pin of the LED
• a jumper from the positive pin of the LED to the digital pin
• a jumper from the resistor to ground

The Beaglebone actually has 65 GPIO pins to choose from, but we’ll go with the one used by the blinkled.js program that is included with bonescript.  This is Pin 3 on Header 8, referred to by the Beaglebone System Reference Manual as  GPIO1_6 on Expansion B, but known to Linux as gpmc_ad6.

Say what?

Well, the “Pin 3 on Header 8″ part is simple enough. If you look at the Beaglebone, Port 8 is one of the 2 double-rows of female headers,  labeled P8 on the circuit board.  (In the figure below, taken from the System Reference Manual, Port 8 is labeled “Expansion B).

Beaglebone, showing pin P8_3 and Ground

At either end of the headers you’ll find the rows marked 1 and 2, and 45 and 46.  So, Pin 3 is the 2^nd row from the top, left column, as indicated in the figure.

The other names for the pin, along with the locations of the ground pins, can be found in the System Reference Manual.  If you look at Table 8 – “Expansion Header P8 Pinout” (a portion of which is shown below), you’ll find the pins labeled with their default usages in the Angstrom Linux demo image (the one that comes packaged with the beaglebone on a microSD card).

Default pin settings in Anstrom Linux

Clearly, Ground is the top row of Port 8, so that’s the last bit of information we need to know to hook up the circuit.  But we’ll need to understand that part about pins having “default usages” – more on that later.

Cloud9 IDE and bonescript

When you boot up the Beaglebone with the microSD card from the box, the Cloud9 IDE is automatically started.  Once you have an  IP address assigned to the Beaglebone (either through its Ethernet port connection or through USB networking), you can load the Cloud9 IDE on your PC browser at http:<beaglebone address>:3000

(I haven’t tried to use USB networking myself, but the procedure for doing so is explained in Getting started with your new BeagleBone.)

The Cloud9 IDE interface is pretty intuitive.  You select a source code file in the left pane, edit it in a tab in the right pane, and select Debug or Run from the toolbar to execute the code.

Cloud9 IDE

If you are coming at this from the Arduino, you will notice 3 significant differences from the Arduino IDE:

• You don’t upload your code to the board.  The Beaglebone is more like a PC than an Arduino – the code is stored on its file system, and you just run it.
• You can debug your code.  Not Arduino’s form of debugging – print statements to the console (though you can do that too) — but real debugging, as in breakpoints, watch variables, step-by-step execution.
• The coding language is Javascript, not C.  Specifically, it’s node.js, which is Javascript optimized for running on a server, rather than in a browser, by way of some extra libraries.  The “server” in this case is the little old Beaglebone.  As you might imagine, node.js is not the fastest environment for running code on the Beaglebone, but for LED blinking and many other types of prototyping, it’s fast enough.

Despite the differences, Arduino coders should find the transition to Cloud9 and bonescript to be quite easy.  The blinkled.js code looks very much like Arduino code.  That’s no coincidence: the README for the bonescript project, which you can find on its github page here,  says that the goal is “to have something that provides most of the Arduino functions and is generally usable by Summer 2012″.

var ledPin = bone.P8_3;
var ledPin2 = bone.USR3;

setup = function() {
    pinMode(ledPin, OUTPUT);
    pinMode(ledPin2, OUTPUT);
};

loop = function() {
    digitalWrite(ledPin, HIGH);
    digitalWrite(ledPin2, HIGH);
    delay(1000);
    digitalWrite(ledPin, LOW);
    digitalWrite(ledPin2, LOW);
    delay(1000);
};

This code from blinkled.js does the following:

• defines 2 pins, P8_3 (Port 8, pin 3) and USR3 (which is one of the built-in LEDS on the board, next to the Ethernet port)
• sets these pins for Output
• loops, turning these 2 LEDs on and off, once per second, ad infinitum

If you’ve attached an LED to pin 3, and you run blinkled.js in Cloud9, you should find it blinking happily away. (There is a dropdown button next to the Run and Debug toolbar icons in Cloud9 to let you choose the file).

It’s that simple.

I lie.

There is actually considerable complexity behind the code which creates those 2 pin objects, bone.P8_3 and bone.USR3.  The complicated code is in one of the 2 “library” files in the bonescript folder, index.js.

Pins and Muxing

Before we dive into the index.js code, let’s return to the Beaglebone System Reference Manual.  As you’ll recall, I earlier referred to the “default usage” on Port 8 Pin 3.  It has other usages, and the process of telling the board how you want to use that pin is called muxing (short for multiplexing).

The available usages of the pin, and all of the others on the Port 8, are listed in Tables 9 (the first part of which is shown below) and 10 of the System Reference Manual.  Each pin can have up to 8 uses, “mux mode” 0 through 7.  The default setting in the Angstrom Image is generally, but not always, mode 7.  Table 8 is the definitive guide to Angstrom’s default mux setting for each pin.

Pin Mux settings from the System Reference Manual

(Incidentally, other Linux distributions for the Beaglebone, such as Ubuntu, will have their own default mux settings.  The board doesn’t control the mux settings, the software does.  The developers of the Angstrom Linux image on the SD card selected their defaults to be the most commonly used ones by hobbyists, providing a good out-of-the-box experience.)

If you Google “Beagleboard mux”, you’ll find lots of pages explaining the various ways in which you can change the mux setting.  Many of them refer to U-Boot configuration and kernel modules, which are complicated and, fortunately, no longer necessary.  There has been a lot of work done recently at making the mux settings accessible to “userland” code by way of the Linux file system.  If you (or your code) wants to read or change the mux setting, it just needs to read or write to a file.

Great.  So which file?

This information used to be hard to come by, scattering amongst various forum and blog posts, or hidden inside code in U-Boot or the linux kernel.  However, if you’re learning to code with the Beaglebone, I think the best way to learn the mux file system is to look at how bonescript handles it.

Muxing the bonescript way

So, back to the Cloud9 IDE.  This time, open up the index.js file in the bonescript directory.  (Note that this part of bonescript is in active development and is likely to change by the time you read this, but the underlying file system will still be the same)

A little ways into the code (line 39 in the current release, bonescript 1.0-r10), you’ll find the following:

var gpio0 = 0;
var gpio1 = gpio0+32;
var gpio2 = gpio1+32;
var gpio3 = gpio2+32;

bone = exports.bone =
{
    P8_1: { name: "DGND" },
    P8_2: { name: "DGND" },
    P8_3: { name: "GPIO1_6", gpio: gpio1+6, mux: "gpmc_ad6" },
    P8_4: { name: "GPIO1_7", gpio: gpio1+7, mux: "gpmc_ad7" },
    P8_5: { name: "GPIO1_2", gpio: gpio1+2, mux: "gpmc_ad2" },
    P8_6: { name: "GPIO1_3", gpio: gpio1+3, mux: "gpmc_ad3" },
    P8_7: { name: "TIMER4", gpio: gpio2+2, mux: "gpmc_advn_ale" },
    P8_8: { name: "TIMER7", gpio: gpio2+3, mux: "gpmc_oen_ren" },
. . .
    USR0: { name: "USR0", gpio: gpio1+21, led: "usr0", mux: "gpmc_a5" },
    USR1: { name: "USR1", gpio: gpio1+22, led: "usr1", mux: "gpmc_a6" },
    USR2: { name: "USR2", gpio: gpio1+23, led: "usr2", mux: "gpmc_a7" },
    USR3: { name: "USR3", gpio: gpio1+24, led: "usr3", mux: "gpmc_a8" }

This table contains 3 important pieces of information:

1. the label that bonescript uses to identify the pins (P8_1, P8_2, etc)
2. the GPIO pin number (P8_3 is gpio1+6, or 38)
3. the mux label (P8_3 is gpmc_ad6)

The GPIO pin number tells you the directory name you will use to read from or write to the pin.  The mux label tells you the filename you will use to read or write the mux setting.

Let’s start with the mux setting.  This is handled by some code just below the exports.bone table:

if(pin.mux) {
 try {
    var muxfile = fs.openSync(
      "/sys/kernel/debug/omap_mux/" + pin.mux, "w"
      );
    fs.writeSync(muxfile, "7", null);
 } catch(ex3) {
    console.log("" + ex3);
    console.log("Unable to configure pinmux for: " + pin.name +
      " (" + pin.mux + ")");
. . .

There is more to the error handling, but the important part is the reference to “/sys/kernel/debug/omap_mux/” + pin.mux.  This is the file used to read and write the mux setting.  In the case of Port 8 Pin 3, the full path is /sys/kernel/debug/omap_mux/gpmc_ad6.

This is the part that is newcomers to pin muxing often trip over: if you want to set a pin to be a GPIO pin, your code needs to reference a filename that appears to be intended for a different usage of the pin (gpmc_ad6).  The mux filename isn’t taken from its intended usage, it’s taken from its mode 0 usage.  The mode 0 usage for Port 8 Pin 3 is gpmc_ad6 – we know this from the table in the bonescript code, but the definitive reference for the Beaglebone pin mux modes are Tables 9 and 11 of the Beaglebone System Reference Manual.

Having opened the file (fs.openSync), the bonescript code writes a 7 to it (fs.writeSync).  This, as you probably guessed, sets the mux mode to 7, the GPIO mode for that pin.  The process of setting mux modes isn’t quite as simple as “write the  mode to a file”:  the mux mode setting also affects other aspects of the pin, such as whether it can be used for input.  The bonescript code shown above is actually correct only for setting pins to be GPIO Output pins.  The bonescript project will soon support other mux mode settings.

Blinking LEDs the bonescript way

Having set the pin to be in digital output mode, the next task is to set it high or low.  You’ll recall that this was handled in blinkled.js by calling a function called digitalWrite, same as the Arduino does.

The source code for digitalWrite can be found further down in index.js:

digitalWrite = exports.digitalWrite = function(pin, value)
{
    fs.writeFileSync(gpio[pin.gpio].path, "" + value);
};

OK, so it’s writing a value to a file, either HIGH (defined as 1) or LOW (0).  But which file?

The code to set that “path” property also in index.js, just below where the pin mux setting was done:

try {
    try {
        fs.writeFileSync("/sys/class/gpio/export", "" + n);
    } catch(ex2) {
        // TODO: If the file is already exported, can we know who did
        // did it so that we aren't opening it twice?  In general, this
        // shouldn't be an error until we have some better resource
        // management.
        //console.log(ex2);
        //console.log("Unable to export gpio: " + n);
    }
    fs.writeFileSync("/sys/class/gpio/gpio" + n + "/direction",
        mode);
    gpio[n].path = "/sys/class/gpio/gpio" + n + "/value";
    return(true);
} catch(ex) {
    // Perhaps we couldn't open it because it was allocated as an LED
    if(pin.led) {
        fs.writeFileSync(
            "/sys/class/leds/beaglebone::" + pin.led + "/trigger",
            "gpio");
        if(mode == OUTPUT) {
            gpio[n].path =
                "/sys/class/leds/beaglebone::" + pin.led +
                "/brightness";
        } else {
            gpio[n].path =
                "/sys/class/leds/beaglebone::" + pin.led +
                "/gpio";
        }
        return(true);
    }
}

The first thing it does is try to write to a file named “export”, specifically , “/sys/class/gpio/export”.  The value written is the GPIO pin number, which you’ll recall was specified in the table earlier in index.js.  For Port 8 Pin 3, it was defined as gpio1+6, or 38.

The export file is a funky weird-ass file: when you write a pin number to it, it (well, the kernel process which monitors that file) creates a directory and a bunch of files that provide interfaces for accessing the pin.  The directory is created at /sys/class/gpio/export/gpioNN. In the case of Port 8 Pin 3, that’s /sys/class/gpio/export/gpio38.

For the purpose of using a GPIO pin, the two most important files in the gpioNN directory are named direction and value.

The direction file determines whether the pin is going to be used for reading or writing.  As mentioned earlier, you can’t use a pin for reading without setting flipping a bit in the mux mode setting, so our only choice at this point is output.   The bonescript code writes the value “out” to the direction file (i.e. to /sys/class/gpio/export/gpio38/direction).

The code then saves the path to the value file (i.e. /sys/class/gpio/export/gpio38/) in the pin’s path property.  This, then, explains what the code in the digitalWrite function is doing:

fs.writeFileSync(gpio[pin.gpio].path, "" + value);

It writes a 1 to the value file (i.e. /sys/class/gpio/export/gpio38/value) to set the pin high (and the turn the LED on) and a 0 to set it low (and the LED off).

But wait, there’s more!

The bonescript code shown above also has an error handler.

Writing to the export file also tells the kernel that you intend to use that pin.  If the pin is already being used by something more important than your dinky userland application (i.e. the kernel or one of its pals), it will helpfully toss an error at you.

Generally, when your attempt to export a pin fails, you have no option but to go away and sulk.  Something is using that pin, and it might be a hardware driver that won’t be giving it up any time soon (such as the SD card socket, or an LCD).  There are ways of tracking down what’s using it, but I won’t cover them in this post.

One possibility is that the GPIO pin is being used by one of the built-in “user LEDs”, USR0 – USR3.  As you can see from the final entries in the bonescript mux table, those LEDs are connected to GPIOs 53-56.  So, the bonescript code checks to see if you’re trying to write to those GPIOs – if so, it assumes you want to access the user LEDs, and redirects you to their address.

These user LEDs are accessed through a different part of the file system than the GPIOs – technically, they are part of the Beaglebone board, not part of the CPU.  So, they are accessed through the /sys/class/leds/beaglebone directory, not /sys/class/gpio.

The Beagleboard (the ‘bone’s big brother) also has user LEDs, and they are accessed in basically the same way there, so you can find a good explanation of how to write to them in some of the articles written for the Beagleboard.  The command line interface is explained in this article on eLinux.  For C language code that interfaces to the user LEDs, see this sample from Jan Axelson’s USB Embedded Hosts: The Developer’s Guide.  (This, by the way, is one of the few books currently available that specifically covers Beagleboard programming).

Blinking LEDs the Python Way

The directories and paths used by the bonescript code can also be used from other programming languages: pretty much anything that runs on Linux can read and write from the file system.

Here is my own humble contribution, a snippet of Python code which blinks the USR2, USR3 and Port 8 Pin 3 ten times.  It has the advantage of distilling the bonescript code down to the bare bones needed to access that particular pin.

[Updated Jan 22 - added support for User LEDs 2 and 3, handle case where pin already exported, and simplified  the file I/O syntax:]

import time

# put Port 8 Pin 3 into mode 7 (GPIO)
open('/sys/kernel/debug/omap_mux/gpmc_ad6', 'wb').write("%X" % 7)

try:
   # check to see if the pin is already exported
   open('/sys/class/gpio/gpio38/direction').read()
except:
   # it isn't, so export it
   print("exporting GPIO 38")
   open('/sys/class/gpio/export', 'w').write('38')

# set Port 8 Pin 3 for output
open('/sys/class/gpio/gpio38/direction', 'w').write('out')
# we will assume that USR1 and USR 2 are already configured as LEDs

for i in range(10):
   # turn on USR1 and external LED
   open('/sys/class/gpio/gpio38/value', 'w').write("1")
   open("/sys/devices/platform/leds-gpio/leds/beaglebone::usr1/brightness", 'w').write("1")
   # turn off USR2
   open("/sys/devices/platform/leds-gpio/leds/beaglebone::usr2/brightness", 'w').write("0")

   time.sleep(1)

   # turn off USR1 and external LED
   open('/sys/class/gpio/gpio38/value', 'w').write("0")
   open("/sys/devices/platform/leds-gpio/leds/beaglebone::usr1/brightness", 'w').write("0")
   # turn on USR2
   open("/sys/devices/platform/leds-gpio/leds/beaglebone::usr2/brightness", 'w').write("1")

   time.sleep(1)

# cleanup - remove GPIO38 folder from file system
open('/sys/class/gpio/unexport', 'w').write('38')

The Python code also demonstrates something that the bonescript code doesn’t handle.  To be a nice little userland app and clean up after yourself, you can write the GPIO pin number to /sys/class/gpio/unexport.  This doesn’t “release” the GPIO to other apps – you never had it locked for your exclusive use in the first place – so unexport’ing is just a convention to make the gpio file system is a little more manageable.

Since python is already installed on the Angstrom image, you can download the file and run it as follows:

wget http://gigamega-micro.googlecode.com/files/gpiotester.py
python gpiotester.py

Wrapping Up

If you think that’s a lot of work in order to blink an LED, you should have tried it a few years ago, when the Beagleboard was first released.

Back in the day, to do anything with a GPIO pin you pretty much had to be an embedded Linux guru, or beg for crumbs of knowledge from the guru’s table.  (Oh, and good luck getting your LED to light up on 1.8V.  You kids have it easy these days!)

The Beaglebone arrives at a time when the embedded Linux device market is growing by leaps and bounds, both in terms or hardware and development tools.  As a hobbyist (or a budding professional), this is a good time to hop on board the platform.

Incidentally, while the Beaglebone platform is geared for hobbyists and prototypers, the chip it uses is very much targeted at professionals.  The Texas Instruments Sitara AM3359 is a descendent of (and largely code compatible with) the storied OMAP chip family, which powers a lot of consumer gadgets: many of Nokia’s high-end smartphones like the E90, Motorola’s Droid line of Android smartphones, the Nook Color and the Kindle Fire.

If you can get to a root command line on one of those devices, you can probably set a GPIO high and low using the same code as above (and if you’re lucky, cause an inglorious crash).  How cool is that?