Setting up BeagleBone Black for development (Clojure in particular)

I just got another BeagleBone Black (BBB) to tinker with as I finish up my pin-ctrl library and wanted to record the steps so it's easier for me and others in the future.

In particular, I show here how to set up a non root user with access to the board's pins. This is useful no matter what programming language you care to use on the BBB. (Deving as root is bad, m-kay?)

Thank you Debian

My first BBB came with Angstrom. While it's a fine distribution, I rather missed access to aptitude for package management, as well as other various Debian-isms. But I was also too lazy to bother setting up Debian and figured it was worth getting a feel for Angstrom. To my pleasant surprise though, it appears the newer rev C BBB is now shipping with Debian! This made setup this time around much easier. However, if you have an older board, these instructions may not work in entirety for you, without first installing Debian (the steps taken for the non root user are likely the same though).

Prereqs - connecting to the board

In my opinion the easiest way to get things going is to just connect the board to a router via ethernet, since this will both let you ssh into it and give you network access for installing packages, which you'll want to do anyway. Once connected, you can ssh in to the beaglebone with ssh root@beaglebone (note: on some routers/installations, you may have to do @beaglebone.local). There shouldn't be any password prompt.

Alternatively, you can follow these directions on your non-beaglebone computer so that you can ssh into the BBB over the USB cable. This is handy for when you don't have ethernet around, so worth doing on it's own right. But again, you'll need net access anyway.

Setting up a non root user

Unfortunately, all of these boards (BBB, Pi, etc.) assume you will be running as root, which is terrible Linux practice. You really only ever want to be running as root when you're doing system maintenance and such. Additionally, as far as Clojure related things go, Leiningen does not particularly like running as root. You can override this with LEIN_ROOT=1 lein ..., but doing so feels all the more like you're going against the grain of Unix best practice.

The real kicker here is that by default only the root user has access to the pins. To give a non root user access to these pins, we can do the following:

• add a group named pinusers
• create a new user belonging to that group
• set up some udev rules so that on boot our pin files will automatically have the group permissions they need

Here's how we do this:

# First create new user group
groupadd pinusers

# Next create user (don't use the -s flag if you don't want to use zsh) and homedir
mkdir /home/
useradd -G pinusers,admin -d /home/ 
chown -R csmall /home/csmall
# Enter password for new user when prompted
passwd 

# Download the permissions script and udev rules
wget https://gist.githubusercontent.com/metasoarous/a7308779837f9dcba662/raw/b6717752469da4184c4aaa8bd88407290df15e19/80-pinusers-permissions.rules -O /etc/udev/rules.d/80-pinusers-permissions.rules
wget https://gist.githubusercontent.com/metasoarous/a7308779837f9dcba662/raw/8b7dfc236514caeca0274c6144afe195cd074a0c/set-pinusers-permissions.sh -O /usr/local/bin/set-pinusers-permissions.sh
chmod +x /usr/local/bin/set-pinusers-permissions.sh

# Execute the permissions script to kick things off, while we're at it
set-pinusers-permissions.sh

Note that the udev rules and permissions script come from this gist, if you care to inspect them before downloading.

You should now be able to su .

Opinionated dev setup

If you have your own opinionated 'nix setup, by all means, have at it however you usually like to set it up. I myself have a pretty opinionated setup which emphasizes vim + tmux + zsh. If you're interested in giving it a whirl, read on.

(I'm also working on a more general post about the environment things I like to set up for the future, which I'll link here when done).

Apt packages

Thankfully, the Debian distribution already comes with a lot of the things I want in my dev environment. In particular:

tmux / vim / git / ruby

Some other things I want/need for various reasons:

zsh / java / rake / exuberant-ctags

To install these, simply (EDIT: Added ctags here so vim would stop complaining about absence)

sudo apt-get install zsh openjdk-7-jdk rake exuberant-ctags

To change to zsh as the standard shell for your user, simply chsh, and enter /usr/bin/zsh when prompted. To fully apply these changes, log out and back in again.

Dotfiles

I have a dotfiles repo I use to keep things in sync between computers (an approach I strongly recommend). To get that going, simply:

# First download the dotfiles, and cd into them
git clone https://github.com/metasoarous/dotfiles.git ~/.dotfiles
cd ~/.dotfiles

# Backup all existing dofiles, then install new ones
rake backup
rake install

Vim setup

Now that I've switched to Vundle for vim plugin management, all of my vim plugins are managed directly through my .vimrc, making it a lot easier to set things up. The dotfiles script installs Vundle for us, so the only thing left to do is fire up vim and execute the command :PluginInstall. This will install all the plugins specified in the vimrc, which should then be available on a restart of vim.

Tmux settings

Unfortunately, the tmux package available on this version of Debian is a bit old, so there are some configuration settings that won't work. This can be amended with the following replacement in ~/.tmux.conf:

#bind-key - split-window -v -c "#{pane_current_path}"
#bind-key _ split-window -v -c "#{pane_current_path}"
#bind-key | split-window -h -c "#{pane_current_path}"
bind-key - split-window -v
bind-key _ split-window -v 
bind-key | split-window -h

Clojure specific stuff

This is actually relatively straight forward. The main thing is deciding on which Java to install. I've heard you get more mileage out of your little board if you go with Oracle JDK, but you have to add a ppa for that, so to keep things simple we'll stick with OpenJDK 7. (EDIT: Turns out there is a nasty bug that crashes OpenJDK 7 for intermittently; see link for other options; I'll be posting more soon).

# First install the JDK (already did this above...)
sudo apt-get install openjdk-7-jdk

# Download Leiningen, and make it executable
wget https://raw.githubusercontent.com/technomancy/leiningen/stable/bin/lein -O ~/bin/lein
chmod +x ~/bin/lein

# Initialize lein, and download dependencies
lein

Now you can try firing up a repl with lein repl. Note that it will likely take about three and a half minutes :-/ However, this is a lot better than the older Raspberry Pis, one of which I timed at around 20 minutes to boot a repl!

Rocking the Clojures

With the long boot times, it's highly recommended you use the reloaded and/or component pattern in your applications to avoid wasted time waiting for Clojure to boot up as you change code. Further, once you're finished developing your application and are ready to let it "just work", it's recommended you create an uberjar that you can run with java directly. This will reduce overhead on the board.

Once I've finished putting together a preliminary implementation of pin-ctrl for the BBB, I'll update this post with a link to getting that set up on the board. There will likely be some other Clojure development optimizations and customizations I'll post about in time as well.

RFC

As always please let me know in the comments if there's anything that could use clarification, or if you have any questions. I hope you found this useful.