SKILL LEVEL: FIT

Intro

The BeagleBone Black (AKA BBB) is a small, 1GHz ARM Cortex-A8 computer with a powerful NEON accelerator, many pin-outs (65!) and great power handling. In this HOWTO we’re going to use it as the core of a cellular base-station that can interact with mobile phones/handsets; manage calls between handsets, interface between handsets and SIP, sending SMSs, etc.

Why the BBB and not a Raspberry Pi? While lacking the graphical processing power of the R-Pi, the BBB is significantly faster and as such better suited to high-I/O applications like (small-footprint) cellular infrastructure. More so, unlike the R-Pi, the BBB has 4Gb of on-board storage, doing away with the need for an SD Card to boot. This makes the cost of getting setup with a BBB more or less the same as that of a R-Pi but with notably better overall performance (for most applications).

A BBB can be powered from standard 5v DC or with Mini-USB. The advantage of the latter is that during development a USB Ethernet interface can also be created, allowing command-line users a convenient way of working with the board - you get both power and network connectivity over a single USB cable.

For an example of using a DIY BTS in a Critical Engineering context, see PRISM: The Beacon Frame.

For code relating to that project, see Documentation of GSM spoofing strategy used at Transmediale, 2014.

Pre-requisites

This HOWTO assumes certain pre-requisites are taken care of.

Linux or OS X laptop (this HOWTO assumes the former)

BeagleBone black

4Gb (or more) MicroSD card (for installation only)

Micro-SDcard sleeve and SDCard reader

UHD capable Ettus USRP or RTL SDR solution (this HOWTO assumes the former - yes they’re expensive)

GSM antenna fitted to TRX mount of USRP

Wired Internet connection (for BeagleBone)

Basic knowledge of the UNIX command line (we’ll work headless).

More than a little patience

Flash Debian Wheezy 7 on eMMC

First you need a 4Gb or more MicroSD card. Stick it into your laptop, open up a terminal and type dmesg. Look for “mmcblk” in the output and note it down.

In my case I see:

[25633.985447] mmc0: new SDHC card at address b368

[25633.985738] mmcblk0: mmc0:b368 USD 3.75 GiB

[25633.987178] mmcblk0: p1 p2

For this reason I will choose mmcblk0 as the device representing the MicroSD card.

Now download the Debian image that we’ll use to flash onto the card. Now cd into a familiar place on your operating system (like /home/you/Desktop) and:

Verify the image:

md5sum BBB-eMMC-flasher-debian-7.8-console-armhf-2015-02-19-2gb.img.xz

adbfa79c6748f47e81dd233f06d98b49 BBB-eMMC-flasher-debian-7.8-console-armhf-2015-02-19-2gb.img.xz

Now we can dd it onto the MicroSD (note that I use mmcblk0 - yours may differ!):

unxz BBB-eMMC-flasher-debian-7.8-console-armhf-2015-02-19-2gb.img.xz

sudo dd if=./BBB-eMMC-flasher-debian-7.8-console-armhf-2015-02-19-2gb.img of=/dev/mmcblk0

When done take it out of the laptop and plug it into the unpowered BBB. Plug in an ethernet cable connected to your Internet gateway. I like to have both laptop and ethernet cable on a switch for this next part.

Find a mini-USB to USB cable. Plug the USB end into your laptop.

Now hold down the “Power” button and plug in the mini-USB end of the cable into the BBB, supplying power. Wait for the LEDs to start flashing and release. After a short while you’ll see a LED pulse go from left to right and back again. This indicate the Debian image is being flashed to the eMMC. It will take around 10 minutes and then stop flashing, with all 4 LEDs on and static. This indicates success.

Now remove the Mini-USB cable from the BBB, take out the MicoSD card and plug the Mini-USB jack back into the BBB.

Above information resourced from here.

Configure network between BBB and laptop

Type ifconfig -a on your laptop and you should note a new Ethernet device. In my case it’s labelled eth5. This is an Ethernet over USB device that you can use to connect directly with your BBB.

Ask for a lease from the BBB:

sudo dhcilent eth5 # change “eth5” to whatever you have on your system

Type:

ifconfig eth5

Note the IP you were given. In my case it is always 192.168.7.1. Now test to see if you can ping the BBB:

ping 192.168.7.2

Now ssh into the BBB:

Use debian:temppwd for username and password.

