OsmocomBB

= 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 [http://openbsc.osmocom.org/trac/wiki/OsmoBTS OsmoBTS] and [http://openbts.org/ OpenBTS] front-ends.

== 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 [http://bb.osmocom.org/trac/wiki/Software/GettingStarted working setup] 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.

== 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:

{{{

#!sh

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

cd libosmo-dsp/

autoreconf -i

./configure

make

sudo make install

cd ..

}}}

Then clone and compile the jolly/testing branch:

{{{

#!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

}}}

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

==== 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 [wiki:rssi.bin RSSI] or cell_log find the strongest cell and remember it's ARFCN number.

==== Usage ====

{{{

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

}}}

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:

{{{

#!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

}}}

And you should see something like this:

{{{

<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

...

}}}

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

== CalypsoBTS with OsmoBTS ==

[http://openbsc.osmocom.org/trac/wiki/OsmoBTS 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 ​[http://sysmocom.de/ sysmocom].

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

* Wideband SDR transceiver hardware supported by OpenBTS transceiver or [http://openbsc.osmocom.org/trac/wiki/OsmoTRX 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 [http://openbsc.osmocom.org/trac/wiki/OpenBSC project home] for details. NiTB is a simple core network implementation - network in the box. It emulates basic core elements like MSC, HLR, VLR, etc.

=== Dependences ===

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

Install/update the following packages in your distribution:

{{{sudo apt-get install sqlite3 libdbi-dev libdbd-sqlite3 libsctp-dev}}}

==== oRTP ====

This package installs the open source RTP protocol required for libosmo-abis. It can be downloaded at [http://download.savannah.gnu.org/releases/linphone/ortp/sources/]. Current OsmoBTS source works fine with **0.22.0 oRTP** version only. Otherwise there may be problems with voice support.

{{{

#!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 ..

}}}

==== libosmo-abis ====

{{{git clone git://git.osmocom.org/libosmo-abis.git}}}

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: 

{{{PKG_CONFIG_PATH=/usr/local/lib/pkgconfig/ ./configure .....}}}

{{{

#!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 ..

}}}

==== libosmo-netif ====

This package is dependency of OsmoNITB.

{{{

#!sh

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

cd libosmo-netif/

autoreconf -i

./configure

make

sudo make install

sudo ldconfig

cd ..

}}}

=== OsmoNITB ===

The latest version can downloaded via git:

{{{git clone git://git.osmocom.org/openbsc.git}}}

Finish the installation:

{{{

#!sh

cd openbsc/openbsc/

autoreconf -i

./configure

make

sudo make install

cd ../..

}}}

=== OsmoBTS ===

The latest version can downloaded via git:

{{{git clone git://git.osmocom.org/osmo-bts.git}}}

Finish the installation:

{{{

#!sh

cd osmo-bts

autoreconf -i

./configure --enable-trx

make

sudo make install

cd ..

}}}

=== Configuration ===

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

{{{

#!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

}}}

Then init default configuration:

{{{

#!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

}}}

Configure OsmoBTS manually:

{{{

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

}}}

**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 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:

{{{slotmask 1 1 0 0 0 0 0 0}}}

Now find and change following initial config parameters of OpenBSC.

{{{

# 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] section

arfcn <your BTS ARFCN (see note)>

}}}

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

WIP...