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.

Disabling root 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

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

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?

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

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

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

Analog Input

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

- Potentiometer and MCP9700A:

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

- Sparkfun level converter:

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

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

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

Testing Analog Input

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

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

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

So, we can proceed directly to using the pins.

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

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

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

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

The analog input pins on the Beaglebone are 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-serial. To install it:

root@beaglebone:~# opkg install python-serial

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

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

Then, just run the program as root:

root@beaglebone:~# python serdisplay.py

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

root@beaglebone:~# kill %1

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

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

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

root@beaglebone:~# screen –r –d

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

Programmer’s Show And Tell

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

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

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

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

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

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

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

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

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

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

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

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

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

Wrapping Up

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

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

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

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

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?

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.

I’ve been pretty happy with Angstrom – it has proven to be fast, stable and low maintenance.  When Ubuntu’s Natty Narwal release arrived in April, I didn’t jump at the chance to try it.  However, when I finally got around to checking it out, something in the release notes caught my eye:

OMAP3 CPUs don’t run at full speed by default. While we set the required mpurate cmdline parameter on our images, the values for the different OMAP3 CPUs are not always correct, to work around this you can edit the cmdline in /boot/boot.script and call “sudo flash-kernel”, the change will take effect on next reboot. This should only affect BeagleXM users

Ah, now you tell me!  It was all a misunderstanding – just a typo in the boot parameters.  Ubuntu baby, here I come. Nice knowing ya, Angstrom.

Alas, it was not to be.  Ubuntu 11.04 is no faster on the XM than Ubuntu 10.10 was.  The release notes actually refer to the fact that, by default, the processor is now throttled back to 600 Mhz (!), but you can change the boot parameters to lift it back to 800 Mhz.

However, Ubuntu does have some nice new features that Angstrom lacks, and I came across a couple of not-so-nice “features” that might trip up others who try out Ubuntu on the Beagleboard XM.  So, here’s the full story of getting Ubuntu 11.04 up and running loping.

Preparing the Boot Image

One of the new features in Ubuntu 11.04 is that the official images from Canonical Inc. include a version intended for “headless” configurations: where you intend to use the Beagleboard as a server with no monitor or keyboard.

Unlike other Linux images for the Beagleboard, Canonical’s images automatically run an installation program the first time you boot.  In Ubuntu 10.10 and earlier this install program required a physically connected monitor: now there is a text version that can be run in a serial terminal program like WinPutty.

An alternative (and the method I used when installing earlier Ubuntu releases) is Robert Nelson’s preconfigured “demo” Ubuntu image.

A short digression… If I was going to install Ubuntu 11.04 again, I would actually go with Robert Nelson’s version over Canonical’s.  He updates the image quite often (and it now sports the shiny new version 3.0 Linux kernel – still no 1 Ghz support  ).  Canonical’s image is now a few months out of date, and the first time you update the packages to their latest version you’ll get 100s of megabytes of data that take hours (no exaggeration) to install.

If you decide to use Robert Nelson’s image, then you can skip ahead to the “Getting on the Network” section.

Canonical’s instructions for downloading their image and copying it to the microSD card are a little confusing, since you get directed to a download page that includes builds for all the processors they support.

The correct file for the Beagleboard (both XM and earlier) is this one: http://cdimage.ubuntu.com/releases/11.04/release/ubuntu-11.04-preinstalled-headless-armel+omap.img.gz.  It’s a 204M file.

You’ll also need to download the updated kernel for the XM from  http://people.canonical.com/~tobin/natty/beagleXM-natty.tgz

Windows users will probably need to find a way to use Linux in order to configure the microSD card.  Canonical’s  install instructions for their oddly-named ”Netbook” image – the one you would use if you have a monitor, mouse and keyboard connected to your Beagleboard – mentions that a Windows package like Image Writer  can be used to write the .img file to the microSD card.  True enough,  but then you’ll have to figure out how to mount the ext3 partition on the card to transfer over the kernel patch.  Personally, I used VMPlayer running the PC version of Ubuntu.

As usual, you’ll need to know what the device name of your card is before you start.  Generally, the best method is to run “dmesg” immediately after connecting the microSD card to the PC – the messages at the end of the output will identify the device name.  In my case, it was /dev/sde.

To copy the Ubuntu download to the microSD card:

dwatts@ubuntu:~$ sudo umount /dev/sde?
dwatts@ubuntu:~$ gunzip -c ubuntu-11.04-preinstalled-headless-armel+omap.img.gz
 | sudo dd bs=4M of=/dev/sde
0+48794 records in
0+48794 records out
1675173888 bytes (1.7 GB) copied, 310.701 s, 5.4 MB/s
dwatts@ubuntu:/mnt/hgfs/download/Beagleboard$ sync

You’ll also need to install the updated kernel for the XM, as described at the bottom of the install instructions.

The quickest way to mount the 2 partitions on the microSD card is to remove the card are reconnect it, Ubuntu – and most other OSes — will automatically mount them.  Otherwise:

dwatts@ubuntu: sudo mkdir /media/boot
dwatts@ubuntu: sudo mkdir /media/ubuntu
dwatts@ubuntu: sudo mount –t vfat /dev/sde1 /media/boot
dwatts@ubuntu: sudo mount /dev/sde2 /media/ubuntu

Then extract and copy over the 2 files.  Note that the 2^nd file should be copied as root

dwatts@ubuntu: tar -zxf beagleXM-natty.tgz
dwatts@ubuntu: cp uImage /media/boot
dwatts@ubuntu: sudo cp vmlinuz-2.6.38-8-omap /media/ubuntu/boot
dwatts@ubuntu: sync
dwatts@ubuntu: sudo umount /dev/sde?

Booting Ubuntu

As mentioned earlier, the first boot will automatically launch an install program.  You can’t bypass it, and you can’t connect to the Beagleboard over a network until the installer completes.  So, if you don’t have a monitor physically connected to the Beagleboard, you’ll need to connect a PC to its serial port.

A USB-serial adapter should work well.  Mine is a generic brand that, when inserted into Windows, loads the common “Prolific” driver.

I used WinPutty as the serial terminal.

