openbts+sw1

Contents

1 Introduction to OpenBTS: 4

1.1 What is a Base Transceiver Station: 4

2 overall architecture and implementation plan of the OpenBTS. 6

2.1 Typical “upstream” data flow in the GSM air interface of the OpenBTS: 6

2.2 Typical “downstream” data flow in the GSM air interface of the OpenBTS : 7

3 Coding: Use of Objects, Threads and C++ 7

3.1 Threads 7

3.2 Namespaces 8

3.3 Optimization 8

3.4 Testing and Consistency Checking 8

3.5 C++ Tools 8

3.6 Wrappers 8

3.7 Vector Classes 9

3.8 Interthead Classes 9

3.9 Important C++ Object Hierarchies 9

3.10 Data Transfer Object Classes 9

3.11 Logical Channel Structure and Subclasses 10

4 Time Domain Mutliplexing (TDM) Sublayer 11

5 Software Transceiver 11

6 Global GSM Object 12

6.1 Global Configuration Information 12

6.2 LCH Creation, Allocation and Deallocation 12

7 Use of SIP and Asterisk 13

8 OpenBts Modules-Files: 13

8.1 AsteriskConfig 13

8.2 CommonLib 13

8.3 Control 13

8.3.1 Introduction 13

8.3.2 CallControl.cpp: 14

8.3.3 DCCHDispatch.cpp 20

8.3.4 MobilityManagement.cpp 21

8.3.5 SMSControl.cpp 21

8.3.6 ControlCommon.cpp: 22

8.3.7 ControlCommon.h: 22

8.4 GSM 23

8.4.1 Introduction: 23

8.4.2 GSM layer 3: 23

8.4.2.2.2 L3 MM messages 27

8.4.3 GSM layer 2: 31

8.4.4 LAYER 1 : 32

8.5 SIP 34

8.6 SMS 34

8.7 TRXManager 34

8.8 Transceiver 34

8.9 apps 34

8.9.1 OpenBTS.config 34

8.9.2 OpenBTS.cpp 34

8.10 doc 34

8.11 tests 34

8.12 Smqueue 34

8.13 CLI 35

8.13.1 What is the function of the command line interpreter? 35

8.13.2 Some of the supported commands in OpenBTS: 35

8.14 HLR 36

8.14.1 What is a home location register ? 36

8.14.2 HLR in Open BTS : 36

9 Compiling and running OpenBTS: 38

9.1 Hardware used: 38

9.2 Software used: 38

9.3 Important notes before GNU radio setup 38

9.3.1 GNU radio dependencies: 38

9.3.2 Other useful packages 39

9.4 GNU radio setup 39

9.5 Testing the WBX 42

9.6 Compiling and running openbts 42

Tables:

Table 1-L3 RR messages 24

Table 2- L3 RR messages (cont.) 25

Table 3-L3 MM messages 27

Table 4-L3 CC messages 29

Table 5-some of the supported commands in OpenBTS 35

Figures:

Figure 1-MOC sequence diagram for L3 messages 16

Figure 2-MOC sequence diagram 17

Figure 3-MTC sequence diagram for L3 messages 19

Figure 4-MTC sequence diagram 19

Figure 5-successful result for GNU radio configuration 41

List of abbreviations:

RR Radio Resource

MM Mobility Management

CC Call Control

BTS Base Transceiver Station

CLI Command Line Interpreter

HLR Home Location Register

MOC Mobile Originated Call

MTC Mobile Terminated Call

Software Architecture of the OpenBTS

1 Introduction to OpenBTS OpenBTS is an open-source Unix application that uses the Universal Software Radio Peripheral

(USRP) to present a GSM air interface ("Um") to standard GSM handset and uses the Asterisk®

software PBX to connect calls. The combination of the ubiquitous GSM air interface with VoIP

backhaul could form the basis of a new type of cellular network that could be deployed and

operated at substantially lower cost than existing technologies in green fields in the developing

world [1]

In plain language, we are working on a new kind of cellular network that can be installed and

operated at about 1/10 the cost of current technologies, but that will still be compatible with most of

the handsets that are already in the market. This technology can also be used in private network

applications (wireless PBX, rapid deployment, etc. ) at much lower cost and complexity than

conventional cellular[1] .

Telecom industry is one of the rapidly growing industries all over the world. The entrance of open-

source team into the telecom industry made a revolutionized change in the industry. Asterisk was a

typical example for it which was a featured PBX for home users, enterprises, VoIP service

providers and telecoms in such a low cost that anyone even imagined. Asterisk is both an Open

Source Community and a commercial product from Digium[1] .

Now again another open source coming which allows standard GSM-compatible mobile phones to

make telephone calls without using existing telecommunication providers’ networks. ie we can

build up our own network just like vodafone, airtel or any. The project was started by

HarvindSamra and David A. Burgess and named it as OpenBTS. . OpenBTS is notable for being

the first free software implementation of the industry-standard GSM protocol stack[1] .

1.1 What is a Base Transceiver Station:

A normal GSM network working is as follows. The end point of the system will be BTS (Base

Transceiver Station) which send radio frequency signal to and from mobile devices or a modem.

The BTS comes under BSC(Base station Controller) with makes the communication between there

radio signals with MSC/VLR. The MSC/VLR is responsible to authenticate the user against the

database (HLR – Home Location Register, AuC -Authentication Center), call setup and call routing.

A typical GSM network diagram is shown below[1] .

The OpenBTS replaces the entire setup with USRP(Universal Software Radio Peripheral), and a

computer as hardware. USRP to receive and transmit the GSM signaling(GNURadio is the driver

software for this),OpenBTS package play the role of MSC/VLR and Asterisk software PBX will be

used to connect calls. The below diagram shows a typical OpenBTS network[1] .

Potential applications include:

rural/village telephony and text messaging

cellular coverage in remote areas (e. g. ships, oil rigs)

law enforcement and security operations

rapidly deployable emergency communications

network emulation and handset testing.

2 overall architecture and implementation plan of the OpenBTS. [1] The general shape of the OpenBTS is a collection of parallel “logical channels”, defined in GSM04.

