OsmocomBB

h1. [[CalypsoBTS]]

This tutorial describes how to turn cheap Calypso based phone(s) into a BTS. Due to hardware limitations the [[CalypsoBTS]] setup cannot provide normal quality of service and only can be used to learn how the base stations works. Because Calypso based phone cannot perform BTS functionality itself, in this tutorial we consider how to use it with "OsmoBTS":http://openbsc.osmocom.org/trac/wiki/OsmoBTS and "OpenBTS":http://openbts.org/ front-ends.

h2. Requirements

First of all you have to understand what you're doing and possible consequences. You can use the frequencies you have valid license for. In many countries you cannot operate any GSM RF equipment unless you have obtained a proper license from the regulatory authority. Accomplishing to operate a BTS without having such a license and/or interfering with a public telecommunications network is a crime and punishable under applicable law! 

Also you need to have a "working setup":http://bb.osmocom.org/trac/wiki/Software/GettingStarted of [[OsmocomBB]]. And finally some things can be differ in your distribution, so you should be able to solve possible problems yourself because it's your machine.

h2. TRX preparation

There are two [[OsmocomBB]] branches provide the transceiver firmware and application. I advice you to use the jolly/testing branch because it have multiple phones support. The transceiver app is an external interface of [[CalypsoBTS]] which abstracts a BTS software from the L1 physical layer. It needs libosmo-dsp as a dependency:

<pre>

<code class="sh">

git clone git://git.osmocom.org/libosmo-dsp.git

cd libosmo-dsp/

autoreconf -i

./configure

make

sudo make install

cd ..

</code></pre>

Then clone and compile the jolly/testing branch:

<pre>

<code class="sh">

# Get the sources	

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

cd trx/

git checkout jolly/testing

cd src/

# It needs TX support

# Just uncomment 'CFLAGS += -DCONFIG_TX_ENABLE' in target/firmware/Makefile

# And make with transceiver support

make HOST_layer23_CONFARGS=--enable-transceiver

</code></pre>

And at this step your transceiver is ready. Let's check how it works!

h4. A bit of theory

It is very important to have a good clock synchronization between the BTS and mobile phones. Time-division (TDMA) systems require very accurate counting of the time segments and when they start and stop. If the towers clocking were out of sync, then communications would falter as each node would be trying to deal with segments that were slightly offset and this would introduce errors. The GPS signals can be used as clock source. But there is more simple way to grab the clock from existing public mobile networks.

Using [[rssibin|RSSI]] or cell_log find the strongest cell and remember it's ARFCN number.

h4. Usage

<pre>

Usage: ./transceiver -a arfcn_sync

Some useful options:

  -h   --help             this text

  -d   --debug MASK       Enable debugging (e.g. -d DL1C:DTRX)

  -e   --log-level LOGL   Set log level (1=debug, 3=info, 5=notice)

  -D   --daemonize        For the process into a background daemon

  -s   --disable-color    Don't use colors in stderr log output

  -a   --arfcn-sync ARFCN Set ARFCN to sync to

  -p   --arfcn-sync-pcs   The ARFCN above is PCS

  -2   --second-phone     Use second phone for TS 1

  -r   --realtime PRIO    Set realtime scheduler with given prio

</code></pre>

Where --arfcn-sync or --arfcn-sync-pcs indicates the *ARFCN of clock source cell*. High priority scheduling required for handling bursts (-r 99). Just try to sync:

<pre>

<code class="sh">

# Load the TRX firmware in first terminal

cd trx/src/

sudo host/osmocon/osmocon -r 99 -m c123xor -p /dev/ttyUSB0 -c target/firmware/board/compal_e88/trx.highram.bin

# In second terminal run the transceiver

cd trx/src/host/layer23/src/transceiver/

sudo ./transceiver -a <ARFCN> -r 99

</code></pre>

And you should see something like this:

<pre>

<0012> l1ctl.c:383 Reset received: Starting sync.

<0012> l1ctl.c:338 Sync acquired, setting BTS mode ...

<0011> trx.c:194 TRX CLK Indication 1255520

<0011> trx.c:194 TRX CLK Indication 1255571

<0011> trx.c:194 TRX CLK Indication 1255622

<0011> trx.c:194 TRX CLK Indication 1255673

<0011> trx.c:194 TRX CLK Indication 1255724

<0011> trx.c:194 TRX CLK Indication 1255775

