Update May 5: Wherefore art thou, PWM?  In kernel version 3.2.14 (released in April), PWM disappeared from the file system.  I haven’t read an explanation of why it was removed, or when it will return.  If you need to access the PWM registers through the file system, my advice is to stick with kernel version 3.2.13.  

Depending on which image you are running, you may find the 3.2.13 kernel in your /boot folder.  If not, you can download it from http://www.gigamegablog.com/docs/uImage-3.2.13 (md5sum is 1f62bc400c76a4b174c5ae7ba50afe9e). Copy uImage-3.2.13 to uImage on your boot partition, as described in the Enabling PWM Support in the Kernel section below.

My earlier articles [1, 2] on Beaglebone coding ignored one of the basics: digital input.  The main reason I skipped it is that the I only knew how to handle input by polling, and polling is lame.  I decided to wait until I had some Python code to handle input using interrupts, and write about that instead.

Well, here we are, a couple of months later, and … um … it turns out that polling is cool.  Interrupts are lame.  You know who uses interrupts?  Microsoft!  Need I say more?

I’ll also cover a relatively new addition to the Beaglebone’s kernel, PWM.

Digital Input

The Beaglebone has a number of pins that default to GPIO mode, and all of them are initially configured for input, not output: the receive feature is enabled, and the GPIO direction flag is set to “in”.

If you take a look at the pin mux settings for these pins, you’ll notice they are similar, but not the same.

For example, here is Port 8 Pin 3:

root:/sys/kernel/debug/omap_mux# cat gpmc_ad6
 name: gpmc_ad6.gpio1_6 (0x44e10818/0x818 = 0x0037), b NA, t NA
 mode: OMAP_PIN_OUTPUT | OMAP_MUX_MODE7
 signals: gpmc_ad6 | mmc1_dat6 | NA | NA | NA | NA | NA | gpio1_6

And here is Port 8 Pin 11:

root:/sys/kernel/debug/omap_mux# cat gpmc_ad13
 name: gpmc_ad13.gpio1_13 (0x44e10834/0x834 = 0x0027), b NA, t NA
 mode: OMAP_PIN_OUTPUT | OMAP_MUX_MODE7
 signals: gpmc_ad13 | lcd_data21 | mmc1_dat5 | mmc2_dat1 |
 NA | NA | NA | gpio1_13

Both pins are configured for Mode 7 (GPIO mode), but Pin 3′s mux setting is x37, and Pin 11′s is x27.

From the mux register description in the AM335x Technical Reference, we know that this means both pins are configured for input (Received enabled), but Pin 3 is set to use pullup resistors, and Pin 11 is set to use pulldown resistors.

By default, then, Pin 3 reads HIGH when nothing is connected to it, and Pin 11 reads LOW.

Sure enough, if we export the pin, then look at its value, we see that it is a 1 for Pin 3:

root:/sys/class/gpio# echo 38 > export
root:/sys/class/gpio# cd gpio38/
root:/sys/class/gpio/gpio38# cat value
 1

…and a zero for Pin 11:

root:/sys/class/gpio# echo 45 > export
 root:/sys/class/gpio# cd gpio45
 root:/sys/class/gpio/gpio45# cat value
 0

I have no idea why these default settings were chosen: possibly to give creators of capes more plug-and-play flexibility, possibly to give me yet another opportunity to write about mux settings, or maybe they just couldn’t decide.  However, when you hook up a circuit you really do have to make a choice.

With Pin 3′s setting, a button (or any other digital input device), needs to connect to Ground when the button is pressed.  If you connect it to a voltage pin, nothing good will come of it, but quite possibly a lot of bad.

The GPIO pins on the Beaglebone are quite fragile, compared to the Arduino‘s or Netduino‘s.   The Arduino is happy with 5V of input, but can also work with 3.3V.  The Netduino prefers 3.3V, but is 5V “tolerant”, meaning you can get away with it.  The Beaglebone, on the other hand, is decidedly intolerant of 5V.  Hook it up to 5V, even for a split second, and it will die.  I wish I could say that I learned this by reading about it, but you can trust me on this one.

The GPIO pins are also more delicate than the Arduino when it comes to current.

According to this post  by Beaglebone hardware designer Gerald Coley, the recommended max output current through a pin is 4-6 mA, and the max input current is 8 mA.  On the Arduino, it is 40 mA.  (Based on my own experience, the Beaglebone seems to be tolerant of higher currents: I’ve measured 60 mA coming out of a GPIO pin.  That was a different Beaglebone than the one that died, by the way. What can I say: I’m the Michael Vick of electronics!)

For this reason, I think it’s safest to configure a digital input pin with a pull-up resistor, and connect the button to ground.  If you go the other way and use a pull-down resistor, be very certain you don’t accidentally hook it up to the 5V pins, and be sure to use an external resistor too – the internal pull-down resistor won’t knock down the current for you.

The photo below shows 2 pushbuttons connected to 2 GPIO pins: Port 9 Pins 12 (purple wire) and 15 (green wire).

Pin 12 is configured with a pull-up resistor by default.  (Note that there is a typo in the System Reference Manual: the pin name is gpmc_ben1, not gpmc_be1n. )

root:/sys/kernel/debug/omap_mux# cat gpmc_ben1
 name: gpmc_ben1.gpio1_28 (0x44e10878/0x878 = 0x0037), b NA, t NA
 mode: OMAP_PIN_OUTPUT | OMAP_MUX_MODE7
 signals: gpmc_ben1 | mii2_col | NA | mmc2_dat3 | NA | NA | mcasp0_aclkr | gpio1_28

So, the circuit for connecting a button is quite simple:

• Pin 12 to Button (purple wire)
• Button to Ground

When the button is pressed, the value will change from 1 to 0, making the button behave like a normally closed button (unless you actually have a normally closed button – hey, so that’s what those crazy NC buttons are for!). Be sure to account for this in your code.

root:/sys/class/gpio# echo 60 > export
root:/sys/class/gpio# cd gpio60
root:/sys/class/gpio/gpio60# cat value
0

Pin 15 is, by default, configured to use pull-down resistors.

root:/sys/kernel/debug/omap_mux# cat gpmc_a0
name: gpmc_a0.gpio1_16 (0x44e10840/0x840 = 0x0027), b NA, t NA
mode: OMAP_PIN_OUTPUT | OMAP_MUX_MODE7
signals: gpmc_a0 | mii2_txen | rgmii2_tctl | rmii2_txen | NA | NA | NA | gpio1_16

You can, of course, change that mux setting if you want to use the same simple button circuit as with Pin 12, but for the sake of variety I’ve hooked it up as-is:

• Pin 15 to button
• Button to 1K resistor
• Resistor to 3.3V

The resistor value is actually quite unimportant, as long as it’s 550R or higher.  While the Beaglebone’s GPIO pins don’t like high current, they have no problem with very low current, so 1K, 10K or 100K resistors should all work.

With the button connected to Pin 15 held down, we get a value of 1:

root:/sys/class/gpio# echo 48 > export
root:/sys/class/gpio# cd gpio48
root:/sys/class/gpio/gpio48# cat value
1

As promised, I’ll be showing some code that reads the buttons using some cutting edge polling technology, but first let’s take a look at PWM.

Enabling PWM Support in the Kernel

PWM support was added to version 3.2 of the Angstrom kernel.  (I believe it was initially in 3.2.0, but I didn’t start working with it until 3.2.6.)  These kernel updates were delivered via opkg updates in February.

Unfortunately, while opkg delivers the new kernels, it doesn’t activate them.  That requires some manual intervention.  Let me walk you through it…

First, check what kernel version you are currently running

root:~# uname -r
3.2.6+

If you have 3.2.6+ (or later), then great, you’re ready to go.  Skip ahead to the Activating the PWM Clock section below.

Otherwise, you’ll need to update the kernel.

Check to see what kernels have been installed by opkg:

root:~/tmp# ls -l /boot
total 12180
-rwxr-xr-x 1 root root      33 Feb 14 18:31 uEnv.txt
lrwxrwxrwx 1 root root      13 Mar  7 20:26 uImage -> uImage-3.2.9+
-rw-r--r-- 1 root root 3042328 Jan 26 12:49 uImage-3.1.0+
-rw-r--r-- 1 root root 3135840 Feb 10 03:57 uImage-3.2.0+
-rw-r--r-- 1 root root 3137472 Feb 22 05:37 uImage-3.2.6+
-rw-r--r-- 1 root root 3140088 Mar  6 13:47 uImage-3.2.9+

Right now (mid March), the latest and greatest is 3.2.9+.

If you don’t have the 3.2.x kernels listed in /lib/modules, then be sure to update your packages:

opkg update
opkg upgrade

If the opkg fairy still didn’t leave a new kernel under your pillow, then you might need to upgrade to a new image on the SD card.

Currently, the latest image is the February 14^th “2012.02” version, which shipped with Revision 5 of the Beaglebone.  You can download it from the Beaglebone Demo page  or from CircuitCo .  Circuitco’s page has instructions for installing the image to an SD card using Windows.  This image comes with the 3.2.5+ kernel, which supports PWM, but after giving it a spin you’ll probably want to go ahead and upgrade to the latest kernel anyway.

When opkg delivers the kernels, it doesn’t install them.   To start using a new kernel, you need to manually install it onto the boot partition of the SD card – you can easily do this right from the Beaglebone command prompt.

Begin by mounting the boot partition.  You need to use a directory as a mount point: I’m using one called tmp:

root:~# mkdir tmp
root:~# mount /dev/mmcblk0p1 tmp

If you look at the mount point, you should see the following files:

root:~# ls tmp
Docs     LICENSE.txt  README.htm    u-boot.img  uImage
Drivers  MLO          autorun.inf  info.txt    uEnv.txt

Overwrite the uImage with the latest kernel file from /boot:

root:~# cp /boot/uImage-3.2.9+ tmp/uImage

Unmount to make sure everything is nicely tucked away on the SD card, then reboot:

root:~# umount tmp
root:~# shutdown -r now

After rebooting, your system should report the new kernel:

root:~# uname -r
3.2.9+

Activating the PWM Clock

By default, the 3.2 kernel supports PWM, but doesn’t enable it.  If you try to use it through the file system, you’ll get “segmentation errors” and a lot of other moaning and groaning from the kernel.

As explained in this post on the Beagleboard group, the PWM clock needs to be enabled before you start using PWM.

The clock control register is documented in the AM335x Technical Reference Manual as follows:

The clock register isn’t exposed through the file system, so the only way to change this setting is by directly updating the register in memory.  Fortunately another post in the Beagleboard group provided the necessary code:

I’ve put a copy of the code here.  To run it on the Beaglebone:

root:~# opkg install python-mmap
root:~# wget http://www.gigamegablog.com/docs/setPWMReg.py
root:~# python setPWMReg.py

You should see:

Register CM_PER_EPWMSS1_CLKCTRL was 0x30000
Register CM_PER_EPWMSS1_CLKCTRL changed to 0x2

So, the IDLEST field is initially set to Disable – the code clears that field, and set the MODULEMODE field to ENABLE.

Having got the clock up and running, we’re ready to control the PWM settings through the file system.

Controlling PWM Using the File System

There are 2 pins on Port 9 that, by default, are configured for PWM, Pins 14 and 16.  The Beaglebone System Reference manual identifies these as EHRPWM1A and EHRPWM1B; to the file system, they are ehrpwm.1:0 and ehrpwm.1:1, respectively.

The “EHR” part means Enhanced High Resolution.  There is also a second type of PWM pin on the Beaglebone, called ECAP, or Enhanced Capture.  The 2 types of PWM pins have similar settings exposed through the file system, as explained in the AM335x PWM Driver’s Guide on the TI web site.

To me, the most important difference between the 2 type of PWM is that I can’t get ECAP to work.  So, let’s give the EHR PWM a whirl.

A good way to experiment with the PWM settings is to connect the positive pin of an LED to one of these pins, and negative pin of LED to ground.  You can safely do so without using a resistor, assuming the LED can be powered by the 3.3V that comes out of these pins.

A garden variety red or white LED should be fine – in the photo below, I have a red LED connected to pin 14.

[Updated Apr 25: Added the mux mode settings] 

For starters, set the mux mode settings for the 2 pins to Mode 6 for EHRPWM:

root:~# echo 6 > /sys/kernel/debug/omap_mux/gpmc_a2
root:~# echo 6 > /sys/kernel/debug/omap_mux/gpmc_a3

There are a variety of PWM settings exposed through the file system, as described in the PWM Driver’s Guide, but the two key ones are period_freq, which is the frequency in Hz, and duty_percent, the duty cycle setting.

The following will blink the LED slowly, once per second: [Updated Mar 25: Before changing the period_freq  setting, duty_percent should be set to 0.  Otherwise, the value of duty_percent might be (silently and mysteriously) reset to another value]

root:~# cd /sys/class/pwm/ehrpwm.1:0
root:/sys/class/pwm/ehrpwm.1:0# echo 0 > duty_percent
root:/sys/class/pwm/ehrpwm.1:0# echo 1 > period_freq
root:/sys/class/pwm/ehrpwm.1:0# echo 50 > duty_percent
root:/sys/class/pwm/ehrpwm.1:0# echo 1 > run

The following settings will cause the LED to glow dimly [Corrected Mar 20]

root:/sys/class/pwm/ehrpwm.1:0# echo 0 > run
root:/sys/class/pwm/ehrpwm.1:0# echo 0 > duty_percent
root:/sys/class/pwm/ehrpwm.1:0# echo 200 > period_freq
root:/sys/class/pwm/ehrpwm.1:0# echo 20 > duty_percent
root:/sys/class/pwm/ehrpwm.1:0# echo 1 > run

To make the LED glow more brightly:

root:/sys/class/pwm/ehrpwm.1:0# echo 80 > duty_percent

It’s safe to change the duty_percent setting on the fly, without changing the other settings first.

