This wiki has been deprecated
Table of Contents
- Getting the Code
- Required Libraries/Utilities
- Building OpenBTS
- Configuring OpenBTS
- Running OpenBTS
- Build and Install the Subscriber Registry and Sipauthserve
- Running sipauthserve
- Building Smqueue
- Configuring Smqueue
- Running Smqueue
- Data Service
Building, Installing and Running OpenBTS
This document describes the installation of a single instance of OpenBTS on a single PC with a single radio. This default configurations support this setup, and it's the right place to start. For a multi-BTS environment, see this page.
If you are updating OpenBTS, please see UpdateOpenBTS.
If you want to install OpenBTS using debian packages, please see DebOpenBTS.
This document details installation from trunk, with all of the latest community changes. If you want to install the latest tagged release (version 3.1.3) read this document, then see InstallOpenBTSrP313.
A complete installation of OpenBTS comprises these components:
- OpenBTS itself. This is the GSM implementation from the TDMA part of L1 up through L3 and the L3/L4 boundary. Its SIP interface is normally on port 5062. This is located in openbts/trunk.
- Transceiver. This is the software radiomodem, implementing the lower part of L1. OpenBTS starts the transceiver automatically. These are located in openbts/trunk/Transceiver*.
- A SIP PBX or softswitch (Asterisk, FeeeSWITCH, etc.) This component connects speech calls. Its SIP interface is normally on port 5060. This is not packaged with OpenBTS.
- 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. This is located in subscriberRegistry/trunk.
- 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. This is located in smqueue/trunk.
- 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. This is located in RRLP/trunk.
Getting the Code
To compile the various parts of OpenBTS (minus the PBX) you'll need the following packages:
libsqlite3-dev (sipauthserve only)
These can be installed (on a Debian-flavored unix distro) with the following command:
sudo apt-get install autoconf libtool libosip2-dev libortp-dev libusb-1.0-0-dev g++ sqlite3 libsqlite3-dev erlang libreadline6-dev libncurses5-dev
You will also need to install liba53, which is included with the distribution. The following commands should install it correctly from the OPENBTS_ROOT
cd a53/trunk sudo make install
In this diagram, Black links are network connections (SIP). Red links are file system connections (sqlite3 lookups). Blue links are ODBC (network/local DB lookups).
Build and Install OpenBTS and the Transceiver
OpenBTS can be run a variety of hardware. You must first note the specific hardware being used. There are three distinct types:
- Range Equipment (e.g., RAD1?)
- Fairwaves UmTRX (use own UHD version)
- Ettus Research USRP Devices (B100, B200, B210, E100, E110, USRP1, USRP2, N200, N210)
OpenBTS should, in principle, build and run on any Unix-like operating system, including 64-bit. However, in practice, most of our development is done on Ubuntu 10 or 12.04 LTS systems, so these are best-supported.
Range Networks RAD1
Building for Range equipment is easiest, as it has no external dependencies. Just run the following commands:
cd openbts/trunk autoreconf -i ./configure make
With the build resolved, you'll need to build and link the transceiver appropriate for your hardware. For a Range Networks basestation unit these links are
(from OpenBTS root) cd apps make ln -s ../TransceiverRAD1/transceiver . ln -s ../TransceiverRAD1/ezusb.ihx . ln -s ../TransceiverRAD1/fpga.rbf .
All Other Devices (except for USRP1)
All UHD devices from Ettus Research - with the exception of the USRP1 - use the UHD (Universal Hardware Driver) with OpenBTS. In addition, the UmTRX from Fairwaves uses a its own UHD driver, which is API compatible.
UHD devices include the following:
- Ettus Research USRP
- B-Series: B100, B200, B210
- E-Series: E100, E110 (limited support)
- N-Series: N200, N210, USRP2
Instructions to install UHD can be found here.
Information on UmTRX and the Fairwaves UHD driver is available here.
To verify proper driver installation, run the uhd_usrp_probe utility installed with the UHD driver. Output should be similar to the following truncated output. Also, to facilitate of FPGA loading times, it is suggested that the uhd_usrp_probe be run at least once after powering on the device and before starting OpenBTS.
$ uhd_usrp_probe linux; GNU C++ version 4.8.1 20130603 (Red Hat 4.8.1-1); Boost_105300; UHD_003.005.004-140-gfb32ed16 -- Opening a USRP2/N-Series device... -- Current recv frame size: 1472 bytes -- Current send frame size: 1472 bytes _____________________________________________________ / | Device: USRP2 / N-Series Device | _____________________________________________________ | / | | Mboard: USRP2 r4 | | hardware: 1024 | | mac-addr: 00:50:c2:85:36:1e | | ip-addr: 255.255.255.255 | | subnet: 255.255.255.255 | | gateway: 255.255.255.255 | | gpsdo: none | | serial: 1566 | | FW Version: 12.4 | | FPGA Version: 10.1
To enable support for UHD devices regardless of type,
cd openbts/trunk autoreconf -i ./configure --with-uhd make
Create a symbolic link to the built Transceiver52M executable.
#(from OpenBTS root) cd apps ln -s ../Transceiver52M/transceiver .
Note that previously available --resamp and --extref options are removed. Device specific sample rate selection and resampling, if applicable, are now handled automatically by the transceiver. External clock referencing is now enabled through the configuration database.
To enable the external 10 MHz reference the, the entry "TRX.Reference" should be added to the OpenBTS.db configuration with a value of '1'. The default setting, which occurs when the entry does not exist or is set to '0', is to use the internal reference. Most UHD devices can operate fine with the on board TCXO. USRP2 does not include a TCXO, and use of an external reference source is required for reliable operation.
"TRX.Reference" '0' for Internal or '1' for External 10 MHz reference
The USRP1 has been deprecated by Ettus, making this install more difficult. To run OpenBTS using the USRP1, you'll need to install GNU Radio. If you ordered an older USRP-based Range Developers' Kit, GNU Radio is already installed. For more information on installing GNU Radio go here. Make sure to install something after 3.3.0, but before 3.5.0 (where they removed USRP1 support). With that installed:
Standard two daughterboard configuration (Tx side A, Rx side B):
cd openbts/trunk autoreconf -i ./configure --with-usrp1 make
Single daughterboard configuration (Tx and Rx on side A). Side B is unused.
cd openbts/trunk autoreconf -i ./configure --with-usrp1 --with-singledb make
With the build resolved, you'll need to build and link the transceiver appropriate for your hardware. For the USRP1 installs:
#(from OpenBTS root) cd apps ln -s ../Transceiver52M/transceiver . #and for the USRP1, install std_inband.rbf sudo mkdir -p /usr/local/share/usrp/rev4/ sudo cp ../Transceiver52M/std_inband.rbf /usr/local/share/usrp/rev4/
With OpenBTS built, you now need to configure it to run correctly. There are a two key files that must be created for this to happen.
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"
Test this by running:
sqlite3 /etc/OpenBTS/OpenBTS.db .dump
If you see a lot of configuration variables, the DB has been installed correctly.
At this point, we should be able to perform a basic sanity check of OpenBTS.
(from OpenBTS root) cd apps sudo ./OpenBTS
You should see output like this:
system ready use the OpenBTSCLI utility to access CLI
And if you scan for GSM towers on your phone, you should see a 00101 (test) network. If you try to attach, it will reject you. This is because OpenBTS, by default, only allows registered handsets to connect. As we are not running our registration server (sipauthserve) no phones will camp. From here, we should look at a few OpenBTS configuration variables. Connect to OpenBTS with the OpenBTSCLI command:
(from OpenBTS root) cd apps sudo ./OpenBTSCLI
and then, in the CLI
You will see a lot of stock configuration options. You can find these listed here. 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.
- Control.LUR.OpenRegistration - Set this to a regular expression 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.
The values can be modified from OpenBTSCLI with the config command. For example,
config Control.LUR.OpenRegistration .*
to allow registrations from any phone regardless of their provider. Caution: With this config all phones have access, without any restriction. When an antenna is attached, at least your neighbors will connect, so do not try this at home :-)
If these steps are complete, you have a working BTS. If they do not, check out the common errors.
You also need a home location registrar (sipauthserve), short message service center (smqueue) and switch (PBX) in order to register, send and receive sms, and send and receive calls. Those steps are below.
Build and Install the Subscriber Registry and Sipauthserve
OpenBTS depends on the installation of Sipauthserver the SIP authorization server for registration traffic. You will not be able to have a usable system without it.
To setup the Subscriber Registry database you must first create the file path the db will reside in. By default, this is /var/lib/asterisk/sqlite3dir.
sudo mkdir -p /var/lib/asterisk/sqlite3dir
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:
(from svn root) cd subscriberRegistry/trunk make
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 subscriberRegistry.example.sql /etc/OpenBTS/sipauthserve.db ".quit"
Running sipauthserve will provide you with a registration server. To do so:
(from subscriberRegistry root) sudo ./sipauthserve
sipauthserve does not have a CLI, so you'll only see a small output:
ALERT 139639310980928 sipauthserve.cpp:214:main: ./sipauthserve (re)starting
Remember, if you change any of the config variables, you'll need to restart sipauthserve for the changes to take effect.
Build and Install Smqueue
Smqueue is the store-and-forward message service packaged with OpenBTS. Building and running is very similar to the process used for OpenBTS.
In the smqueue/trunk directory, run the following commands:
autoreconf -i ./configure make
You should now have an smqueue executable in the smqueue/trunk/smqueue directory.
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. 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.
Smqueue is run with the following command:
(from the smqueue directory) cd smqueue sudo ./smqueue
Smqueue does not have a command-line interface, instead just reading configuration values and processing messages. So you'll only see a small output:
ALERT 140545832068928 smqueue.cpp:2421:main: smqueue (re)starting smqueue logs to syslogd facility LOCAL7, so there's not much to see here
Remember, if you change any of the variables, you'll need to restart smqueue for the changes to take effect.
Selecting and Configuring a PBX
There are three primary open-source PBX/Soft switches available. These are Asterisk, FreeSwitch and yate. The differences, tradeoffs, and advantages to using one system over the other are too numerous and outside the scope of this document. However, the key point is that all are actively supported and used by the OpenBTS community.
Asterisk is the "standard" OpenBTS PBX and is shipped in the commercial units. It's the easiest to set up, and most documented option. However, it's probably the most difficult. The steps for installing and configuring Asterisk to work with OpenBTS are located here.
FreeSwitch is an up-and-coming Asterisk competitor. Its interoperation with OpenBTS is supported primarily by the group at Berkeley. It provides programmatic voice and text routing, as well as a more flexible programming environment for voice/sms applications at the cost of being buggier and having less support. The steps for installing and configuring FreeSwitch to work with OpenBTS are documented here.
RRLP is a bit of a mess. As such, we generally don't think you should build it. However, if you're really interested in getting the location of your users, head over here.
Build and Install the CGIs
Running It All
Use one of the startup scripts or run each individual executable in a separate terminal/window. These would be:
smqueue/trunk/smqueue/smqueue subscriberRegistry/trunk/sipauthserve openbts/trunk/apps/OpenBTS openbts/trunk/apps/OpenBTSCLI
Then 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. For this basic install, the network will be announced as: 001 01. Connect to that network. Your BTS should reply, allowing the phone to associate. 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 voice connection. Call 600 from the phone (9196 with FreeSWITCH) to call the "echo" service. If that's working, congrats!
Lastly, we can test SMS support. Send an SMS to 101 with a 7-10 digit number (configurable in smqueue). That is now your new number in the system. Do this with a second phone/SIM and then text between them. If this is working, congrats, your SMS services are working as well!
If you wish to enable data service on your network, visit here.
By default OpenBTS logs to syslogd. As such, you can see all openbts traffic with the following command:
tail -f /var/log/syslog | grep OpenBTS
If you're seeing problems, check here for any glaring issues (Probably ALARM/ERR). You can similarly look for issues with sipauthserve and smqueue.
Please see UpdateOpenBTS.
OpenBTS is a registered trademark of Range Networks, Inc.