You should now be logged into the BBB and able to start updating.

First, check you are online with the BBB with a simple ping criticalengineering.org. It should’ve been granted an IP by your DHCP server on boot. If not, ask for a new lease.

Change password

passwd

Upgrade Linux kernel on BBB

Click on this link on your laptop and find the latest stable (non-rc) kernel for the BBB. In my case it is v3.15.2-bone2. Right-click on the link for the file “install-me.sh” and copy it to the buffer.

Now on the BBB (not on the laptop) download the file using wget, pasting the link you saved above into your terminal (note my URL may differ from yours):

Make it executable:

chmod +x install.sh

Run it:

sudo ./install.sh

When done, you’ll be asked to reboot the board. Once it’s booted, log in again and type uname -r. It should report you have a new kernel version.

Install software

Update software database:

sudo apt-get update

Install software:

sudo apt-get install vim bash-completion libboost-date-time-dev libboost-filesystem-dev libboost-program-options-dev libboost-regex-dev libboost-system-dev libboost-thread-dev libboost-test-dev subversion git build-essential cmake python-dev autoconf libtool libosip2-dev libusb-dev sqlite3 libsqlite3-dev libreadline6-dev libncurses5-dev localepurge python-cheetah php5 php5-cgi libapache2-mod-php5 libusb-1.0.0-dev libortp-dev

Once installed, type the following to clear out all the downloaded packages from the cache, recovering precious disk space:

sudo apt-get clean

Add extra storage

Now plug in a blank USB stick (or another blank MicroSD card) with more than 2Gb of storage into the BBB. This we’ll use to host the OpenBTS, OSMO-TRX and UHD code repositories.

Type dmesg and note the device in the output. In my case, an 8Gb USB stick appears as /dev/sda1:

As the user debian, create a mount point called src in the home directory of the BBB:

mkdir ~/src

Now we mount it, in such a way that our user, debian, can write to the mount point:

sudo mount /dev/sda1 ~/src -o uid=1000,gid=1000 # note that it may not be /dev/sda1 on your system!

Compile and install UHD, our interface between the BBB and USRP

UHD is the driver from Ettus Research that we need to talk to our USRP

git clone git://github.com/EttusResearch/uhd.git

cd in and create a build directory:

cd ~/src/uhd/host

mkdir build

cd build

I have the B200 USRP. If you have an E100 or other USRP, note that you’ll need to change the value for -DENABLE_B200 (below) to match your setup there. Available options are: USRP1, USRP2, B100, X300, B200.

The below command will build UHD for a USRP B200 (and thus B210), omitting documentation and manpages to preserve eMMC storage space.

cmake …/ -DENABLE_MANUAL=OFF -DENABLE_DOXYGEN=OFF -DENABLE_MAN_PAGES=OFF -DENABLE_B200=ON -DENABLE_USB=ON

Assume all went well, start compiling:

make && sudo make install

Now go and do something entirely unrelated and come back in an hour. Hopefully you’re greeted by sudo asking you for a password needed for install.

Now let’s download the latest firmware using a Python script installed in the last step.

sudo /usr/local/lib/uhd/utils/uhd_images_downloader.py

Compile and install osmo-trx, an ARM-friendly GSM transceiver

The Transceiver52M that ships with OpenBTS is unusable on the BBB. For this reason we’ll install an alternative transceiver called osmo-trx, written by the fine folks at OSMO-COM.

Fetch and build osmo-trx

cd ~/src

git clone git://git.osmocom.org/osmo-trx

It’s very important we compile osmo-trx using the –with-neon option.

cd osmo-trx

autoreconf -i

./configure --with-neon

make

sudo make install

Check out OpenBTS and compile

OpenBTS is the software that provides us with the software part of a cellular station. It allows us to control the transceiver, manipulate our cell station, interface with SIP (for calls and SMS) and all sorts of other things. Importantly we won’t install the OpenBTS applications that are built in the process, rather choosing to place them in a folder in /home/debian/bin.

Ensure you’re in the /home/debian/src directory.

Check out OpenBTS with subversion:

svn co http://wush.net/svn/range/software/public openbts #save as openbts

We need to compile and install a53 first:

cd openbts/a53/trunk

sudo make install