The serial settings are 115200 bps, N-8-1 with no Flow Control.  In order for the pseudo-graphics in the Canonical installer to appear correctly, you’ll need to change the character set from the default of Latin-1 to UTF8, as shown below:

In its full glory, the install program looks like this.  The lovely magenta background is, as far as I know, a design choice, not a bug:

The installer lets you enter the a machine name, as well as your user-ID and password.  Beyond that, I selected the default on most menus.

In the screen that allows you to select software, shown above, I selected Basic Ubuntu Server, OpenSSH Server and Samba File Server.  Don’t go crazy with your software selections.  At this point your XM’s processor has been throttled down to an extra slow 600Mhz, so you don’t want to give the installer any more work than necessary.

Fixing the Processor Speed

After the install program runs and the Beagleboard XM is rebooted, the first thing you’ll want to do is fix the processor speed.  If you look at the processor info, you’ll see

dwatts@bigdog:~$ cat /proc/cpuinfo
Processor        : ARMv7 Processor rev 2 (v7l)
BogoMIPS       : 471.61
Features          : swp half thumb fastmult vfp edsp neon vfpv3
CPU implementer      : 0x41
CPU architecture: 7
CPU variant    : 0x3
CPU part         : 0xc08
CPU revision   : 2
Hardware       : OMAP3 Beagle Board
Revision          : 0020
Serial              : 0000000000000000

The BogoMIPS rating, a crude performance benchmark, is actually slightly lower than I get with an original (non-XM) Beagleboard.

To fix this you’ll need to change the mpurate setting from 1000 to 800 in /boot/boot.script, as marked in bold below.

fatload mmc 0:1 0x80000000 uImage
fatload mmc 0:1 0x81600000 uInitrd
setenv bootargs ro elevator=noop vram=12M omapfb.mode=dvi:1280x720MR-16@60 _
  mpurate=800 root=UUID=25210e81-e728-4a73-96ff-06df5c29216f fixrtc _
  quiet splash console=ttyO2,115200n8
bootm 0x80000000 0x81600000

The not-terribly-user-friendly vi editor is good enough for this.  Just :

• launch vi (sudo vi /boot/boot.script)
• cursor down to the beginning of the “1000″ after “mpurate=”
• press x twice to erase the 1 and the 0
• press I once to enter insert mode
• type 8
• press Esc
• Enter w
• Enter q

Crude, but effective.  If you mess up, you can exit vi at any time without saving by pressing Esc and entering q!.

After updating the file, enter

dwatts@bigdog:~$ sudo flash-kernel
dwatts@bigdog:~$ sudo shutdown –r now

After rebooting, the BogoMIPs score should be about 630, which is the same as with Ubuntu 10.10.

Unfortunately, based on this post by Robert Nelson in Beagleboard Google Groups, it isn’t clear when (or if) Ubuntu is going to be able to run at 1 Ghz.

Getting on the Network

The default network configuration needs to handle the Beagleboard XM’s non-standard Ethernet device name of usb0.  The /etc/network/interfaces file should contain the 2 lines marked in bold below:

dwatts@bigdog:~ cat :/etc/network/interfaces
# This file describes the network interfaces available on your system
# and how to activate them. For more information, see interfaces(5).
# The loopback network interface
auto lo
iface lo inet loopback
# The primary network interface
auto usb0
iface usb0 inet dhcp 

 If they aren’t there, you’ll need to add them.  If you were traumatized by using the vi editor earlier, another approach to editing the file is :

dwatts@bigdog:~ sudo –i
root@bigdog:~# echo auto usb0 >> /etc/network interfaces
root@bigdog:~# echo iface usb0 inet dhcp >>/etc/network interfaces

Then activate the Ethernet port:

root@bigdog:~# ifup usb0

The Beagleboard XM’s Ethernet adapter uses a dynamic MAC address, so if you are using DHCP to assign the IP address (as the above configuration will do), the IP address will change each time it’s rebooted.  This can be rather frustrating if your Beagleboard is going to be used as a server.  You can change this by using the same settings as explained in my blog post about Angstrom– the interface file in Ubuntu has the same format as in Angstrom.  (A more advanced solution to the problem, which I haven’t tried, is to patch the kernel so that the same MAC address is used each time: see this post on the Electrons on Radio blog).

Updating Ubuntu

Now you get an opportunity to fully and completely appreciate how slowly the Ubuntu package updater runs on the Beagleboard XM.  You’ll need to download and install a few month’s (or more) worth of Ubuntu updates.

root@bigdog:~# aptitude update
root@bigdog:~#: aptidude upgrade

Unless you’re practicing to be a Buddhist monk, you’ll probably not want to sit and watch aptitude crawl along for the next couple of hours.

Speed issues aside, Ubuntu’s package installer software works the same on the Beagleboard as it does on a full PC.  Here are some of the more useful options (though you might end up using Webmin rather than the command line for this — see the Webmin section below):

To list the packages that are currently installed:

root@bigdog:~#: dpkg --get-selections

To find a package based on text in its name or description:

root@bigdog:~#:  aptitude search <text>

To get more info on a specific package

root@bigdog:~#:  aptitude show <packagename>

Updating the Date and Time

If you enter the  ”date” command you’ll likely find that the date is correct, but the time is off by a few hours or more.  Ubuntu has already installed the NTP software needed to automatically set the time, but it needs to know where you live:

To display the current timezone:

root@bigdog:~#:  cat /etc/timezone
America/North_Dakota/Center

To change the timezone

root@bigdog:~#: dpkg-reconfigure tzdata

You’ll then see a pop-up dialog to guide you through the process.

WebMin

After going through the indignity of manually hobbling your processor, then watching it take a couple of hours to slog through the software updates,  you might be wondering why any sane person would choose Ubuntu over Angstrom.  Here’s why: Webmin!

WebMin is the tops.  It’s the thing.  All the girls get up when it sings (yeah).

And Angstrom doesn’t have it.

Installing WebMin isn’t as easy as “aptitude install webmin”, but trust me: it’s worth it.  Full instructions are here: http://www.webmin.com/deb.html, but you should need just 2 or 3 commands:

