ITP is running OpenBTS 2.8 on Ubuntu 11.04 with a USRP2 Software Radio from Ettus Research with an RFX900 Daughterboard.
What is OpenBTS?
OpenBTS is a Unix application that uses a software radio to present a GSM air interface to standard 2G GSM handset and uses a SIP softswitch or PBX program to connect calls. The combination of the global-standard GSM air interface with low-cost VoIP backhaul forms the basis of a new type of cellular network that can be deployed and operated at substantially lower cost than existing technologies in many applications, including rural cellular deployments and private cellular networks in remote areas.
What makes up the OpenBTS System?
- Ubuntu 12.04LS clean install.
- Prerequisites and basic updates suggested after a new Ubuntu install.
- GNU Radio and UHD drivers which are the software radio components that allow control and modulation over the USRP Radio. They also have prerequisite libraries to install.
- OpenBTS itself. Currently version 2.8 Opelousas. This is the GSM implementation and the main SIP interface which is normally on port 5062.
- Transceiver. This is the software radio-modem which is started by OpenBTS automatically.
- A SIP PBX or softswitch (Asterisk, FreeSwitch, etc.). This component connects speech calls. Its SIP interface is normally on port 5060. This is not packaged with OpenBTS and needs to be installed separately and following a non-standard procedure mentioned in this guide. Note that, if using Asterisk as in this guide, Asterisk will need the ODBC module installed and supporting libraries for proper configuration because it needs to communicate in realtime with the databases that store the phone and IMSI numbers. An IMSI number is the unique identifier of a SIM card.
- Sipauthserver. This is the SIP registration and authorization server, used to process location updating requests from OpenBTS and perform corresponding updates in the subscriber registry database. Its SIP interface normally runs on port 5064.
- Smqueue. This is the store-and-forward text messaging server. It needs to be started independently of OpenBTS. Its SIP interface is normally run on port 5063. Smqueue is not required in installations that do not support text messaging.
- Rrlpserver. This is the RRLP aiding server and it is run as a CGI script in a web server. Rrlpserver is not required if RRLP is not being used.
- A laptop, desktop or other CPU running Linux (most supported are Ubuntu 10.04, 11.04, 11.10, 12.04). This guide uses Ubuntu 12.04LS. Versions exist also for Windows and Mac OSX. It’s important that the computer is capable of Gigabit Ethernet and that the Ethernet card supports those speeds.
- A USRP device from one of the recommended vendors (Range, Ettus, or else). There is a wide range of radio modems depending on the application and requirements. The radio I have worked the most with is the USRP2 which has now been replaced by the USRP-N Series. I currently use USRP-N200 and this guide refers to that specific model. http://www.ettus.com/home
- RF Daughterboard, in the RF range desired for operation. This guide uses the configuration for USRP2 and N-Series with 1 RFX1800 daughterboard, which can cover the range of any band within 750-2100MHz. http://www.ettus.com/home
- An RX and a TX antenna just for testing purposes, not to actually obtain large range of operation and also because you need an antenna plugged in to not burn the board out. Recommended small GSM quad-band or penta-band antennas.
- 2 or more 2G handsets (regular phones and smart phones) that work at the chosen cellphone band or are quad-band phones.
OpenBTS has a Radio physical layer in order to reproduce the GSM frequency. GSM is frequency duplexed, meaning that the network and MS transmit on different frequencies, allowing the BTS to transmit and receive at the same time. Transmission from the network to the MS is called “downlink”. Transmission from the MS to the network is called “uplink”. GSM uplink and downlink bands are separated by 45 or 50 MHz, depending on the specific band. Uplink/downlink channel pairs are identified by an index called the ARFCN.
You will need to first install software to support that radio. The required support driver depends on the type of USRP device. For the USRP1, this is GnuRadio. For all other Ettus Hardware (USRP2, B100, N200 and E100 series) you use the UHD (Universal Hardware Device) libraries.
A complete OpenBTS P2.8 installation, in summary, comprises of several distinct applications:
- OpenBTS – The actual OpenBTS application, containing most of the GSM stack above the radio-modem.
- Transceiver – The software radio-modem and hardware control interface.
- Asterisk – The VoIP PBX in the standard public release configuration. OpenBTS uses a SIP switch or PBX to perform the call control functions that would normally be performed by the mobile switching center in a conventional GSM network, although in most network configurations this switching function is distributed over multiple switches.
- Smqueue – The RFC-3428 store-and-forward server for text messaging to send text messages from one MS to another.
- Subscriber Registry – A database of subscriber information that replaces both the Asterisk SIP registry and the GSM Home Location Register (HLR).
- Other Servers – Other optional GSM services, beyond speech and text messaging, are supported through external servers.
Steps to Install OpenBTS
The following step-by-step guide is based on the incredibly useful OpenBTS Public Wiki. It's recommended to read the latest news and make sure that the installation steps are executed in the right order.
1. Install Ubuntu.
Go to the Download Ubuntu page to do a clean install of any Ubuntu version from 10.04 to the current latest version of Ubuntu, Oneiric Ancelot 12.04LS. If the machine comes with the newest version freshly installed, then hopefully you can skip this step.
1.a Install Extras.
I usually follow the 10 to 25 steps recommended after a clean Ubuntu install. Those usually involve installing apt, aptitude and other important packages, run all updates, plugins and codecs like restricted extras, proprietary drivers (if any are necessary) and main applications needed.
1.b Fix Network Manager issues.
After a clean Ubuntu install is possible to have internet service but Network Manager does not properly recognize or manage the networks. If Wired or Wireless networks are Not Managed in the Network Connections menu, please do the following:
sudo gedit /etc/NetworkManager/NetworkManager.conf
Press (ctrl+s) and close the file, then type:
sudo service network-manager restart
This should take care of the issue, in my experience.
Asterisk is the PBX software I prefer to use, but there are alternatives such as FreeSwitch. If you plan on seriously delving into Asterisk, then I suggest installing and building Asterisk from source for a complete 1.8 version. In that case I recommend following the instructions described at http://www.asterisk.org/ or in a Asterisk book (more about those resources below). For a demo unit, Asterisk can be installed using a package manager, but it will require a couple of additional modules as covered further below. FreeSwitch is a great alternative, but not as documented. To install Asterisk from package manager in Ubuntu, run the following command:
sudo apt-get install asterisk
During configuration and install process you may be asked to supply your country code to set telephony preferences for your area. See here for the right codes:
In order to use Asterisk as PBX for OpenBTS, we will have to modify a few files and configure a couple of modules, I will explain those steps further below.\\
3. Software Phone, like Twinkle [optional]
If you want to test Asterisk with a Software Phone application, you can download and install something like Twinkle (which is free) for Linux or iSoftPhone (paid) for Mac OSX.
On Ubuntu machine, you can run:
sudo apt-get install twinkle
4. Create Directory
Make a directory called OpenBts where you will place everything related to the OpenBTS system by running the following command, not as sudo in order to give access to all users:
5. GNU Radio
GNU Radio is the software used to communicate with the USRP device. If using a USRP1 model, then a version higher than 3.3 and lower than 3.5 is required. http://gnuradio.org/redmine/projects/gnuradio/wiki/
If you are planning on using the USRP2 or N series devices, then you can use the latest version of GNU Radio, which can be installed using the script below. In fact, for the USRP2 or N series all you need GNU Radio for are the UHD drivers.
Copy and Paste or download the script from here:
Place the build-gnuradio file inside your OpenBts folder where you will build GNU Radio. This script not only builds GNU Radio but also all the prerequisite libraries, thanks a lot to the developer Markus for making it so easy. Cd into the OpenBts folder and run the following commands not as root:
NOTE: This process usually takes 3 or more hours! Let it run its course and monitor for errors. This script downloads and builds the latest version of GNU Radio.
chmod a+x build-gnuradio
6.a OpenBTS prerequisites
To properly compile and install OpenBTS install the following:
autoconf (sipauthserve only)
libboost-all-dev (very important for asterisk OCBD realtime driver)
These can be installed with the following command:
sudo apt-get install autoconf libtool libosip2-dev libortp-dev libusb-1.0-0-dev g++ sqlite3 libsqlite3-dev libboost-all-dev libreadline6-dev erlang
Install subversion as well with the same method. And also git is really useful for pulling repositories.
6.b Downloading OpenBTS
The best way to get OpenBTS is by pulling the code directly from the source code repository as an anonymous read-only user by running the following command (for version 2.8):
svn co http://wush.net/svn/range/software/public
if svn is not installed, first run:
sudo apt-get install subversion
If you're planning on developing for OpenBTS, we recommend using git instead of svn. This allows you to commit and test your code locally, before uploading it to the main repository.
(for version 2.8)
git svn init http://wush.net/svn/range/software/public openbts
git svn fetch
If git is not installed, run the appropriate apt-get command to install it first.
6.c Building OpenBTS
To build OpenBTS fist cd into the appropriate folder:
Then depending on what hardware radio you are using you can configure accordingly. USRP2 and N200 series require host-based re-sampling support and use UHD drivers, so you would run the following commands:
./configure --with-uhd --with-resamp
Additional built time options for UHD devices include 10 MHz external reference support (we are not using this). For example, to use the front panel reference input on a N210, configure with the following options:
./configure --with-uhd --with-resamp --with-extref
For USRP1 Single daughterboard configuration we use GNURadio driver and would run the following command:
./configure --with-usrp1 --with-singledb
With the build resolved, you'll need to build and link the transceiver appropriate for your hardware. For the USRP/UHD installs:
(from OpenBTS root)
ln -s ../Transceiver52M/transceiver .
6.d Configuring OpenBTS
With OpenBTS built, you now need to configure it to run correctly. There are key files that must be created for this to happen. For example
OpenBTS.db is the database store for all OpenBTS configuration. It must be installed at /etc/OpenBTS, which likely does not exist. So, to create this file:
(from the OpenBTS directory)
sudo mkdir /etc/OpenBTS
sudo sqlite3 -init ./apps/OpenBTS.example.sql /etc/OpenBTS/OpenBTS.db ".quit"
This generates a lot of stock configuration options. You can find these listed here: https://wush.net/trac/rangepublic/wiki/openBTSConfig. Most of these only need to be tweaked if you are moving beyond a simple desktop setup. However, a few are required for basic operation. These are:
- GSM.Radio.Band - Set this to the GSM band appropriate for your hardware.
- GSM.Radio.C0 - This is the ARFCN. Set it to something appropriate for your band as described below.
- Control.LUR.OpenRegistration - Set this to a regular expression of numbers matching the IMSIs of your test phones. This tells OpenBTS to not reject your handset just because your registration server (below) isn't responding. Useful for debugging and initializing the system.
To edit the OpenBTS.db file I recommend downloading and installing SQLite Database Browser which allows to visualize the entire database and its fields.
sudo apt-get install sqlitebrowser
Or another great program:
sudo apt-get install sqliteman
Then you can run SQLite Database Browser or SQLite Manager by calling it in terminal:
Let's take for example setting up the system in the Netherlands, where there are specific channels and frequencies allowed and open for research purposes.
NOTE: The Dect Guardband is a frequency band between 1877 MHz and 1880 MHz (in duplex band between1782 MHz and 1785 MHz). The maximum capacity without a license is 200 mW ERP (Effective Radiated Power). Therefore the Radio can be programmed on the Channel 871, but any of these channels would work.
You can find the complete list of Channels here: http://gnuradio.org/redmine/attachments/115/all_gsm_channels_arfcn.txt#L829
829 Channel: 871; Band: GSM-1800 Uplink: 1782 MHz, Downlink: 1877 MHz
830 Channel: 872; Band: GSM-1800 Uplink: 1782.2 MHz, Downlink: 1877.2 MHz
831 Channel: 873; Band: GSM-1800 Uplink: 1782.4 MHz, Downlink: 1877.4 MHz
832 Channel: 874; Band: GSM-1800 Uplink: 1782.6 MHz, Downlink: 1877.6 MHz
833 Channel: 875; Band: GSM-1800 Uplink: 1782.8 MHz, Downlink: 1877.8 MHz
834 Channel: 876; Band: GSM-1800 Uplink: 1783 MHz, Downlink: 1878 MHz
835 Channel: 877; Band: GSM-1800 Uplink: 1783.2 MHz, Downlink: 1878.2 MHz
836 Channel: 878; Band: GSM-1800 Uplink: 1783.4 MHz, Downlink: 1878.4 MHz
837 Channel: 879; Band: GSM-1800 Uplink: 1783.6 MHz, Downlink: 1878.6 MHz
838 Channel: 880; Band: GSM-1800 Uplink: 1783.8 MHz, Downlink: 1878.8 MHz
839 Channel: 881; Band: GSM-1800 Uplink: 1784 MHz, Downlink: 1879 MHz
840 Channel: 882; Band: GSM-1800 Uplink: 1784.2 MHz, Downlink: 1879.2 MHz
841 Channel: 883; Band: GSM-1800 Uplink: 1784.4 MHz, Downlink: 1879.4 MHz
842 Channel: 884; Band: GSM-1800 Uplink: 1784.6 MHz, Downlink: 1879.6 MHz
843 Channel: 885; Band: GSM-1800 Uplink: 1784.8 MHz, Downlink: 1879.8 MHz
Or if you notice too much interference, you can try and use a different band that is not being used in the US.
These values can be modified, in the most recent version of OpenBTS, from OpenBTSCLI with the config command:
config GSM.Radio.Band 1800
config GSM.Radio.C0 880
config Control.LUR.OpenRegistration *
7. Subscriber Registry and Sipauthserve
OpenBTS depends on the installation of Sipauthserver the SIP authorization server. You'll need to build and install it before running OpenBTS.
7.a Subscriber Registry
To setup the Subscriber Registry database run:
(from svn root)
sudo mkdir -p /var/lib/asterisk/sqlite3dir
sudo sqlite3 -init subscriberRegistryInit.sql /var/lib/asterisk/sqlite3dir/sqlite3.db ".quit"
Sipauthserve is an aptly-named daemon providing SIP authentication services. The SIP.Proxy.Registration config variable in openbts should point to its hostname and port. To build Sipauthserve, you MUST HAVE ALREADY BUILT OPENBTS. This is a makefile hack, and will hopefully be fixed at some point in the future. To build Sipauthserve:
(from svn root)
This will produce a sipauthserve executable.
As with OpenBTS, you'll need to configure sipauthserve. We assume /etc/OpenBTS/ already exists.
(from subscriberRegistry root)
sudo sqlite3 -init sipauthserve.example.sql /etc/OpenBTS/sipauthserve.db ".quit"
Smqueue is the store-and-forward message service packaged with OpenBTS. Building and running is very similar to the process used for OpenBTS.
8.a Build and Install
In the smqueue/trunk directory, run the following commands:
You should now have an smqueue executable in the smqueue/trunk/smqueue directory.
8.b Configuring Smqueue
Similar to OpenBTS, Smqueue also depends on a configuration file, located at /etc/OpenBTS/smqueue.db. Smqueue creates an empty, nonfunctional version of this db if it is not available. That's of no use to anyone. Instead, do as we did with OpenBTS and run the following command:
(from the smqueue directory)
sudo sqlite3 -init smqueue/smqueue.example.sql /etc/OpenBTS/smqueue.db ".quit"
That will initialize /etc/OpenBTS/smqueue.db with default values. These configuration variables should work without modification, and are listed here: https://wush.net/trac/rangepublic/wiki/smqueueConfig
9. Configuring the PBX (Asterisk 1.8)
Asterisk is the "standard" OpenBTS PBX and is shipped in the commercial units. It's the easiest to set up, most documented, and generally simplest option. The steps for installing and configuring Asterisk to work with OpenBTS are located here: https://wush.net/trac/rangepublic/wiki/asteriskConfig
9.a Asterisk RealTime with ODBC Connector
The previous command should have downloaded the latest version (1.8) or you can build from source by following the instructions on the Asterisk wiki. https://wiki.asterisk.org/wiki/display/AST/Home
For Asterisk to work with OpenBTS, Sipauthserve, Smqueue and all, we need to install and configure MySQL and ODBC. For a detailed series of steps (it would take a guide by itself to do!) please refer to the steps highlighted in Chapter 16 and 18 of Asterisk, The Definitive Guide published by O’Reilly: http://ofps.oreilly.com/titles/9780596517342/
And then follow the steps mentioned here:
10. Running It All
If you are not going to require WiFi or other networking capabilities for your machine while running OpenBTS you can disable networking, otherwise keep networking enabled. Plug the Radio power supply into an outlet and after the power lights come on, plug it into the computer through the Ethernet Cable. Now follow these easy steps to run the entire system:
- Turn off firewall. Ubuntu has a new firewall feature that conflicts, so we need to turn off by saying:
sudo ufw disable
- Give the port a static IP. The Ubuntu network needs to be manually configured to talk to the Radio, so we use the
ifconfig command to get it to bind to a specific address ( you need to do it each time you start the system).
sudo ifconfig eth0 192.168.10.1 netmask 255.255.255.0 promisc
If it worked, and you run the
ifconfig command again, you should see something like:
Link encap:Ethernet HWaddr 00:22:15:d3:7e:1f
inet addr:192.168.10.1 Bcast:192.168.10.255 Mask:255.255.255.0
inet6 addr: fe80::222:15ff:fed3:7e1f/64 Scope:Link
UP BROADCAST RUNNING PROMISC MULTICAST MTU:1500 Metric:1
RX packets:8752 errors:0 dropped:0 overruns:0 frame:0
TX packets:8993 errors:0 dropped:0 overruns:0 carrier:0
RX bytes:2712616 (2.7 MB) TX bytes:2769249 (2.7 MB)
Interrupt:43 Base address:0x8000
- Make sure the computer recognizes the UHD Device. To test if this works you can find your USRP N200 by issuing the command:
If everything is plugged in together and installed correctly, in the terminal you will read:
linux; GNU C++ version 4.6.1; Boost_104601; UHD_003.004.000-b1f34b4
UHD Device 0
- Check the lights on the USRP N200. The LED indicator should show you D and F lit as well as the left light on the ethernet port lit, the port green LED, if the Ethernet cable is plugged in.
- Run each individual executable in a separate terminal window as sudo. These are:
(this is to run in verbose mode, so we get to read everything it does)
(this is what it will respond with:)
(this is the directory to look for it in)
(if everything runs correctly this is what it should respond:)
ALERT 3077551824 smqueue.cpp:2347:main: smqueue (re)starting
smqueue logs to syslogd facility LOCAL7, so there's not much to see here
(this is the directory to look for it into)
(if everything runs correctly this is what it should respond:)
ALERT 3078424272 sipauthserve.cpp:213:main: ./sipauthserve (re)starting
(this is the directory to look for it into)
(if everything runs correctly this is what it should respond:)
ALERT 3079374544 OpenBTS.cpp:148:main: OpenBTS starting, ver P2.8TRUNK build date Feb 20 2012
Copyright 2008, 2009, 2010, 2011 Free Software Foundation, Inc.
Copyright 2010 Kestrel Signal Processing, Inc.
Copyright 2011 Range Networks, Inc.
Release P2.8TRUNK formal build date Feb 20 2012
"OpenBTS" is a trademark of Range Networks, Inc.
Range Networks, Inc.:
David Burgess, Harvind Samra, Donald Kirker, Doug Brown
Kestrel Signal Processing, Inc.:
David Burgess, Harvind Samra, Raffi Sevlian, Roshan Baliga
Anne Kwong, Jacob Appelbaum, Joshua Lackey, Alon Levy
Alexander Chemeris, Alberto Escudero-Pascual
Incorporated GPL libraries and components:
libosip2 (LGPL), liportp2 (LGPL)
This program comes with ABSOLUTELY NO WARRANTY.
Use of this software may be subject to other legal restrictions,
including patent licsensing and radio spectrum licensing.
All users of this software are expected to comply with applicable
regulations and laws. See the LEGAL file in the source code for
Starting the system...
linux; GNU C++ version 4.6.1; Boost_104601; UHD_003.004.000-b1f34b4
Welcome to OpenBTS. Type "help" to see available commands.
If you now type
help and hit return it will show a series of options and commands.
Congratulations! You now have the whole software package running properly and ready for phones to camp (aka register onto the network)!
- Check the lights again. You should now see that A C E D F LEDs on the N200 are lit and both the green and orange LEDs on the ethernet port are ON.
- Let’s camp some phones! Turn on a phone with a GSM SIM card installed. It would be best if this SIM was NOT from a local carrier; then the phone will not immediately camp to one of their towers in the area.
In most cases, on most phones, there is a way to select the specific network you wish to attach to by navigating the phone menu to scan the available networks. For this basic install, the network will most likely be announced as: 001 01
or a variation. Connect the phone to that network. Your BTS should reply with a Welcome message, allowing the phone to associate and send back a desired 7 digit unique number. If this fails, make sure you set the Control.LUR.OpenRegistration variable in OpenBTS.db.
With these two tests passed, you can now test the connection to the network. Register two phones and see if you can call each other’s numbers or send an SMS to each other. If that's working, congrats again! You now have a working system!
- tmsis. In the OpenBTS terminal screen you can type the command
tmsis and this should show you the IMSI numbers of the SIM cards that are now associated and are camping on the network.
- Just as a recap, the local addresses and ports for all the applications to run on are these:
- The extension numbers for the registered phones are saved into the
sqlite3.db under the sip_buddies table. You can edit the entries in this table in order to erase some of the extensions or IMSI numbers that have been registered. The path for the SIP_BUDDIES table is:
- If in running OpenBTS you encounter this message:
ortp-warning-Must catchup 51 miliseconds.
ortp-warning-Must catchup 56 miliseconds.
ortp-warning-Must catchup 57 miliseconds.
ortp-warning-Must catchup 45 miliseconds.
It’s OK, it happens quite often. It just means that because of the computer hardware or the antennas, the CPU is running slightly behind but it’s catching up. It might happen if you are trying to do other things while running the entire system (like checking email, or opening an extra terminal window). The system should keep running properly regardless and if not you can try running OpenBTS with real-time priority (using the `chrt` command).
- Asterisk can be very temperamental, so it’s best to handle calls with extra care and allow for enough time to pass between initiating calls back and forth. The system, because of having just 1 daughter board, can handle innumerable amounts of SMS text messages, but it can only handle 2 voice calls (among 4 phones) at once. It was tested and it actually behaved quite well.
If you experience dropped calls it might be because of the actual GSM frequency getting spammed with other devices that might be on the same network.
If you get something similar to this Warning:
Packet timed out after 32000ms with no response
It just means that there has been some issue and some asynchronous communication between the Radio and Asterisk. Be patient and try another handheld or try killing all running processes and restart the system.
- OpenBTS is an Open Source project released under Open Source licenses and therefore in constant development and evolution, I recommend sticking to a version that has been tested by multiple organizations and for which there is extended documentation, but if you feel brave and want to update to the latest and greatest, here is a link to do so: https://wush.net/trac/rangepublic/wiki/UpdateOpenBTS
- Lastly, DO NOT UPGRADE THE OPERATING SYSTEM ON THE ITP MACHINE! A new Linux Kernel just came out, Ubuntu 12.04, but do not upgrade. You can update individual packages and applications but I recommend NOT to and definitely I advise against upgrading the OS since it will drastically change the file structure and the system might stop working. DO NOT PRESS THE UPGRADE BUTTON!
12. Useful Links