OsmocomBB

h1. CalypsoBTS

{{>toc}}

This tutorial describes how to turn cheap Calypso based phone(s) into a GSM BTS. We will consider both [[OsmoBTS:]] and "OpenBTS":http://openbts.org/ projects as GSM network front-ends. Due to some hardware limitations, the CalypsoBTS setup cannot provide normal quality of service and can only be used to learn how do the base stations work.

h2. Requirements

First of all, you need to understand what are you doing and any possible consequences. Please note, that you can only use the frequencies you have a valid license for. In many countries you cannot operate any GSM RF equipment until a proper license from the regulatory authority is obtained. Running a BTS without such license and/or interfering with the commercial networks is out of law and may be punished! 

This tutorial assumes that you already have a [[Software_Getting_Started|working setup]] of [[OsmocomBB]]. Some things (package names, etc.) can be different in your distribution, so you should be able to resolve possible problems yourself.

h2. Transceiver preparation

Transceiver is a software that performs some low-level GSM L1 operations, such as burst detection, modulation and demodulation, abstracting a BTS or MS from doing that. There are two [[OsmocomBB]] branches implementing the transceiver firmware and host application: 'sylvain/testing' and 'jolly/testing'. The last one is based on the first, but additionally allows to use multiple phones, so I advice you to choose it. 

h3. Dependences

Excepting [[libosmocore:]], the signal processing library [[libosmo-dsp:]] is also required.

1. Make sure you have the latest version of [[libosmocore:]]:

If you don't have the library:

<pre>

$ git clone git://git.osmocom.org/libosmocore

$ cd libosmocore/

</pre>

If you do, but need to update:

<pre>

$ cd libosmocore/

$ sudo make uninstall

$ make distclean

$ git pull --rebase

</pre>

Then:

<pre>

$ autoreconf -f -i

$ ./configure

$ make

$ sudo make install

</pre>

2. Install [[libosmo-dsp:]]:

<pre>

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

$ cd libosmo-dsp/

$ autoreconf -i

$ ./configure

$ make

$ sudo make install

</pre>

h3. Firmware and host software

1. Clone the 'fixeria/trx' branch:

<pre>

$ git clone git://git.osmocom.org/osmocom-bb.git -b fixeria/trx trx

$ cd trx/src/

</pre>

2. Enable TX support in firmware:

Uncomment 'CFLAGS += -DCONFIG_TX_ENABLE' in 'target/firmware/Makefile'.

3. Compile OsmocomBB with transceiver support:

<pre>

$ make HOST_layer23_CONFARGS=--enable-transceiver

</pre>

At this step your transceiver should be ready.

h3. Clock source

Time-division (TDMA) systems require very accurate counting of the time segments (frames and timeslots) and when they start and stop. Also, multiple base stations within a network must be time-synchronized between themselves to make subscribers able to perform handover operation (switching from one BTS to another). 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. This is why a good clock source is required to operate a base station.

The satellite systems, such as GPS and Iridium, do have pretty accurate clock that is being distributed in addition to the prime services (location, calls, etc). They could be used (and often used in commercial networks) for synchronization purposes. This approach would require one to have a corresponding receiver and a direct sky view, but there is a simpler way. We can use the SCH clock indications from existing base stations, eventually a phone is designed to do that!

So, use [[rssibin|RSSI]] or [[cell_log]] applications to find cells with good signal and remember the ARFCN numbers. One of them will be used as a clock source for our own base station.

h3. Usage

1. First, you need to run the transceiver firmware:

<pre>

$ cd trx/src/

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

</pre>

Additionally, if you have two (or more) phones, load the firmware to a second phone (optional):

<pre>

$ cd trx/src/

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

</pre>

2. The host application could be found in 'src/host/layer23/transceiver/':

<pre>

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

$ ./transceiver -h

</pre>

<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

</pre>

The --arfcn-sync or --arfcn-sync-pcs are used to specify the ARFCN of a clock source cell. The high priority scheduling is recommended for low-performance PCs.