root@bigdog:~#: wget http://www.webmin.com/download/deb/webmin-current.deb
root@bigdog:~#: dpkg –install webmin-current.deb

Unless you’ve installed a bunch of Perl-specific packages, you’ll get a bunch of errors due to missing dependencies.  It looks messy, but it’s actually quite simple to fix:

root@bigdog:~#: aptitude install perl libnet-ssleay-perl openssl _
  libauthen-pam-perl libpam-runtime libio-pty-perl apt-show-versions python

Don’t worry if not all of those packages are missing.  Ubuntu’s updater might be slow, but it’s no dummy.  Not only will it sort out what’s needed, but it will automatically install webmin for you once all of the missing packages are there.

Once it’s installed, you can load Webmin in a brower from any PC at:

https://<ipaddress>:10000

Note that Webmin will want to use secure protocol (https) by default, and your browser will mutter about missing security certificates as a result.  You can turn off the requirement for a secure connection within Webmin later.

Ordinarily, you should be able to login to Webmin using your own user-ID.  I couldn’t – no idea why, but something went wrong.  I had to login as root.

Wait, what? Login as root?  Impossible, you say!  Ubuntu won’t allow it.

Bah, Ubuntu and what army?  You just have to set a root password manually first:

root@bigdog:~# passwd root
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully

If you want to prevent Webmin from requiring an https connection, click the Webmin link in the upper left of the main Webmin menu, then Webmin Configuration, then SSL Encryption.  “Change the Enable SSL if available” setting to No:

Among the many Linux system administration tasks that Webmin makes a lot easier are:

1. Updating Ubuntu packages.  (Easier, but sadly not faster.)

2. Viewing System Logs

3. Reading documentation and help files for packages.  Note that Webmin goes beyond man pages and puts together a list of all the documentation installed with the package.

4. Mounting drives, include shared folders on Windows PCs (after you’ve installed Samba and configured, as described below).  It will also handle updating fstab so that the drive is automatically mounted when the system is booted.

5. File management. Tucked away under the “Others” section of the left-hand menu is a Java-based File Manager.

6. Software configuration.  The Servers menu in the lefthand pane contains custom modules for configuration some common software packages, such as SSH and Samba.

SSH

If you selected OpenSSH from the Ubuntu installer’s software menu, then the SSH is already up and running.  Otherwise, you can install it with:

root@bigdog~#: aptitude install openssh-server

Alternatively, you can use Webmin to locate and install a package, using the “Software Packages” menu:

The default settings will allow you to login using your Ubuntu user-ID and password.  The SSH server also supports file transfer using an SCP package like WinSCP.

If you intend to access your Beagleboard through the Internet, then you’ll probably want to replace password authentication with public key authentication.  To enable this:

1. Upload your public key to a file named ~/.ssh/authenticated_keys – you’ll probably have to create the ~/.ssh folder first.  You can use WinSCP to copy the file over, or WebMin’s file manager, which includes Edit and Upload functions.

2. Test that you can now login using your public key, rather than entering a password.  In WinPutty, you specify the location of your private key here:

3. In Webmin, select Servers in the lefthand pane, then select SSH Server. Set “Allow authentication by password” to No.  While you are there, set “Allow login by root” to No as a security precaution.  Return to the main SSH Server menu and click the Apply Changes button, which will restart the SSH server.

Incidentally, the SSH server’s default configuration will allow client-to-server port forwarding.  This allows you to access the web server and WebMin from a remote PC after connecting through SSH.  For example, the following settings in WinPutty allow you to connect with SSH and then securely access Webmin through a browser as http://localhost:10000.

Samba

If you didn’t select “Samba File Server” from the Ubuntu installer’s  software menu, then you can install it using Webmin or by running

root@bigdog:~# aptitude install samba

Users are automatically added as Samba users, but their passwords aren’t.

You can configure Samba through Webmin  by selecting Samba Windows File Sharing under the Servers menu.  You need to click on “Edit Samba Users and Passwords”, then select “New password” and type in your password.  This is the password that Windows PCs will need to supply in order to access your Samba shares.

To share a folder, click on “Create a new file share”.  Fill in the “Share name” and “Directory to share”.  If the directory already exists, set “Automatically create directory” to No.

By default, shares are read only.  To change that, click on the share name at the top of the window, then click on Security And Access Control.  Change “Writeable” to yes.

At the bottom of the window is a button to restart Samba and apply changes right away, but generally changes are automatically loaded by Samba without restarting.

Wrapping Up

Aside from Webmin, Ubuntu offers a few other advantages over Angstrom that you might want to consider:

• Its VNC server is much easier to configure than Angstrom’s.
• If you are running VNC, or physically connected with a monitor, keyboard and mouse, Ubuntu offers some shiny new window managers that aren’t available on Angstrom, such as GNOME 3  and Ubuntu’s own Unity2D desktop.
• The Google Chrome browser (with support for extensions) and Arduino IDE (running on Java) are among the applications that Ubuntu offers, and which aren’t available as packages for Angstrom.

However, if you try running software like GNOME 3 and Chrome, you’ll find that they just serve to emphasize Ubuntu’s biggest weakness: they are just too slow to be usable for most tasks.

Ubuntu is, in my opinion, a solid choice for the Beagleboard XM when used as a server.  Background processes like Samba, the CUPS print server, and lighttpd web server run well – I haven’t noticed any response time annoyances there.  When combined with Webmin (which is also quite fast), it’s a relatively user friendly way to learn the basics of Linux system administration.

But, when you have the need for speed, Angstrom is still way ahead of the pack.

Updated Dec 3/11: I fixed a broken feature: autoscaling of the Y axis was no longer working, resulting in values above 100 being cut-off.  

Updated Dec 14/11: I’ve added a couple of new settings: Graph Width and Gadget Height.  For details, see the “Settings” section below.

As mentioned in my post about the data-logging service Pachube, I found the best way to monitor my datastreams was with the Pachube Google Gadget.  Stick it on your iGoogle page, and it allows you to quickly and conveniently keep an eye on your data without having to go out of your way to find it.