03. Each channel, in turn, is built from layers that roughly follow the OSI standard model. (We say

“roughly” because GSM predates the OSI model. )GSM 04. 01 Section 7 gives an initial overview

of these layers.

As per GSM 04.01 Section 7. 3, the layers of the air interface Um are:

• L1, “PHYSICAL LAYER”, the radio modem, time-division multipexing, and error-correcting

coding, GSM 04. 04 and GSM 05.xx series

• L2, “DATA LINK LAYER”, link layer addressing, segmentation and retransmission (LAPDm),

GSM 04. 05 and 04.06, ITU-T Q. 921.

• L3, “L3”, signaling and connection management, GSM 04. 07, 04.08, 04.10, 04.11, 04.12 and

ITU-T Q. 931.

When describing these layers we will refer to the “low” side of the layer as the side the interfaces

closer to the hardware and the “high” side as the side that interfaces to higher-level functions. In a

BTS, the low-to-high direction is “uplink” and the high-to-low direction is “downlink”. In the MS,

those labels are reversed.

2.1 Typical “upstream” data flow in the GSM air interface of the OpenBTS: 1. Radio bursts arrive at the USRP and are digitized. The resulting samples are transferred to the

transceiver software in the host CPU in time-tagged USB packets, using the standard USRP

interface.

2. The transceiver syncs the USRP timetags with the GSM master clock, isolates each radio burst

and demodulates it into a vector of symbol likelihoods (“soft symbols”). The modulation format is

defined in GSM 05. 04 and the burst formats are described in GSM 05. 02 Section 5. 2.

3. The soft symbol vector for each radio burst is timetagged with the GSM frame clock and

transferred to the GSM stack via a datagram interface.

4. In the GSM stack, the TDM sublayer (of L1) demultiplexes each bust according to its timetag

and sends it to the appropriate logical channel.

5. The logical channel passes each burst into its L1 FEC processor according to the rules of GSM

05. 02.

6. The L1 FEC processor performs the FEC decoding described in GSM 05. 03. The output is a

sequence of L2 frames taken by the logical channel and sent up to an L2 processor.

7. The L2 processor runs the LAPDm state machine that performs acknowledgments,

retransmissions and segmentation. This state machine is defined implicitly in GMS 04. 06 and

given explicitly in ITU-T Q. 921. When an incoming L3 frame has been verified and assembled, it

is placed into a queue for consumption by L3. In the course of operation, LAPDm also injects L2

frames into the downstream flow for acknowledgment and retransmission requests.

8. In L3, a dispatch function determines the message protocol and type and calls the appropriate

control function to deserialize the message and act on its content, generally producing an L3

response on the downlink. These control functions also interact with the outside world via SIP and

other protocols.

2.2 Typical “downstream” data flow in the GSM air interface of the OpenBTS :

1. In L3, a control function generates an L3 message, serializes the message into an L3 frame and

sends it into the logical channel, which in turn passes it down to L2.

2. The L2 processor breaks the L2 frame into segments, wraps each segment in an L2 frame. Each

L2 frame is sent down to L1 according to the LAPDm state machine of GSM 04. 06 and ITU-T Q.

921.LAPDm may also generate additional L2 frames on its own according to its acknowledgment

and retransmission rules.

3. The L1 FEC processor encodes each L2 frame according to the rules of GSM 05. 03, generating

four outgoing radio bursts. Each radio burst is timetagged with its intended transmission time

according to the TDM rules of GSM 05. 02. These bursts are passed on to the TDM interface.

4. The downstream TDM sublayer is just a mutex-controlled socket interface where the radio bursts

from L1 are reformatted into messages on the transceiver’s datagram interface.

5. Upon arriving in the transceiver, the outgoing radio bursts are sorted into a priority queue

according to transmission time. Bursts are pulled from the queue as they become ready for

transmission and the modulated according to GSM 05. 04. The modulated waveform samples are

sent to the USRP over the standard timetagged USB interface. If no burst is ready for transmission

at a given time the transceiver generates an appropriate filling sequence.

6. In the USRP the samples are converted to an analog waveform for transmission over the radio

channel.

3 Coding: Use of Objects, Threads and C++ The OpenBTS software is written in C++ and should be portable to any 32-bit Unix system. Initial

supported platforms will be Fedora and Darwin, but there is no reason for the resulting system not

to be portable to other Unix variants. In the interest of simplicity, compactness and efficiency,

limit our use of allocated memory, multiple inheritance, templates and standard library container to

the greatest degree practical.

3.1 Threads The implementation of the OpenBTS makes use of the POSIX thread library, pthreads. For those

unfamiliar with threads or who have an aversion to them, this may seem frightening and strange, but

the effect of this approach is to greatly simplify the code in each layer of the BTS. You can have N

threads each with K states or one thread with KN states. We choose the former. The price of

threads is discipline in the use of synchronized interthread communication. Do use mutexes. Do

not just use volatiles.

The general rule is that single-state transformational operations are performed with direct calls

while multi-state machines, especially those with internal timeout behaviors, have their own threads

and accept their inputs over FIFOs. The threads and FIFOs may be hidden inside the state machine

objects. This approach allows the state machines to be decoupled, greatly simplifying the code.

3.2 Namespaces

The OpenBTS will use the following namespaces:

GSM – The GSM L1-L2 stack and L3 messages.

SIP – The SIP stack.

Control – The GSM/SIP hybrid control layer.

SMS used to add the SMS function

SMqueue

Commandline a name space for the command line interface

3.3 Optimization

From prior experience with several software radio systems, we expect that the bulk of the

computational load in the OpenBTS will be in the software transceiver and L1 FEC decoding.

That’s because L2 frames arrive at a maximum rate of about 50 Hz while radio burst are transacted

at about 200 Hz and GSM channel symbols must be processed at 271 kHz. For the rural telecom

application, optimization of beacon generation and RACH detection is also important since the BTS

is expected to sit largely idle most of the time. There’s not a lot of point in optimizing most of the

rest of the code for speed. Instead, the rest of the system should be optimized for space to minimize

cache misses in the computationally intensive code.

3.4 Testing and Consistency Checking The full BTS will be a complex system that will be nearly impossible to debug if the individual

