Project

General

Profile

FakeTRX » History » Version 39

fixeria, 04/19/2019 06:35 PM

1 1 fixeria
h1. FakeTRX (Virtual Um-interface)
2 1 fixeria
3 37 fixeria
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!
4 37 fixeria
5 37 fixeria
h2. Source code
6 37 fixeria
7 37 fixeria
FakeTRX is a part of [[OsmocomBB:]]. The source code is available at git.osmocom.org.
8 37 fixeria
9 37 fixeria
You can browse it via cgit: https://git.osmocom.org/osmocom-bb/tree/src/target/trx_toolkit, and download using git:
10 37 fixeria
11 37 fixeria
<pre>
12 37 fixeria
$ git clone git://git.osmocom.org/osmocom-bb.git
13 37 fixeria
</pre>
14 37 fixeria
15 37 fixeria
Contributions are welcome via [[cellular-infrastructure:Gerrit]].
16 1 fixeria
17 1 fixeria
h2. FAQ
18 1 fixeria
19 3 fixeria
h3. What is the difference from [[cellular-infrastructure:Virtual_Um|VIRT-PHY]]?
20 1 fixeria
21 36 fixeria
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.
22 1 fixeria
23 1 fixeria
h3. Python?
24 1 fixeria
25 38 fixeria
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.
26 19 msuraev
27 5 fixeria
h3. What about RSSI and ToA (Timing of Arrival)?
28 1 fixeria
29 39 fixeria
Since we are talking about the virtual Um-interface, it's possible to emulate different parameters of the physical RF interface:
30 39 fixeria
31 39 fixeria
* ToA (Timing of Arrival) - measured difference between expected and actual time of burst arrival in units of 1/256 of GSM symbol periods.
32 39 fixeria
* RSSI (Received Signal Strength Indication) - measured "power" of the signal (per burst) in dBm.
33 39 fixeria
* Path loss - bit errors, burst clipping, interference, etc.
34 39 fixeria
35 39 fixeria
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.
36 1 fixeria
37 1 fixeria
h3. Can I run multiple BTS and / or multiple MS instances?
38 1 fixeria
39 28 fixeria
Yes (since #3667 is done)!
40 1 fixeria
41 1 fixeria
h2. Running
42 1 fixeria
43 1 fixeria
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]].
44 1 fixeria
45 13 msuraev
{{graphviz_link()
46 13 msuraev
digraph G {
47 13 msuraev
    rankdir = LR;
48 13 msuraev
    subgraph cluster_M {
49 33 fixeria
        L23APP1 [label="L2&3 app (e.g. mobile)"];
50 33 fixeria
        L23APP2 [label="L2&3 app (e.g mobile)"];
51 33 fixeria
        TTCN3MS [label="TTCN-3 TC (MS side)"];
52 30 fixeria
        TRXcon1 [label="trxcon"];
53 30 fixeria
        TRXcon2 [label="trxcon"];
54 30 fixeria
        TRXcon3 [label="trxcon"];
55 1 fixeria
        label = "Mobile side";
56 13 msuraev
    }
57 30 fixeria
58 30 fixeria
    FakeTRX [label="FakeTRX"];
59 30 fixeria
60 1 fixeria
    subgraph cluster_N {
61 1 fixeria
        OsmoBSC;
62 33 fixeria
        TTCN3NET [label="TTCN-3 TC (BTS side)"];
63 1 fixeria
        OsmoBTS1 [label="osmo-bts-trx"];
64 1 fixeria
        OsmoBTS2 [label="osmo-bts-trx"];
65 30 fixeria
        OsmoBTS3 [label="osmo-bts-trx"];
66 1 fixeria
        label = "Network side";
67 1 fixeria
    }
68 30 fixeria
69 30 fixeria
    L23APP1 -> TRXcon1 [label="L1CTL"];
70 30 fixeria
    L23APP2 -> TRXcon2 [label="L1CTL"];
71 30 fixeria
    TTCN3MS -> TRXcon3 [label="L1CTL"];
72 30 fixeria
73 30 fixeria
    TRXcon1 -> FakeTRX [label="TRX Interface"];
74 30 fixeria
    TRXcon2 -> FakeTRX [label="TRX Interface"];
75 30 fixeria
    TRXcon3 -> FakeTRX [label="TRX Interface"];
76 30 fixeria
77 30 fixeria
    FakeTRX -> OsmoBTS1 [label="TRX Interface"];
78 30 fixeria
    FakeTRX -> OsmoBTS2 [label="TRX Interface"];
79 30 fixeria
    FakeTRX -> OsmoBTS3 [label="TRX Interface"];
80 13 msuraev
    OsmoBTS1 -> OsmoBSC;
81 13 msuraev
    OsmoBTS2 -> OsmoBSC;
82 30 fixeria
    OsmoBTS3 -> TTCN3NET;
83 13 msuraev
    }
84 13 msuraev
}
85 13 msuraev
}}
86 29 fixeria
87 30 fixeria
[[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.
88 1 fixeria
89 1 fixeria
_Tip: feel free to use tmux or screen to avoid a mess with multiple windows_
90 1 fixeria
91 1 fixeria
1. Run the network side stack you have. In this example we will use the [[osmonitb:|Network in the Box]]:
92 1 fixeria
93 1 fixeria
<pre>
94 1 fixeria
$ osmo-nitb -c ./openbsc.cfg -l ./hlr.sqlite3 -P -C --debug=DRLL:DCC:DMM:DRR:DRSL:DNM
95 1 fixeria
</pre>
96 1 fixeria
97 31 fixeria
2. Run the fake_trx.py:
98 1 fixeria
99 6 fixeria
<pre>
100 23 msuraev
$ cd osmocom-bb/src/target/trx_toolkit/
101 31 fixeria
$ python ./fake_trx.py
102 1 fixeria
</pre>
103 11 osmith
104 31 fixeria
3. Start [[OsmoBTS:]]:
105 1 fixeria
106 1 fixeria
<pre>
107 23 msuraev
$ osmo-bts-trx -c ./osmo-bts.cfg
108 23 msuraev
</pre>
109 23 msuraev
110 1 fixeria
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.
111 1 fixeria
112 31 fixeria
4. In order to "bridge" [[Host_Software|L2&3 applications]] with FakeTRX, you need to run [[TRX Interface#The-trxcon-application|trxcon]]:
113 1 fixeria
114 23 msuraev
<pre>
115 1 fixeria
$ cd osmocom-bb/src/host/trxcon/
116 31 fixeria
$ ./trxcon
117 23 msuraev
</pre>
118 1 fixeria
119 1 fixeria
5. Finally, run any L2&3 application, e.g. ccch_scan:
120 1 fixeria
121 1 fixeria
<pre>
122 1 fixeria
$ cd osmocom-bb/src/host/layer23/src/misc/
123 1 fixeria
$ ./ccch_scan -a ARFCN -i 127.0.0.1
124 1 fixeria
</pre>
125 1 fixeria
126 1 fixeria
Please note that ARFCN value should match the one your BTS configured to.
127 1 fixeria
128 31 fixeria
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.
129 1 fixeria
130 1 fixeria
h2. Running [[mobile]] application
131 12 osmith
132 1 fixeria
As you should already know, [[mobile]] applications implements a simple 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.
133 1 fixeria
134 1 fixeria
<pre>
135 1 fixeria
test-sim
136 1 fixeria
  imsi 901700000000000
137 1 fixeria
  no barred-access
138 1 fixeria
  rplmn 901 70
139 1 fixeria
</pre>
140 1 fixeria
141 1 fixeria
Make sure you have the virtual network running, then run mobile the same way as in case of a Calypso based phone:
142 1 fixeria
143 1 fixeria
<pre>
144 1 fixeria
$ cd osmocom-bb/src/host/layer23/src/mobile/
145 1 fixeria
$ ./mobile -i 127.0.0.1
146 1 fixeria
</pre>
147 1 fixeria
148 1 fixeria
Now you can use mobile's telnet interface to manage your virtual phone:
149 1 fixeria
150 1 fixeria
<pre>
151 1 fixeria
$ telnet localhost 4247
152 1 fixeria
$ ...
153 1 fixeria
</pre>
154 1 fixeria
155 34 fixeria
h2. Multiple transceivers
156 34 fixeria
157 34 fixeria
It's possible to handle multiple MS and/or BTS connections in a single [[FakeTRX]] process using _--trx_ option.
158 34 fixeria
159 34 fixeria
Additional MS-/BTS-side transceiver:
160 34 fixeria
161 34 fixeria
<pre>
162 34 fixeria
$ ./fake_trx.py --trx 127.0.0.1:6703
163 34 fixeria
</pre>
164 34 fixeria
165 34 fixeria
Two child transceivers of the main BTS:
166 34 fixeria
167 34 fixeria
<pre>
168 34 fixeria
$ ./fake_trx.py --trx 127.0.0.1:5700/1 --trx 127.0.0.1:5700/2
169 34 fixeria
</pre>
170 34 fixeria
171 34 fixeria
Additional transceiver with name:
172 34 fixeria
173 34 fixeria
<pre>
174 34 fixeria
$ ./fake_trx.py --trx foo@127.0.0.1:5703
175 34 fixeria
</pre>
176 34 fixeria
177 34 fixeria
Additional transceiver with IPv6 address:
178 34 fixeria
179 34 fixeria
<pre>
180 34 fixeria
$ ./fake_trx.py --trx ipv6@[2001:0db8:85a3:0000:0000:8a2e:0370:7334]:5700/5
181 34 fixeria
</pre>
182 34 fixeria
183 1 fixeria
h2. Demo
184 1 fixeria
185 1 fixeria
https://www.youtube.com/watch?v=Uxdaui8EkjY
186 1 fixeria
187 1 fixeria
h2. Project status
188 10 fixeria
189 10 fixeria
Supported:
190 10 fixeria
191 10 fixeria
* Simulation and randomization of both RSSI and ToA
192 32 fixeria
* Multiple MS / BTS transceivers (see #3667)
193 10 fixeria
* Burst capture to file (see data_dump.py)
194 1 fixeria
* Injection of bursts and commands
Add picture from clipboard (Maximum size: 48.8 MB)