When I started logging data to the open source Nimbits system, the first thing I went looking for was some equally convenient way to keep tabs on my Nimbits data. While Nimbits offers a lot of built-in methods for monitoring your data, such as e-mail, Google Talk, and Twitter, I decided that nothing worked as well for me as that Gadget. So, I decided to write a Nimbits Gadget.

The Gadget displays up to 3 line graphs, with each line graph containing as many Data Points (i.e. datastreams) as you like. You can optionally include a Status line showing the last data point received.

You can grab the gadget from its Google Directory page.

In this post I’ll describe the settings for the Gadget, and in the next post I’ll write a bit about the Gadget code and the underlying Nimbits API.

What You’ll Need

If you’ve never used Nimbits before, you’ll need to start posting data to it before the Gadget will do you any good. The Gadget is display-only – it won’t help you get data into the system. The process of creating and configuring a Nimbits account and adding Data Points to it was described in an earlier post.

One major caveat: the Data Points that the Gadget displays must be Public. Admittedly, this is just to keep the coding relatively simple. Private data points require authentication, something which can be tricky from a Javascript application like a Gadget, though I expect (hope?) that this will be streamlined somewhat by the shared Googly underpinnings of Nimbits and the gadget. If it works, I’ll add authentication in a future update of the code.

Settings

The settings dialog, shown below, is longer than the average gadget’s. Not to brag, or anything.

Most of the options are there so that you can tinker with the gadget appearance and features to see what suits you best. The defaults should work fine, but there are a few settings which you’ll need to supply. Let’s start with those.

Required Settings

Server

If you are using the public Nimbits server, then leave this at the default, app.nimbits.com. If you’ve installed your own copy of the Nimbits code on the Google App Engine, then fill in the name of that GAE instance (usually your-app-name.appspot.com)

Data Points

In Nimbits, a Data Point is the unique name assigned to a specific datastream. For example, in the screenshot to the right there are 2 Data Points, Home Meter and Plant Light. (Power Usage is a category – the Gadget only works with Data Points, not Categories).

Enter the name of a Data Point in the textbox then click the Add button. You’ll then see it listed below the textbox.

To add a second Data Point to the same graph, enter its name in the textbox then click the Add button. (You have to add them one at a time, rather than typing them in all at once).

To display a Data Point in a separate graph, click the “Display Graph 2?” checkbox to turn it on. Fill in the name of the Data Point in its textbox then click the Add button.

The following screenshot shows 2 Data Points added to the 1st graph, and 1 Data Point in the second graph.

To remove a Data Point from a graph, click the “X” next to the Data Point name. To remove a graph entirely, turn off its checkbox. (OK, here’s the thing: You can’t remove a graph by removing all of its Data Points – Google’s idea, not mine. The gadget “list” interface pretends to remove them, then adds back the last item when you’re not looking. Apparently, that is not evil.)

Your Email Address

This field is mandatory when using the public Nimbits server (i.e. when the Server fields is app.nimbits.com). That’s how Nimbits figures out which Data Points belong to you.
The field is optional if you’ve setup your own Nimbits server using the Google App Engine.

Update June 4: Actually, the e-mail address is optional when using your own Nimbits server only if you’re authenticated with the backend Google App Engine. Since I’m not sure what triggers that authentication, you should just go ahead and fill in your e-mail address.

Graph Height

This determine the height, in pixels, of the graph. The default of 200 will only allow one full graph to fit. A size of 80 will allow 2 graphs with Status lines to fit.

Graph Width   [Added: Dec 14 2011]

This determines the width, in pixels, of each graph.  The default of 310 pixels fits snugly in the gadget container on my desktop PC, but the optimal width will vary depending on the browser and device you’re using.

Gadget Height   [Added: Dec 14 2011]

This determines the height, in pixels, of the gadget container.  The default setting is 240 pixels, which is big enough for a couple of graphs and status lines.

Other Settings

Time Span

The amount of data displayed on the graph is specified in the Time Span field. You can enter it either as hour or as # of readings. In either case, you’ll get the most recent data: that is, the most recent x hours of data, or the most recent x readings.

By default, this is set to display the last 24 hours of data.

Legend

This option determines whether a list of the Data Points and their colours are displayed at the top of the graph. This option is particularly useful if you have multiple Data Points in a graph. Turning the legend off frees up more vertical space for the data in the graph.

Grid Style

This option determines the grid lines displayed on the graph: None, Vertical, Horizontal or Both. You can have any number of grid lines you like, as long as that number is 10.

Show Status

This option determines whether a status line is displayed above each graph, giving the name of the first Data Point and the date and time of the last reading. The status is particularly useful to identify that your data stream has stopped working, since the line graph won’t make that outage apparent. (Integrating downtime into the graph is definitely a top priority for future updates of the gadget.)

The downside to displaying the status is that it slows down the refresh time of the gadget, and (ahem) the code doesn’t always work. See the Troubleshooting section below if the Status line displays something other than a status.

Troubleshooting

Blank or missing graphs

When something goes wrong, you generally end up with a blank graph rather than an error message. That’s kind of by design: if there is no data matching the settings, the Nimbits API will dutifully provide an empty set of data to Google Charts, which will dutifully display it.

If the graphs are missing entirely, then the gadget likely couldn’t find a Nimbits server, so check your Server setting.

If blank graphs are displayed, try turning on the Legend and Status options in the settings – they may give an indication of what went wrong.

If the legend is labeled “Doesn’t exist”, then the Data Point might not have been correctly entered in the settings.

Status line errors

The Status might be set to one of the following errors:

• The requested URL /service/currentvalue was not found on this server. Check the server name in the settings. This error means the server exists, but Nimbits isn’t running on it.
• Could not identify user. Check the email address field in the settings.
• Status unknown or Undefined. Unfortunately, there seem to be a variety of causes to this one. The problem isn’t with the settings – it’s likely something I can fix in the code. So, don’t blame yourself, blame me. Fixing this is a priority for future versions of the gadget.

Slow updates

If the Gadget takes too long to update itself, try turning off the Status option in the settings, and/or putting multiple Data Points on the same graph. Each graph and each status field require an extra call to the Nimbits server. Three data points on one graph take much less time to appear than 3 graphs.