components are not tested in isolation prior to integration. 2 To enforce good testing practices, we

recommend the following:

• Use assert() calls liberally to insure internal consistency. Do not continue once an unresolvable

error condition is identified.

• Build unit test fixtures for every component in the system. Do not check in code that does not

pass the unit tests. It would be especially nice if someone could automate this testing process.

• If you know there’s a potential problem in a piece of code, use a “FIXME” comment. If you leave

something undone, use a “TODO” comment.

• Use the bug tracking system. That’s why it’s there.

3.5 C++ Tools Part of what will let us build an efficient BTS quickly is careful choice of underlying tools.

3.6 Wrappers

The project uses a set of simple wrapper classes that give object-oriented interfaces for some

pthreads and stdlib mechanisms. These include wrappers for threads, signals, recursive mutexes,

and C time-of-day facilities. These wrappers simplify the use of these facilities by including

standard allocation and initialization steps that are common across the application.

3.7 Vector Classes The Vector template is a fixed size array that offers simple pointer-based access. The key feature of

the Vector subclass is the ability to create “aliases”, where multiple Vector objects share the same

physical block of memory. These aliases can also have different offsets into the common block,

forming subvectors. The underlying mechanism is a C array. The SoftVector is used to represent

symbol likelihood vectors used in soft input and soft output Viterbi coders and decoders. The

BitVector is a Vector class for serialization and deserialization of packed bitfields. The

SignalVector and ComplexVector are are numeric classes used in the GMSK modem.

3.8 Interthead Classes Most interthread communication is mediated through special container classes with built-in

synchronization controls.

The InterthreadQueue class is a thread-safe pointer FIFO that supports non-blocking writes,

nonblocking reads and blocking reads with a timeout. The underlying mechanism is a singly-linked

list with head and tail pointers having no maximum size. The normal use of the InterthreadQueue is

to allocate an object and then put the pointer into the queue. The reader is responsible for deleting

the pointer. For fixed-size objects used in this manner, a special-purpose allocator can reduce

overhead.

The InterthreadMap class is a thread-safe associative array that includes a blocking read that waits

for the arrival of a specified key. The underlying mechanism is std::map.

3.9 Important C++ Object Hierarchies The OpenBTS will use C++ object classes and inheritance. There are a few object hierarchies of

particular interest:

• Layer Processor Classes. These objects implement the layers L1-L3 of the air interface.

• Data Transfer Classes. These are the objects that are used for interlayer communication. Most

are BitVector subclasses.

• Logical Channel Classes. These objects define the L1-L2 logical channels between the MS and

the BTS control functions.

• L3 Message and Element Classes. These are used to serialize and deserialize the messages of

GSM 04. 08.

3.10 Data Transfer Object Classes The interlayer communication uses these object classes:

• RadioBurst. Carries a radio burst of GSM 05. 02 Section 5. 2 along with timestamp.

– TxBurst. Used for downlink radio bursts to be transmitted. Carries hard-valued channel bits and

transmit power level relative to full scale on the given ARFCN. The timestamp indicates the

intended transmission time.

– RxBurst. Used for received uplink radio bursts. Carries soft-value channel bit estimates, RSSI,

and receive timing error. The timestamp indicates the arrival time of the burst.

• L2Frame. Carries an L1-L2 interlayer primitive. Optionally carries a data link layer frame as

described in GSM 04. 06 Section 2 and a restriction on the placement of the data in the TDM

structure.

• L3Frame. Carries an L2-L3 interlayer primitive. Optionally carries the serialized bits of a single,

complete L3 message from GSM 04. 08 Section 9.

3.11 Logical Channel Structure and Subclasses Following the OSI model, each logical channel is processed in three layers: L1, L2, L3. Each layer

is represented by an object (a layer processor) that has read and write methods on its high and low

sides. These objects are persistent over the life of the application. In the normal course of the

OpenBTS application, the destructors for these classes should never be invoked.

The layer processor classes are:

• L1FECEncoder. Accepts L2Frame objects, encodes them into TxBurst objects. Algorithms

defined in GSM 05. 03.

• L1FECDecoder. Accepts RxBursts from the TDM sublayer and processes them into L2Frame

objects. Algorithms defined in GSM 05. 03.

• L1FEC. A container for a channel’s L1FECEncoder and L1FECDecoder.

• L2LAPDm. The L2LAPDm transacts L2Frame objects with L1 and L3Frame objects with L3.

Implements the LAPDm state machine as described in GSM 04.06 and ITU-T Q. 921.

• L3StateMachine. The L3StateMachine transacts L3Frame objects with L2. Implements the

protocols of GSM 04. 08 and also interfaces with SIP entities.

• BCH (broadcast channels)

– SCH

– FCCH

– BCCH

• NDCCH (non-dedicated control channels)

– CCCH (downlink unicast)

– RACH (uplink shared)

• DCCH (dedicated control channels, Dm)

– SDCCH

– SACCH

– FACCHF (full rate)

• TCHF (full rate speech, GSM 06. 10, Bm). Many traffic channel classes are ignored here, as are

half-rate channels. They are not a priority in a first release.

4 Time Domain Mutliplexing (TDM) Sublayer The TDM sublayer forms the interface between the physical channels on the transceiver interface

and the logical channels in the higher layers. It implements the rules of GSM 05. 02. All LCHs on

an ARFCN share a common TDM sublayer. In the uplink side, the TDM sublayer accepts all of the

RxBurst objects from a single ARFCN and demultiplexes them according to their frame count

timestamps into a table of LogicalChannel objects. In the downlink side, the multiplexing layer is a

pass-through to the transceiver interface, but with mutex controls and serialization.

5 Software Transceiver The software transceiver includes the subband tuner, GMSK modems and the master GSM symbol

clock for the air interface. Its low side interface transfers raw baseband samples to and from the

USRP. Its high side interface transfers RxBurst and TxBurst objects to and from the GSM stack

and transacts control commands and clock values. To compensate for latency in the stack and

interface, the GSM frame clock value reported to the GSM stack is advanced slightly. The timing

reference for the GSM symbol clock is the sample clock in the USRP, as is standard in most

software radio designs.

