Project

General

Profile

Virtual Um » History » Version 6

laforge, 07/19/2017 03:49 PM

1 1 laforge
h1. Virtual Um
2 1 laforge
3 1 laforge
In July 2017, the Osmocom project has inroduced a _Virtual Um interface_ (i.e. virtual radio layer) between [[OsmoBTS:]] and [[OsmocomBB:]].  This allows us to run a complete GSM network with 1-N BTSs and 1-M MSs without any actual radio hardware, which is of course excellent for all kinds of testing scenarios.
4 1 laforge
5 1 laforge
The Virtual Um layer is based on sending L2 frames (blocks) encapsulated via GSMTAP UDP multicast packets.  There are two separate multicast groups, one for uplink and one for downlink.  The multicast nature simulates the shared medium and enables any simulated phone to receive the signal from multiple BTSs via the downlink multicast group.
6 1 laforge
7 1 laforge
In [[OsmoBTS:]], this is implemented via the new @osmo-bts-virtual@ BTS model.
8 1 laforge
9 1 laforge
In [[OsmocomBB:]], this is realized by adding @virtphy@ virtual L1, which speask the same [[OsmocomBB:L1A_L23_Interface|L1CTL]] protocol that is used between the _real_ OsmcoomBB Layer1 and the Layer2/3 programs such as [[OsmocomBB:Mobile] and the like.
10 1 laforge
11 1 laforge
This page describes how to set up the Virtual Um layer.  It assumes that you are famliar with classic operation of [[OsmocomBB:]] and [[OsmoBTS:]] and [[OsmoNITB:]] with a real radio layer.  In case of doubt, look at the genric documentation and tutorials for real RF hardware.
12 1 laforge
13 1 laforge
h1. The big picture
14 1 laforge
15 2 laforge
h2. Using OsmoNITB
16 1 laforge
17 2 laforge
{{graphviz_link()
18 2 laforge
digraph G {
19 2 laforge
  rankdir = LR;
20 2 laforge
  bts [label="osmo-bts-virtual"];
21 3 laforge
  mobile [label="OsmocomBB\nmobile"];
22 2 laforge
  network [label="GSMTAP multicast\nUDP/IP" shape="diamond"];
23 2 laforge
  subgraph cluster_ms {
24 2 laforge
    label = "Mobile Station side"
25 2 laforge
    mobile -> virtphy
26 2 laforge
  }
27 2 laforge
  virtphy -> network
28 2 laforge
  network -> bts
29 2 laforge
  subgraph cluster_net {
30 2 laforge
    label = "Network side"
31 2 laforge
    bts -> OsmoNITB
32 2 laforge
  }
33 2 laforge
}
34 2 laforge
}}
35 2 laforge
36 2 laforge
h2. Using OsmoBSC, OsmoMSC, OsmoHLR
37 2 laforge
38 2 laforge
{{graphviz_link()
39 2 laforge
digraph G {
40 2 laforge
  rankdir = LR;
41 2 laforge
  bts [label="osmo-bts-virtual"];
42 3 laforge
  mobile [label="OsmocomBB\nmobile"];
43 2 laforge
  network [label="GSMTAP multicast\nUDP/IP" shape="diamond"];
44 2 laforge
  subgraph cluster_ms {
45 2 laforge
    label = "Mobile Station side"
46 2 laforge
    mobile -> virtphy
47 2 laforge
  }
48 2 laforge
  virtphy -> network
49 2 laforge
  network -> bts
50 2 laforge
  subgraph cluster_net {
51 2 laforge
    label = "Network side"
52 2 laforge
    bts -> OsmoBSC
53 2 laforge
    OsmoBSC -> OsmoMSC
54 2 laforge
    OsmoMSC -> OsmoHLR
55 2 laforge
  }
56 2 laforge
}
57 2 laforge
}}
58 1 laforge
59 1 laforge
h1. The BTS side
60 1 laforge
61 4 laforge
Setting up [[OsmoBTS:]] in its @osmo-bts-virtual@ flavor isn't really much different from setting it up with real hardware.  The amount of required configuration at the BTS configuration file is (as always) very minimal, as in the GSM network architecture provides almost all relevant configuration to the BTS from the BSC.
62 4 laforge
63 4 laforge
An example configuratin file is provided as part of the osmo-bts source code: @doc/examples/virtual/osmobts-virtual.cfg@ (http://git.osmocom.org/osmo-bts/tree/doc/examples/virtual/osmobts-virtual.cfg)
64 4 laforge
65 4 laforge
The only parameters that you must ensure to match your local configuration are:
66 4 laforge
<pre>
67 4 laforge
bts 0
68 4 laforge
 band DCS1800
69 4 laforge
 ipa unit-id 6969 0
70 4 laforge
 oml remote-ip 127.0.0.1
71 4 laforge
</pre>
72 4 laforge
73 4 laforge
* *band* must match the frequency band of your simulated radio layer
74 4 laforge
* *ipa unit-id* must match what you have configured on the BSC ([[OsmoBSC:]] or [[OsmoNITB:]])
75 4 laforge
* *oml remote-ip* must point to the IP address to which your BSC is listening
76 4 laforge
77 4 laforge
You can subsequently start @osmo-bts-virtual@ using the following commands:
78 4 laforge
<pre>
79 4 laforge
$ ./osmo-bts-virtual -c osmo-bts.cfg
80 4 laforge
</pre>
81 4 laforge
whre of course @osmo-bts.cfg@ is the file name (in current directory or with path) of your configuration file, starting from the provided example.
82 4 laforge
83 4 laforge
You should get output like this:
84 4 laforge
<pre>
85 4 laforge
((*))
86 4 laforge
  |
87 4 laforge
 / \ OsmoBTS
88 4 laforge
<000f> main.c:117 Unimplemneted bts_model_phy_instance_set_defaults
89 4 laforge
<0017> control_if.c:788 CTRL at 127.0.0.1 4238
90 4 laforge
<0006> bts_model.c:175 Unimplemneted bts_model_ctrl_cmds_install
91 4 laforge
<0010> telnet_interface.c:102 telnet at 127.0.0.1 4241
92 4 laforge
<0012> input/ipaccess.c:884 enabling ipaccess BTS mode, OML connecting to 127.0.0.1:3002
93 4 laforge
<000d> abis.c:207 Input Signal 4 received
94 4 laforge
<0006> phy_link.c:58 PHY link state change shutdown -> connecting
95 4 laforge
<0006> scheduler.c:216 Init scheduler for trx=0
96 4 laforge
<0007> scheduler_virtbts.c:637 starting VBTS scheduler
97 4 laforge
<0006> phy_link.c:58 PHY link state change connecting -> connected
98 4 laforge
<0006> phy_link.c:68 trx_set_avail(1)
99 4 laforge
<0012> input/ipa.c:129 connection done.
100 4 laforge
<0012> input/ipaccess.c:705 received ID get
101 4 laforge
<000d> abis.c:101 OML Signalling link up
102 4 laforge
</pre>
103 4 laforge
104 4 laforge
followed by the usual OML initialization sequence according to TS 12.21 and finally the RSL initialization:
105 4 laforge
106 4 laforge
<pre>
107 4 laforge
<0000> rsl.c:299  Rx RSL BCCH INFO (SI1, 23 bytes)
108 4 laforge
<0000> rsl.c:299  Rx RSL BCCH INFO (SI2, 23 bytes)
109 4 laforge
<0000> rsl.c:299  Rx RSL BCCH INFO (SI3, 23 bytes)
110 4 laforge
<0000> bts.c:374 Updated AGCH max queue length to 25
111 4 laforge
<0000> rsl.c:299  Rx RSL BCCH INFO (SI4, 23 bytes)
112 4 laforge
<0000> rsl.c:506  Rx RSL SACCH FILLING (SI5, 19 bytes)
113 4 laforge
<0000> rsl.c:506  Rx RSL SACCH FILLING (SI6, 13 bytes)
114 4 laforge
</pre>
115 4 laforge
116 5 laforge
If the BTS process exits immediately, it is likely you have an error in your configuration file syntax, or your BSC does not know any BTS with the unit-id that you have specified in the config file.
117 5 laforge
118 4 laforge
At this point your virtual BTS should be happily transmitting virtual radio frames.  How can you verify that?  Check in wireshark if you see it emitting UDP multicast packets to *239.193.23.1 port 4729*.  Those packets should be properly displayed/decoded by the wireshark GSMTAP dissector, and you should see e.g. the repeated transmission of the SYSTEM INFORMATION messages on BCCH.
119 1 laforge
120 5 laforge
If you cannot see related packets, it might be that your network stack (routing, packet filter) is configured in a way that multiast is disabled/filtered.  On a typical workstation permitting all outbound IP traffic in the firewall and having a default route to eth0, the multicast traffic should appear on that interface.  Please see attached file @osmo_bts_virtual_gsmtap.pcapng@ for an example of how the traffic should look like.
121 1 laforge
122 1 laforge
h1. The MS side
123 6 laforge
124 6 laforge
On the MS side, you will need to compile the classic [[OsmocomBB:]] host-side programs, particularly @layer23/mobile@ and also the new @virtphy@ program
125 6 laforge
126 6 laforge
h2. virtphy
127 6 laforge
128 6 laforge
@virtphy@ is a small program that does not much more than to
129 6 laforge
* bind a local UDP socket to port 4729
130 6 laforge
* subscribe to the downlink IP multicast group 239.193.23.1 to receive downlink messages from the BTS(s)
131 6 laforge
* provide the @/tmp/osmcom_l2@ unix domain socket to whcih L1CTL-using programs such as @mobile@ can connect.  This socket is traditionally provided by the [[OsmocomBB:osmocon]] demultiplexer program, which is only used in context with physical phones.
132 6 laforge
133 6 laforge
You don't need to configure anything, simply run the program 
134 6 laforge
<pre>
135 6 laforge
$ ./virtphy
136 6 laforge
</pre>
137 6 laforge
138 6 laforge
139 6 laforge
h2. mobile
140 6 laforge
141 6 laforge
The [[OsmocomBB:Mobile]] program did not need any modifications and hence does not know whether it is talking to a real L1/PHY or to the @virtphy@ program.  So there's nothing _Virtual Um_ specific regarding its configuration, just configure it as usual.
142 6 laforge
143 6 laforge
One notable requirement is that you use the built-in software SIM card emulation, though, as @virtphy@ doesn't implement the handling of any virtual or physical SIM Card.
144 6 laforge
145 6 laforge
You can then start the program like this:
146 6 laforge
<pre>
147 6 laforge
$ ./mobile -c mobile.cfg
148 6 laforge
</pre>
149 6 laforge
150 6 laforge
Once the @mobile@ program is running, it will instruct @virtphy@ to perform a network scan (which basically just listens for some multicast frames and reports for which ARFCN we have seen CCCH/BCCH frames) and perform operator selection and subsequently the first Location Update (LU).
151 6 laforge
152 6 laforge
A protocol trace of the location update as captured on the Virtual UM layer can be found attached.
153 6 laforge
154 6 laforge
!wireshark_gsmtap_virtphy_lu.png!