We need to edit a Makefile to represent the correct architecture. While the rest of OpenBTS is fine, the Transceiver component (which we actually replace with osmo-trx) is not. I didn’t find a convenient way or disable the Transceiver52M component. It was easier/faster just to make this one small change to finish the compile:

In the file ~/src/openbts/openbts/trunk/Transceiver52M/Makefile.in, change the line that reads:

AM_CFLAGS = $(STD_DEFINES_AND_INCLUDES) -std=gnu99 -march=native

To:

AM_CFLAGS = $(STD_DEFINES_AND_INCLUDES) -std=gnu99 -march=armv7-a

Now move into the OpenBTS trunk and get building:

cd ~/src/openbts/openbts/trunk

autoreconf -i

./configure --with-uhd

make

Now go and learn an endangered natural language, take up horse-back archery or go to Micronesia in search of a rare, carnivorous and aquatic snail. On your return OpenBTS may have compiled.

Original OpenBTS installation notes are here.

Setup the OpenBTS sqlite3 database

This db holds the runtime configuration of OpenBTS:

sudo mkdir /etc/OpenBTS

sudo sqlite3 -init ./apps/OpenBTS.example.sql /etc/OpenBTS/OpenBTS.db “.quit”

Compile sipauthserve, for cellular subscriber registration

sudo mkdir -p /var/lib/asterisk/sqlite3dir

cd ~/src/openbts/subscriberRegistry/trunk

make

Copy over a database for sipauthserve to work with:

sudo sqlite3 -init subscriberRegistry.example.sql /etc/OpenBTS/sipauthserve.db “.quit”

Compile smqueue, our message manager

Smqueue stores and forwards messages received and sent by OpenBTS in a delay-tolerant way

cd ~/src/openbts/smqueue/trunk/

autoreconf -i

./configure

make

Smqueue needs a database for messages in and out of the system:

sudo sqlite3 -init smqueue/smqueue.example.sql /etc/OpenBTS/smqueue.db “.quit”

Copy compiled binaries to ~/bin folder

Now we’ll now put our freshly compiled OpenBTS applications into a convenient folder:

mkdir ~/bin # probably already exists

cp ~/src/openbts/smqueue/trunk/smqueue ~/bin/

cp ~/src/openbts/subscriberRegistry/trunk/sipauthserve ~/bin

cp ~/src/openbts/openbts/trunk/apps/{OpenBTS,OpenBTSCLI} ~/bin/

You can now unmount the storage device you used to hold the source code we compiled and remove it from the BBB. We don’t need it anymore.

Test the BTS

Now plug in your USRP. You may need to power the BBB from DC as USB power will likely not be enough to drive something like a B200!

Start osmo-trx with the filler table option “Enable C0 filler table”. This enables OpenBTS style idle bursts and retransmissions.

sudo osmo-trx -f

Wait for it to report that the transceiver is up and running. Once it is, SSH in with another terminal and type the following:

cd ~/bin

sudo ./smqueue &

sudo ./sipauthserve &

sudo ./OpenBTS &

Wait for OpenBTS to report that it’s running. You should see something like:

system ready

use the OpenBTSCLI utility to access CLI

Take out your phone and search for networks. You should see a 00101 network. Now start the OpenBTSCLI:

sudo ./OpenBTSCLI

Type ‘help’ to see available commands. Interesting commands to immediately familiarise yourself with are:

config <-- dump or set the configuration of your BTS

tmsis <-- list IMSIs attached to your BTS

rxgain <-- list or set the gain, in dBm, of your BTS

sendsms <-- send an SMS to an IMSI

For instance, to allow for automatic registration, use the following command (warning, your neighbours may connect automatically!):

config Control.LUR.OpenRegistration .*

To set the MNC of the BTS to 07 and the MCC to 262 (Germany) on channel 85, you would:

config GSM.Identity.MNC 07

config GSM.Identity.MCC 262

config GSM.Radio.C0 85

Next steps

A natural next step would be to install Asterisk, turning your BTS into a fully functional PBX or communications server. That way people can make calls through your BTS and onto other SIP addresses on the Internet from their phone.

Another would be to write shell-scripts to automate the start up process. I like to write scripts that are started in /etc/rc.local and poll ps intermittently to ensure OpenBTS and/or osmo-trx are still running.

Our finished ‘BoneTS’: BeagleBone Black with 12000mAh 5V Battery, USRP B200 and Vert900 Antenna.