For the uplink, the software transceiver has information about which timeslots and frame positions

carry active channels and it demodulates only those active parts of the signal. It timestamps each

TxBurst according to the frame clock value when the burst arrived.

For the downlink, the timestamp on anTxBurst indicates the time at which a radio burst is to be

transmitted. If a downlink radio burst is not available for transmission when the GSM clock

reaches a given value, the transceiver generates an appropriate filler pattern based on the clock

value. TxBursts can be sent over this interface out of order, with the transceiver interface sorting

them prior to transmission. If the TxBurst’s indicated time has passed, the burst is discarded and

the clock advance value is adjusted to prevent further late bursts. This adjustment is in one

direction and quickly settles to an appropriate value for the system.

Because the software transceiver links with the GPL’d USRP driver, it is compiled as a separate

application and communicates with the rest of the GSM stack over a UDP interface. Expressed in

terms of a base port, B, the UDP ports used for the transceiver interface are:

• master clock interface on port B

• control interface for ARFCN N on port B + 2N + 1

• data interface for ARFCN N on port B + 2N + 2

The protocol on the master clock interface has a single message that periodically indicates the

current value of the BTS master clock, with an additional advance to compensate for latency. This

message is an unacknowledged indication from the transceiver to the GSM stack. These are

human-readable ASCII messages sent once per superframe and whenever the clock advance value

is adjusted.

The protocol on the per-ARFCN control interface has commands for power control, tuning and

configuration of the channel combination on each slot. Each command has a corresponding

response for integrity on the UDP link. The are human-readable ASCII messages.

The protocol on the per-ARFCN data interface uses binary messages to convey RxBurst and

TxBurst objects with one burst per UDP packet to minimize latency. There are no

acknowledgments on this interface because there is no point in retransmitting packets in a low-

latency realtime link.

Eventually, we will replace to USRP driver with non-GPL code and replace this socket protocol

with a direct method interface just like the interface on every other layer and sublayer object in the

system.

6 Global GSM Object There is a single global object of the class GSM::Configuration, called gBTS, that acts as a

collection point for the complete state and configuration of the access point’s GSM stack. This

object is created during initialization and never destroyed.

6.1 Global Configuration Information

The global object gBTS keeps all of the BTS configuration parameters and state for the cell,

including ARFCN set, cell ID, LAC, etc. This information is used to fill system information

messages on the BCCH and SACCH and is readily available to the control layer.

6.2 LCH Creation, Allocation and Deallocation The gBTS object tracks all of the existing LogicalChannel objects in the system in an allocation

pool. The allocator includes methods to create new LogicalChannel objects and add them to the

pool as the BTS’s channel combinations are configured on start-up. Once created, these

LogicalChannel objects are persistent over the life of the application.

When a control layer function determines that it needs a new logical channel for a transaction, it

invokes the channel allocator to find an available LogicalChannel object of the proper type in the

pool. Channel availability is defined by a set of Z. 100-type timers in L1: T3101, T3107, T3109

and T3111, described in GSM 04. 08 Section 11. 1. 2. If any timer is expired, the channel is

available. Once identified, the channel is opened, reseting the channel state and starting T3101 or

T3107. This timer change moves the channel to the non-available state. The channel is then given

to the calling control layer function for use in a transaction.

Normally, at the end of the transaction the channel is closed from above with a “release” primitive

that passes down to L1, starting T3111. Once T3111 expires, the channel becomes available for

reuse. In an abnormal release (a dropped connection), one of the other timers will expire instead.

T3107 or T3101 will expire if the MS fails to pick up an assigned channel at the start of a

transaction. T3109 will expire if the uplink signal is lost during a transaction. Any any case, one of

the timers will expire, moving the channel to the available state.

It should be stressed that this mechanism does not create or destroy LogicalChannel objects. It

manages a pool of long-lived objects that are recycled for different transactions, just like the radio

channels themselves.

7 Use of SIP and Asterisk One of the keys to simplifying the OpenBTS is to push as much of the control layer as possible into

the Asterisk PBX. To that end, we will use Asterisk for nearly all call control functions and as

an integral part of mobility management. The simplest way to do this in a first release is to use

subscriber IMSIs as SIP user names and to present each GSM handset to Asterisk as a SIP client.

The OpenBTS control layer (L3) largely exists to perform mapping operations:

• GSM location updates get mapped to SIP registrations.

• Call connection transactions get mapped to corresponding SIP transactions. Since GSM call

control is very similar to H. 323 and ISDN/Q. 931 call control, there’s very little that is mysterious

or novel about this mapping.

• GSM traffic channels get mapped to RTP channels. Again, the mapping is obvious and the only

tricky piece of engineering is latency control.

Only radio resource operations are fully terminated in the OpenBTS itself, with the RR control layer

providing the functional equivalent of a BSC. Everything else maps to SIP and eventually

terminates in Asterisk, with the Asterisk network providing the functional equivalent of an MSC.

This is “network in a box” with Asterisk replacing the SS7 parts.

8 OpenBts Modules-Files:

8.1 AsteriskConfig Asterisk configuration files for use with OpenBTS.

8.2 CommonLib

Common-use libraries, mostly C++ wrappers for basic facilities.

8.3 Control

8.3.1 Introduction

Control functions carry out the various procedures described in GSM 04. 08 Sections 3-5. These

functions are called in L3.

access grant (GSM 04. 08 Section 3. 3. 1)

paging (GSM 04. 08 Section 3. 3. 2)

location updating (GSM 04. 08 Section 4. 4)

mobile-terminated call setup (GSM 04. 08 Section 5. 2. 1)

mobile-originated call setup (GSM 04. 08 Section 5. 2. 2)

mobile-terminated call disconnect (GSM 04. 08 Section 5. 4. 4)

mobile-originated call disconnect (GSM 04. 08 Section 5. 4. 3)

E-MOC -- Emergency Mobile Originated Connect (mobile calling out)

This is the minimum transaction set to support telephony. These transactions are run by these top-

level control functions:

• AccessGrantor sends out SDCCH Immediate Assignments on the CCCH. It is invoked from the

RACH dispatcher and returns when the assignment has been delivered. Its arguments are the tag