The TI guide advises checking the availability of the PWM pin first:

root~:/sys/class/pwm/ehrpwm.1:0# cat request
 ehrpwm.1:0 is free

I haven’t seen it return anything except “free” yet, so I’m not sure under which circumstances it returns “busy”.  But, feel “free” to check.

With the second PWM port, right next door,  I decided to try a high-power LED with this one, the CREE XLAMP. This is actually a good use of PWM, since without it the CREE’s brightness makes it a pain to work with.  (I blinded me with science!)

Here, the GPIO pin’s current restriction is a problem: the CREE won’t even flicker with the max recommended output current of 6mA.  The 300 mA that flows out of the 3.3V port will do the trick, though.

To control the flow using PWM, you can use a transistor.  I used a common NPN “switching” transistor, the 2N2222.

The base of the transistor can be connected to the PWM pin, through a resistor. The resistor keeps the current within the recommended 4-6 mA for a GPIO pin.  I used a 1K resistor, but as with the digital input sensors the exact value doesn’t matter as long as you’re above 550R:  you don’t need much current to control the transistor base.

• Pin 16 to 1K resistor.
• Resistor to Base
•  3.3V to positive pad of XLAMP
• Negative pad of XLAMP to Collector of 2N2222
• Emitter of 2N2222 to ground

With this circuit, and a duty cycle of just 1%, the XLAMP is no longer blinding (though still surprisingly bright).

A couple of things to note about the frequency setting:

• Corrected Mar 21: As pointed out by muhoo in the Comments section, you can take the PWM frequency well past 250 Hz.  The key is to set the duty_cycle to zero before changing the frequency.  I’m not sure what the actual maximum frequency is, but the file system allows it to be set to 10 Mhz:

# echo 0 > run
# echo 0 > duty_percent
# echo 10000000 > period_freq
# echo 50 > duty_percent
# echo 1 > run
# cat period_freq
10000000
# cat period_ns
100

• The maximum is 250 Hz.  I actually couldn’t find this documented anywhere, but currently setting it to anything above that value returns an error message.  (There is an alternative setting of period_ns, but the minimum for that is 4 million – same difference.)

root:/sys/class/pwm/ehrpwm.1:0# echo 251 > period_freq sh: echo: write error: Invalid argument

• The frequency setting is shared between ehrpwm.1:0 and ehrpwm.1:1 — if you change it for one, the other will be automatically set to the same frequency.  So, unlike the duty_percent, you’ll probably want to set the “run” flag to 0 for both PWM devices before changing it.

Programmer’s Show And Tell

There aren’t many interesting ways to combine digital input and PWM output, and I’ve set out to prove this with some sample Python code  I’ve used one of the buttons and the 2 PWM-driver LEDs from earlier in the article.  Press the button and the lights come on.  Press and hold the button, and light state toggles between on and off.  Whee!

You can download the program from my Google Code site.

There are, however, a few things worth pointing out in the code.

Firstly, I’ve (ahem) borrowed the pin mode table from bonescript in order to implement Python versions of pinMode, digitalRead and digitalWrite .

Python’s Dictionary is an easy-going data type: you can store anything in it, including another dictionary.  This  is similar to node.js, so the syntax of the bone_pins definition is almost identical to its bonescript counterpart:

bone_pins = { "P8_1": { "name": "DGND" },
 "P8_2": { "name": "DGND" },
 "P8_3": { "name": "GPIO1_6", "gpio": gpio1+6, "mux": "gpmc_ad6", "eeprom": 26 },
 "8_4" : . . .

Adding more information to a pin definition is just a matter of adding another entry to the dictionary.  So, to extend the table to include PWM pins, I just added a “pwm” key …

"P9_14": { "name": "EHRPWM1A", "gpio": gpio1+18, "mux": "gpmc_a2", "eeprom": 34, "pwm" : "ehrpwm.1:0" },
 "P9_16": { "name": "EHRPWM1B", "gpio": gpio1+19, "mux": "gpmc_a3", "eeprom": 35, "pwm" : "ehrpwm.1:1" },

To check if a pin supports pwm:

if not "pwm" in bone_pins[pin]:
   print "ERROR: pin %s does not support PWM" %  pin

Like node.js, Python provides a command line for experimenting with code without running the full application. So, you can take advantage of these functions by loading the module, then calling the functions manually.

This is somewhat quicker and a lot easier than controlling the settings from the Linux command prompt.  For example, to set Port 8 Pin 5 for input, then check the current input value (you’ll need to run python from the directory that contains ButtonsAndLights.py):

root:~# python
>>> import ButtonsAndLights as bb
>>> bb.pinMode("P8_5", "in")
 setting /sys/kernel/debug/omap_mux/gpmc_ad2 to 0x37
 getting direction /sys/class/gpio/gpio34/direction
 exporting GPIO 34
 Exported /sys/class/gpio/gpio34/direction is in

 >>> bb.digitalRead("P8_5")
 /sys/class/gpio/gpio34/value is 1
 1

The extra “verbiage” are some print statements in the Python code for debugging purposes – I haven’t fully cleaned up the code yet to make it more usable as a plug-in module. For a more polished and better performing Python implementation of digital I/O functions, take a look at PyBBIO.  This code interacts with the GPIO pins using direct register access, rather than the file system, so PyBBIO should prove much faster, perhaps fast enough to handle the microsecond-level timing needed to implement device drivers.

I’ve also implemented pwmMode, pwmStart and pwmStop functions.  (This time I didn’t go with the Arduino naming convention – I can’t bring myself to refer to PWM as “analogWrite” like those bohemian Arduinoists.).

def pwmWrite(pin, frequency, duty_cycle, start = True):
 """ Changes settings of specified PWM pin (e.g. "P9_14") and optionally enables it.
 Note that frequency and duty_cycle can be omitted to leave them unchanged """

def pwmStart(pin):
 """ Turn on PWM on the specified pin. PWM settings must previously have been passed to pwmWrite() """

def pwmStop(pin):
 """ Turn off PWM on the specified pin """

These, too, can be used from the Python command line.  To set Port 9 Pin 14 to run at 200 Hz 80%:

>>> bb.pinMode("P9_14", "pwm")
 setting /sys/kernel/debug/omap_mux/gpmc_a2 to 0x6
>>> bb.pwmWrite("P9_14", 200, 80)
>>> bb.pwmStop("P9_14")

Last, and least, there is the polling for digital input:

lastButtonState = digitalRead(BUTTON_NC_PIN)
while 1 == 1:
    buttonState = digitalRead(BUTTON_NC_PIN)

    # NOTE: will return another value if unable to read
    if buttonState == HIGH or buttonState == LOW: 
         if buttonState != lastButtonState:
         # do stuff
    time.sleep(BUTTON_POLL_INTERVAL / 1000.0)

While polling is, um, rather quaint, the AM335x is fast enough that it doesn’t significantly slow things down – the polling done in the sample code, once every 250 ms, spends about 99% of its time sleeping.

However, polling becomes somewhat less quaint when you’ve got a lot of digital inputs or sensors to keep track of, so I’m still looking for an interrupt driven solution for GPIO pins.  If anyone has that working from Python on a Beaglebone, please let me know.

Wrapping Up

These are still early days for the Beaglebone, and some of the basic building blocks for hobbyists are yet to fall in place.  No big surprise, of course: when the Arduino first appeared (back in the day, naught-5 I believe it was) it lacked libraries for things like LCDs and I2C sensors, but over the next few years those were written and became standardized.

But I’ve noticed quite a few interesting projects over the last month pushing out the boundaries of what can be done with userspace applications, like the aforementioned PyBBIO project,  and this bonescript project that writes to a Nokia 5110 display.

The kernel continues to leap ahead with new releases every few weeks: kernel maven Koen Kooi recently posted a proposed roadmap for what lies ahead.

The Beaglebone has also popping up on some popular hobbyist sites, like Make Magazine and Hack-A-Day.

It’s quite fun to watch a platform grow from the ground up!

Ooops!

It turns out that this sleight-of-hand is the work, aptly enough, of a package named Connman.

This newfangled connection manager is, in some ways, a good fit for the Beaglebone, since it was designed to run on memory-constrained embedded Linux systems. It was originally developed for use on 2 Linux platforms that have struggled, Meego and Moblin, but we won’t hold that against it.

However, Connman presents one big problem for Beaglebone users: it’s rather difficult to configure from the command line.

It doesn’t come with a command line configuration tool, but it does provide some well documented APIs that command line applications can use. As such, the best command line interface right now can be found in a package intended to test that the APIs are working correctly: connman-tests.

To install the package:

opkg install connman-tests

This will install a set of Python scripts in /usr/lib/connman/test.

To check your current configuration:

cd /usr/lib/connman/test/
./get-services

The output should look like the following:

[ /net/connman/service/ethernet_405fc276b749_cable ]
 IPv6.Configuration = { Method=auto Privacy=disabled }
 AutoConnect = false
 Proxy.Configuration = { }
 Name = Wired
 Nameservers = [ 206.47.244.104 206.47.199.155 ]
 Provider = { }
 Favorite = true
 Domains.Configuration = [ ]
 State = online
 Proxy = { Method=direct }
 Nameservers.Configuration = [ ]
 LoginRequired = 0
 IPv6 = { }
 Domains = [ lan ]
 Ethernet = { Interface=eth0 MTU=1500 Method=auto 
Address=xx:xx:xx:xx:xx:xx }
 Security = [ ]
 IPv4.Configuration = { Method=dhcp }
 Type = ethernet
 Immutable = false
 IPv4 = { Netmask=255.255.255.0 Gateway=192.168.1.1 
Method=dhcp Address=192.168.1.161 }

The important thing to note here is the service ID at the top of the output, in my case  ethernet_405fc276b749_cable.  (Dumb name for an ethernet cable, if you ask me.)

You can also get the DNS nameserver and gateway IP addresses from this output, if you don’t already know them.

To change the configuration, you use 2 other scripts, set-ipv4-method and set-nameservers.

The syntax for set-ipv4-method is:

./set-ipv4-method <service> [off|dhcp|manual <address> [netmask] [gateway]]

The service parm is that long string that appears at the top of the output from the get-services script.

So, to set the Beaglebone to use a static IP address of 192.168.1.2, with a gateway of 192.168.1.1, I entered:

./set-ipv4-method ethernet_405fc276b749_cable manual 
192.168.1.2 255.255.255.0 192.168.1.1

To set the DNS nameservers, use set-nameservers.  The syntax is:

./set-nameservers <service> [nameserver*]

In my case, I entered

./set-nameservers ethernet_405fc276b749_cable 206.47.244.104 
206.47.199.155

That’s it: after entering those 2 commands, you’ll be running with the new network settings, no reboot required. (Though, if you plan to blog about it, a reboot is definitely recommended!)

In this article I’m going to cover the basics of using the Beaglebone in a different but complementary role: as a network-connected Linux computer.

If you’re not already familiar with Linux you might be tempted to ignore this aspect of the Beaglebone — once you’ve figured out how to copy programs onto the Beaglebone and run them,  you’re good to go.  However,  by doing some basic Linux configuration you can open up a lot of extra functionality, such as editing files on the Beaglebone directly from your desktop PC, or making the Beaglebone command line more user friendly.

I’m going to focus on the Angstrom Linux distribution that is included in the microSD card packaged with each Beaglebone. Angstrom is not as widely used as other flavours of Linux, like Ubuntu or Fedora. This can be a frustrating to newcomers, since you’re less likely to figure out how to do things by Googling for the answer. However, Angstrom is well suited to a memory and storage-constrained platform like the Beaglebone, being bloat-free and able to squeeze out more performance from the ARM processor.

I should also mention off the top that I’m not going to show you how to run a spreadsheet, browser or any other GUI applications on the Beaglebone. That is possible, even without a cape that has a video port (by using VNC), but I think you’re likely to be disappointed. The Beaglebone’s memory and CPU constraints will cause a GUI system to be annoyingly slugglish . Think of it more as an Arduino on steroids, not a poor man’s PC.

Configuring a terminal on Windows

(Sorry Mac and Linux users – the first couple of sections are Windows-centric.)

Whether you connect to the Beaglebone via USB or over the network using SSH, the best terminal software to use on Windows is PuTTY.

You might be scared off after a glimpse of PuTTY’s plain Jane website – it looks like a relic from the early days of the Internet. Trust me, though: PuTTY is the way to go. Unlike other Windows terminal programs, it “gets” Linux. It may not be the best all-around terminal program, but it’s the best Windows client for a Linux server.

PuTTY is bristling with options, but for the most part the default settings are fine.  When the Beaglebone is connected via USB, select Serial, fill in the COM port ID, and change the Speed to 115200.  When connecting over the network, select SSH and fill in the IP address.  You should also fill in a  name in the Saved Sessions textbox and click Save.

With the default settings, you’ll find that some keys don’t work as expected.  For example, neither Home nor End will work when editing the command line.  To fix this, under Connection –> Data, change the Terminal-type from the default of xterm to linux.

While you are in this window, you can also fill in a default username for logins. (Which, come to think of it, must be “root”, since you haven’t read the “Creating a user” section yet).

One other less-than-obvious thing about PuTTY is the way it handles copy-and-paste: Ctrl-C and Ctrl-V won’t work.  Instead, any text you highlight on the terminal is automatically copied to the Windows clipboard, and Shift-Insert is the shortcut for Paste.

Transferring and editing files from Windows

The other important piece of software you should install on Windows is something to  transfer files to the Beaglebone. If you aren’t yet comfortable with using Linux command line editors, then this tool is vital, since you are going to need to edit some files below.

For this, you’ll need to access the Beaglebone over the network (i.e. not a COM port), and use a Windows program called WinSCP.  The only default setting you’ll have to change is the File Protocol: the Angstrom demo image’s SSH server, Dropbear, doesn’t support SFTP.

You can use WinSCP to transfer files back and forth between Windows and the Beaglebone but, more importantly, you can also use it to edit files directly on the Beaglebone, safely from the comfort of your Windows desktop.

I know, I know, eventually you’ll want to cut the Windows apronstrings and learn to Esc-Alt-whatever in a command line editor. But having GUI training wheels will save you a lot of frustration as you get started

Creating a user

Angstrom Linux initially contains just a root user. I suspect a lot of people like it that way – root is God, so why bother running as a mere mortal instead? I would actually agree: since you’re almost certainly using it as a single user development platform, go crazy, have fun, be root.

However, if your Beaglebone is going to be accessible from a network, and especially if it’s going to be accessible over the Internet, disabling the root login is a wise security precaution: having to guess the user-ID makes the Beaglebone much harder to crack.

(Needless to say, if you aren’t going to disable root logins, then for-the-love-of-God give the root user-ID a password!)

My own approach is to login with my user-ID, then switch to root when needed (generally about 10 seconds after logging in, admittedly).

To create a new user-ID, johndoe:

beaglebone:~#useradd johndoe
beaglebone:~# passwd johndoe
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully

To give the root user a password:

beaglebone:~# passwd
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully

Switching to root

So you’ve logged in as an ordinary user, and have quickly discovered that you need to be root to actually do anything, including pretty much all of the steps below. To switch to root

beaglebone:~$ su

The password you enter is the root password, not the user’s. This ain’t Ubuntu, son.

If you find that you prefer Ubuntu’s way of doing things, you can install the sudo package:

beaglebone:~# opkg install sudo

I think this is well worth doing, if only for the comedy element.  sudo is the most uptight piece of software that I’ve come across.   The first time you use sudo, you’ll get a bossy warning:

We trust you have received the usual lecture from the local System
Administrator. It usually boils down to these three things:
    #1) Respect the privacy of others.
    #2) Think before you type.
    #3) With great power comes great responsibility.

After you enter your password, sudo will shriek and run off to tell on you:

johndoe is not in the sudoers file.  This incident will be reported.

To fix this, you don’t directly edit the /etc/sudoers file — oh no, that would be too easy.  Instead, you (logged in as root, of course) run visudoer, which forces you to grapple with the notorious vi editor.

If you haven’t lost your nerve yet, you can add your user-ID to the User Privilege section:

##
## User privilege specification
##
root ALL=(ALL) ALL
johndoe ALL=(ALL) ALL

I suspect that the creator of sudo would have a conniption if he saw you make such a crude change (the rules governing sudoer configuration are rather elaborate), but what do you have to lose: your actions have already been reported.

Disabling root SSH login

This step is optional, especially if your Beaglebone isn’t accessible from the Internet.  In fact, if you’re using WinSCP to edit system files then don’t disable the root login – you can’t switch to root from within WinSCP.

If you still want to do it, you can disable root login by specifying the “-w” command line parm when running the SSH server, Dropbear.

Ordinarily, Dropbear configuration is done by setting options in file /etc/default/dropbear.  This used to work in Angstrom.  However, they’ve recently switched to launching Dropbear in a way that doesn’t use any configuration file.

As far as I know, the only way to change the dropbear configuration now is to edit the ExecStart line in a well-hidden file: /lib/systemd/system/dropbear@.service:

beaglebone:/lib/systemd/system$ cat dropbear@.service
[Unit]
Description=SSH Per-Connection Server
Requires=dropbearkey.service
After=syslog.target dropbearkey.service
[Service]
ExecStart=-/usr/sbin/dropbear -i -r /etc/dropbear/dropbear_rsa_host_key -p 22 -w
ExecReload=/bin/kill -HUP $MAINPID
StandardInput=socket

Note the “-w” at the end of the ExecStart line – I added that to disable the root login.

To restart Dropbear, you still reference the old (but ultimately unused) init.d script:

/etc/init.d/dropbear restart

Changing the host name

This is purely optional, unless you have multiple Beaglebones, but it’s an easy way to personalize things:

Edit /etc/hostname and change beaglebone to your new host name.

Then, edit /etc/hosts and make the same change there. Leave the rest of the file as is: it should look something like this when are done, with yourhostname being replaced with – yeah, you got it:

cat /etc/hosts
127.0.0.1 localhost.localdomain localhost
127.0.0.1 yourhostname

Your command line prompt won’t display your shiny new device name until you reboot:

shutdown –r now

Using a static IP address

Updated 2/6/12: The instructions in this section don’t work when using Connman to handle network connections (which is the default for Angstrom Linux on the Beaglebone) — it will revert to using DHCP after rebooting.  See Beaglebone Linux 101: Assigning a Static IP Address with Connman)