<0011> trx.c:194 TRX CLK Indication 1255826

<0011> trx.c:194 TRX CLK Indication 1255877

<0011> trx.c:194 TRX CLK Indication 1255928

<0011> trx.c:194 TRX CLK Indication 1255979

<0011> trx.c:194 TRX CLK Indication 1256030

<0011> trx.c:194 TRX CLK Indication 1256081

...

</code></pre>

If something goes wrong, find another ARFCN and try again.

h1. [[CalypsoBTS]] with [[OsmoBTS]]

"OsmoBTS":http://openbsc.osmocom.org/trac/wiki/OsmoBTS is a software implementation of Layer2/3 of a BTS. Currently it supports a few hardware back-ends only:

* Multiple indoor and outdoor BTS products called ​sysmoBTS which is sold by ​"sysmocom":http://sysmocom.de/.

* Multiple indoor and outdoor ​fairwaves BTSs, like [[UmDESK]] and [[UmSITE]].

* Wideband SDR transceiver hardware supported by [[OpenBTS]] transceiver or "OsmoTRX":http://openbsc.osmocom.org/trac/wiki/OsmoTRX PHY layer software, including the [[UmTRX]], the USRP family, etc.

* A pretty crazy experimental BTS hardware based on several [[OsmocomBB]] phones.

The simplest way to test how it works is to use [[OsmoBTS]] with [[OpenBSC]] in [[NiTB]] mode. Refer "project home":http://openbsc.osmocom.org/trac/wiki/OpenBSC for details. [[NiTB]] is a simple core network implementation - network in the box. It emulates basic core elements like MSC, HLR, VLR, etc.

h3. Dependences

Make sure that you have installed "libosmocore":http://bb.osmocom.org/trac/wiki/libosmocore.

Install/update the following packages in your distribution:

<pre>

h4. oRTP

This package installs the open source RTP protocol required for libosmo-abis. It can be downloaded at "Current [[OsmoBTS]] source works fine with **0.22.0 oRTP** version only. Otherwise there may be problems with voice support.

<pre>

<code class="sh">

wget http://download.savannah.gnu.org/releases/linphone/ortp/sources/ortp-0.22.0.tar.gz

tar -xvf ortp-0.22.0.tar.gz

cd ortp-0.22.0/

./configure

make

sudo make install

sudo ldconfig

cd ..

</code></pre>

h4. libosmo-abis

<pre>

Sometimes it is necessary to point to different pkgconfig path, because your distribution may use other pkgconfig path than the default path of the packages above. Use the following prefix: 

<pre>

<pre>

<code class="sh">

cd libosmo-abis

autoreconf -i

./configure

(sometimes it is necessary to point to different .../lib/pkgconfig/ path: PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/ ./configure .....)

make

sudo make install

sudo ldconfig

cd ..

</code></pre>

h4. libosmo-netif

This package is dependency of [[OsmoNITB]].

<pre>

<code class="sh">

git clone git://git.osmocom.org/libosmo-netif.git

cd libosmo-netif/

autoreconf -i

./configure

make

sudo make install

sudo ldconfig

cd ..

</code></pre>

h3. [[OsmoNITB]]

The latest version can downloaded via git:

<pre>

Finish the installation:

<pre>

<code class="sh">

cd openbsc/openbsc/

autoreconf -i

./configure

make

sudo make install

cd ../..

</code></pre>

h3. [[OsmoBTS]]

The latest version can downloaded via git:

<pre>

Finish the installation:

<pre>

<code class="sh">

cd osmo-bts

autoreconf -i

./configure --enable-trx

make

sudo make install

cd ..

</code></pre>

h3. Basic configuration

Now wee need to configure [[OpenBSC]] and [[OsmoBTS]] to work together with [[CalypsoBTS]].

<pre>

<code class="sh">

# Create the configuration folder if it isn't exist yet

mkdir ~/.osmocom

cd ~/.osmocom

touch ~/.osmocom/open-bsc.cfg

touch ~/.osmocom/osmo-bts.cfg

</code></pre>

Then init default configuration:

<pre>

<code class="sh">

# Run [[OpenBSC]]

osmo-nitb -c ~/.osmocom/open-bsc.cfg -l ~/.osmocom/hlr.sqlite3 -P -C --debug=DRLL:DCC:DMM:DRR:DRSL:DNM