and timestamp of a RACH Channel Request message.

• Pager sends out paging messages. It is invoked from the SIP stack whenever an INVITE message

arrives and returns when the subscriber IMSI has been enqueued for paging on the CCCH. Its

argument is a reference to an IMSI.

• LocationUpdater runs the registration transaction of GSM 04. 08 Section 4. 4. It is invoked by

the SDCCH dispatcher when a Location Updating Request is received and returns when the

transaction is complete. Its argument is a reference to an SDCCH LogicalChannel where the

transaction is carried out.

• MTCConnector starts a mobile terminated call and returns when the call is cleared. It is invoked

by the SDCCH dispatcher when a Paging Response is received. It continues the SIP transaction

started by the INVITE message that triggered the corresponding Paging Request. Its argument is a

reference to an SDCCH LogicalChannel where the transaction will start. It allocates a

TCH/FACCH as part of the transaction. It calls CallManager once the call is connected.

• MOCConnector starts a mobile originated call (MOC) and returns when the call is cleared. It is

invoked by the SDCCH dispatcher when a CM Service Request is received. Its argument is a

reference to an SDCCH LogicalChannel where the transaction will start. It allocates a

TCH/FACCH as part of the transaction. It calls CallManager once the call is connected.

• CallManager runs a call once the setup transaction is complete. It processes any L3 messages

that arrive while the call is in progress and invokes functions as needed for the call disconnection

state machines.

Most control layer functions return boolean values indicating whether or not the transaction ended

during the function call. For example, a function for some call control sub-procedure will return a

boolean indicating whether or not the call was cleared during the sub-procedure. Most control layer

functions take a LogicalChannel reference as an argument

E-MOC -- Emergency Mobile Originated Connect used for handling emergency calls.

8.4

8.4.1 CallControl.cpp:

8.4.1.1 What is implemented?

Mobile originated call procedure

Mobile terminated call procedure

Emergency calls

Test calls

8.4.1.2 Mobile originated call:

A mobile originated call is initiated by the MS. In the open source version, we will skip the

authentication steps and simply respond to the CM Service Request with a CM Service Accept or

Reject.

8.4.1.2.1 Steps of mobile originated call?

– CM Service Request (MM, 9.2.9)1, decode. This message indicates to the BTS that the

phone will require ISDN-style (connection-oriented) services.

– CM Service Accept (MM, 9.2.5), encode. This message allows us to bypass authentication

and proceed directly to ISDN-style/Q.931call control.

– CM Service Reject (MM, 9.2.6), encode. This message is sent to reject service if the call

setup cannot be performed for some reason, such as an lack of available traffic channels.

– Setup (CC, 9.3.23), decode. Simply skip unsupported elements based on T and L fields

when parsing. This message triggers an INVITE message to the Asterisk server that

starts the hybrid Q.931/SIP call setup procedure.

– Call Proceeding (CC, 9.3.3), encode.

– Assignment Command (RR, 9.1.2), encode. This message moves the transaction from

the SDCCH to the TCH/FACCH.

– Assignment Complete (RR, 9.1.3), decode. This is the first message sent from the phone

on the newly assigned TCH/FACCH.

1 GSM 04.08

– Alerting (CC, 9.3.1), encode. This message corresponds to the SIP 180 Ringing message.

– Progress (CC, 9.3.17), encode. This message is needed to keep the connection alive when

Asterisk delays are large. It is similar in purpose to the SIP 100 Trying message.

– Connect (CC, 9.3.5), encode. This message corresponds to the SIP 200 OK message.

– Connect Acknowledge (CC, 9.3.6), decode. This message corresponds to the SIP ACK

message.

8.4.1.2.2 MOC sequence diagram:

BTS MS

CM Service Request

CM Service Accept

setup

call proceeding

assignment command

Assignment Complete

alerting

connect

connect acknowlege

progress

ASTERISK

send INVITE()

send ok()

send ACK for OK

Figure 1-MOC sequence diagram for L3 messages

8.4.1.2.3 How it is implemented in OpenBTS ?

Mobile originated call is implemented in OpenBTS in the file CallControl.cpp & CallControl.h

through the two functions MOCStarter which implements the MOC sequence until the transaction

is moved from the SDCCH to the TCH/FACCH & MOCController which implements the rest of

the MOC sequence

8.4.1.2.4 Sequence of functions' call:

DCCHDispatchOpenBTS CallControlMobilityManagement

main()

DCCHDispatcher ()

CMServiceResponder ()

MOCStarter()

MOCController()

Figure 2-MOC sequence diagram

8.5

8.6

8.6.1.1 Mobile terminated call:

A mobile terminated call is a call that is received by the MS. In the open source version, we will

skip the authentication steps by sending a CM Service Accept or Reject after receiving the Paging

Response.

8.6.1.1.1 Steps of mobile terminated call?

– Paging Request Type 1 (RR, 9.1.22), encode. This message is sent whenever a SIP

INVITE message arrives from Asterisk.

paging response (RR, 9.1.22) , decode

– Setup (CC, 9.3.23), encode. This message carries the content of the SIP INVITE message

to the phone.

– Call Confirmed (CC, 9.3.2), decode.

– Assignment Command (RR, 9.1.2), encode.

– Assignment Complete (RR, 9.1.3), decode.

– Alerting (CC, 9.3.1), decode.

– Progress (CC, 9.3.17), encode.

– Connect (CC, 9.3.5), decode.

Connect Acknowledge (CC, 9.3.6), encode

8.6.1.1.2 MTC sequence diagram

BTS MS

Paging Request Type 1

Paging Response

setup

call confirmed

assignment command

Assignment Complete

alerting

connect

connect acknowlege

progress

Figure 3-MTC sequence diagram for L3 messages

8.6.1.1.3 How it is implemented in OpenBTS ?

Mobile terminated call is implemented in OpenBTS in the file CallControl.cpp & CallControl.h

through the two functions MTCStarter which implements the MTC sequence until the transaction

is moved from the SDCCH to the TCH/FACCH & MTCController which implements the rest of

the MTC sequence

8.6.1.1.4 Sequence of functions' call:

DCCHDispatchOpenBTS CallControlMobilityManagement