This step is also optional, if you have a DHCP server and don’t mind using its choice of IP address. Unlike the Beagleboard XM, the Ethernet adapter on the Beaglebone always uses the same MAC address, which means that the IP address assigned by the DHCP server won’t change each time you boot.

Setting a static IP  address requires editing /etc/network/interfaces.  The default version of this file in the Angstrom demo image looks like this:

beaglebone:~$ cat /etc/network/interfaces
# /etc/network/interfaces -- configuration file for ifup(8), ifdown(8)
# The loopback interface
auto lo
iface lo inet loopback
# Wireless interfaces
iface wlan0 inet dhcp
wireless_mode managed
wireless_essid any
wpa-driver wext
wpa-conf /etc/wpa_supplicant.conf
iface atml0 inet dhcp
# Wired or wireless interfaces
auto eth0
iface eth0 inet dhcp
iface eth1 inet dhcp
# Ethernet/RNDIS gadget (g_ether)
# ... or on host side, usbnet and random hwaddr
iface usb0 inet static
address 192.168.7.2
netmask 255.255.255.0
network 192.168.7.0
gateway 192.168.7.1
# Bluetooth networking
iface bnep0 inet dhcp

You need to replace the “iface eth0 inet dhcp” line with hard-coded settings for your IP address, gateway, and DNS servers. (Oh, and you might want to do it while connected to the Beaglebone via the USB cable, rather than Ethernet, in case you mess things up).

Comment out the ”iface eth0 inet dhcp” line and add new lines with the correct IP addresses in the address, gateway, and dns-nameservers address (don’t just copy mine – that’s cheating):

#iface eth0 inet dhcp
iface eth0 inet static
address 192.168.1.2
netmask 255.255.255.0
network 192.168.1.0
broadcast 192.168.1.255
gateway 192.168.1.1
dns-nameservers 192.168.1.1

To test your settings, cross your fingers and enter:

/etc/init.d/networking restart

Then check to see that you have the new IP address:

ifconfig eth0

and gateway…

netstat –nr

and DNS server:

 
cat/etc/resolv.conf

Ha, were you worried? Me neither!

Setting the time zone

You probably noticed shortly after connecting your Beaglebone to the Internet that it  automatically figured out the date and time, sort of: everything except the time zone.

The demo image includes a “cron” job that uses NTP to get the correct date and time. You can see this by entering:

crontab -l
30 * * * * /usr/bin/ntpdate -b -s -u pool.ntp.org

Every 30 minutes, it will run the ntpdate command to update the system date and time.

The system determines the time zone using a file called /etc/localtime. Don’t try editing this file – instead, you point it at the correct time zone under /usr/share/zoneinfo. To see what’s available:

 ls -lr /usr/share/zoneinfo/

These files in the zoneinfo directory are installed by package tzdata.

Don’t feel bad if they don’t include your town – they missed mine too. However, you should be able to find your time zone, or another city in it. For me, I set the timezone by entering:

rm /etc/localtime
ln -s /usr/share/zoneinfo/America/New_York /etc/localtime

Note that “ln -s” creates a pointer to an existing file – make sure you get the parms in the right order.

Reboot to update the system time.

Updating packages

If you haven’t updated the Linux packages on your Beaglebone before, and you’re using one of the early Angstrom images (the original 11-16-11 image, or the 12-26-11 image) you’re in for a treat. A movie, perhaps, or dinner, or a long romantic walk on the moonlight. As long as it takes an hour or two, cause the first package update is sloooooow.

I don’t know why, but there has been a steady stream of package updates released since the Beaglebone came out. Usually, Angstrom is a “sleepier” distribution – just the occasional bug fix or security update. I’m guessing that package development for the Beaglebone is more active because the platform is new, and package updates will become less frequent over time.

The basics of updating packages is to remember 2 commands:

Opkg update
Opkg upgrade

The first updates your local copy of the list of available packages, and the second does the updating. It’s all automated – you shouldn’t see any prompts, so no need to stand around watching it go… and go ….

.. phew, done! After the first batch of updates, it’s a good idea to reboot.

After awhile, the “opkg upgrade” will begin to mutter complaints when it’s done – stuff like:

Collected errors:
* check_data_file_clashes: Package shadow wants to install file /etc/login.defs
But that file is already provided by package * shadow-sysroot
* check_data_file_clashes: Package shadow wants to install file /etc/login.defs
But that file is already provided by package * shadow-sysroot

Yada yada yada.  Whatever.

Honestly, you generally don’t have to do anything to fix the errors – as other packages get updated, the problems get fixed. If they don’t, there is always Google.

Installing packages

The demo image comes with a lot of software, but there are thousands of other packages available. To see everything that is out there, you can enter:

opkg list

That’s a lot of packages! If you have an idea of what you are looking for, use grep to filter the results:

Opkg list | grep "python"

To install the package

Opkg install <packagename>

If you can’t find what you want that way, try the online Angstrom package browser. It has a more convenient interface, and it’s possible that the package you’re looking for isn’t listed by opkg but can be found on the web site (in the dreaded “unstable” branch – scary!).

For example, my preferred command line editor is Emacs, but that doesn’t appear in the output of “opkg list”.  It is, however, listed in the package browser.

The “available versions” section lists 2 options:

The 2 available versions are for the “Angstrom 2011.03″ release, and the Beaglebone is running a more recent release, currently Angstrom 2012.01.  That’s why “opkg list” didn’t include emacs.

I don’t know why emacs isn’t made available in the new release — it could be lack of popularity, or a lower priority for conversion and testing, or a horrendous incompatibility with other packages.  However, since emacs is a user app that few other packages make use of, a horrendous incompatibility seems unlikely.  (And I’ve been running emacs on the Beaglebone for several weeks with no problems).

The Beaglebone is compatible with armv7a packages, so when that platform is available you should select it.  (Packages compiled for earlier versions of ARM processors will generally also run on the Beaglebone, but more slowly)

You can just click on the link to download it, and copy the package over via WinSCP, or use wget to download it directly to the Beaglebone:

 wget http://www.angstrom-distribution.org/feeds/unstable/ipk/glibc/armv7a/base/emacs_22.3-r1.6_armv7a.ipk

To install it, just specify the filename instead of the package name:

opkg install emacs_22.3-r1.6_armv7a.ipk

You’ll likely find that it complains about a missing dependency file, liblockfile:

Installing emacs (22.3-r1.6) to root...
Collected errors:
 * satisfy_dependencies_for: Cannot satisfy the following dependencies for emacs:
 * liblockfile (>= 1.06) *
 * opkg_install_cmd: Cannot install package emacs.

Yada yada yada.  Actually, this one we can fix.

The package browser web page for emacs, above, lists liblockfile as a dependency.  You can click on the link to open up the liblockfile page and download it from there, or enter the following to download the dependency and install both packages:

wget http://www.angstrom-distribution.org/feeds/2011.03/ipk/glibc/armv7a/base/liblockfile_1.06-r1.6_armv7a.ipk
opkg install liblockfile_1.06-r1.6_armv7a.ipk emacs_22.3-r1.6_armv7a.ipk

Other useful opkg commands

To remove a package

opkg remove <packagename>

To rip a package from the grasp of a protesting opkg (generally because you intend to replace the package with one that provides the same files):

opkg remove <packagename> --force-removal-of-dependent-packages

To get more information about a package:

opkg info packagename

To get a list of files that are installed by the package:

opkg files packagename

(Which only works after you’ve already installed the package - so much for look before you leap!)

To find the package that installed a specific file:

opkg search '<path_to_file>'

e.g.

opkg search '/bin/ps.procps'
procps - 3.2.8-r4

The search function supports wildcards:

opkg search '*bash*'

Automating package updates

There are some people, who we’ll call “sissies”, who would argue that automating package updates is dangerous and irresponsible, since the updates might fail and you don’t want to leave your system in an unstable state.

Others, who we’ll call “real men”, think that the package update process is reliable enough that it rarely requires manual intervention. And, besides, you can always check the logs to detect any problems. It’s not like you’re going to forget to check the logs, right?

Personally, I’m a sissy. I’m also forgetful, so I’ve automated opkg anyway. Needless to say, I rarely bother to look at the output logs. (I know what I’ll find.. “Collected errors: yada yada yada”. Whatever.)

If you’re a real man, you can add a line to the crontab to automatically update your system.

[2/2/12: the following script was updated to add error handling]

First, create a script to run.  I use the following:

#!/bin/sh
# runopkg.sh
# Update packages and append output to log file
/usr/bin/opkg update
# opkg update returns 0 if OK, 1 if error
if [ $? = 0 ]; then
    /usr/bin/opkg upgrade &>> /var/log/opkgupgrade.log
    echo "opkg complete rc $?  $(date)" >> /var/log/opkgupgrade.log
else
    echo "ERROR: opkg update returned $?" >> /var/log/opkgupgrade.log
fi

You can download this file from my site:

beaglebone:~# wget http://www.gigamegablog.com/docs/runopkg.sh

…make it executable…

beaglebone:~# chmod u+x runopkg.sh

…then add this script to the list of scheduled cron tasks:

beaglebone:~# crontab -e
30 * * * * /usr/bin/ntpdate -b -s -u pool.ntp.org
33 3 * * * /home/root/runopkg.sh

By default, the “crontab -e” command invokes the vi editor, which you’ll either love or hate.  Probably hate.

If you stored runopkg.sh in a directory other than the root home folder, be sure to enter the correct path in the crontab line.