3. Let's try to synchronize with a BTS:

If you have two (or more phones), add '-2' option.

<pre>

$ ./transceiver -a <ARFCN>

</pre>

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

...

</pre>

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

As soon as you get the transceiver synchronized, just keep it running.

h2. CalypsoBTS with [[OsmoNITB:]]

The simplest way to setup a GSM network is to use [[OsmoBTS:]] with [[OpenBSC:]] in [[OsmoNITB:]] mode. [[OsmoNITB:]] is a simple core network implementation - network in the box. It emulates basic core elements like MSC, HLR, VLR, etc. [[OsmoBTS:]] is a part of Osmocom GSM core network implementation, that supports a variety of different hardware back-ends, including [[TRX Interface]] transceivers like [[OsmoTRX:]]. Unlike "OpenBTS":http://openbts.org/, this software stack is well maintained, so I would recommend you to choose it.

h3. Installation

This guide is not about building the core network software, so please follow [[openbsc:Building_OpenBSC|Building OpenBSC]]. Feel free to browse the wiki and check out the official documentation http://ftp.osmocom.org/docs/.

You will need to build / install the following components:

* openbsc (legacy Network in the Box)

* osmo-bts (with --enable-trx flag)

h3. Configuration

Almost each program has the configuration examples. Just look for 'doc/examples/'. I recommend you to customize them as you need and put the updated files in a separate directory. Let's use the '~/.osmocom/' for such purposes:

<pre>

$ mkdir ~/.osmocom/

</pre>

You can use the following configuration examples:

* [[OsmoNITB:]]: 'doc/examples/osmo-nitb/sysmobts/openbsc.cfg'

* [[OsmoBTS:]]: 'doc/examples/calypso/osmo-bts.cfg'

There are some important things you need to pay attention.

The recommended values are listed below.

h3. OsmoNITB configuration

h4. Network identification

<pre>

network

  ...

  network country code 901

  mobile network code 70

  short name OpenBSC

  long name OpenBSC

</pre>

h4. Network access

Warning! Setting the access policy to 'accept-all' may be dangerous. It's recommended to use the 'closed' policy, adding your test subscriber(s) info to the HLR database.

<pre>

network

  ...

  auth policy (closed | accept-all | regexp | token)

  authorized-regexp .*

</pre>

h4. Encryption

To be able to use any encryption algorithm, you need to know the Ki of subscribers. So, it's recommended not to use any encryption (A5/0) for testing.

<pre>

network

  ...

  encryption a5 (0 | 1 | 2 | 3)

</pre>

h4. Channel configuration

