OsmocomBB

h1. FakeTRX (Virtual Um-interface)

FakeTRX is a virtual Um-interface implementation written in Python, that allows to connect both [[OsmocomBB:]] and [[OsmoBTS:]] without the actual RF hardware. The main purpose of this software is to facilitate and simplify development and testing process. In other words, you don't need to physically run your GSM network nor use any kind of special hardware - just run a few scripts and do anything you want / need in your virtual GSM network!

h2. Source code

FakeTRX is a part of [[OsmocomBB:]]. The source code is available at gitea.osmocom.org.

You can browse it via gitea: https://gitea.osmocom.org/phone-side/osmocom-bb/src/branch/master/src/target/trx_toolkit, and download using git:

<pre>

$ git clone https://gitea.osmocom.org/phone-side/osmocom-bb

Contributions are welcome via [[cellular-infrastructure:Gerrit]].

h2. FAQ

h3. What is the difference from [[cellular-infrastructure:Virtual_Um|VIRT-PHY]]?

The main difference is that FakeTRX basically works on GSM L1 and deals with bursts, while [[cellular-infrastructure:Virtual_Um|VIRT-PHY]] works on GSM L2, using GSMTAP and multicast sockets to exchange MAC-blocks. FakeTRX provides the [[TRX Interface]] for both [[OsmocomBB:]] and [[OsmoBTS:]], and forwards GSM bursts between both sides. So, there is no need to do any modifications in the [[OsmoBTS:]] source code, just use osmo-bts-trx.

h3. Python?

Of course, Python is slower than C, for example. But it's more than enough for exchanging UDP messages between [[OsmocomBB:]] and [[OsmoBTS:]], and vice versa. Moreover, it can be easily reimplemented in C/C++, if someone needs better performance.

h3. Python2 or Python3?

The current implementation is known to work with both versions of Python. FakeTRX is not using any version-specific features or modules.

h3. What about RSSI and ToA (Timing of Arrival)?

Since we are talking about the virtual Um-interface, it's possible to emulate different parameters of the physical RF interface:

* ToA (Timing of Arrival) - measured difference between expected and actual time of burst arrival in units of 1/256 of GSM symbol periods.

* RSSI (Received Signal Strength Indication) - measured "power" of the signal (per burst) in dBm.

* Path loss - bit errors, burst clipping, interference, etc.

By default, ToA is 0 and RSSI is -60 dBm. All simulation parameters mentioned above can be changed at runtime using the control commands with prefix 'FAKE_'. For more details, see documentation of the main FakeTRX class.

h3. Can I run multiple BTS and / or multiple MS instances?

Yes (since #3667 is done)!

h2. Running

This guide assumes that you already have the Osmocom GSM [[cellular-infrastructure:|network side stack]] compiled and installed. If not, the simplest way is to use the [[osmonitb:|Network in the Box]].

{{graphviz_link()

digraph G {

    rankdir = LR;

    subgraph cluster_M {

        L23APP1 [label="L2&3 app (e.g. mobile)"];

        L23APP2 [label="L2&3 app (e.g mobile)"];

        TTCN3MS [label="TTCN-3 TC (MS side)"];

        TRXcon1 [label="trxcon"];

        TRXcon2 [label="trxcon"];

        TRXcon3 [label="trxcon"];

        label = "Mobile side";

    }

    FakeTRX [label="FakeTRX"];

    subgraph cluster_N {

        OsmoBSC;

        TTCN3NET [label="TTCN-3 TC (BTS side)"];

        OsmoBTS1 [label="osmo-bts-trx"];

        OsmoBTS2 [label="osmo-bts-trx"];

        OsmoBTS3 [label="osmo-bts-trx"];

        label = "Network side";

    }

    L23APP1 -> TRXcon1 [label="L1CTL"];

    L23APP2 -> TRXcon2 [label="L1CTL"];

    TTCN3MS -> TRXcon3 [label="L1CTL"];

    TRXcon1 -> FakeTRX [label="TRX Interface"];

    TRXcon2 -> FakeTRX [label="TRX Interface"];

    TRXcon3 -> FakeTRX [label="TRX Interface"];

    FakeTRX -> OsmoBTS1 [label="TRX Interface"];

    FakeTRX -> OsmoBTS2 [label="TRX Interface"];

    FakeTRX -> OsmoBTS3 [label="TRX Interface"];

    OsmoBTS1 -> OsmoBSC;

    OsmoBTS2 -> OsmoBSC;

    OsmoBTS3 -> TTCN3NET;

    }

}

}}

