Beaglebone black dashboards

This project is maintained by Colm Vize

Designing a dashboard for development teams using the BeagleBone Black

The BeagleBone black is a small PCB which is slightly bigger than a raspberry pi but it packs quite a bit more of a punch. It is designed by The BeagleBoard Foundation. It boasts 512Mb of DDR3 RAM with a Sitara AM3358BZC100 ARM processor at the cost of $65. The downside of using the BeagleBone Black is that it does not support any better resolution than 1280 x 720 which means it's not suitable for use as a media centre, but it's perfect for making a dashboard which can display any number of different important live statistics for convenience around an office/workspace. In this guide I will give you a step by step process on how I created some dashboards for PageFair. Alternatively I am available to do this if you're located in Dublin or the surrounding area, see contact info for my details.

The process

You will need the following items:

Optional:

The files referenced in this guide are all available in a git repository I have provided here. To begin setting up the board plug in the cables and once the power supply is connected it should boot immediately. The board comes pre-installed with a distribution of linux known as Ångström. This is an embeded linux so it's quite different to others in that a lot of software is either missing or replaced by busybox alternatives. This list of steps should always work as long as you have a supported wifi dongle. If you don't have one you may need to compile the relevent drivers which takes considerable effort. Upon writing this I used the Keebox W150NU and it was supported by Ångström out of the box.

Setting up wifi for the dashboard

Ångström uses the debian-style /etc/networks/interfaces file to configure networks, this is good as it's quite simple and convenient to use.

Write this to /etc/network/interfaces:
auto lo
iface wlan0 inet dhcp
    wireless_mode managed
    wireless_essid any
    wpa-driver nl80211
    wpa-conf /etc/wpa_supplicant.conf

For some reason DBUS on Ångström is configured to start wpa_supplicant at boot, we don't want that as we're going to use systemd to monitor our wifi connection.

Run this command as root:
# pkill wpa_supplicant
# rm /etc/dbus-1/system.d/dbus-wpa_supplicant.conf

In this guide I'm using wpa_supplicant to connect to wifi, this is a great little program that can connect to pretty much any kind of wifi setup. It uses a configuration file in /etc/wpa_supplicant.conf. Unfortunetly its config parser leaves a lot to be desired so try to be careful as it doesn't like whitespace. I will give an example wpa_supplicant config that can connect to a wifi network using WPA2 with a pre shared key. There is copious amounts of documentation for pretty much every other kind of setup available here.

network={
    ssid="my wifi network"
    scan_ssid=1
    key_mgmt=WPA-PSK
    psk="my password"
}

Next we setup our init script that will start this on boot. This is a moderately crude script that will get the wifi connected using ifup. It will work in most cases and if the dashboard can't connect to the internet it's probably because you're completely disconnected.

Write this file to /etc/init.d/wifi:
#!/bin/bash
case $1 in
    start)
        while true;
        do
            ifup wlan0
            if [ $? -eq 0 ]
            then
                ping 8.8.8.8 -c 1
                if [ $? -ne 0 ]
                then
                    ifdown
                    continue
                else
                    break
                fi
            fi
        done
        ntpdate time.tcd.ie
        syslogd
        exit 0
    ;;
    stop)
        ifdown wlan0
        exit 0
    ;;
    restart)
        $0 stop
        $0 start
    ;;
    status)
        ping 8.8.8.8 -c 3 >/dev/null 2>&1
        if [ $? -ne 0 ]
        then
            echo "wlan0 is down"
        else
            echo "wlan0 is up"
        fi
        exit 0
    ;;
    *)
        echo "$0: start/stop/restart/status"
        exit 1
esac

Systemd is next on our todo list. Systemd is a series of tools that monitor services running on linux-based systems, it's quite similar to supervise except it's designed for just system services rather than anything. It uses the directory /etc/systemd/ for most of its configuration. Systemd uses files known as unit files for configuring services.

Write this file to /etc/systemd/system/wifi.service:
 [Unit]
Description=Start wifi
ConditionPathExists=|/usr/bin


[Service]
Type=oneshot
RemainAfterExit=yes
ExecStart=/etc/init.d/wifi start
ExecStop=/etc/init.d/wifi stop
ExecReload=/etc/init.d/wifi restart
ExecStatus=/etc/init.d/wifi status

[Install]
WantedBy=multi-user.target

We then want to enable the wifi in systemd

Run this command as root:

# systemctl enable wifi
# systemctl start wifi

