Project

General

Profile

FakeTRX » History » Version 44

neels, 08/30/2022 01:51 PM

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