Data isn’t updated often enough

Chill, dude! Updates to the graphs and status will only appear every 5 minutes, no matter how much you click the browser Refresh button. This is by design. Google caches the data used by the gadgets, and I’ve set the cache length for 5 minutes.

If you don’t manually refresh the browser page, iGoogle will update all of the gadgets just once per hour.

Some graphs don’t fit

I left the Gadget height at its default, and there is no way for the user to increase the size of a gadget in iGoogle. You can fit more graphs in the space by reducing the Graph Height in the Settings dialog. The default of 200 will fit just one graph; a Graph Height of 80 should fit two graphs with their status fields.

You can see an expanded view of all graphs by clicking Maximize control button on the titlebar, or by selecting the Nimbits gadget in the list on the left of the iGoogle screen.

Wrapping Up

If you have any problems, or requests for features in future versions of the gadget, please leave a comment below.

At about 8:30, my Beagleboard was rebooted and promptly resumed its role as Tweet-A-Watt server.  You’ll have to take my word for that, since it abandoned its role as Tweet-A-Watt Twitterer.  I didn’t notice this latter fact until earlier today.  So, if you read my Beagleboard XM And Angstrom – Getting the Big Dog to Run At Full Speed
post sometime between Jan 1 and Jan 3, you might have wondered if the Big Dog had, indeed, begun to fight with Angstrom.  But, rest assured, the failure was mine, not the Beagleboard’s or Angstrom’s.

Hello, Dali

There is a post on the Mechomaniac blog which explains the process of configuring your timezone and installing the NTP package.  After following those instructions, you can enter ntpdate pool.ntp.org, and your system date and time should be set correctly.  (If the time is off, you probably didn’t set the timezone correctly – as stated in that blog entry, the /etc/timezone file used by some Linux distros seems to be ignored by Angstrom.)

Although I didn’t include the NTP configuration in my initial article about setting up Angstrom the Beagleboard XM, I actually had done it.  I also took the next logical step, which is to configure ntpdate to be automatically run periodically, so that your system date is updated after, say, a power outage.

Or, so I thought.

What I did was

opkg install cron

[Update Aug 13: Oh, hai! Dan from the Future, here. Sorry to interrupt your reading, but I just installed a new Angstrom image generated with Narcissus, and I found that the ntpdate entry was placed in the correct crontabs file after installing cron: /var/cron/tabs/root. So, if you're configuring NTP using an up-to-date cron package, then you're probably done! However, I'm sure you'll want to continuing reading, to see what madcap adventures Dan from the Past got himself into this time...]

Period.  The next step should have been to configure cron to run ntpdate.  However, when I checked to see how cron was configured, I noticed that a folder named /etc/cron/crontabs existed, and in there was a file named root that contained:

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

And, furthermore, the cron package automatically added a file to etc/init.d so that cron was automatically started when the system booted.

Hey yeah! That was easy, especially by Angstrom standards.  Surprisingly easy.  Suspiciously easy.  Hmmm.

On January 1 I belatedly learned that it isn’t quite that easy.  The problem is that /etc/cron/crontabs isn’t where the configuration tables for cron are stored, at least not in the world of Angstrom.  They are in /var/cron/tabs.  One way to configure cron to run ntpdate is to copy the file from /etc/cron/crontabs to here. Then, restart the cron daemon

cp /etc/cron/crontabs/root /var/cron/tabs/
/etc/init.d/cron restart

In the interests of Linux orthodoxy, I should mention that this isn’t the “proper” way.  The proper way is to make use of two crontab commands.

To see what is currently configured (for root – for another user’s crontab, replace “root” in the following commands with the user-ID):

crontab -u root -l

If you are already root (which you should be for the purpose of configuring ntpdate), you can leave out the user name:

crontab -l

To change what is configured

crontab -e

This last one will launch vi so that you can edit the file.

Oops, maybe I should have mentioned that earlier. If you are now staring dumbfounded at the world’s most user-hostile editor, press the Esc key, enter :quit! and take a deep breath. Then, copy the root file from the crontabs folder, as specified earlier. Should you need to change the contents of this file, you can just edit the “root” file using your preferred editor, then copy the resulting file into /var/cron/tabs.  If you go this route, you’ll need to manually restart cron afterwards, whereas changes made with crontab -e are automatically detected by cron.

Actually, its possible to configure crontab to use another editor — Google it if you’re interested.

The above crontab line will run ntpdate at the 30th minute of every hour (i.e. 12:30, 1:30).  That’s probably fine, but if you want to stand out from the crowd you can change it to something less common like 13 * * etc, or change ntp.pool.org to your favorite neighbourhood NTP server.

Not working? Not sure that it’s working, and anal retentive? By default cron will log its results to /etc/cron/log, in a format like this

root (01/03-17:03:00-1237) CMD (-s -u pool.ntp.org )
root (01/03-17:03:00-1236) MAIL (mailed 27 bytes of output but got status 0x0001)

root (01/03-17:08:00-1259) CMD (/usr/bin/ntpdate -s -u pool.ntp.org )

The “MAIL” entry is how it handles errors – presumably you have to configure mail on your Linux box in order for that error message to actually go somewhere.  It wouldn’t matter much in the case of this ntpdate command, since the “-s” tells it to log its output to syslog.  And syslog is another thing that works differently in Angstrom (and doesn’t work at all by default). Sigh. We won’t go there.

If you want to know what went wrong when ntpdate goes wrong, you’ll have to change the crontab entry to something like the following:

13 * * * *  /usr/bin/ntpdate -u pool.ntp.org ›› /home/root/ntpdatelog.txt

This will append the results of the ntpdate command to a text file.

Oh, and a belated Happy New Year from my Beagleboard!

At the time I was somewhat dubious about whether Angstrom would prove to be a stable platform. So far, so good. My Beagleboard XM has been faithfully working 24/7, receiving Tweet-A-Watt data via XBee and posting power usage updates to Twitter.

Over that time, I’ve made a few tweaks to the initial configuration and have begun to give the new dog some new responsibilities.