# In another terminal

telnet localhost 4242

en

write file

exit

# Kill [[OpenBSC]]

Ctrl + C

</code></pre>

Configure [[OsmoBTS]] manually:

<pre>

bts 0

 band DCS1800

 ipa unit-id 1801 0

 oml remote-ip 127.0.0.1

 rtp jitter-buffer 0

 paging queue-size 200

 paging lifetime 0

 fn-advance 30

 ms-power-loop -60

 timing-advance-loop

 settsc

 setbsic

 trx 0

  rxgain 0

  power 0

  slotmask 1 0 0 0 0 0 0 0

</code></pre>

**NOTE: "ms-power-loop" at osmo-bts.cfg should be set to -65, in order to prevent saturating the input. Also if the phone is only one or few meters away, "ms max power" should be set to 0. In case of long distance test it can be set to 30 (DCS) or 33 (GSM 900).**

In case of one phone as TRX only one timeslot will be available for [[OsmoBTS]]. This is enough for basic network functionality including Location Update, SMS and USSD support. For the voice calls support you need one more phone serving a TCH channel. In case of two phones change slotmask to:

<pre>

Now find and change following initial config parameters of [[OpenBSC]]:

<pre>

# In network section

network country code <MNC (for test use 001)>

mobile network code <MCC (for test use 01)>

short name <NAME>

long name <NAME>

# In trx[0":http://download.savannah.gnu.org/releases/linphone/ortp/sources/]. section

arfcn <your BTS ARFCN (see note)>

</code></pre>

*Warning:* Only use an ARFCN you have a *valid license* for.

For other configuration parameters description, see "OpenBSC VTY reference":http://openbsc.osmocom.org/trac/wiki/osmo-nitb_VTY.

h3. Voice calls support

By default [[NiTB]] has built-in voice call routing support. In this case you need at least one timeslot serving TCH/H or TCH/F. If you do a call from one phone to another, you will need one channel for each phone. However, it is possible to allow two traffic channels on a single timeslot. To do this configure second timeslot (TS1) as TCH/H at open-bsc.cnf:

<pre>

...

trx 0

   rf_locked 0

   arfcn <ARFCN>

   nominal power 23

   max_power_red 0

   rsl e1 tei 0

   timeslot 0

    phys_chan_config CCCH+SDCCH4

    hopping enabled 0

   timeslot 1

    phys_chan_config TCH/H

    hopping enabled 0

    ...

mncc-int

 default-codec tch-f amr

 default-codec tch-h amr

...

</code></pre>

h3. LCR (optional)

If you want to manage/route calls outside of [[NiTB]], you can replace internal call control by 

"Linux Call Router": http://isdn.eversberg.eu/

h4. opencore-amr

This package installs GSM adaptive multirate codecs and the EFR codec. The Full-Rate and Half-Rate codecs are included in LCR's repository.

<pre>

<code class="sh">

tar xvzf opencore-amr-x.x.x.tar.gz

cd opencore-amr-x.x.x

./configure

make

sudo make install

sudo ldconfig

cd ..

</code></pre>

h4. Sip-Sofia

This package installs the open source SIP stack of Nokia Research Center.