The example above runs the update process every day at 3:33 am, and appends both the info and error messages to a log file. It checks the return code after running opkg update. Sometimes it fails to connect to one of the repositories, and it is safest not to do an upgrade with an incomplete list of updates.

Customizing the command line

Angstrom provides a standard Bash command line shell without any customizations: no .profile or .bashrc file.

Everybody’s got their own idea of how to make Bash more useful, but here are some common customizations to get you started.

First, create a file named .profile in  your home directory with the following contents:

# ~/.profile: executed by Bourne-compatible login shells.
if [ -f ~/.bashrc ]; then
 . ~/.bashrc
fi
# path set by /etc/profile
# export PATH
mesg n

If you like, you can download this file directly from my site. Make sure you store it in your home folder .

beaglebone:~# wget http://www.gigamegablog.com/docs/.profile

This is an extremely plain .profile which mainly has one purpose: to activate the .bashrc file.

Next, create a file called .bashrc in your home directory with the following contents:

# ~/.bashrc: executed by bash(1) for non-login shells.
export PS1='\h:\w\$ '
umask 022
# You may uncomment the following lines if you want `ls' to be colorized:
export LS_OPTIONS='--color=auto'
# eval `dircolors`
alias ls='ls $LS_OPTIONS'
alias ll='ls $LS_OPTIONS -l'
alias l='ls $LS_OPTIONS -lA'

# Some more alias to avoid making mistakes:
alias rm='rm -i'
alias cp='cp -i'
alias mv='mv -i'
# shell options
# autocorrect cd commands
shopt -s cdspell
# disable Ctrl-D to logout
set -o ignoreeof
# extended pattern matching
shopt -s extglob

This file can be downloaded from my site – it should be stored in your home folder:

beaglebone:~# wget http://www.gigamegablog.com/docs/.bashrc

This does the following:

• shortens the command prompt to just your hostname and the current directory
• changes the default permissions for new files you create so that they are writable by you, and just readable for everyone else
• turns on colors for your “ls” output
• creates a few shortcuts for common ls options (ll is the most useful, I think)
• adds the “-i” parm to the copy, move and delete commands, which prompts you for confirmation when you are about to delete or overwrite a file
• automatically fixes some typos in directory names
• prevents Ctrl-D from dropping your session
• enables extra wildcards for matching files and directories

By the way, when switching from a regular user to root using the su command, you need to include a hyphen to ensure that the root .profile and .bashrc are used:

su -

Windows networking

By now, you’re hopefully starting to look upon your Beaglebone with respect and admiration. You are also probably sick of WinSCP and/or command line editors. Why not welcome your Beaglebone into your Windows network and give it equal standing to your other PCs?

For this, you’ll need to install Samba.

opkg install samba

The correct configuration of Samba is actually quite complicated, or so I would assume since there is an entire book on the topic . I haven’t actually read it, so instead I installed a browser-based configuration utility named Swat:

opkg install xinetd swat

The xinetd utility is the standard way of invoking Swat and many other services that are accessed over the network.  It doesn’t start the service until it is accessed, which is quite helpful on a memory constrained platform like the Beaglebone.

The services are configured by entries in /etc/xinetd.conf or files in /etc/xinet.d, but unfortunately the Swat package currently doesn’t update either.  So, create a file at /etc/xinetd.d/swat, and paste the following into it:

service swat
{
   disable = no
   port = 901
   socket_type = stream
   wait = no
   # only_from = localhost
   user = root
   server = /usr/sbin/swat
   log_on_failure += USERID
}

Note that this configuration uses a port number of 901, allows access to other PCs on the network, and specifies that root is allowed to login.

After changing the xinetd.conf file, you need to restart xinetd:

/etc/init.d/xinetd restart

You should now be able to open the following address in a browser on another PC: http://<your-beaglebone-ipaddress>:901

Login as root at the prompt.

The first thing you’ll want to do is add a user to Samba — Samba doesn’t automatically use the same user-IDs and passwords as Linux.  Ideally, you should add a user that has the same user-ID as a Linux user and Windows user, and the same password as the Windows user – you’ll have fewer problems with permissions that way.

Go to the Swat password page and create a user. The interface isn’t terribly intuitive: fill in the user name and password in the Server Password Management area, then click then “Add New User” button.  You’ll get a subtle confirmation that the user was added, but it doesn’t display a list of users.

Next, click on Shares and add a share for your user’s home directory.

This step is advisable since, if there isn’t at least one share that your Windows user-ID is allowed to access, Samba/Windows will keep prompting for your user-ID and password.  If it’s the first time you are accessing a Samba share, you won’t know the cause of the problem: the user-ID, the password, or the share.  So, ensure you have access to something by explicitly sharing your user’s home directory.

The user interface on the Shares page isn’t very intuitive either: you need to fill in the textbox next to the Create Share button, then click the button

Note that, by default, new shares are read-only and are not “available”. (Grrrr.)  So, you’ll need to manually change the “Available” setting and Read-only setting then click the Commit Changes button.

(When sharing directories other than your home directory, you may want to leave the Read-only setting on.  If your user-ID doesn’t have write permissions to the underlying Linux directory, don’t try to make it a writeable share.  It won’t work.)

I’d also suggest you go to the Global page and change the workgroup to whatever your Windows PC uses – this makes your Beaglebone easily discovered by Windows.

After saving your changes you shouldn’t have to manually restart Samba, since it continually scans for configuration changes.  However, I often find that a restart is necessary to get your changes to be recognized by Windows:

/etc/init.d/samba restart

Now, Windows Explorer should be able to see your Beaglebone in your network, with some shares underneath.

If you are prompted for a user-ID and password, use the one you entered into Swat’s password page.  If Windows prompts for a new user-ID and password when accessing a share or file, remember that the Linux permissions come into play – try changing the Linux  directory permissions to give write access to non-root users.

Wrapping Up

There’s been some debate in the Beagleboard Google Group about whether it makes sense to have a separate group for the Beaglebone.

IMHO, no.  While the Beaglebone is quite different as an electronics hobbyist platform, it’s almost completely identical to the Beagleboard when it comes to Linux configuration.  All of the steps I covered in this article also apply to the Beagleboard.

So, when looking for Linux tips and solutions, don’t ignore postings targeted at the Beagleboard.

Furthermore, while Angstrom has its differences from other Linux distributions, the most commonly used software is the same or very similar.  Dropbear is largely the same as OpenSSH, Busybox is largely the same as the core GNU utilities, and Angstrom Bash is Bash.  Don’t be discouraged by the lack of documentation on Angstrom or some its utilities.  There’s a wealth of information out there on SSH, GNU and Bash, and you’ll find that most of it applies to Angstrom.

The stuff that doesn’t apply? Ignore it.  Wouldn’t you rather be coding than reading, anyway?

[Update May 5: In kernel version 3.2.14, the file system path for the analog pin readings was changed from /sys/devices/platform/tsc to /sys/devices/platform/omap/tsc]

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):

[Update May 5: In kernel version 3.2.14, the path to the analog pins was changed slightly, from /sys/devices/platform/tsc to /sys/devices/platform/omap/tsc.  The following examples use the original path]

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 12-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-pyserial. To install it:

root@beaglebone:~# opkg install python-pyserial

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.

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?

Nimbits itself was recently updated to version 3.3, and the its web site has been reorganized to make all of the documentation easy to find.  If you are new to Nimbits, or haven’t seen it for a while, check it out!

In this article, I’d like to explore parts of the Javascript code in the gadget, and describe how they interface with the Pachube API.

Viewing the Source Code

As with any iGoogle Gadget, the source code can be viewed by clicking the “View source” link in the bottom right of the gadget’s iGoogle Gadget Directory page – my gadget’s page is here.

However, this will only show you the XML definition for the gadget, since I’ve put the Javascript in a separate file.  My gadget has 2 different views defined in the XML file, normal and “canvas” (i.e. maximized), as you can see at the bottom of the XML file.  Using a separate Javascript file allows the 2 views to use the same code.  Here are direct links to the XML and Javascript files.

• XML: http://www.gigamegablog.com/gadgets/gm-pachube.xml
• Javascript: http://www.gigamegablog.com/gadgets/gm-pachube.js.  (It’s OK to click on it.   Since this Javascript can’t execute outside of Google’s gadget container, your browser will just display the source code instead of running it.  Or, you can just right-click the link and save it as a file, you big baby. )

The Pachube API

Pachube’s API documentation is quite good overall, but it can be a little difficult to find the details for a particular feature.

The graphing API I’m using, for example, is in the “Read datastream – GET  v2/feeds/<feed_id>/datastreams/<datastream_id>” section.  It’s just barely there, actually – a passing reference to the all-important PNG parameter, along with a table of parameters you can pass to the API.  (A better way to learn the graphing API is to use Pachube’s Graph Builder – see the next section).

There are a lot of options for setting the time range of a graph, including some that my gadget doesn’t support, such as a specific end date.  These options are described in the “Historical Queries” section tucked away at the end of that documentation page.

To get a list of datastreams in a feed, I use the “Read feed” API, described here.  As you can see from the JSON example in that section, this is a very handy API that returns a lot of information about the feed and each datastream.

An API key must be passed with most API calls, even when accessing Public feeds.     The mechanism for passing the key is described on a separate page, the API Overview.  That page also describes the timezone parameter.  You’ll find more information on the API key and time zones later in this post.

Pachube Graph Builder

The best way to learn the API syntax for generating a graph is Pachube’s Graph Builder.  To display it, go to your Feed’s page on Pachube’s web site, then click on the gear icon in the lower right of the graph for a datastream, as shown below.

Launching the Graph Builder

The Graph Builder page allows you to interactively try out various graph parameters, then copy a URL that calls the API to generate that graph.

Pachube Graph Builder

Pachube Graph API

The URL that you’ll get from the Graph Builder will look something like this:

https://api.pachube.com/v2/feeds/37080/datastreams/JadePlant.png?
    width=500&height=300&colour=%238024f1&duration=3hours 
   &title=Jade Plant Moisture&show_axis_labels=true &detailed_grid=true
   &timezone=Eastern Time (US & Canada)

All Pachube API URLs have the same basic layout, following the REST standard:

• https://api.pachube.com/v2 – All API URLs start with this.  (You can use the non-secure http:// prefix if your coding platform doesn’t support https, such as an Arduino.)
  The V2 refers to Version 2 of the API.  Version 1, which uses a different syntax, is “deprecated” (i.e. still supported, but use is discouraged).  Some of the examples you’ll find on the Web use the V1 API: if there is one /v2 in the URL, it’s a version 1 call.
• feeds/37080  - All API URLs for a specific feed will identify the feed # this way.
• Datastreams/JadePlant.png – All API URLs which deal with a specific datastream will identify it using its ID field (in this case, “JadePlant”).  The “.png” part is what tells the API that you want a graph.  If you replace that with “.xml”, you’ll get back XML data about your datastream instead.
• ?<parms> – The parameters that follow the question mark are specific to the API call you are making.
  Pachube’s API is pretty easy-going about these parameters: if you pass ones that don’t apply to the API call, or even ones that don’t exist at all, the API will just ignore them.
  If you’re familiar with URLs, you might have noticed that the above URL example (copied from the Graph Builder) contains an invalid parameter: the &timezone parameter contains spaces and an ampersand that need to be properly “escaped” when including in a URL.  The API doesn’t tell you this, it just ignores the timezone parameter.  (And, as a result, the X axis of the graph shows UTC times, the default, rather than EST times).

API Keys

I have to admit that I don’t have a firm grasp on which APIs and feeds require authentication.  I’m tempted to just write “always pass an API key – it can’t hurt”.  But that’s way too simple for this blog, so here’s my best guess explanation of how it works…

If you tried pasting URLs from the Graph Builder into your browser, you probably noticed that no login was required, and no API key is being passed.  As far as I know, an API key is never required for a graph of a public datastream.

However, the other API used by the gadget, which retrieves a list of datastreams for a specified feed, does require authentication, even if the feed is public.  If you have a neglected browser from which you’ve never logged into Pachube (that blue E icon will probably do), try accessing  the following URL

http://api.pachube.com/v2/feeds/37080.json? 
   timezone=Eastern%20Time%20%28US%20%26%20Canada%29

You should get a pop-up authentication prompt.

Private feeds always require authentication, even for a graph.  For example, the following should definitely display an authentication prompt, unless you are a nefarious hacker.

http://api.pachube.com/v2/feeds/39460.json? 
   timezone=Eastern%20Time%20%28US%20%26%20Canada%29

If your application were to try doing the same thing, it would get a “404 – Authentication Error”.  When trying to graph a private datastream without an API key, the application gets back a nice “Server error” graphic, instead

To avoid that, the code needs to pass an API key.  The gadget doesn’t ask you to fill in an API key of your own: instead, I’ve hard-coded one that has read access to public feeds, but update access to nothing (including my own feeds).

The key is passed in an HTML header field, as specified in the Pachube API documentation.  Various programming languages have various methods for setting the contents of the header field – the Google Gadgets approach is described in their documentation, and shown below:

var params = {};
params[gadgets.io.RequestParameters.HEADERS] = {
    "X-PachubeApiKey": "<your API key>"
};

Incidentally, if you’re using the gadget to graph datastreams in a private feed, you might wonder how my API key has access to your private feed.  Relax, it doesn’t.  Through some kind of under-the-covers-cached-browser-authentication-cookie-machination (my words, not Pachube’s), the gadget is allowed to access your private feed on a browser in which you’ve previously logged into Pachube.  I’ve noticed intermittent “authentication failed” errors when using the gadget with my own private feed, presumably when my cached authentication expires (or the cookie-machinations go awry).

Time Zones

According to the API documentation on time zones :

There are two places where you can specify the time zone: in your user profile on the website and via a parameter in an API request.