The first of the tweaks is to have it use a static IP address rather than using one assigned by the router’s DHCP service.

This tweak is necessary because the XM’s Ethernet port is not a dedicated piece of hardware with a “burnt-in” Ethernet MAC address. Instead, it makes use of the same USB hub chipset’s ability to handle Ethernet communications. (The chipset is an SMSC LAN9514). Saving and restoring the MAC address is the responsibility of the software, and the Linux driver used for this chipset doesn’t support this feature currently.

The end result is that the DHCP server thinks the Beagleboard XM is a new PC every time it is rebooted, and assigns it a new IP address. This is a major nuisance if you are using the XM as a headless server. After each reboot you have to hunt down the XM over the network by checking the DHCP logs, or by physically connecting to its serial port.

One solution to the problem is to manually assign a MAC address by changing the XM’s boot parameters, as described in Max Galemin’s blog post here.

Another solution is to manually assign the IP address, instead. This is somewhat easier to configure, and it allows you to choose an easy-to-remember address. One downside to this approach is that Wake-On-Lan support won’t work, since you need to configure a MAC address for the “magic packet”. I went with a static IP, but if you can’t let sleeping dogs lie (nyuck nyuck nyuck) then go with the static MAC instead.

The process of configuring a static IP address is the same in Angstrom as in most Linux distros. The only catch is that the device name is /dev/usb0, rather than the /dev/eth0 used on most PCs.

1. Switch to root, backup /etc/network/interfaces, then edit it:

user@beagleboard ~  su -
Password:
root@beagleboard:~# cd /etc/network
root@beagleboard:/etc/network# mkdir back122610
root@beagleboard:/etc/network# cp interfaces back122610/

2. You’ll need to know the IP address of your gateway and your DNS server. If you aren’t sure, you can see what the XM is currently using (as assigned by the DHCP server) by running a couple of commands:

root@beagleboard:/etc/network# netstat -nr
Kernel IP routing table
Destination     Gateway         Genmask         Flags   MSS Window  irtt Iface
192.168.1.0     0.0.0.0         255.255.255.0   U         0 0          0 usb0
0.0.0.0         192.168.1.1     0.0.0.0         UG        0 0          0 usb0

root@beagleboard:/etc/network# cat /etc/resolv.conf
search lan
nameserver 111.222.333.444

Your gateway address is displayeded in the 2nd row of output from netstat -nr (192.168.1.1 in the above example). Your DNS is displayed in the 2nd line of /etc/resolv.conf (111.222.333.444).

3. Edit the interfaces file (e.g. vi interfaces). Comment out the line that says “iface usb0 inet dhcp” and replace it with the following lines, specifying your own IP addresses. In the following example, I’m assigning the XM address 192.168.1.2. The gateway (my router) is address 192.168.1.1. Since my router is configured as a DNS server, my DNS server address is also 192.168.1.1.

# Ethernet/RNDIS gadget (g_ether) or LAN9514
auto usb0
# iface usb0 inet dhcp
iface usb0 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

4. If you are connected from a remote PC, reboot. Otherwise, if you are connected to the Beagleboard’s serial console or with a keyboard and LCD, you can just start and stop the network interface:

root@beagleboard:/etc/network# shutdown -r now

…or…

root@beagleboard:/etc/network# ifdown usb0
root@beagleboard:/etc/network# ifup usb0

I noticed some early signs of trouble on the initial boot: an ominous “”Kernel is not ready for 1Ghz limiting to 800Mhz” message, and a Windows-like leisurely boot time. My first impressions were confirmed by running the HardInfo benchmarks. Every one of them except BogoMIPs was lower on the XM than the C4 by 10-20%. BogoMIPs was a disappointment too, at just over 600. On the Angstrom demo build that is bundled with the XM, the BogoMIPs benchmark was close to 1000.

I tried installing Ubuntu 10.04 on the XM, but the HardInfo benchmarks were just as slow. A Google search confirms that others have run into the same problem with the XM, and as of now (early December 2010) there doesn’t seem to be a workaround. It would appear that Ubuntu isn’t yet optimized for the XM’s faster DM3730 processor.

Performance aside, Ubuntu 10.10 ran well on the XM. But it broke my heart to see the old C4 running rings around the new pup. So goodbye Ubuntu, hello Ångström, at least for now.

Angstrom (sorry, I’m not going to type in those umlauts again) is a Linux distribution that seems to be designed for speed and not comfort. As the name suggests, its roots are as a relatively tiny OS that can run on portable devices that are slower and more memory constrained than the XM, such as Pandora handheld gaming console and the Sharp Zaurus. The XM lets Angstrom stretch its legs, and it responds with blazing speed!

Unfortunately, it’s also much trickier than Ubuntu to configure. Angstrom’s default installation doesn’t include a lot of the packages that are included in every Ubuntu install (and most other distros too). Many of the packages available for Angstrom have generic or misleading names, so it can be hard to track down the one you want. There isn’t a lot of end user documentation for Angstrom, and the user base is much smaller than Ubuntu’s, so Googling won’t always find you the answer either.

Here’s a step-by-step description of how I got Angstrom up and running. To take optimal advantage of Beagleboard’s ultra low power design, my goal was a “headless” application server (i.e. no monitor and therefore no GUI).

1. Angstrom’s has an online image builder named Narcissus. While its pretty easy to generate an image, it isn’t obvious how to boot the image on your Beagleboard. The best instructions that I found were in this article on Trey Weaver’s blog. The only thing that I did differently than what it describes is the command to extract files from the Angstrom image file. Since Narcissus is (currently) using a default image format of gzip (i.e. the downloaded image file ends with .gz), the command to extract the boot files has slightly different parms:

tar --wildcards -xzvf [your-download-file] ./boot/*

Similarly, the command to extract the root filesystem is:

sudo tar -xvz -C /media/Angstrom -f [your-download-file]

2. The Beagleboard XM has a built-in serial port, and the default Angstrom build supports it, so you can initially login by connecting a PC to the serial port (a USB-to-serial adapter works fine) and running a terminal program. (Settings are 115200 bps, N-8-1 no flow control.) On Windows, WinPutty works well – on a Linux PC, minicom is, I think, the best bet.

However, you may run into an irritating problem with the display and keyboard input being garbled. I’ve had that problem when I’ve installed Angstrom on both my Beagleboards, and I’m not aware of any workaround.

Fortunately, the garbled terminal only occurs when connecting through the Beagleboard’s serial port, so you’ll want to switch to some other type of connection as soon as possible.

[Update: It turns out that the garbling occurred only when using a PCI Serial Port card.  I switched to a USB-Serial converter (which uses the common Prolific chipset), and WinPutty works flawlessly.]

Since I wasn’t interested in hooking the Beagleboard up to a monitor and keyboard, I switched to using SSH to bring up a command line connection from another PC. Here is another area where Angstrom is easier to use than Ubuntu – Angstrom activates the Ethernet port by default, and includes an SSH server named Dropbear by default, so you may be able to connect by SSH on your very first boot, bypassing the serial port entirely.

In any case, the default user-ID is root, and it has no password.

3. To set a password, use the passwd command. I’d suggest you do so even if you aren’t at all concerned about security, since some utilities will expect a password.

passwd

Angstrom makes some suggestions about the length and types of characters in your password, but it doesn’t enforce them.

4. You might want to add a regular user account too. The command for that is useradd

useradd youruserid

You need to assign a password to this user-ID before it can be used to login:

passwd youruserid

5. If the only Linux distro you’ve used before is Ubuntu, you might be puzzled about the command used to run root commands when logged in as another user. “sudo” isn’t installed in Angstrom by default. Configuring sudo in Angstrom is surprisingly difficult, so you might want to stick to running as root, or get used to switching from a user account to root by entering:

su -

Enter the root password when prompted, not the user password à la Ubuntu.

6. The command to install packages in opkg (which, like pretty much every other command I list, must be run as root). Entering “opkg –help” will tell you all you need to know, but here are some commonly used commands:
To bring your installed packages up-to-date

opkg update
opkg upgrade

To install a package:

opkg install packagename

To remove a package:

opkg remove packagename

If the removal of a package fails due to a long list of dependent packages (and you are sure you don’t want to keep any of them!):

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

Unlike Ubuntu’s aptitude, opkg doesn’t automagically remove conflicting packages for you. So, when an install fails due to conflicts, you need to either remove them manually, or (as a last resort) grit your teeth, cross your fingers, and enter:

opkg install packagename --force-overwrite

To list the files in an installed package:

opkg files packagename

If you want to install something and are trying to figure out its packagename, you can get a list of packages whose name includes a search term:

opkg list | grep "whatever"

To get a description of a package:

opkg info packagename

A better way of finding a package is to use the package browser on Angstrom’s web site. Better, but frankly not great, since Angstrom tends to use different package names from other distros, and the package descriptions are usually vague.

To get a list of packages already installed:

opkg list_installed

7. As with most Linux distros, the default text editor is “vi”. Lots of alternatives are available, but the one I use is emacs:

opkg install emacs

8. You’ll need an editor to change the hostname to something other than the default of “beagleboard”. The 2 files you’ll need to edit are /etc/hostname and /etc/hosts. For example, to change your hostname to bigdog, the contents should be:

youruserid@bigdog:/etc$ cat hostname
bigdog
youruserid@bigdog:/etc$ cat hosts
127.0.0.1       localhost.localdomain           localhost
127.0.0.1       bigdog

9. [Update: This step may no longer be necessary - I noticed that the Angstrom 11.03 Narcissus image uses bash as the default user shell] By now, you’ve probably noticed that the shell is missing some features that you’re used to, like color coding. Strangely, one of the things that Angstrom doesn’t install by default is the nearly-universal bash shell. To install it:

opkg install bash

After installing it, you need to make it the default for your user-ID (though you can run it temporarily by just entering “bash”). The command for doing this is

chsh /bin/bash

Since you have to be root to do this, if you want to change a non-root user to the bash shell, enter

chsh /bin/bash youruserid

10. You’ll probably want to make some folders on the Beagleboard accessible over the network. In my case, I primarily use Windows PCs, so I needed to install Samba. Since configuring samba can be tedious using its command line tools, I also installed the browser-based samba configuration tool, SWAT:

opkg install xinetd
opkg install samba swat

xinetd is the standard way of invoking SWAT (and other port-based utilities). You’ll probably have to manually edit the SWAT settings in the xinetd configuration file — the following settings will allow access from any PC:

The updated /etc/xinetd.conf file should look like this:

# Simple configuration file for xinetd
#
# Some defaults, and include /etc/xinetd.d/

defaults
{

}

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

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:<ipaddress>901

Login as root at the prompt.

By default, the home folders are shared – if you created a non-root user-ID then the defaults may be fine. However, you’ll need to go to the SWAT password page and enter the user-ID and password that you login to Windows. Click the “Add New User” button when you’re done — it may be old to you, but it’s new to SWAT:

I’d also suggest you go to the Global page and change the workgroup to whatever your Windows PC uses, and enter something meaningful in the “netbios name” field.

After saving your changes you don’t need to restart Samba – it applies your changes automatically.

If you go to a Windows PC, you should now be able to see your Beagleboard 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.

11. One of the things I want to use my XM for is as a Tweet-A-Watt server. It’s a good match: software to monitor electricity usage running on an ultra low-power platform. This requires adding a couple of things to Angstrom: Python, and access to an XBee connected to a USB drive. Both of these turned out to be somewhat trickier than they are on Ubuntu.

12. The main package for Python is named python-core. However, Angstrom’s idea of a “core” lacks a lot of python libraries that are standard on pretty much any other Python installation. After playing hide-and-seek with various packages, I gave in and installed the full set of libraries, packaged as python-modules. I also included pyserial for access to the XBee

opkg install python python-modules python-pyserial

At this point, you can install the Python setuptools package, which includes the easy_install command. easy_install allows you to install many other python libraries that don’t (seem to) have Angstrom packages. In my case, I needed Tweepy, which can be used to provide Twitter access to tweetawatt (I wrote an earlier post about that):

opkg install python-setuptools
easy_install tweepy

13. Unlike Ubuntu for Beagleboard, Angstrom doesn’t include support for serial port USB devices in the kernel. If you plug in a USB serial I/O device like an XBee or Arduino, it will be recognized, but no port (e.g. /dev/ttyUSB0) will be assigned to it.

(On the other hand, USB storage devices are supported by default in the Angstrom kernel. And, unlike Ubuntu on the Beagleboard, some drives are automatically mounted, so after plugging in a USB drive you should be able to immediately access it under /media/sda. Kewl.)

To install support for USB serial I/O devices:

opkg install kernel-module-ftdi-sio

You can temporarily load the kernel module to confirm that it works by entering

/opt/bin/depmod -a
/opt/bin/modprobe ftdi-sio

If you plug in an XBee, it should now be assigned a port. (Probably /dev/ttyUSB0, but you can enter dmesg and look at the bottom of the output to confirm this).

To automatically load the kernel module at bootup:

echo usbserial > /etc/modutils/usbserial
echo ftdi_sio > /etc/modutils/ftdi_sio
update-modules

this will update the /etc/modules file.

Phew. In the unlikely even that you read this far before actually trying to get Angstrom working, you might be wondering if it is worth all the effort. The process of setting up the same configuration in Ubuntu is simpler and much better documented.

While its somewhat rewarding to use long-neglected command line skills (and learn a few new ones), I’d frankly have to admit that I’ll probably change back to Ubuntu when (if?) its performance on the XM is comparable to Angstrom’s. There are some packages that don’t seem to exist yet in Angstrom, and I don’t have the time/skillz to port them over. (Most notably, I would love to have Python’s Matlib package, and a browser administration tool along the lines of WebMin. Oddly, the standard Linux help command, man, is currently not available for the Beagleboard).

One other concern: Ubuntu is rock solid on my older Beagleboard, and Angstrom’s stability is, for me, unproven. However, Tweet-a-Watt is now up and running on my XM – if it’s still posting updates to www.twitter.com/gigamegabot when you read this, then maybe tiny Angstrom and the Big Dog really are a match.

Recommended Reading

This is the second time in five years that I’ve “done my duty”, and in both instances the week consisted of 99% waiting around and 1% being rejected out-of-hand by defense counsel. I am, of course, crushed by the repeated rejections, but I managed to get some benefit from the other 99% of my week by reading a software development e-book.

When I went through this five years ago, I did my reading on a Dell Axim running Windows Mobile 5.0. You laugh, but let me tell you that one thing it did really well was copy and paste. You selected the text with the stylus (stop laughing), used a button to toggle to Word and pasted the text in. A task so simple even Windows Mobile could handle it.

Five years later, I’m using an iPhone. In technical terms, the iPhone is a Porsche and the Axim a Yugo. But when it comes to copy and paste, the Porsche is a freaking nightmare to drive.

The problem isn’t so much with the iPhone as with its apps. Very few of e-readers allow you to copy text into the clipboard. It’s bizarre! Do they think we don’t want that feature (we’re too dumb), or do they not trust us to use it responsibly (we’re too dishonest)? Either way, it’s insulting.

However, it’s not all doom and gloom. There are two very, very good apps that do support the clipboard, and a growing number of e-books that are compatible with them.

Stanza - march to a different drummer

Stanza.   Stanza supports a long list of e-book formats, but unfortunately you are unlikely to encounter most of them when buying e-books. The 3 exceptions are:

1. eReader – This is a “secure” (piracy-protected) format that is used by Fictionwise and Books on Board for most of their books, and by Barnes and Noble for many of them.
2. ePub – The ePub format supported by Stanza is not “secure”, which unfortunately makes it harder to find (we’re dishonest, remember).  However, if you’re a computer geek then you’re in luck: O’Reilly and Microsoft Press offer ePub editions of almost all of their publications.
3. PDF – Support for PDF format documents was added to Stanza last week.  Unfortunately, its copy support is pretty inconsistent, often copying gibberish to the clipboard.

GoodReader - not bad!

GoodReader. GoodReader supports just one format, PDF, but that’s still the most commonly used format for technical publications. I’ve raved about this app before, and I’ve grown more and more impressed with it over time. They added clipboard support a couple of releases ago, and while its not the most convenient implementation (you can only copy a full page of text, not selected text), it is fast and reliable, just like the rest of GoodReader. I’ve yet to find a PDF that GoodReader couldn’t handle — amazingly, it loads 100 meg monsters faster than my desktop PC.

Once you’ve filled the iPhone’s clipboard, your options for pasting text are much better.

You might find that the built-in Notes app is good enough for this task. I use Pastebot – a lot of people rave about its advanced formatting features and automatic synchronization (Mac only), but I like the fact that it automatically saves the clipboard contents when you open the app. If you need to format the text after you paste it (change fonts, italics, etc.), you should consider Documents To Go. I’m really impressed with how quickly it manages to bring you back to your last spot in a document without multitasking — the app is ready to paste a couple of seconds after you click the launcher (on an iPhone 3GS).

The new iOS 4 will make the copy-and-paste process somewhat smoother with its support for multitasking and fast app switching: it might even be able to compete with Windows Mobile 5!

One last piece of good news: O’Reilly (and associated publisher, Microsoft Press) continue to make most of their books available as very inexpensive iPhone apps, generally $5 or $6. That’s the full book, pictures and all.

If you’ve bought one of these apps, you were probably disappointed to find that clipboard support was disabled. This seems to be related to the underlying version of Stanza (which their apps bundle with the e-book). For some reason Stanza quietly disabled clipboard support in an update to their app last year, then quietly re-enabled it in the next update. Hmm.

While O’Reilly continues to use the clipboard-disabled version of Stanza, it is easy enough to do the upgrade yourself. Just follow the process described in my earlier post to extract the ePub from the O’Reilly / Microsoft Press book app, then import the ePub into Stanza using their desktop app or a URL link.

I’m pretty sure that O’Reilly is OK with you doing so — as mentioned in my earlier post, it was O’Reilly themselves who originally documented the process. If not, maybe I’ll get yet another opportunity to read e-books as a guest of the Ontario judicial system!