It can downloaded at [http://sourceforge.net/projects/sofia-sip/files/sofia-sip/":http://sourceforge.net/projects/opencore-amr/files/opencore-amr/]..

<pre>

<code class="sh">

tar xvzf sofia-sip-x.xx.xx.tar.gz

cd sofia-sip-x.xx.xx

./configure

make

sudo make install

sudo ldconfig

cd ..

</code></pre>

h4. LCR

This package installs the open source PBX software to bridge ISDN (DSS1) / SIP / GSM (MNCC protocol).

The latest version can downloaded via git:

<pre>

Now configure, as described here:

<pre>

<code class="sh">

cd lcr

autoreconf -i

./configure --with-sip --with-gsm-bs --with-gsm-ms

</code></pre>

Please note, that Half-Rate codec (--enable-gsmhr) codec is so slow, that only one or two calls may occupy CPU completely. So avoid it's usage except for testing.

Sometimes it is necessary to point to different pkgconfig path, because your distribution may use other pkgconfig path than the default path of the packages above. Use the following prefix:

<pre>

The configure result should include:

<pre>

configure: Compiled with GSM network side support 

configure: Compiled with GSM mobile side support

configure: Compiled with GSM AMR codec support

configure: Compiled with SIP support

</code></pre>

Finish the installation:

<pre>

<code class="sh">

make

sudo make install

sudo ldconfig

cd ..

</code></pre>

h3. LCR configuration (optional)

h4. options.conf

<pre>

Add a line to show logging to the console:

<pre>

h4. interface.conf

The simplest configuration uses only the GSM interface. It allows LCR to forward calls from GSM to GSM or from GSM to a call test feature. 

<pre>

You can remove (or comment out) everything and just add this interface:

<pre>

[gsm]

gsm-bs

tones yes

earlyb no

extern

</code></pre>

h4. routing.conf

<pre>

You can remove (or comment out) everything and just add these rulesets:

<pre>

# All calls from interface 'gsm' are forwarded to rule set 'gsm'.

[main]

interface=gsm                           : goto ruleset=gsm

                                        : disconnect cause=31

# All calls that dial '99' prefix, will be test calls. All other calls will be forwarded back to 'gsm' interface.

[gsm]

dialing=99                              : test

                                        : extern interfaces=gsm

</code></pre>

h2. Running

I suggest to have one shell for every process to run, rather than stating all processes as daemon from one shell. Not starting as daemon allows to easily see the debugging output.

h4. 1. Transceiver

First load the TRX firmware. In case of one phone:

<pre>

<code class="sh">

# Shell #1424

cd trx/src/

sudo host/osmocon/osmocon -m c123xor -p /dev/ttyUSB0 -c target/firmware/board/compal_e88/trx.highram.bin -r 99

# Shell #1425

cd trx/src/host/layer23/src/transceiver/

sudo ./transceiver -a <ARFCN to sync> -r 99

</code></pre>

In case of two phones you should run two osmocon applications:

<pre>

<code class="sh">

# Shell #1424

cd trx/src/

sudo host/osmocon/osmocon -m c123xor -p /dev/ttyUSB0 -s /tmp/osmocom_l2 -c target/firmware/board/compal_e88/trx.highram.bin -r 99

# Shell #1425

cd trx/src/

sudo host/osmocon/osmocon -m c123xor -p /dev/ttyUSB1 -s /tmp/osmocom_l2.2 -c target/firmware/board/compal_e88/trx.highram.bin -r 99

# Shell #1426

cd trx/src/host/layer23/src/transceiver/

sudo ./transceiver -a <ARFCN> -2 -r 99

</code></pre>

Make sure that transceiver successfully synchronized to the clock source BTS.

h4. 2. [[OpenBSC]]

Open another shell and start [[OpenBSC]]:

<pre>

[[OpenBSC]] runs as a stand-alone network with given config file and data base. In order to use LCR, add '-m' option. In this case the LCR replaces the built-in call control.

<pre>

Very important is the option '-C'. On certain machines, osmo-nitb will halt from time to time while writing counters to database. This Without this option, audio might interrupt several seconds from time to time.

The debugging is useful for early tests, because you will quickly see what happens if a mobile requests something.

<pre>

<0005> bsc_init.c:423 

WARNING: You are running an 'accept-all' network on a BTS that is not barred. This configuration is

likely to interfere with production GSM networks and should only be used in a RF shielded environment 

such as a faraday cage!

<001a> input/ipaccess.c:831 enabling ipaccess BSC mode

DB: Database initialized.

DB: Database prepared.

</code></pre>

h4. 2.1 LCR (optional)

Start the LCR:

<pre>

<code class="sh">

sudo lcr start

</code></pre>

You should see following output:

<pre>

** LCR  Version 1.14

000000 DEBUG (in sip.cpp/sip_init() line 1997): SIP globals initialized

LCR 1.14 started, waiting for calls...

000000 TRACE 05.02.16 00:05:03.444 --: LCR 1.14 started, waiting for calls...

</code></pre>

And following message at [[OpenBSC]] log:

<pre>

<0006> mncc_sock.c:273 MNCC Socket has connection with external call control application

</code></pre>

h4. 3. [[OsmoBTS]]

And finally start the [[OsmoBTS]] instance:

<pre>

<pre>

((*))

  |

 / \ [[OsmoBTS]]

Using MAC address of eth0: 'xx:xx:xx:xx:xx:xx'

...

<000a> trx_if.c:176 No response from tranceiver

<000a> trx_if.c:176 No response from tranceiver

<000a> trx_if.c:176 No response from tranceiver

</code></pre>

h2. Test

h3. Location Updating

Switch on the phone.

If you have a SIM card for your network MCC/MNC, you can use it and do automatic network search. If not, do a manual network and select this network. You should see debugging output on [[OpenBSC]] like this:

<pre>

...

 <0002> gsm_04_08.c:424 -> LOCATION UPDATE ACCEPT

...

</code></pre>

h3. USSD

<pre>

h3. Call the music (LCR required)

Now enter phone number 995 to select the test function 5 of LCR. This test function just plays the hold music.

h3. Echo and BFI test (LCR required)

Enter phone number 993 to select the test function 3 of LCR. This test function echoes back everything that is received. Note that it will re-transcode the speech data, so the audio from your voice is compressed and decompressed twice until you can hear a fraction of a second later.

You may experience short beeps. These beeps represent all bad frames that could not be decoded or got lost over the air. (Without this test, the missing frames will be extrapolated from previous frame, so some loss rate will not be recognized by the remote end.)

h2. VTY control interface

It is possible (of course) to control your working setup manually. Connect the [[OpenBSC]] VTY telnet interface (port 4242 by default):

<pre>

telnet localhost 4242

en

# Type 'list' for help

# Go to 'configure terminal' if you want to change some configuration params

[[OpenBSC]]#

  help        Description of the interactive help system

  list        Print command list

  write       Write running configuration to memory, network, or terminal

  show        Show running system information

  exit        Exit current mode and down to previous mode

  disable     Turn off privileged mode command

  configure   Configuration from vty interface

  copy        Copy configuration

  terminal    Set terminal line parameters

  who         Display who is on vty

  logging     Configure log message to this terminal

  drop        Debug/Simulation command to drop Abis/IP BTS

  bts         BTS related commands

  sms         SMS related comamnds

  subscriber  Operations on a Subscriber

  sms-queue   SMS Queue

  meas-feed   Measurement export related

# Example: sending an SMS

subscriber imsi <IMSI> sms sender imsi <IMSI2> send Hello, world!

</code></pre>

See "VTY reference":http://openbsc.osmocom.org/trac/wiki/osmo-nitb_VTY for details.

h1. [[CalypsoBTS]] with [[OpenBTS]]

[[OpenBTS]] is another open source software project aimed to replace legacy telecommunication protocols and traditionally complex, proprietary hardware systems by IP a flexible software architecture. It implements the BTS side protocol stack and also some core network elements like [[OpenBSC]] in [[NiTB]] mode.

h3. Installation and configuration

Follow this "howto":https://github.com/RangeNetworks/dev/wiki in the project wiki. Once you have [[OpenBTS]] up and running, you need to change the following configuration parameters in the database (/etc/OpenBTS/OpenBTS.db):

<pre>

Control.GSMTAP.TargetIP = 127.0.0.1

GSM.Radio.NeedBSIC = 1

GSM.Radio.Band = 1800

GSM.CellSelection.Neighbors =   (set to empty string)

GSM.RACH.MaxRetrans = 3

GSM.RACH.TxInteger = 8

GSM.Radio.C0 = <your ARFCN>

Control.LUR.OpenRegistration = ^26242.*$ (see note)

</code></pre>

**Note:** in this example only IMSIs with MCC 262 and the MNC 42 will be allowed to register to the network, change that accordingly.

h3. TRX executable

Make sure that [[OpenBTS]] in not running. In the folder where the [[OpenBTS]] executable resides, create a script with the filename 'transceiver' with the following content:

<pre>

#!/bin/bash

exec <your path to osmocom-bb>/src/host/layer23/src/transceiver/transceiver -a <ARFCN> -r 99

</code></pre>

Where ARFCN is the channel of clock source cell.

And make it executable:

<pre>

<code class="sh">

sudo chmod +x transceiver

</code></pre>

h2. Running

Run TRX application on the phone as described above.

You now can start up [[OpenBTS]] and should hopefully see the BTS by performing a manual network search with your phone. Monitor the output of osmocon and the transceiver/OpenBTS to see if all goes well. If anything should fail, reboot the phone and start over. 

The [[OpenBTS]] CLI allows you to monitor system status and change many operating parameters of [[OpenBTS]] and the Transceiver in real time. Its executable is located at /OpenBTS/OpenBTSCLI.

Have a fun!