Now you are connected to wifi, and every time it boots it should connect by itself. Now for an example of what you can do with the board. Setup chromium to auto launch on boot and load a website. This can be anything from recent sign-ups on a website, a build monitor, a scrum board or even the news. We can startup chromium in kiosk mode to make it fullscreen so we can get the maximum use of the monitor and then using TamperMonkey we can auto-login and scroll and zoom and otherwise present the page for optimal viewing from your monitor. Unfortunately there's a few catches; chromium on Ångström is quite out of date and can't install recent versions of TamperMonkey, so we use an old version of it and it wasn't built with the google api keys required to do certain things so there's an annoying border at the top of the browser. Don't worry however I've got a workaround for the latter.

First we setup the environment for chromium to launch correctly, you'll need to write a little script for this.

This is an example of how you launch it, you'll need to modify this command to change the website you want chromium to launch and you need to put it somewhere (/opt for example)
#!/bin/bash
GOOGLE_API_KEY=placeholder GOOGLE_DEFAULT_CLIENT_ID=placeholder GOOGLE_DEFAULT_CLIENT_SECRET=placeholder /usr/bin/chrome/chrome --user-data-dir=/root --incognito --kiosk http://user:pass@mystatsdomain.mywebsite.com/

By providing the environment variables we sate chromiums need for API keys even though they're clearly not real. We start in incogneto mode so that it wont ask if we want to relaunch tabs on boot as ideally we just want to plug in the board and it will just work, no keyboards or mice attached to tweek them.

To get gnome (the desktop enviroment that Ångström uses) to launch chromium on login we need to create a file to tell gnome to do it.

Here's how we do it:
# mkdir -p ~/.config/autostart
Then using your favorite editor write this to ~/.config/autostart/chromium:
[Desktop Entry]
Name=Chromium startup
GenericName=Startup chrome
Exec=/path/to/chromium_environment_script.sh
Terminal=false
Type=Application
X-GNOME-Autostart-enabled=true

/path/to/chromium_environment_script.sh refering to wherever you put the script we created from the previous step.

The next step involves installing an old version of TamperMonkey. First we get the extension.

Run this command:
# cd ~
# wget http://tampermonkey.net/crx/tm_legacy.crx

Now we need to install this to chromium, this step requires you to be using the desktop environment as you need to use chrome.

Start chrome using this command as it wont launch using the menu buttons:
 # /usr/bin/chrome/chrome --user-data-dir=/root --enable-easy-off-store-extension-install 

Then you want to open the extensions settings page in settings and drop the file tm_legacy.crx on to the page in chromium. This file should be should be in your home folder. This should install an old version tampermonkey which is compatible with this version of chromium. The old version does have a couple of gotchas however. To add a script you need to click on the options button in the extension in the extensions settings page. Another one is the behaviour of the @include directive in userscripts seems to have been different in older versions, you will need to set this to the same value as @match to stop the script from matching pages it shouldn't.

Pitfalls while using Ångström

Ångström has a few pitfalls that other linux distributions don't have, needless to say it was quite a journey getting this process working

Dropbear is used for an SSH server on Ångström, this makes sense as it's a tiny statically compiled ssh server. However there is a problem is that it allows passwordless root logins. I tried to figure out a real way of stopping dropbear from doing this but it ran out of scope so the solution I suggest is to just remove the daemon from /usr/sbin/dropbear which will stop it from being able to be started at boot. It doesn't really matter unless you have things you want to protect on the board which in certain cases may be true, i.e. you're using an ssh key to access an internal build monitor. If anyone finds a better way of doing this please let me know and I will update this immediately.

The way the auto-login system in Ångström requires a passwordless root account so don't change the password or you'll break it.

Don't try to update software on the boards in Ångström, opkg is kinda treacherous as it lacks the robustness of a proper package manager and will leave your system in an unstable state.

It can be useful to create an image of the board using dd so that if you have made a mistake you have a recovery step or even to speed up configuration.

Final thoughts

Thank you for sticking to this and I hope it's been useful for you. Ångström is a part of the Yocto project which is a framework for building embeded distributions of linux. For this reason it lacks a lot of useful software and sometimes replaces them with incomplete variations, for example wget in Ångström lacks a lot of functionality that is pretty essential (https being the big one). I can see why this could be necessary and even when I don't I'm sure there's a reason. I would however argue that the beaglebone black would be far more useful if it came installed with something like debian or ubuntu as it can be quite difficult to do certain things using Ångström as I'm sure you've noticed. For more complicated dashboards it is probably worth it to install a version of ubuntu as it comes with a full repository of stable software which unfortunatly Ångström lacks. Finally I would like to thank Sean and Brian from PageFair for the support and advice during this project as well as commissioning it.

Contact

I can be contacted preferably on e-mail at vizec@tcd.ie or on twitter @mloccy. Feel free to contact me about the guide and if you're interested in having me design one for you