I think the intention is that your user profile’s timezone setting is automatically used by the API unless overridden, but it currently doesn’t work that way for graphs.  Perhaps that’s a bug that will be fixed at some point, but for now you have to pass the timezone parameter to the graph API call, or the X axis will display UTC times.

I had originally planned to have a “UTC offset” field in the gadget settings, where you would fill in the # of hours difference between your time zone and UTC: for example, -5 for Eastern Standard Time.

However, when testing I noticed something odd: timezone=-5 gave me UTC minus 5 hours, as expected, but timezone=-4 gave me UTC minus 3 hours.

As described in this post in the Pachube Community forum, if you set the timezone parameter to a numeric value, the API will select the first matching entry in Pachube’s (rather eclectic) list of geographic time zone settings.

For example, timezone=-4 is the same as specifying “Atlantic Time (Canada), and timezone=-5 is the same as specifying “Bogota”.  Rather than being dependent on the local customs of Atlanteans and Bogatians, I gave in and included the full list of geographic timezones in the the gadget’s Edit Settings page.  (If you have no idea which one on those time zones you are in, ask Pachube, not me.)

Yes, Virginia, there is a Nuku'alofa

As shown in the Graph Builder section above , another tricky thing to consider when working with timezones is proper encoding of non-URL characters, like spaces and ampersands.  Javascript makes this easy: the gadget’s code for handling the conversion is simply:

// replace And with & (Google's Gadget API hates ampersands)
timeZone = timeZone.replace(" and ", " & ");
// use escape function to encode spaces and ampersands in URL
urlSuffix = "timezone=" + escape(timeZone);

One last pothole to avoid: Google’s Gadget API seems to have a particular distaste for ampersands, however they’re encoded: the dropdown list of timezones wouldn’t display until I took them out.

Getting the List of Datastreams in a Feed

Pachube makes it easy to get the list of datastreams in a feed: just one API call returns a variety of properties, including the timestamp and value of the last datapoint received by each datastream.

The Javascript code for doing this is shown below, most of which is from the gadget’s getDatastreamStatus function:

var urlPrefix = "https://api.pachube.com/v2/";
var urlSuffix = "timezone=" + escape(timeZone);
var url = urlPrefix + "feeds/" + feedID + ".json" + "?" + urlSuffix;
var params = {};