Set a proper ARFCN for running BTS (don't confuse with a clock source). Also, set a corresponding band name.

<pre>

network

  ...

  bts 0

    ...

    band (GSM900 | DCS1800)

    ...

    trx 0

      ...

      arfcn ARFCN

</pre>

h4. MS power control

If the normal phones are only one or few meters away, the maximal power should be set to 0. In case of long distance test it can be set to 30 (DCS) or 33 (GSM 900).

<pre>

network

  ...

  bts 0

    ...

    ms max power 0

</pre>

h4. Logical channel mapping

I recommend you to use the combined channel configuration (CCCH+SDCCH4) for TS0, because CalypsoBTS at the moment cannot serve all timeslots.

<pre>

network

  ...

  bts 0

    ...

    trx 0

      ...

      timeslot 0

        phys_chan_config CCCH+SDCCH4

        hopping enabled 0

</pre>

If you have two or more Calypso based phones, it's also possible to serve the second timeslot (TS1). For example, 'TCH/H' channel could be used to serve one voice call between two subscribers.

<pre>

network

  ...

  bts 0

    ...

    trx 0

      ...

      timeslot 1

        phys_chan_config TCH/H

        hopping enabled 0

</pre>

h4. Subscriber management policy

Of course, you can manually edit HLR database and configure as much subscribers as you need. But the simplest way is to create subscriber records on fly, during the Location Update Request.

<pre>

network

  ...

  bts 0

    ...

    trx 0

      ...

nitb

  subscriber-create-on-demand

  assign-tmsi

</pre>

h3. OsmoBTS configuration

h4. GSM band configuration

The band value should match one in the [[OsmoNITB:]] configuration.

<pre>

bts 0

  ...

  band (900 | 1800)

</pre>

h4. A-bis link configuration

In the most cases both [[OsmoNITB:]] and [[OsmoBTS:]] are working on the same host. So, the loopback address should be used for 'remote-ip'. The 'unit-id' should be the same as in the [[OsmoNITB:]] configuration.

<pre>

bts 0

  ...

  oml remote-ip 127.0.0.1

  ipa unit-id 1801 0

</pre>

h4. Transceiver configuration

In order to prevent the input saturation, 'ms-power-loop' should be set to -65.

<pre>

phy 0

  ...

  osmotrx ms-power-loop -65

</pre>

Since the CalypsoBTS transceiver is obsolete, it still requires BSIC to be set instead of TSC.

<pre>

phy 0

  ...

  osmotrx legacy-setbsic

</pre>

h3. Running

_Tip: feel free to use tmux or screen to avoid a mess with multiple windows_

0. Make sure your transceiver is still runing...

1. Start [[OsmoNITB:]]:

<pre>

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

</pre>

2. Start [[OsmoBTS:]]:

<pre>

$ osmo-bts-trx -c ~/.osmocom/osmo-bts.cfg

</pre>

Congratulations! Now you should get the network running. You can use telnet interface to control both [[OsmoNITB:]] and [[OsmoBTS:]]:

<pre>

# OsmoNITB telnet interface

$ telnet localhost 4242

# OsmoBTS telnet interface

$ telnet localhost 4241

</pre>

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

h2. CalypsoBTS with "OpenBTS":http://openbts.org/

"OpenBTS":http://openbts.org/ 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 important core network elements.

h3. Installation and configuration

Follow this "howto":https://github.com/RangeNetworks/dev/wiki in the project wiki.

By default, the stock transceiver is used by "OpenBTS":http://openbts.org/. It's designed to work on SDR based hardware (like USRP), but this is not our case. So, we need to replace it by OsmocomBB transceiver.

1. Replace the stock transceiver

Make sure that "OpenBTS":http://openbts.org/ in not running. In the folder where the "OpenBTS":http://openbts.org/ 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>

</pre>

Where ARFCN is the channel of clock source cell. If you have two (or more phones), add '-2' option.

2. And make it executable:

<pre>

sudo chmod +x ./transceiver

</pre>

h3. Running

Run the TRX firmware on the phone as described above. No need to start transceiver, "OpenBTS":http://openbts.org/ will run it automatically.

The "OpenBTS":http://openbts.org/ CLI allows you to monitor system status and change many operating parameters of "OpenBTS":http://openbts.org/ and the Transceiver in real time.

h2. Demo

https://www.youtube.com/watch?v=Aj1A6F-FAGU

https://www.youtube.com/watch?v=FifvFov3RsI

https://www.youtube.com/watch?v=PZ4-UCH2ED8

h2. References

https://www.youtube.com/watch?v=xFjVcxMpA6c

https://events.ccc.de/congress/2012/Fahrplan/attachments/2244_29c3_further_hacks_on_the_calypso_platform

h2. Known limitations and issues

* Two timeslots limitation. Due to some DSP limitations and the non-BTS nature of CalypsoBTS, one phone can serve only one timeslot. Moreover, despite the current transceiver code was extended to support multiple phones ('jolly/testing' branch), this feature is still incomplete. So, for now, up to two phones could be used to serve up to two physical timeslots.

* Non-continuous C0 transmission. According to the GSM specifications, a C0 base station should keep transmission on all timeslots even if there is nothing to transmit. This makes the mobile stations able to detect them and measure the power levels. Again, a phone isn't BTS. It takes some time to tune between DL and UL frequencies.