main()

DCCHDispatcher ()

CMServiceResponder ()

MTCStarter()

MTCController()

Figure 4-MTC sequence diagram

8.6.2 DCCHDispatch.cpp

8.6.2.1 What is implemented?

Dispatcher for messages passing through DCCH

Dispatcher for RR messages passing through DCCH

Dispatcher for MM messages passing through DCCH

8.6.2.2 Important functions:

1- void Control::DCCHDispatcher(LogicalChannel *DCCH)

persistent-thread control function for the DCCH

2- void DCCHDispatchRR(const L3RRMessage* req, LogicalChannel *DCCH)

Dispatch the appropriate controller for a Radio Resource message

3-void DCCHDispatchMM(const L3MMMessage* req, LogicalChannel *DCCH)

Dispatch the appropriate controller for a Mobility management message

8.6.3 MobilityManagement.cpp

8.6.3.1 What is implemented:

Imsi detach

Location update

A handler for CM service request

sending the welcome message

8.6.3.2 Important functions:

1-void Control::CMServiceResponder(const L3CMServiceRequest* cmsrq, LogicalChannel*

DCCH)

Controller for CM Service requests, dispatches out to multiple possible transaction controllers

2- void Control::IMSIDetachController(const L3IMSIDetachIndication* idi, LogicalChannel*

DCCH)

Controller for the IMSI Detach transaction

3- void Control::LocationUpdatingController(const L3LocationUpdatingRequest* lur,

SDCCHLogicalChannel* SDCCH)

Controller for the Location Updating transaction

4-bool sendWelcomeMessage(const char* messageName, const char* shortCodeName,

SDCCHLogicalChannel* SDCCH)

Send a given welcome message from a given short code

8.6.4 SMSControl.cpp

8.6.4.1 What is implemented:

methods to handle sending SMS between the BTS and a MS

Mobile Originated Short Message Service controller

Mobile Terminated Short Message Service controller

8.6.4.2 Important functions:

void Control::MOSMSController(const L3CMServiceRequest *req, LogicalChannel *LCH)

Mobile Originated Short Message Service controller

void Control::MTSMSController(TransactionEntry& transaction, LogicalChannel *LCH)

Mobile Terminated Short Message Service controller

8.6.5 ControlCommon.cpp:

8.6.5.1 What is implemented:

Functions that are used to update the transaction table or search for a certain mobile

identifier in it.

Functions that resolve a mobile identity to get the corresponding IMSI and maybe the

corresponding TMSI for the retrieved IMSI.

8.6.6 ControlCommon.h:

This file contains the prototype definitions for the functions implemented in the .CPP files

mentioned above.

8.7 GSM

8.7.1 Introduction:

The GSM stack is divided into 3 layers, we will discuss each layer briefly and how it is

implemented in the Open BTS project, first the document starts by discussing L3 messages and

their classification into 3 types RR ,MM and CC , a brief description for L2LAPDm protocol is

found in section 3 and finally the document describes how L1 is implemented in the OpenBTS

project.

8.7.2 GSM layer 3:

Messages sent between the BTS and the MS are described in GSM layer 3 and they are called GSM

layer 3 messages they are used in debugging problems during communication between BTS and

MS.

8.7.2.1 Imperative part of L3 messages:

The imperative part of a standard L3 message is composed a header possibly followed by

mandatory standard IEs having the format V or LV.

For further details on L3 messages please see GSM 04.07 clause 11.

8.7.2.2 L3 messages in OpenBTS:

Forming and parsing L3 messages are implemented in the following files:

GSML3Message.cpp

GSML3Message.h

Some important functions:

void L3Message::write(L3Frame& dest) const