params[gadgets.io.RequestParameters.CONTENT_TYPE] = gadgets.io.ContentType.JSON;
// NOTE - this API key has READ access only
params[gadgets.io.RequestParameters.HEADERS] = {
    "X-PachubeApiKey": "nBGUIT63Onke5-sfOoARTvKvkwl45b85wjz5PKDIZkc"

// refresh data if longer than 5 minutes since last request
makeCachedRequest(url, getDatastreamsResponse, params, 300);

Yes, that’s an actual, genuine API key that I’ve published – my own, in fact.  As mentioned earlier, this one is defanged, limited to read-only access to public feeds.

The “.json” in the URL specifies that the data is to be returned in JSON format: other options are XML and CSV.  Your choice of format depends primarily on the coding platform you’re using.  Google’s Gadget API supports both XML and JSON, but I went with JSON because it is more light-weight (i.e. faster), a consideration if you’re working with a lot of datastreams.  The CSV option is intended for platforms that don’t support XML or JSON, such as an Arduino.

The code for makeCachedRequest is taken directly from Google’s API documentation.  The code allows you to override Google’s default caching algorithm for gadget data, which retrieves updated data from the source (i.e. Pachube in this case) every 60 minutes, regardless of how often the user clicks the browser refresh button.  I’m overriding the interval to be every 5 minutes.

Note that the gadget doesn’t automatically update every 5 minutes: the update only occurs when the user first opens the web page containing the gadget, or clicks the refresh button, or when iGoogle refreshes the gadget.  (iGoogle refreshes each gadget once an hour, if the iGoogle page is in the foreground tab).  As far as I know, your gadget code has no way of forcing a refresh to occur.

The response to the API request is returned to the callback function passed as a parameter to makeCachedRequest, a simplified version of which is:

function getDatastreamsResponse(obj)
{
  if (obj.data === null || typeof obj.data === "undefined")
  {
    // something’s wrong – check the other obj properties, like obj.error and obj.rc
    . . .
  }

  jsonData = obj.data;

  if (!jsonData.datastreams)
  {
    displayErrorMsg("No datastreams found in feed");
    return;
  }

  datastreamList = jsonData.datastreams;
  feedTitle = jsonData.title;
  feedStatus = jsonData.status;
  feedDesc = jsonData.description;

The meat of the response is contained in the .data property of the parm passed to the callback function.  If that property is empty, then an error occurred.  Generally the error information is found in obj.error and/or obj.rc.  The former contains an error message as a raw JSON text string, and the latter contains one of the standard HTTP return codes as listed in Pachube’s documentation.

The data object is bristling with useful information about the feed and datastream.  As shown in the code, I’m getting the feed’s title, status and description from there, as well as a list of datastreams, each of which is itself a JSON object with properties.  The screenshot below shows some of the other properties in this data object as seen in the Google Chrome Javascript console.  For a full list of all of the available properties, see the example in Pachube’s Get Feeds documentation.

Getting the Datastream Graphs

The Javascript which handles the calls to the Graph API, displayGraphs(), basically just pieces together the URL for the Graph API,  as explained in the “Pachube Graph API” section above.

There are a couple of issues handled here that I didn’t describe earlier.

Unbeknownst to the user (wouldn’t want to worry their pretty little heads, would we?), the code scales down the graph if necessary to fit within Pachube’s limit 300K pixels.

var MAX_GRAPH_SIZE = 300000;  // Pachube's maximum graph size, in pixels
. . .
var defaultWidth = 320; // in normal gadget mode, 320 is the recommended width
if (graphHeight * graphWidth > MAX_GRAPH_SIZE)
{
  // set to maximum size that will fit within Pachube's limit
  if (graphWidth > defaultWidth)
  {
    graphWidth = defaultWidth;
  }

  graphHeight = Math.floor(MAX_GRAPH_SIZE / graphWidth);
}

This is done somewhat crudely, basically yanking the graph width back to 320 pixels, then yanking the height down as needed to fit within the 300K.

Also admittedly quite crude is the support for increasing the graph size when the gadget is maximized.

// in canvas mode, double the graph size
if (gadgets.views.getCurrentView().getName() === "CANVAS")
{
  graphHeight *= 2;
  graphWidth *= 2;
  defaultWidth *= 2;
}

I’m a little surprised that most gadgets ignore the maximized setting altogether, just displaying the same content in the same cramped size.  I think the problem is one of “discoverability”, to use a Googley term: the feature is disabled by default, and Google’s documentation on the feature confusingly insists on referring to it as “canvas” mode.

As shown in the API documentation, enabling “canvas” mode is just a matter of pasting some boilerplate XML settings into your gadget, like so:

<Content type="html" view="home">
<![CDATA[
 <div id="content_div"></div>
. . .
<script src="http://www.gigamegablog.com/gadgets/gm-pachube.js" type="text/javascript"></script>
]]>
</Content>
<Content type="html" view="canvas">
<![CDATA[
 <div id="content_div"></div>
. . .
<script src="http://www.gigamegablog.com/gadgets/gm-pachube.js" type="text/javascript"></script>
]]>
</Content>

Perhaps Google would prefer that your gadget take on an entirely new form when maximized, since the XML allows for a separate block of Javascript for canvas mode (the “content_div” section).  I wasn’t that ambitious, so instead I use a script tag to feed the same Javascript code into both the normal and canvas mode XML definitions, then changed the code to check which mode it’s in, as shown in the earlier code sample.

Wrapping It Up

If you’ve read the Programmer’s Show and Tell for my Nimbits gadget, you’ll notice that this time I’ve done much  less ranting about how frustrating Google’s Gadget API is to work with.  The API hasn’t changed, but once you know where the potholes are, the drive is a lot smoother. If you intend to write your own gadget I’d suggest you read my earlier rant/article first, since it points out a lot of those potholes.

I’m still dubious about the future of Google gadgets given Google’s newfound emphasis on monetization and focusing on core products.   The iGoogle Developer Blog hasn’t had any new posts since a May post asking “Did you know we are continuously adding new features” ?  (In fairness, they were referring to the Gadget Dashboard – they stopped adding new features to the gadget API long before May).

Methinks the best browser-based platform for making use of the Pachube API lies elsewhere, perhaps a Google App Engine project like this one. .  The App Engine would give your code a lot more elbow room, and there is so much more to the Pachube API than what I’ve covered here.

I like Pachube — it’s reliable, well-designed, well-documented, and very much open to hobbyists.  They recently did away with paid plans and made all aspects of the site and service free, so I’d encourage you to give them a try. If you need help at getting your data into Pachube, see their Quick Start guide and Tutorials. My article on connecting Tweet-A-Watt to Pachube also contains some tips on getting started, and my article on the FEZ XBee Sensor shows an easy way to post data to Pachube from Python.

Pachube’s site provides a page for each of your feeds, showing a graph of the last 24 hours of readings from each of your datastreams. That’s good if you remember to go look at it, but I’d prefer that my graphs come to me, via a gadget on my iGoogle home page.

Pachube released a Google Gadget some time ago, and I’ve been using it for some time. It works well, but there are a few extra features that I really wanted:
- larger graphs, and the ability to resize the gadget container to see them
- a time axis in local time, rather than UTC
- the ability the set the timespan: 12 hours, 1 week, 1 month, etc.
- a Maximized view that shows the graphs in humongous GigaMegaSize

So, I’ve created a Google Gadget which adds these features, plus a few more.

You can grab the gadget from the Google Gadgets directory.

Settings

Here is a description of the various options available on the Edit Settings dialog.

Feed #: Numeric Pachube Feed ID

Datastreams: To graph all datastreams in the feed, leave this field blank. Otherwise, enter the datastream ID and click the Add button. For example, to add the 2 datastreams below…

…type Cactus, click Add, type CatGrass, click Add. The field should then look like this:

Time Span, Time Span Units – This determines what period of time will be graphed. As shown in the screenshot, the default is 24 hours. Time Span Units can be set to hours, days, weeks or months.

Show Status. If true, each graph will be preceded by a line of text giving the Datastream ID, the last reading and the date and time it was received, as shown in this screenshot.

Detailed Grid. If true, vertical and horizontal grid lines will be displayed, as in the 2 graphs above. If false, only a vertical grid separating each time span unit is displayed, as in the following (GigaMegaSized) graph.

Axis Labels: If true, numeric labels are added to the vertical and horizontal axis indicating the range of values. Note that, depending on the time span, these labels tend to overlap in a smaller graph (and I don’t have any control over the format of the labels). If false, the only labels are the minimum and maximum value of the vertical axis.

Graph Width and Graph Height: Determines the size of each graph, in pixels. When the gadget is maximized, both sizes are automatically doubled. These values are required, and are initially set to a width of 280 and a height of 100.

Gadget Height: Determines the height of the overall gadget, in pixels. If not specified, a default of 200 is used. (The gadget width can’t be set by the code, and varies depending on the browser type and the resolution of the monitor.)

Time zone: Your local time zone. The default is UTC (aka Greenwich Mean Time). This setting affects the timestamp in the Status field, as well as the labels on the horizontal axis of the grid. The rather eclectic collection of names in the dropdown lists was Pachube’s idea, not mine. (Look here if you don’t believe me!)

Wrapping Up

I’d welcome any bug reports or feature requests.

iGoogle’s Gadget framework does a lot of caching sleight-of-hand, so if you find that a change of settings doesn’t appear in the gadget, try refreshing the page. As for features , there are some things I can’t add because they aren’t supported by Pachube’s API yet (multiple datastreams in a graph, for example), but otherwise I’m open to suggestions.

For developers, I plan to write an article in the near future explaining the gadget’s use of the Pachube API.

Like its predecessor, the XBee Sensor is a .Net Micro Framework device, which uses an XBee wireless transceiver to post data to the Internet by way of a Python middleman.

I’m structuring the code to be more flexible, supporting a variety of sensors and logging to a variety of databases.  Personally, I’m using it to measure plant soil moisture, light levels, temperature and humidity, as described in the “Hardware Configuration” section below.

If you decide to use a different mix of sensors (as I’m sure you will), you’ll need to make a small change to the C# code, as shown in the Programmer’s Show and Tell section below.  I’m aiming for a more generic device configuration, where all  sensor devices run exactly the same code, and all sensor configuration is done through Python.

Since a new project gives me an excuse to start playing with new hardware, I’ve also switched from using the Netduino to a rival Micro Net Framework product, the FEZ Panda.

I’m not abandoning the Netduino: my own Netduino continues to perform its duties as a Plant Light Controller, and I’ll do my best to continue to support the Netduino in the XBee Sensor source code.  It’s relatively easy to switch the code between a FEZ and Netduino target.  I’ll point the code changes that are required in the Programmer’s Show and Tell section .

Also, the Python code used in this article is compatible with the Netduino Plant Light controller code from Watching the Watcher, so you can have both a Netduino Plant Light Controller and an XBee sensor reporting data to the Python code if you like, or even just the Netduino.

The FEZ Panda

The FEZ Panda is one of a line of products from GHI Electronics: Fez Mini, Panda, Panda II and Domino.  The Fez Mini is similar to the Netduino Mini — both mimic the form factor and pinout of the Basic Stamp — while the Pandas are similar to the Netduino.  The Domino is a more powerful beast, using a chipset that supports USB Host.

FEZ Panda II

Compared to the Netduino, the Pandas (both versions I and II) have a few advantages that will come in handy when acting as a remote sensor.

1. More pins: 54 digital I/Os, as opposed to the Netduino’s (and Arduino’s) 13, and 3 COM ports to the Netduino’s 2.  More analog pins would have been even better, but the Panda only has 6, same as the other platforms.

2. Native code.  This one is huge: the .Net code can invoke “unmanaged” native code, which has full access to the microprocessor’s capabilities, including microsecond-level timing.  This eliminates the Micro Net Framework’s biggest disadvantage to the Arduino.

3. Ability to store data in flash memory.  The FEZ firmware includes a class that allows .Net code read/write access to 4K of flash memory, analogous to the Arduino’s Flash library.

4. More documentation!  This one might not excite you as much as it does me (whee!), but GHI’s TinyCLR site offers a ton of documentation covering pretty much every feature of the FEZ platform and the underlying Net Micro Framework.  I’d particularly like to point out the Beginner’s Guide to .Net Micro Framework, which I feel is still the best publication of any type covering the MNF, and much of which is also applicable to the Netduino.  A Tutorials section was recently added to the TinyCLR site, which has rapidly expanded to cover a lot of very useful features, again many of them applicable to the Netduino.  (Both the Beginners Guide and the Tutorials section can be found on the TinyCLR Support page).

Back in the Netduino: A Little Help From Its Friends article, I used an Arduino as a helper to the Netduino.  It handled a couple of actions that the Netduino (and Micro Net Framework) couldn’t do: read data from the DHT11 temperature/humidity sensor and saving settings to Flash memory.  The FEZ Panda can actually do both these things itself.    Smarter than the average bear!

By the way, the difference between the Panda and Panda II is that the latter contains a micro SD card socket, and adds female headers for most of the additional digital pins, which are repositioned to be accessible even when an Arduino shield is in place.  I’m using Panda Is (currently being sold off by GHI at the ridiculously low price of $15), but everything that I’m doing in this project will also work on a Panda II.   The code will work almost unchanged – all you have to do is remove the Project Reference to FEZPanda_… and replace it with FezPandaII_…, as shown in the screenshot.

Selecting Panda II Assembly

Hardware Configuration

At this point, the XBee Sensor project is geared towards supporting analog sensors plus one particular digital sensor, the DHT11/DHT22 temperature and humidity sensor. I’m using the analog ports as moisture and light sensors, but any analog sensor that can run on 3.3V should work without code changes.

The XBee Sensors are intended to be used without displays, but when first configuring them it’s handy to connect an LCD to see what they’re doing (or failing to do). So, I added an optional “Debug LCD”, which displays the current sensor readings, as well as any Exceptions or other error messages.

I’ve written the code so that, if the LCD isn’t connected, it shrugs and keeps going.  However, if your device seems to behave erratically when the LCD is disconnected, you can disable use of the LCD by removing the DEBUG_LCD compiler flag (as shown in the Programmer’s Show And Tell section below).

You can also select the type of LCD using a compiler flag.  LCD support is basically the same as in the Netduino Plant Light Controller code, with the addition of the Adafruit i2c / SPI character LCD backpack — more details on that support are also in the Programmer’s Show And Tell section.

If you are using an LCD, you’ll probably want to add a button to D7, to toggle the backlight on or off.

Soil Moisture Sensors

The soil moisture sensors use the same approach as in the Garduino project.  I built mine from

• A pair of galvanized nails.  I think any nails will do, as long as they’re galvanized and big-assed, I’m using Tree Island Gold 4” 20d Hot Dip Galvanized nails
• 2 lengths of 20 AWG wire, long enough to go from the plant pot to the Panda
• a 10K resistor, connecting the analog in to ground

As you can see from the photo, one end of each wire is soldered to a nail, then covered with heat shrink tubing to keep it attached tight.  The other end of the wires connect to the Panda.  One wire connects directly to 3.3V, and the other other wire is split: it connects directly to an analog port, then connects through a 10K resistor to ground.

Moisture Sensor Wiring - Click to Enlarge

I found that the screw connectors on the Adafruit Wing Protoboard is ideal for this setup, since the screw connectors firmly hold the wires in place , and the protoboard layout makes it easy to add the resistor-to-ground connection.  The Adafruit board also provides 4 spare screw connectors, in the upper-right of the above photo – I used mine to provide the extra 3.3V connections required for this project.

The Garduino actually uses 5V, but 3.3V works just as well for this purpose, with similar calibration.  My oldest moisture sensor has been in service for almost 3 months now, with no apparent degradation of the nails or weird behaviour in the voltage readings.  (No electrocuted plants either – the 10K resistor ensures that the current is too low to hurt either plants or humans).

The light sensor is a garden variety (nyuk nyuk) cadium sensor that uses the exact same circuit as the moisture sensors: one wire connected to 3.3V, and the other split between an analog pin and ground through a 10K resistor.

Here is what the XBee Sensor looks like with all its accoutrements:

FEZ XBee Sensor - Up and Running

FEZ XBee Sensor - The Next Generation

Temperature/Humidity Sensor

I have the DHT11 from the A Little Help From Its Friends article connected to one of my XBee Sensor configurations, and the DHT11′s big brother, the DHT22, connected to another.

The code used to read from the 2 devices is identical – the only difference is how the .Net code parses the data to retrieve the temperature and humidity values.

As mentioned earlier, the Panda’s support for native “RLP” (Runtime Loadable Procedures) code means that it can handle the microsecond-level timing required by the DH22 and DHT11.

The RLP code that I’m using comes from this project on GHI’s TinyCLR site.  The description of the project only mentions the DHT11, but the RLP code works for the DHT22 too.

I’ve modified the code slightly to prevent an infinite loop if anything goes wrong with the communication, and added a few comments to explain why the code is doing what it’s doing. My modified version, along with a compiled .elf file and all of the files needed to build the .elf, can be downloaded from my Google Code project page.

(By the way, if you Google for the DHT11 or DHT22 datasheet, you’ll probably find a “Chinglish” version that’s awfully hard to understand.  A better datasheet can be found here: it refers to the RHT21, but that’s identical to the DHT22 as far as the communication is protocol is concerned).

The native code isn’t something that you copy and paste into Visual Studio alongside your C# code – instead, it is built using a separate piece of open source software with the charming name of Yagarto (Yet Another GNU ARM Toolchain).

An introduction to generating RLPs with Yagarto can be found in TinyCLR’s tutorial.  I’d recommend you use this more extensive tutorial instead, which covers a few small but important steps skipped by the TinyCLR tutorial.

However, if you’d rather not learn Yet Another Anything at this time, the good news is that you can just use the .elf file that is included with the source code for this article.  It should work with any DHT11 or DHT22 connected to any of the FEZ devices that use the USBizi100 chipset: Fez Mini, Panda, or Panda II.

You will have to get your own unlocking code from GHI, to paste into the Visual Studio project. It’s a quick and painless, if somewhat mystifying, process:

1. Create a MyGHI account here: http://www.tinyclr.com/register/

2. Once registered, login and click on the My Account link.

3. Click on the RLP Access Code link

4. Click the checkbox to agree to the “Technology Access Agreement” (which I assume is the whole point of this process), click Submit and your access code will be e-mailed to you.

The access code is pasted into the Visual Studio project, as shown in the Programmer’s Show and Tell section below.  The first time you run the unlock command on a FEZ device, it sets aside 10K for RLP use, then reboots.  The device remains unlocked after that, until the next time you update the firmware.

I’m not sure what exactly the unlock command does to your FEZ device, but based on my experience it’s a safe thing to try.  It doesn’t cause any instability or change the way that you debug your code.  If you decide you’d rather have the 10K back for .Net code, then you can remove RLP support by reloading the FEZ firmware.

I should point out one “gotcha” regarding the DHT11/DHT22 support, which probably applies to any RLP code that is timer-dependent.  You need to invoke the RLP subroutines from the main thread of the .Net application, not from a timer or event handler.  When I tried reading invoking the code from the timer thread that reads the other sensors, I found that the code ran slightly too slowly to keep up with the signals being sent from the DHT22 (which explains why I modified the code to break out of an infinite loop).  When invoked from the main thread, the code is rock solid – I haven’t noticed any failed readings in the weeks that I’ve been running it.

You might be wondering if RLP support is worth all the trouble.  If all you want is to support the DHT11/22, then you actually have an alternative to RLP: this TinyCLR Code project describes an alternative approach using just managed C# code and a clever hardware hack (which would probably also work with a Netduino, by the way).  However,  I really think RLP is worth learning, since it opens up support for all kinds of accessories previously off-limits to Micro Net Framework devices, such as Graphical LCDs and audio input.  For examples, do a search of “RLP” in the TinyCLR Code section.  Pretty much anything that the Arduino supports can (in theory) also be supported for Fez using RLP.

XBee

The XBee configuration at both the FEZ and Python end is the same as in the Netduino Meets World article, with one exception. The Python code will now be using the XBee in API mode, and its XBee (but not the one at the FEZ end) must therefore have its API mode enabled.

The easiest way to do this is to open a console connection to the XBee (as described in Netduino Meets World), and enter

+++
ATAP 1
ATWR

Or, if you prefer, you can use the X-CTU Windows application to turn on API mode.

X-CTU setting for API Mode

Note that the XBee address at the FEZ still needs to be hard-coded as “1”, even if you are using multiple XBee Sensors, or both XBee Sensors and a Netduino Plant Light Controller.  This isn’t a problem yet, since the FEZ/Netduino code doesn’t care what it receives, and the Python code doesn’t use the address to identify what it is receiving.  That will change in a future stage of the project

Python Middleware

The Python code has the same role as in the Watching the Watcher article: it forwards the sensor readings to a data repository on the Internet.

I’ve expanded the Python code to support 2 different repositories: Nimbits and Pachube.  I’ve also expanded the configuration file to give you a bit more control over which sensors are posted to which sites.

The Python code is compatible with the Netduino Plant Light controller that was created in my previous blog posts.

You can download the Python code and sample configuration file from my Google Code project page.  Note that I’ve renamed them to better reflect their role: SensorRelay.py.

The sample configuration file looks like this:

# Configuration file for SensorRelay.py
# ----------- General App Settings ------------
# XBEEPORT = \.COMxx <-- on some systems, Windows COM port 
#   must be specified in this format
XBEEPORT = COMxx
# USBPORT = COMyy
LOGFILENAME = SensorRelay.log
LOGDATA = False
SENDTIME = True
DEBUG = True
# -------- Sensor Settings -----------
#  - sensor line format is <Netduino Sensor ID> 
# = <Nimbits Data Point ID OR Pachube Datastream ID>
#[,Update Interval in seconds]
[Nimbits 1]
NIMBITS_SERVER = http://app.nimbits.com
NIMBITS_USERID = you@wherever.com
NIMBITS_API_KEY = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
UPDATE_INTERVAL = 300
A1 = ASensor,60
A2 = AnotherSensor
T1 = TemperatureSensor,1500
H1 = HumiditySensor
[Pachube 1]
PACHUBE_FEED_ID = nnnnn
PACHUBE_API_KEY = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
UPDATE_INTERVAL = 300
A1 = ASensor,60
A3 = AThirdSensor
T1 = TemperatureSensor
H1 = HumiditySensor

The settings are:

XBEEPORT = The serial port that the XBee is connected to.  On a Linux box, this would have a different format, like /dev/ttyUSBn.

USBPORT = The (very optional) serial port that an XBee Sensor is directly connected to.  (Technically, this would make it a FEZ USB/XBee Sensor – nice acronym!)

Note that you can use an XBEEPORT or a USBPORT, or both.  Just comment out or delete the one you aren’t using.

In the Python code in the Watching the Watcher article, I mentioned that the XBEEPORT setting could actually be set to the port of a USB-connected Netduino.  Why did I break that out to a separate USBPORT setting now?  The Python code now sends data to the XBEEPORT using the lower-level XBee API, while it still uses a generic Serial interface to a USB-connected device.

LOGFILENAME – The filename (or full path and filename) to which sensor data is logged in CSV format.  Note that, unlike the Python code in the Watching the Watcher article, errors and debug messages aren’t written to this file – they are written to a file named SensorRelayError.log instead, in the directory from which SensorRelay.py is run.

LOGDATA – This is used to enable or disable the logging of data to LOGFILENAME.   If your Python code is running on a ultra low power device like the Beagleboard, with just an SD card as its disk drive, then turning off data logging saves some wear-and-tear on the SD card.

SENDTIME – If true, the date and time will be sent to the XBeeSensor each minute.  You’ll want to leave this turned off if you’re using an XBee Sensor, but you should turn it on if you’re using the Netduino Plant Light Controller from my previous blog posts.

DEBUG – If true, debug messages will be written to both the console and the XBeeSensorError.log file.

The sensor configuration sections of the configuration file must always start with a name in square brackets, like “[Nimbits 1]”.  (The name can be whatever you like, actually, as long as you don’t use it more than once).  There must be at least 1 sensor configuration section, but you can have multiple sections if you want to send your data to multiple data repositories.

Personally, I use three: 1 for the public Nimbits app server (to test my code with the latest version of Nimbits), one for my personal Google App Server installation of Nimbits (to which I log more frequently), and one for Pachube, so that I can play around with its API too.

The Nimbits settings are identical to the ones used in the Watching the Watcher article – please see it for details.

The Pachube settings are almost the same as the Nimbits settings, but the lingo is somewhat different.  For details on getting started with Pachube, see my Tweet-A-Watt: Beyond the Twitter article

PACHUBE_FEED_ID = The numeric feed ID.  (A Pachube Feed is a group of datastreams.  A datastream is the Pachube equivalent of a Nimbits Data Point.)  If you want to send different sensor readings to different feeds, you should create multiple Pachube sections in your configuration file (e.g. [Pachube 1], [Pachube 2]).

PACHUBE_API_KEY = A Pachube API key that you’ve generated, and which has write access to your feeds.

UPDATE_INTERVAL = As with Nimbits, this determines how often the sensor data will be posted to Pachube, in seconds.  Note that Pachube has a rate limiter that depends on the type of plan you have.  Each datastream update counts as a separate API call, so if you have 5 datastreams, that is 5 API calls.

SENSOR_ID = DATASTREAM_ID[, UPDATE_INTERVAL] = Determines which sensor reading received from the XBee Sensor will be sent to which Pachube datastream, optionally overriding the default update interval.  For example

A1 = ASensor,60

…means that sensor A1 received from the XBee Sensor will be sent to Pachube Datastream ASensor, every 60 seconds.

Programmer’s Show and Tell

.Net Code

As before, you can get the .Net code from my Google Code page in either of 2 ways:

1. If you are familiar with Subversion, you use any SVN client (my favorite is TortoiseSVN) to get a copy of all the project files.  The SVN URL is https://gigamega-micro.googlecode.com/svn/trunk, and the code for this article is in the XBeeSensor article.
2. Or, download the good old .zip file from the Downloads section of the Google Code project. Here is a direct link to the code for this article.

I’m using the MicroLiquidCrystal library to add support for an i2c-connected LCD. The solution file will look for this project, and grumble if it can’t find it.  If you aren’t using an i2c LCD, you should remove the Reference to the MicroLiquidCrystal library from the project References list.  Otherwise, you’ll need to download the MicroLiquidCrystal source code and store it in the XBeeRemoteSensor solution folder..

While the .Net code is a totally separate project from the Netduino Plant Light controller, a lot of its contents will be familiar if you’ve read the Show and Tell sections of my previous blog posts.

Switching from the Netduino to the FEZ doesn’t require many changes to the code.  The underlying .Net Micro Framework codebase is 100% identical, and very little of the XBee Sensor code makes use of features that are specific to the Netduino or FEZ.  Where it does, I’ve used “#if” conditional compiler flags to include the correct code.

By the way, I’ve switched to putting compiler flags in the Project properties, as shown in the screenshot below, rather than hard-coding them with #define statements.  The default flag is “FEZ” – if you want to use a Netduino instead of a FEZ device, remove “FEZ” from the Conditional Compilation Symbols

Compiler Flags

In addition to getting the compiler flag right, the project’s References need to point to the right set of assemblies. For the FEZ Panda, use GHI’s libraries; for the Netduino, use SecretLabs’.  Your references lists should look like the one below – if you’ve got exclamation marks next to the GHIElectronics libraries, then perhaps you haven’t installed the FEZ SDK yet?  Otherwise, any problems are likely due to differences in the versions of the GHI libraries that I’m using and the ones you’re using – just delete the 3 GHI libraries from the References list, then add them back from the list on your PC.

Project References List

The compiler flags take care of the rest.  For example, the “using” statements at the top of each class ensure that the proper assemblies are being used:

#if FEZ
using GHIElectronics.NETMF.FEZ;
using GHIElectronics.NETMF.Hardware;
#if DHT22 || DHT11
using GHIElectronics.NETMF.Native;
#endif
#else
using SecretLabs.NETMF.Hardware;
using SecretLabs.NETMF.Hardware.Netduino;
#endif</pre>

Near the top of Program.cs, you’ll find the following code:

// !!!!!!!!!!!!!!!! USER MUST SET THE FOLLOWING 3 LINES!!!!!!!!!!!!!!!!!!!!!!!

const int NUM_ANALOG_SENSORS = 5; // number of analog sensors

#if FEZ

static FEZ_Pin.AnalogIn[] sensorPins = new FEZ_Pin.AnalogIn[] { FEZ_Pin.AnalogIn.An0, FEZ_Pin.AnalogIn.An1,

FEZ_Pin.AnalogIn.An2, FEZ_Pin.AnalogIn.An3, FEZ_Pin.AnalogIn.An4};

#else

static Cpu.Pin[] sensorPins = new Cpu.Pin[] { Pins.GPIO_PIN_A0, Pins.GPIO_PIN_A1, Pins.GPIO_PIN_A, Pins.GPIO_PIN_A3, Pins.GPIO_PIN_A4 };

#endif

static string[] sensorIDs = new

string[] { "M1", "M2", "M3", "M4", "L1", "T1", "H1" };

// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

By default, this is configured for 5 analog sensors, A0 – A4, as well as a DHT22 providing temperature and humidity readings.  You’ll need to modify this to match your own configuration.  Note that, if using a DHT11 or DHT22, the 2 sensor IDs for temperature and humidity should be added to the end of the sensorIDs array.  The tags you use for sensorIDs can be anything you like, but they need to match the sensor IDs in the Python configuration file, SensorRelay.cfg.

Note that the above code uses a different syntax to reference analog pins on a FEZ device as compared to the Netduino.  This difference in syntax applies to the digital pins too.  While the pins might be in the same location on the outside, they map to very different CPU pins internally.

As mentioned earlier, I’ve added support for the Adafruit i2c/SPI Character LCD backpack.  This required very little code, since the backpack is supported by the MicroLiquidCrystal .Net library that I used in the Netduino Plant Light Controller code.

The backpack is enabled by adding MLC_I2C to the compiler flags.

There is only 1 I2C port on the FEZ devices (as with the Netduino), and the .Net Micro Framework is able to figure out which pins the i2c interface uses.  So, the i2c LCD initialization code just passes the number of rows and columns:

lcd = new clsLCD_MLC(4, 20);

Beyond that, the LCD interface is identical to the one used by parallel LCDs, as described in earlier articles about the Netduino Plant Light Controller.  One catch, though: I2C is quite slow compared to other LCD interfaces, and if you have multiple threads writing to the LCD, there is a good chance that one will interrupt another in mid-communication, causing the LCD to hang go all garbly.  To prevent this, I use the Monitor method of .Net’s Threading library:

static string lcdLock = "LockMe!";

. . .

try
{
	if (blnDisableLCD)
	{
		return;
	}

	// prevent other thread from writing to lcd at same time (mandatory for I2C LCD)
	Monitor.Enter(lcdLock);

	. . .

	for (int i = 0; i <= intLastRow; i++)
	{
		lcd.SelectLine((byte)(i + 1), true);
		lcd.WriteStringToLCD(strLCDBuffer[i]);

	}
finally
{
	Monitor.Exit(lcdLock);
}

Support for the DHT11 or DHT22 temperature/humidity sensor is enabled by adding the “DHT11″ or “DHT22″ compiler flag.  As mentioned earlier, this makes uses of the FEZ support for native RLP code.  The DHT11/DHT22 code won’t work at all if you’re using a Netduino.

All RLP code is initialized in basically the same way:

-          Call RLP.Enable

-          Call RLP.Unlock, passing it the values that you received in the e-mail.  Just copy and paste the “RLP.Unlock” statement from the e-mail into the code.

-          Load the RLP code (an ELF file) from your projects Resources section

-          Call GetProcedure for each RLP function that you want to call.

RLP.Enable();

//TODO - If your device isn't already unlocked,
//  you MUST paste YOUR ID and byte array into the code below
//RLP.Unlock();

byte[] elf_file = Resources.GetBytes(Resources.BinaryResources.dht11_rlp);
RLP.LoadELF(elf_file);

RLP.InitializeBSSRegion(elf_file);

ReadDHT = RLP.GetProcedure(elf_file, "ReadDHT");
DHTSetup = RLP.GetProcedure(elf_file, "Setup");

// We don't need this anymore
elf_file = null;
Debug.GC(true);

If the initialization succeeds, you can then call the DHTSetup function in the RLP code, passing it the pin that the DHT11 or DHT22 is connected to:

// Call setup function - use Di4 for DHT22
if (DHTSetup != null)
{
	success = DHTSetup.Invoke((int)(FEZ_Pin.Interrupt.Di4));
}
if (success == 0)
{
	Debug_WriteToLCD("DHT Setup failed!");
	DHTSetup = null; // disable use of DHT22
}
else
{
	// give DHT time to stabilize
	Thread.Sleep(1000);
}

To read the temperature and sensor data, call the ReadDHT function.  It returns a 5-byte array:

int intResult = ReadDHT.Invoke(bytArray);

Up to this point, the code used for the DHT11 and DHT22 is 100% identical.  The only difference is how the 5-byte array is processed to extract the temperature and humidity:

if ((intTotal & 255) == bytArray[4])
{

#if DHT22
	int intValues = 256 * (bytArray[2] & 0x7f) + bytArray[3];
	if ((bytArray[2] & 0x80) != 0)
	{
		intValues *= -1;
	}
	fltTemperature = intValues;
	fltTemperature /= 10;
#endif
#if DHT11
	fltTemperature = bytArray[2];
#endif

	Debug_WriteToLCD("Temp " + fltTemperature.ToString("F1"));

#if DHT22
	intValues = 256 * bytArray[0] + bytArray[1];
	fltHumidity = intValues;
	fltHumidity /= 10;
#endif
#if DHT11
	fltHumidity = bytArray[0];
#endif

	Debug_WriteToLCD("Hum " + fltHumidity.ToString("F1"));
}
else
{
	Debug_WriteToLCD("Checksum failed");
}

Python Code

The Python code is based on that described in the Watching the Watcher article, but with some notable improvements.

I’ve rewritten the logging code to follow proper Python standards.  So, instead of dumping error messages and debug information in the same file that contains the sensor data, I’m using the standard Python logging library:

logging.basicConfig(level=logging.DEBUG,

format='%(asctime)s %(levelname)s %(message)s',

filename='SensorRelayError.log')

log = logging.getLogger()

Note that you can change the level of logging, and the log file name, by changing this line of code.  For example, if you wanted to have debug messages sent just to the console, but not the log file, change logging.DEBUG to logging.ERROR.

Exception logging now follows Python standards as well, with the full stack trace being written to the log.  For example:

try:

    . . .

except:

    log.exception('Error sending to pachube, datapoint ' + dataPoint)

The resulting error message in the log includes all the fixings:

2011-09-19 17:40:06,180 ERROR Error sending to pachube,
   datapoint PlantLight1
Traceback (most recent call last):
File "SensorRelay.py", line 51, in sendToPachube
pac.put()
File "build/bdist.linux-armv7l/egg/eeml/datastream.py", line 45, in put
conn.request('PUT', self._url, self._eeml.toeeml().toxml(),
   {'X-PachubeApiKey': self._key})
File "/usr/lib/python2.6/httplib.py", line 914, in request
self._send_request(method, url, body, headers)
File "/usr/lib/python2.6/httplib.py", line 951, in _send_request
self.endheaders()
File "/usr/lib/python2.6/httplib.py", line 908, in endheaders
self._send_output()
File "/usr/lib/python2.6/httplib.py", line 780, in _send_output
self.send(msg)
File "/usr/lib/python2.6/httplib.py", line 739, in send
self.connect()
File "/usr/lib/python2.6/httplib.py", line 720, in connect
self.timeout)
File "/usr/lib/python2.6/socket.py", line 547, in create_connection
for res in getaddrinfo(host, port, 0, SOCK_STREAM):

The Xbee is no longer being treated as a generic serial interface, as it was in the Watching the Watcher article.  Instead, I’m using the Python XBee library, which reads and writes data using the XBee’s API.

To be honest, there is no great advantage to using the XBee API at this point.  I’ve found it to be quite stable – after the Python code opens the XBee port after startup, the port stays open and keeps working regardless of what’s going on at the sensor end of the connection.  The serial port interface to the XBee was just as stable. However, the API lets me send data to a specific remote sensor device, and lets me know which remote sensor device I’m receiving data from, something which will be necessary later in the project.

The code which communicates with the XBee is similar to the serial interface described in the Show and Tell section of Watching the Watcher.  The only significant difference is that I can now define a callback to activated when data is received, rather than having to poll for incoming  data:

if XBEEPORT:
    try:
        serXBee = serial.Serial(XBEEPORT, BAUDRATE, timeout=TIMEOUT)
        serXBee.close() # workaround for known problem when running on Windows
        serXBee.open()
        xbee = XBee(serXBee, callback=readXBeeData)

The callback function receives a “frame” as its parameter.  To get to the sensor data sent by the FEZ (i.e. the same data that would be received from the XBee when it is used as a serial device), just access the frame.data property.  Note that the frame has a bunch of other potentially useful properties, as shown in the code below.

def readXBeeData(frame):
    global buf
    try:
        frame_id = frame['id']
        # source address is 2-bytes binary (e.g. x00x01)
        # this also works: source_addr = struct.unpack('>h', frame['source_addr'])
        source_addr = ord(frame['source_addr'][0]) * 256 + ord(frame['source_addr'][1])
        # rssi (signal strength) is 1-byte binary
        rssi = ord(frame['rssi'])
        data = frame['rf_data']
        if DEBUG:
            print "read_frame, id=", frame_id, ", source_addr=", source_addr, ", rssi=", rssi, ", data=", data
            log.debug("read_frame, id=" + str(frame_id) + ", source_addr=" + str(source_addr) + ", rssi=" + str(rssi) + ", data=" + data)
        if frame_id == "rx":
            processXbeeData(data)

When sending data to the FEZ, you need to package the data into a frame.  I found that the syntax for doing this is surprisingly unGooglable: the Python XBee library is more commonly used to send the XBee a command (e.g. set D2 high), not a custom data string.  The trick is to format the data in a “TX” command.  Note that I’m adding an ending null to the data – this makes the Python code compatible with the Netduino Plant Light Controller code used in previous blog posts.

        if xbee:
            strData = strPrefix + ":" + strCommand
            # HACK - append null to data to make it look like serial data to the other end
            xbee.send("tx", dest_addr = 'x00x01', data=strData + 'x00')

When sending data to Pachube from Python, I originally used the python-eeml library, as described in the Tweet-A-Watt: Beyond the Twitter article.  However, that library still uses the Pachube V1 API, which was limited to numeric datastream IDs.  Since the XML EEML format contains a bunch of optional data that I’m not using, I decided to simplify things and use Python’s standard urllib2 libraryinstead:

        # Note - the following codes uses the V2 Pachube API and CSV data format
        url = 'http://api.pachube.com/v2/feeds/' + siteconfig["PACHUBE_FEED_ID"]
           + '/datastreams/' + dataPoint + '.csv?_method=put'
        # HACK round to 3 decimal places and drop trailing zeros : technically not needed, but makes Pachube output nicer looking
        data = ("%.3f" % floatValue).rstrip('0').rstrip('.')
        headers = {'X-PachubeApiKey': siteconfig["PACHUBE_API_KEY"]}
        if DEBUG:
            print url
            print data
            print headers
        req = urllib2.Request(url, data, headers)
        try:
            response = urllib2.urlopen(req)
        except urllib2.HTTPError, e:
            log.exception('Error code ' + e.code + ' sending to pachube, datapoint ' + dataPoint)
            return False
        except urllib2.URLError, e:
            log.exception('Reason code ' + e.reason + ' sending to pachube, datapoint ' + dataPoint)
            return False

Note the code adds an  “X-PachubeApiKey” setting to the HTTP header, something that isn’t well documented for the urllib2 library.

Wrapping Up

Whew, another super-sized article.  Believe it or not, it takes even longer to write than it does to read!  The upside is that I’ve had the code running for over a month now, so I can report that the FEZ XBee Sensor is a reliable platform with no[t too many] bugs.

I’m quite impressed with the FEZ Panda.  Its support for native code and for Output Compare (another Arduino feature that isn’t supported by the .Net Micro Framework) opens up a lot of new opportunities. GHI updates the firmware quite frequently – more often than Secret Labs does with Netduino – and I suspect they will be first out of the gate with support for the newly released .Net Micro Framework 4.2

Next, though, I’m going to turn my attention to the other end of the data stream, the data repositories.

 It’s been a few months now since the Netduino in this project, with the help of its Arduino cousin, learned to measure the temperature and humidity in the room.  It’s faithfully reporting this data on its LCD… I think.  Who really knows what it’s doing when I’m not around?  It might be sleeping, or watching Fox News, or doing God-knows-what with its “cousin”.

 Clearly, this situation demands a nanny cam.  But my eyes ache at the thought of reviewing hours of footage of an LCD displaying temperature and humidity data (… I think).

Fortunately, now that the Netduino is connected to the Internet, we have a better option: online data monitoring.

 The Asocial Network: Rise of the Machines

 You’ve probably read recently of a rising trend, The Internet of Things.  It is becoming increasingly easy to hook devices and sensors up to the Internet, where they can report their status, receive instructions, play Farmville, and murder us in our sleep.

 The backbone of this system is the online data repository, which records the data and allows you to view the results..  I’ve written before of two of the early entrants in the field, Pachube and Nimbits. 

In this article, I’ll be connecting the Netduino to Nimbits via a Python middleman.  As explained in my last article, I prefer this approach to a common alternative, connecting the Netduino directly to an Ethernet connection.  If you’re interested in trying that approach instead, there’s a whole book that shows you how.

 Both Pachube and Nimbits use a REST API to receive data from sensors.  In past articles, I showed the Python code I use to send Tweet-A-Watt data to Pachube and to Nimbits.  I’m using the same API here.

 My article on using Tweet-A-Watt with Nimbits also covers the process of creating an account on the Nimbits server, getting an API key, and creating Data Points.  You’ll need to do all these things in order to receive data from the Netduino.  Your Nimbits settings are saved in the Python configuration file, explained below.

Netduino Configuration

The Netduino hardware and software is unchanged from the previous stage of the project, Netduino Meets World.  You’ll need to have XBees configured at both the Netduino and Python ends of the configuration – details are in Netduino Meets World.

Well, actually, you don’t need XBees if the Netduino is located quite close to the PC that’s running Python.  This was true for the Netduino Meets World article as well, I just forgot to mention in there.  Since we’re using the XBees as a generic serial device, a USB connection will also work with no software changes needed.  I have one of my Netduino’s connected by USB to a Beagleboard XM running Python. 

You can’t use the Netduino’s USB port for this, but you can connect the pins to TTL-to-USB adapter.  One option is the 3.3V FTDI cable that I described way back in the Netduino: Time and Weather article.  A slightly cheaper option is an FTDI breakout board – I’m using this one from Sparkfun and can confirm that it works fine with the code accompanying this article.

Configuring the Python Interface

The Python code, TimeRelay.py, builds upon the foundation of the Python program used last time, TimeServer.py.  TimeServer was configured using command line switches – since there are a lot more settings now, I’ve switched to using a configuration file.  You can download the Python code and sample configuration file from my Google Code page, here.

The configuration file contains the following settings.   The ones that you have to fill in are marked in italics.

# Configuration file for TimeRelay.py
# SERIALPORT = \.COMxx <-- Windows COM port must be specified in this format
SERIALPORT = /dev/ttyUSB0
LOGFILENAME = TimeRelay.log
DEBUG = True
NIMBITS_SERVER = http://app.nimbits.com
NIMBITS_USERID = 
NIMBITS_API_KEY = 
NIMBITS_UPDATE_INTERVAL = 300
# Sensor IDs - format is <Netduino Sensor ID> = <Nimbits Data Point ID>[,Nimbits Update Interval in seconds]
H1 = PlantRoomHumidity,1800
T1 = PlantRoomTemperature

The first 3 settings correspond to the command line parameters in the program’s predecessor, as listed in the last article:

• SERIALPORT – Specifies the serial port that the XBee is connected to.  Note the unusual format of the serial port name for Windows PCs — this is required by the PySerial library.
• LOGFILENAME – The logfile has an expanded role – in addition to any error messages, it also records the data readings received from the Netduino in a comma-delimited format.  You can disable the local logging feature by leaving this setting blank (i.e. deleting “TimeRelay.log” from that line).
• DEBUG – Turns on debug messages written to the console.  This is on by default, since it is quite useful for troubleshooting.

The Nimbits settings are taken from your Nimbits account:

• NIMBITS_SERVER -  The default setting, app.nimbits.com, is the public Nimbits server.  If you don’t want to rub shoulders with the unwashed masses, you can setup your own private Nimbits server on Google App Engine – you would then enter your GAE server name here (e.g. whatever.appspot.com).  (Both Nimbits and GAE are free when used for this purpose.  I briefly described the process of setting up a Nimbits server in the “Rolling Your Own” section of my Nimbits article)
• NIMBITS_USERID – This is the Gmail address you used when creating your Nimbits account.
• NIMBITS_API_KEY – This key is e-mailed to you when you click the “Secret Key” toolbar button in your Nimbits server console. 
• NIMBITS_UPDATE_INTERVAL – This specifies how often Nimbits will be updated with the latest sensor reading.  The default is 300 seconds (i.e. 5 minutes), but you can override this for individual sensors on the sensor lines at the bottom of hte configuration file.  Note that the Netduino will send a new measurement every 60 seconds, regardless of what you configure here – the Python app will  send Nimbits an average of all the readings since the last update.

The sensor settings are used to link the sensor IDs hard-coded in the Netduino application with the Data Point Names that you created in Nimbits.  The default settings assume Data Point names of PlantRoomTemperature and PlantRoomHumidity – if you use other names (as you might if you don’t actually have a Plant Room), then fill them in on these lines of the configuration file.

Note that the settings shown above will send a new humidity reading to Nimbits every 30 minutes, while the temperature will be sent using the default interval of 5 minutes.  Feel free to change this depending on how meteorologically active your home is.

Activate Sensors

After you’ve finished updating TimeRelay.cfg, run TimeRelay.Py and watch the console.

The program will start by listing the settings it found in the configuration file, then will open the serial port and wait for something to happen.

If a Netduino running the code from the last article is powered on,  and you left the “Debug” setting turned on in the TimeRelay.cfg file, you should see a temperature and humidity reading displayed within a minute.  A message showing the REST API call that sends the data to Nimbits should be displayed in 5 minutes (or whatever interval you used in the TimeRelay.cfg file). 

Switch to your Nimbits web page, double-click on the Data Point in the left hand pane, and the Data Channels pane should update with the newly received value.  

There are a bunch of useful settings that you can experiment with in the Data Points dialog.  I use the Idle Alarm setting to tell me when something has gone wrong with Netduino/Python configuration, and the High and Low Value alert to tell me when something has gone terribly wrong with my home.

The Nimbits web page also has some nifty built-in graphing capabilities.  These have recently changed with the release of Nimbits 3.2, and will continue to evolve, so see the Nimbits web page and Nimbits blog for the latest.

Since I have a fairly large number of data points that I like to glance at from time to time, I wrote a Google Gadget to display line charts in the iGoogle page.  I also wrote a blog post describing its development.  Check it out and let me know of any new features you’d like to see. (Or feel free to take the code and add the features yourself).

Programmer’s Show and Tell

Although the Netduino code isn’t new, I haven’t previously explained in the sensor data handling.

The upload process is run on yet another timer.  This is hardcoded to occur every 60 seconds — nothing magical about that interval, and it could certainly be changed as needed.

Since we’re using the XBee as a generic serial interface, all the Netduino needs to do is write the data to the serial port.  The sensor ID is hard-coded, and each reading is ended with a CR/LF – a “crude but effective” message format. I haven’t noticed any problems with data being garbled or truncated:

// upload sensor readings once a minute
timerUploadSensors = new Timer(new TimerCallback(uploadSensorData),
 null, 60000, 60000);

. . .
private static void uploadSensorData(object data)
{
 string strReading = "";
 if (blnHumidityUpdated)
 {
  blnHumidityUpdated = false;
  // make copy of humidity reading, since it
  //    could be overwritten at any time
  strReading += "H1:" + strHumidity + "rn";
 }
 if (blnTempUpdated)
 {
  blnTempUpdated = false;
  // make copy of temperature reading, since it
  //    could be overwritten at any time
  strReading += "T1:" + strTempDHT11 + "rn";
 }
 uart.WriteToUART(strReading);
}

The Python code is a little more interesting.

First, I’ve added a workaround for a known problem with the PySerial library when running on Windows.  When PySerial tries to open the COM port it thinks that its already open – the workaround is to always close it before opening it.  Trippy but effective, and the workaround doesn’t cause problems on other OSes:

ser = serial.Serial(SERIALPORT, BAUDRATE, timeout=TIMEOUT)
ser.close() # workaround for known problem when running on Windows
ser.open()

The code which reads TimeRelay.cfg demonstrates some of Python’s file- and string-handling power.  Five lines of code is all that is required to open a file, read its contents, parse the lines, and store them in a dictionary. 

def readConfigFile():

    #global config

    for line in open(CONFIGFILE):

        if line.strip()[0] != "#": # skip comment lines

            parts = line.split("=", 1)

            if len(parts) == 2:

                config[parts[0].strip()] = parts[1].strip()

The sensor readings received from the Netduino are stored in a dictionary.  The key is the sensor ID (e.g. “T1”) and the value is a List with format:

<# of readings since last upload>,
<total of readings since last update>,
<date/time of last upload> 

Python dictionaries are cool because they can store any object as their value, and the object type can be different for different entries in the same dictionary.  Less cool is the fact that Python throws an exception if you try to read a dictionary key that doesn’t exist yet, so be sure to check to see if an earlier reading is already stored there.

 
# add this reading to the sensor's list
if sensor in sensorValues:
    sensorValues[sensor][0] = sensorValues[sensor][0] + 1
    sensorValues[sensor][1] = sensorValues[sensor][1] + float_value
    if DEBUG:
        print "found sensorValue", sensor, sensorValues[sensor]           
else:           
    sensorValues[sensor] = [1, float_value, datetime.datetime.now()]
    if DEBUG:
        print "adding new sensorValue", sensor, sensorValues[sensor] 

Note that Python isn’t too picky about variable types except when it is.  If “sensorValues[sensor][1] ”or “float_value” weren’t both floating point values, an Exception would be thrown when they are added together.

The code that sends the data to Nimbits uses the CurrentValue REST API.  This API has a dual role of writing new values and reading the most recent value, but we’re only using it to write data here.

The code starts out with a hack, to round the value to 3 decimal places before sending it. This is done for purely asthetic reasons, so that the readings displayed in the Nimbits web page look nice and tidy.  I call it a hack because rounding a number shouldn’t require this degree of string manipulation.  (Note to Pythonistas: I’m criticizing my code, not your language. Peace out.)

 
# HACK round to 3 decimal places and drop trailing zeros
#  - technically not needed, but makes Nimbits output nicer looking
stringValue = ("%.3f" % value).rstrip('0').rstrip('.') 

try:
    LogMsg(dataPoint + "," + stringValue)
    url = (NIMBITS_SERVER + "/service/currentvalue?value=" +
        stringValue + "&point=" + dataPoint.replace(" ", "+") +
   "&email=" + NIMBITS_USERID +
        "&secret=" + NIMBITS_API_KEY)

    urllib.urlopen(url)
    return True
except IOError:
    print 'Error sending to nimbits'
    print sys.exc_info()[0]

The REST API call is a 2-liner, another example of Python’s power and simplicity compared to .Net.  (Note to Microsoft Fanboys: I’m on your side. Peace out.)  The only trick is to replace spaces in the Data Point name with plus signs, this being a URL and all.

Note that it isn’t necessary to send a timestamp with the data – the CurrentValue API assumes the value has a current timestamp unless otherwise specified.  Good thing, that, since working with time zones in Python can be a nightmare.  (Note to Pythonistas: yeah, now I’m criticizing your language).

Unfortunately the Nimbits CurrentValue API doesn’t return a value to indicate whether the API call was successful, so the Python code won’t write an error message to the console or log file if something goes wrong.  My first indication that something is wrong is generally when Nimbits’ “Idle Alarm” sends me an e-mail.

 Wrapping Up

The Netduino project has admittedly become quite unwieldy, with each stage heaping on more hardware and/or software to the previous stage.    It’s unlikely that anyone but me has all of the Netduino hardware add-ons needed to make use of all the software’s features.

In the next article in the series, I’m going to switch to a slimmed-down Netduino software image for a sensor node, that consists of only a Netduino, an XBee, and a few new analog sensors.