[[TRX Interface]] is a part of the upstream [[OsmocomBB:]], just make sure that you have compiled the latest version of [[TRX Interface#The-trxcon-application|trxcon]] application. FakeTRX is a part of TRX toolkit, that is located in 'src/target/trx_toolkit/'. See README for more details.

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

1. Run the network side stack you have. In this example we will use the [[osmonitb:|Network in the Box]]:

<pre>

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

</pre>

2. Run the fake_trx.py:

<pre>

$ cd osmocom-bb/src/target/trx_toolkit/

$ python ./fake_trx.py

</pre>

3. Start [[OsmoBTS:]]:

<pre>

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

</pre>

Congratulations! Now you have a virtual GSM network running. As you can see, the virtual transceiver emulates the clock source, as this is required for [[OsmoBTS:]]. Also, it handles only a few important commands, such as RXTUNE and TXTUNE, but ignores other irrelevant ones.

4. In order to "bridge" [[Host_Software|L2&3 applications]] with FakeTRX, you need to run [[TRX Interface#The-trxcon-application|trxcon]]:

<pre>

$ cd osmocom-bb/src/host/trxcon/

$ ./trxcon

</pre>

5. Finally, run any L2&3 application, e.g. ccch_scan:

<pre>

$ cd osmocom-bb/src/host/layer23/src/misc/

$ ./ccch_scan -a ARFCN -i 127.0.0.1

</pre>

Please note that ARFCN value should match the one your BTS configured to.

At this stage, you should see the broadcast messages coming from the virtual network, like in case of a real one. You can use Wireshark to analyze them.

h2. Running [[mobile]] application

As you may already know, [[mobile]] application implements GSM mobile phone with SMS, USSD and voice calls. In the virtual network we can benefit from using a virtual SIM card. Just configure one according to your network configuration, see the example below. If you are starting with the default config from the source tree (@osmocom-bb/doc/examples/mobile/default.cfg@), make sure to change @sim reader@ to @sim test@ in the @ms 1@ section.

<pre>

test-sim

  imsi 901700000000000

  no barred-access

  rplmn 901 70

</pre>

Make sure you have the virtual network running, then run mobile the same way as in case of a Calypso based phone:

<pre>

$ cd osmocom-bb/src/host/layer23/src/mobile/

$ ./mobile -i 127.0.0.1

</pre>

Now you can use mobile's telnet interface to manage your virtual phone:

<pre>

$ telnet localhost 4247

$ ...

</pre>

h2. Multiple transceivers

It's possible to handle multiple MS and/or BTS connections in a single [[FakeTRX]] process using _--trx_ option.

Additional MS-/BTS-side transceiver:

<pre>

$ ./fake_trx.py --trx 127.0.0.1:6703

</pre>

Two child transceivers of the main BTS:

<pre>

$ ./fake_trx.py --trx 127.0.0.1:5700/1 --trx 127.0.0.1:5700/2

</pre>

Additional transceiver with name:

<pre>

$ ./fake_trx.py --trx foo@127.0.0.1:5703

</pre>

Additional transceiver with IPv6 address:

<pre>

$ ./fake_trx.py --trx ipv6@[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:5700/5

</pre>

h2. Demo

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

h2. Project status

Supported:

* Simulation and randomization of both RSSI and ToA

* Multiple MS / BTS transceivers (see #3667)

* Burst capture to file (see data_dump.py)

* Injection of bursts and commands