writes a l3 message (header skip indicator , pd , message type then calls the function that

writes the l3 message's body.

GSM::L3Message* GSM::parseL3(const GSM::L3Frame& source)

Parses l3 messages and determines which type is it(RR,MM,CC)

There are three main types of L3 messages which are implemented in the Open BTS project:

radio resource messages

mobility management messages

call control messages

These messages are used in debugging problems occurring during the communication between the

BTS and the MS and they are logged through the logging file of the project.

These messages are described in the ETSI GSM standard 04.08 clause 9.

8.7.2.2.1 L3 RR messages

Table 1-L3 RR messages

Table 2- L3 RR messages (cont.)

8.7.2.2.1.1 L3 RR messages in Open BTS:

system information types 1-9

system information types 13, 16 and 17

Paging Response

Paging Request Type 1

Measurement Report

Assignment Complete

Immediate Assignment

Immediate Assignment Reject

Assignment Command

Assignment Failure

Channel Release

Channel Mode Modify

Channel Mode Modify Acknowledge

GPRS Suspension Request

Classmark Change

RR Status

8.7.2.2.1.2 Files that implement L3 RR messages in OpenBTS:

GSML3RRMessages.cpp

GSML3RRMessages.h

GSML3RRElements.cpp

GSML3RRElements.h

The first two files contain functions that are responsible for structuring the RR messages as

specified in the standards , they also provide parsing methods for messages that come from the MS

as a response for any of the RR messages.

Each message is implemented by a function that is responsible for structuring the message and is

named like that messagename::writebody( )

For incoming messages that need to be parsed the message is named like that

messagename::parsebody( )

Example:

Parsing the page response message which is initiated by the MS as a response for any of the

following RR messages :

Paging request type 1

Paging request type 2

Paging request type 3

The other two files provide methods to ease dealing with the elements that form the RR messages.

8.7.2.2.2 L3 MM messages

Table 3-L3 MM messages

8.7.2.2.2.1 L3 MM messages implemented in Open BTS:

IMSI Detach Indication

CM Service Request

CM Service Accept

CM Service Reject

CM Service Abort

CM Re-establishment Request

Identity Response

Identity Request

MM Information

Location Updating Accept

Location Updating Reject

Location Updating Request

MM Status

8.7.2.2.2.2 Files that implement L3 MM messages in OpenBTS:

GSML3MMMessages.cpp

GSML3MMMessages.h

GSML3MMElements.cpp

GSML3MMElements.h

The first two files contain functions that are responsible for structuring the MM messages as

specified in the standards.

Each message is implemented by a function that is responsible for structuring the message and is

named like that messagename::writebody( ).

The other two files provide methods to ease dealing with the elements that form the MM messages.

8.7.2.3 L3 CC messages

Table 4-L3 CC messages

8.7.2.3.1.1 L3 CC messages implemented in Open BTS:

Alerting

Connect

Disconnect

Connect Acknowledge

Release Complete

Setup

Emergency Setup

CC Status

Call Confirmed

Call Proceeding

Start DTMF

Start DTMF Reject

Start DTMF Acknowledge

Stop DTMF

Stop DTMF Acknowledge

Hold

Hold Reject

8.7.2.3.1.2 Files that implement L3 CCmessages in OpenBTS:

GSML3CCMessages.cpp

GSML3CCMessages.h

GSML3CCElements.cpp

GSML3CCElements.h

The first two files contain functions that are responsible for structuring the CC messages as

specified in the standards.

Each message is implemented by a function that is responsible for structuring the message and is

named like that messagename::writebody( )

The other two files provide methods to ease dealing with the elements that form the CC messages.

8.7.3 GSM layer 2:

Layer 2 in the GSM stack the data-link layer. Across the Um interface, the data-link layer is a

modified version of the Link access protocol for the D channel (LAP-D) protocol used in ISDN,

called Link access protocol on the Dm channel (LAP-Dm)

Note: The term Dm channel is used for convenience to designate the collection of all the various

signaling channels required in the GSM system.

It is implemented through the following files :

GSML2LAPDm.cpp

GSML2LAPDm.h

GSMTransfer.h

GSMTransfer.cpp

The first two files implement the algorithms and the state machines of the LAPDM protocol.

The other two files implement methods for structuring and formatting L2 meesages.

For further details on L2 LAPDM please see GSM 04.06 .

8.7.4 LAYER 1 :

Represents the physical layer of the GSM stack.

Maps physical channel into logical channels.

Sends and receives bits from the transceiver module.

Interfaces with the transceiver through the transceiver manager module.

The interface with the transceiver is through a UDP port to ensure portability and modularity for

both modules.

8.7.4.1 LAYER 1 in OpenBTS:

Layer 1 is implemented through the following files :

GSML1FEC.cpp

GSML1FEC.h

GSMLogicalChannel.h

GSMLogicalChannel.cpp

GSMTDMA.h

GSMTDMA.cpp

The GSML1FEC.h file contains the classes representing encoders and decoders for different logical

channels here are some of them:

class L1Encoder

Abstract class for L1 encoders.

In most subclasses, writeHighSide() drives the processing.

class L1Decoder

An abstract class for L1 decoders.

writeLowSide() drives the processing.

class L1FEC

The L1FEC encapsulates an encoder and decoder.

class RACHL1Decoder

L1 decoder for Random Access (RACH).

class XCCHL1Decode

Abstract L1 decoder for most control channels

class SDCCHL1Decoder

L1 decoder for the SDCCH.

class SACCHL1Decoder

L1 decoder for the SACCH

The GSML1FEC.h file implements the encoders and decoders for the various logical channels and

also the L1 FEC which is an encapsulated encoder and decoder.

The GSML1FEC.cpp file contains some important functions such as:

void FCCHL1Encoder::generate()

BCCHL1Encoder::generate()

void SCHL1Encoder::generate()

void RACHL1Decoder::serviceLoop()

The first three functions are called through service loops ,they run continuously until the looping

condition is violated , these functions are responsible for sending the data sent by the logical

channel calling it

example : void FCCHL1Encoder::generate()

Responsible for sending the zero burst which is sent on the FCCH logical channel as specified in

the GSM standards.

The fourth function has a service loop pulls RACH bursts from a FIFO and sends them to the

decoder.

GSMLogicalChannel.h & GSMLogicalChannel.cpp provide classes and methods to deal with

the logical channels in general such as open & close or constructors and service loops that weren't

mentioned in GSML1FEC.cpp and GSML1FEC.h.

GSMTDMA.h & GSMTDMA.cpp are responsible for mapping logical channels into physical

channels.

8.7.4.2 Other important files

GSMCommon.cpp

GSMCommon.h

GSMConfig.cpp

GSMConfig.h

GSMSAPMux.cpp

GSMSAPMux.h

GSMCommon.cpp and GSMCommon.h contain some important functions which set the uplink and

downlink frequencies and calculate the current frame number besides other functions.

GSMConfig.cpp and GSMConfig.h contain the GSMConfig class which holds the GSM

configuration parameters such as:

network color code

basestation color code

GSM operating band

copy of the BTS master clock

Encoded L2 frames to be sent on the BCCH

Encoded L3 frames to be sent on the SACCH

GSMSAPMux.cpp and GSMSAPMux.h implement methods needed for dealing with a SAPMUX.

8.7.4.3 What is a SAPMUX?

A SAPMux is a multipexer the connects a single L1 to multiple L2s.

A "service access point" in GSM/ISDN is analogous to port number in IP.

GSM allows up to 4 SAPs, although only two are presently used.

See GSM 04.05 5.2 for an introduction.

8.8 SIP

Components of the SIP state machines used by the control layer.

8.9 SMS

The SMS stack.

8.10 TRXManager The interface between the GSM stack and the radio.

8.11 Transceiver The software transceiver and specific installation tests.

8.12 apps OpenBTS application binaries , these folder contains some important files such as:

8.12.1 OpenBTS.config

Through this file you can alter all system’s configurations such as the GSM band(900/1800) ,the

logging file’s path , which transceiver to use (52 MHZ/64 MHZ) , …. Etc.

8.12.2 OpenBTS.cpp

Contains initializations for some objects then implements the main function of the project

8.13 doc Project’s documentation.

8.14 tests Test fixtures for subsets of OpenBTS components.

8.15 Smqueue RFC-3428 store-and-forward server for SMS.

8.16 CLI

8.16.1 What is the function of the command line interpreter?

It receives a command from the user through the command line interface, checks if it is a valid one

and if so it executes this command.

It can also be used to get help about any of the available commands.

8.16.2 Some of the supported commands in OpenBTS:

command Help

Loglevel [level] -- get/set the logging level, one of {ERROR, ALARM, WARN, NOICE, INFO,

DEBUG, DEEPDEBUG}.

Setlogfile <path> -- set the logging file's path.

Printtmsis [\"clear\"] -- print/clear the TMSI table

Sendsms send SMS to <IMSI>, addressed from <src>, after prompting

cellID [MCC MNC LAC CI] -- get/set location area identity (MCC, MNC, LAC) and cell ID

(CI)

Table 5-some of the supported commands in OpenBTS

The command line interpreter is implemented through the following two files:

CLI.cpp

CLI.h

8.17 HLR

8.17.1 What is a home location register ?

The home location register (HLR) is a central database that contains details of each mobile phone

subscriber that is authorized to use the GSM core network. There can be several logical, and

physical, HLRs per public land mobile network (PLMN), though one international mobile

subscriber identity (IMSI)/MSISDN pair can be associated with only one logical HLR (which can

span several physical nodes) at a time.

The HLRs store details of every SIM card issued by the mobile phone operator. Each SIM has a

unique identifier called an IMSI which is the primary key to each HLR record

8.17.2 HLR in Open BTS :

HLR in Open BTS is implemented through the following files :

1- HLR.cpp

2-HLR.h

Open BTS does its calls through ASTERISK so the HLR implemented in Open BTS records data

related to ASTERISK such as the registration IP .

Here are some of the important functions in this subsystem and their description:

1-virtual char* getIMSI(const char* ISDN) =0;

Resolve an ISDN or other numeric address to an IMSI.

2-virtual char* getCLIDLocal(const char* IMSI) =0;

Given an IMSI, return the local CLID, which should be a numeric address

3-virtual char* getCLIDGlobal(const char* IMSI) =0;

Given an IMSI, return the global CLID, which should be a numeric address.

4-virtual char* getRegistrationIP(const char* IMSI) =0;

Given an IMSI, return the IP address of the most recent registration.

5-virtual Status addUser(const char* IMSI, const char* CLID) =0;

Add a new user to the HLR.

6-virtual Status addAddress(const char* IMSI, const char* ISDN) =0;

Add an address for a user.

9 Compiling and running OpenBTS:

9.1 Hardware used:

USRP

WBX daughter board

2 antennas for tx and rx

Your PC or laptop

9.2 Software used:

LINUX operating system(ubuntu 10.10)

GNU radio 3.3.0

Open BTS software version 2.6 ttsou expanded daughter board support

Python 2.6

GRC 1.3

9.3 Important notes before GNU radio setup

If you have gnuradio 3.2 then you should completely remove it

Wbx doesn't work with gnuradio before 3.3

openbts 2.5.4 lacassine doesn't work with gnuradio 3.3.0 (not sure)

9.3.1 GNU radio dependencies:

You need to install these packages before installing GNU radio:

python-dev

FFTW 3.X (fftw3, fftw3-dev)

cppunit (libcppunit and libcppunit-dev)

libboost (for GNU radio 3.3.0 install libboost 1.40)

libusb and libusb-dev

wxWidgets (wx-common) and wxPython (python-wxgtk2.8)

python-numpy (via python-numpy-ext) (for SVN on or after 2007-May-28)

ALSA (alsa-base, libasound2 and libasound2-dev)

Qt (libqt3-mt-dev for versions earlier than 8.04; version 4(libqtcore4-libqtgui4) works for 8.04 and

later)

SDL (libsdl-dev)

GSL GNU Scientific Library (libgsl0-dev >= 1.10 required for SVN trunk, not in binary

repositories for 7.10 and earlier)

SWIG (1.3.31 or newer required)

Edgy or previous: requires installation from source

Feisty or newer: use the standard package install (swig)

QWT and QWT PLot3d libraries (optional for Qt Gui)

9.3.2 Other useful packages

doxygen (for creating documentation from source code)

octave (from "universe")

9.4 GNU radio setup

Install guile

Install sdcc

Install JACK,libjack-dev

Install libosip

Install libqtgui4,python-qt4,libgnuradio-qtgui0,python-gnuradio-qtgui

Install Python-lxml,Python-Cheetah ==> for grc

Install libortp-dev ==> for OpenBts code configure

Cd GNU radio

Enable ./configure:type “chmod a+x ./configure” in gnuradio-3.3.0 and gnuradio-

3.3.0/usrp2/firmware

Enable ./configure.gui

./configure

Make

Sudo make install

If the configuration is successful the following message should appear on the terminal:

Figure 5-successful result for GNU radio configuration

After ./ configure you should make sure that gr-usrp compnent was successfully installed

You should make sure that the make command doesn't result in any error

Install GRC 1.3 from synaptic package manager

Set the pythonpath and the LD_LIBRARY path as follows:

Cd home/<username>

Gedit .bashrc

Write the following lines at the end of the .bashrc file

export LD_LIBRARY_PATH=/usr/local/lib

export PYTHONPATH=usr/local/lib/python2.6/site-packages

To make sure that these paths were changed type the following command in the terminal:

Env

Go to usr/local/share/gnuradio/grc/freedesktop

Run grc

If you get an error telling you that the python or ld_library paths are not installed correctly then

make sure that python-gnuradio is installed

9.5 Testing the WBX

Connect the usrp

Type lsusrp in the terminal

9.6 Compiling and running openbts

copy these files into ur code's directory:

all files in /usr/share/libtool/config/ except the softlinks config.sub and config.guess

copy config.sub and config.guess from /usr/share/misc to ur code's directory

Type the following commands in the terminal:

1-aclocal

2-autoconf

3-autoheader

4-automake

5-./configure

6-make

7-sudo make install

8-cp OpenBTS.config.example OpenBTS.config

9- alter the required settings in OpenBTS.config(mcc= 602 ,mnc= 04 or greater,arfcn =20)

10-cd apps

11-./OpenBTS

Now start searching for the OpenBTS network

10 REFERENCES

[1] The Open BTS Project, David A. Burgess, Harvind S. Samra, August 3, 2008.

[2] Mobile radio interface layer 3 specification, GSM 04.08 version 7.7.1 Release 1998