|Version 77 (modified by kurtis.heimerl, 20 months ago)|
Table of Contents
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.
A complete installation of OpenBTS P2.8 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.
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?)
- Ettus Research USRP1
- Ettus UHD Devices (e.g., USRP2?, N200 Series, B100)
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
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 should, in principle, build and run on any Unix-like operating system. However, in practice, most of our development is done on Ubuntu 10 systems, so these are best-supported.
Building for Range equipment is easiest, as it has no external dependencies. Just run the following commands:
autoreconf -i ./configure make
If you are "rolling your own" with Ettus USRP hardware, 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. If you ordered an older USRP-based Range Developers' Kit, GNU Radio is already installed. If you have a newer RAD1-based Range Developers' Kit, GNU Radio is not required.
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, run the following 'auto-foo' process.
Standard two daughterboard configuration (Tx side A, Rx side B):
autoreconf -i ./configure --with-usrp1 make
Single daughterboard configuration (Tx and Rx on side A). Side B is unused.
autoreconf -i ./configure --with-usrp1 --with-singledb make
For all other Ettus Hardware (USRP2, B100, N200 and E100 series) you use the UHD (universal hardware device) libraries. The download of these libraries is demonstrated here and the installation here. Configuration options depend on the type of device.
USRP2 and N200 series require host-based resampling support:
autoreconf -i ./configure --with-uhd --with-resamp make
B100 and E100 series:
autoreconf -i ./configure --with-uhd make
Additional built time options for UHD devices include 10 MHz external reference support. For example, to use the front panel reference input on a N210, configure with the following options:
autoreconf -i ./configure --with-uhd --with-resamp --with-extref make
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) cd Transceiver52M make 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/
If you are using a Range Networks basestation unit these links are
(from OpenBTS root) cd apps make ln -s ../TranceiverRAD1/transceiver . ln -s ../TranceiverRAD1/ezusb.ihx . ln -s ../TranceiverRAD1/fpga.rbf .
and GNU Radio is not required.
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
This generates 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.
Build and Install the 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.
In the svn repository there is a sql file that you need to create the Subscriber Registry. It is located at:
To setup the Subscriber Registry database run:
sudo mkdir /var/lib/asterisk/sqlite3dir sudo sqlite3 -init subscriberRegistryInit.sql /var/lib/asterisk/sqlite3dir/sqlite3.db
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) 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) sqlite3 -init sipauthserve.example.sql /etc/OpenBTS/sipauthserve.db
With sipauthserve installed, you can run OpenBTS. To do so, run the following command
(from the OpenBTS directory) cd apps sudo ./OpenBTS
You should see a splash screen describing the project, and then a command-line interface:
To camp phones, you'll also need to run sipauthserve:
(from sipauthserve home) sudo ./sipauthserve
If this doesn't work, check out the common errors.
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 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
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. 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 two primary open-source PBX/Soft switches available. These are Asterisk and FreeSwitch. 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 both 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, most documented, and generally simplest option. 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, harder to set up, and having less support. The steps for installing and configuring FreeSwitch to work with OpenBTS are documented here.
Yate is another SIP switch in active development. Instructions for interoperating with Yate are 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
Now run each individual executable in a separate terminal/window. These would be:
openbts/trunk/apps/OpenBTS smqueue/trunk/smqueue/smqueue subscriberRegistry/trunk/sipauthserve
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 connection. Call 600 from the phone (9196 with FreeSWITCH) to call the "echo" service. If that's working, congrats!
OpenBTS is a registered trademark of Range Networks, Inc.