Project

General

Profile

SDR PHY » History » Version 24

fixeria, 08/09/2018 08:03 PM

1 2 fixeria
h1. SDR (Software Defined Radio) hardware
2
3 17 fixeria
{{>toc}}
4
5 2 fixeria
Unlike the obsolete [[Phones|Calypso based phones]], "SDR (Software Defined Radio)":https://en.wikipedia.org/wiki/Software-defined_radio has many advantages, providing much more freedom for the implementation of mobile side [[Software|GSM protocol stack]]. This page describes all steps required for running the higher layer (L2&3) applications (e.g. [[mobile]] or [[ccch_scan]]) on SDR hardware.
6
7
h2. SDR PHY vs Calypso
8
9
h3. What's so special about SDR?
10
11
* General purpose hardware
12
** i.e. not limited to any particular technology and/or protocol stack,
13
** could be used as PHY for GSM, LTE, IEE802.11, GPS, Bluetooth, etc.
14
* Becomes cheap and available for everyone
15
** e.g. RTL-SDR, LimeSDR-Mini
16
* Becomes even smaller than a credit card
17
** e.g. XTRX
18
* Open Source friendly
19
** GNU Radio, GQRX, OpenBTS, OsmoTRX, srsLTE, etc.
20
** some drivers, firmware and PCB schematics are available
21
22
h3. Advantages over Calypso
23
24 11 ipse
* No need to rely on a 'black box' DSP
25 2 fixeria
* No hardware availability problem
26
* No reverse engineering required
27
* No freq. band limitations
28
29
h3. Disadvantages
30
31
* Low output power
32
* General purpose hardware
33
** No screen, no keyboard,
34
** No built-in SIM reader,
35
** No built-in audio
36
** etc.
37
38
h3. What is it for?
39
40
* Another hardware platform for [[OsmocomBB]]
41
* 100% Open Source GSM L1 implementation
42
** GSM TS 05.02 scheduling
43
** GSM TS 05.03 channel coding
44
** GSM TS 05.04 (de)modulation
45
** GSM TS 05.10 synchronization
46
47
h2. Supported SDR hardware
48
49
At the moment, only USRP hardware is supported via UHD driver. This limitation caused by the requirement of RX / TX time tags persistence.
50 13 fixeria
We are currently working on adding support of RX / TX time tags to both Osmocom SDR Source and Sink...
51 2 fixeria
52
The current implementation is known to work on the following devices:
53
54
* USRP B2X0, including 'mini'
55
* Fairwaves [[UmTRX:]]
56
57
h2. Software installation
58
59 5 fixeria
!graph_trxcon.png!
60
61 2 fixeria
The signal processing part is based on [[GR-GSM:]] (https://github.com/ptrkrysik/gr-gsm) project, which is represented by a set of "GNU Radio":https://www.gnuradio.org/ blocks for GSM. So, first of all you need to install "GNU Radio":https://www.gnuradio.org/ with compiled-in "UHD driver":http://files.ettus.com/manual/ support.
62
63
h3. 1. "UHD driver":http://files.ettus.com/manual/
64
65
Follow the "Installing and/or Building UHD" section of official project documentation. After the installation, make sure that your device is recognized properly:
66
67
<pre>
68
$ uhd_find_devices
69
$ uhd_usrp_probe
70
</pre>
71
72
h3. 2. "GNU Radio":https://www.gnuradio.org/
73
74
Despite "GNU Radio":https://www.gnuradio.org/ is available as a binary package on some distributions, we recommend to build the latest release version from source. Please follow the corresponding "building guide":https://wiki.gnuradio.org/index.php/BuildGuide.
75
76
During the build configuration process, make sure you have the following components:
77
78
* python-support
79
* gr-digital
80
* gr-filter
81
* gr-blocks
82
* gr-uhd
83
84
For binary or already installed builds, use the following command to get build info:
85
86
<pre>
87
$ gnuradio-config-info --enabled-components
88
</pre>
89
90
h3. 3. [[GR-GSM:]] with transceiver
91
92 6 fixeria
!graph_trx.png!
93
94 2 fixeria
For now, the transmitter implementation lives in separate branches. This manual compilation from source is required. "General building process":https://github.com/ptrkrysik/gr-gsm/wiki/Manual-compilation-and-installation and dependences are described in the "project's wiki":https://github.com/ptrkrysik/gr-gsm/wiki/.
95
96
<pre>
97
# Get the source code
98
$ git clone git://git.osmocom.org/gr-gsm
99
$ cd gr-gsm/
100
$ git checkout fixeria/trx
101
102
# Configure and compile
103
$ mkdir build
104
$ cd build
105
$ cmake ..
106
$ make
107
108
# Install
109
$ sudo make install
110
$ sudo ldconfig
111
</pre>
112
113 12 fixeria
The transceiver logic is represented by the following flow graph:
114 8 fixeria
115
!grc_trx.png!
116
117 2 fixeria
h3. 4. [[OsmocomBB:]]
118
119
You need to compile OsmocomBB with the [[TRX_Interface|TRX interface]] support. Please refer the corresponding [[TRX_Interface|wiki page]].
120
121
h2. Running
122
123 4 fixeria
First of all, please see [[SDR_PHY#Project-status|known limitations]].
124 2 fixeria
125
h3. Hardware preparation
126
127
You need to have two antennas connected: one for RX, another for TX. Both antennas should be chosen for a proper frequency band, otherwise the distance will be limited. Also, it's strongly recommended to use a band-pass filter for TX in order to *avoid interference*.
128
129
_Note: There is a bug of USRP B2X0 hardware, which affects the burst transmission quality. It appears when both transmission and reception are performed of the same side of device. To mitigate this, please use an attenuator or antenna with some resistance between the active pin and ground._
130
131
Finally, connect your SDR hardware and make sure it's working. 
132
133
h3. Transceiver
134
135
Check available configuration options:
136
137
<pre>
138
$ grgsm_trx --help
139
140
...
141
142
  TRX interface specific
143
   -i --remote-addr  Set remote address (default 127.0.0.1)
144
   -p --base-port    Set base port number (default 5700)
145
146
  Radio interface specific
147
   -a --device-args  Set device arguments
148
   -s --sample-rate  Set sample rate
149
   -g --rx-gain      Set RX gain (default 30)
150
   -G --tx-gain      Set TX gain (default 10)
151
      --rx-antenna   Set RX antenna (default RX2)
152
      --tx-antenna   Set TX antenna (default TX/RX)
153
      --ppm          Set frequency correction (default 0)
154
</pre>
155
156
If you already have another transceiver runing, e.g. [[OsmoTRX:]], choose a different TRX base port. Keep in mind that a single transceiver process occupies six UDP ports at the same time.
157
158
Choose proper RX / TX antennas and corresponding gain values depending on your device. TX gain requires more attention and should be set depending on your environment and antennas used. Feel free to use a spectrum browser, such as GQRX or osmocom_fft, for measuring the proper values.
159
160
PPM value is typically measured at runtime, so no need to specify it manually.
161
162
<pre>
163
$ grgsm_trx --rx-gain 30 --tx-gain 80
164
linux; GNU C++ version 4.8.5; Boost_105500; UHD_003.010.002.000-0-122bfae1
165
166
License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl.html>
167
This is free software: you are free to change and redistribute it.
168
There is NO WARRANTY, to the extent permitted by law.
169
170
[i] Init Radio interface
171
-- Detected Device: B200
172
-- Operating over USB 3.
173
-- Initialize CODEC control...
174
-- Initialize Radio control...
175
-- Performing register loopback test... pass
176
-- Performing CODEC loopback test... pass
177
-- Setting master clock rate selection to 'automatic'.
178
-- Asking for clock rate 16.000000 MHz... 
179
-- Actually got clock rate 16.000000 MHz.
180
-- Performing timer loopback test... pass
181
-- Setting master clock rate selection to 'manual'.
182
-- Asking for clock rate 26.000000 MHz... 
183
-- Actually got clock rate 26.000000 MHz.
184
-- Performing timer loopback test... pass
185
-- Asking for clock rate 26.000000 MHz... OK
186
[i] Init CTRL interface
187
[i] Init complete
188
</pre>
189
190
At this step transceiver is ready.
191
192
h3. The trxcon application
193
194
As we don't use Calypso-based phones, the [[osmocon]] application is useless here. Instead, you need to run another application called trxcon. You should use the same TRX base port as specified to transceiver.
195
196
<pre>
197
$ cd osmocom-bb/src/
198
$ host/trxcon/trxcon
199
200
License GPLv2+: GNU GPL version 2 or later <http://gnu.org/licenses/gpl.html>
201
This is free software: you are free to change and redistribute it.
202
There is NO WARRANTY, to the extent permitted by law.
203
204
<0001> l1ctl_link.c:235 Init L1CTL link (/tmp/osmocom_l2)
205
<0003> trx_if.c:646 Init transceiver interface
206
<0005> sched_trx.c:112 Init scheduler
207
<0000> trxcon.c:277 Init complete
208
</pre>
209
210
See help details.
211
212
h3. L2&3 applications
213
214
At this step you should be able to run the higher layer applications.
215
216
For example, run [[ccch_scan]]:
217
218
<pre>
219
$ cd osmocom-bb/src/
220
$ cd host/layer23/src/misc/
221
$ ./ccch_scan -i 127.0.0.1 -a <ARFCN>
222
</pre>
223
224
It should synchronize with a BTS on specified ARFCN, and start decoding BCCH messages.
225
226 22 fixeria
h2. Docker images
227
228
It's possible to run the software in Docker containers. This way is recommended for beginners.
229
230
_Note:_ at the moment, there is a build script for GR-GSM TRX only.
231
232
The build script for [[GR-GSM:]] (i.e. Dockerfile) is shipped as a part of a separate project called "docker-playground".
233
It's based on "base/archlinux" image, which provides the recent versions of both UHD and GNU Radio without tons of
234
dependencies such as Xorg, GTK, fonts, etc.
235
236
h3. Building Docker image
237
238
You need to clone the "docker-playground" repository first:
239
240
<pre>
241
$ git clone git://git.osmocom.org/docker-playground/
242
</pre>
243
244
Then make sure you have stable Internet connection and enough disk space, and start building:
245
246
<pre>
247
$ cd docker-playground/
248
$ cd gr-gsm-master/
249
$ make build
250
</pre>
251
252
It will take a while...
253
254
As soon as the building process is finished, you should see the new images:
255
256
<pre>
257
$ docker image ls
258
REPOSITORY                TAG                 IMAGE ID            CREATED             SIZE
259 23 fixeria
user/gr-gsm-master        latest              c5912ee7d6ae        About an hour ago   2.09GB
260 1 fixeria
base/archlinux            latest              7477438791e3        28 hours ago        689MB
261 23 fixeria
</pre>
262
263
Please note that *this container requires privileged access* to the host USB devices (USRPs).
264
265
h3. Running Docker image
266
267
Read the above part about running first.
268
269
As soon as you build the image, feel free to start it:
270
271
<pre>
272
$ cd docker-playground/
273
$ cd gr-gsm-master/
274
$ make run
275
</pre>
276
277
The last command will drop you into a bash shell. As there are no build scripts for the higher layer applications of [[OsmocomBB:]], the following part assumes that you are running [[OsmocomBB:]] on the host side.
278
279
By default, Docker should create a network interface for interacting with containers:
280
281
<pre>
282
$ ip addr
283
# ...
284
5: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default 
285
    link/ether 02:42:13:85:c2:c9 brd ff:ff:ff:ff:ff:ff
286
    inet 172.17.0.1/16 scope global docker0
287
       valid_lft forever preferred_lft forever
288
</pre>
289
290
In this example, the host has 172.17.0.1 assigned. Remember this address.
291
292 24 fixeria
_Note:_ make sure your firewall doesn't block the connections with Docker's interface.
293
294 23 fixeria
The container itself should also have it's own address. You can check it:
295
296
<pre>
297
[root@f7e86148c1c2 tmp]# pacman -S net-tools
298
[root@f7e86148c1c2 tmp]# ifconfig
299
eth0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
300
        inet 172.17.0.2  netmask 255.255.0.0  broadcast 0.0.0.0
301
        ether 02:42:ac:11:00:02  txqueuelen 0  (Ethernet)
302
        RX packets 40  bytes 139097 (135.8 KiB)
303
        RX errors 0  dropped 0  overruns 0  frame 0
304
        TX packets 32  bytes 2752 (2.6 KiB)
305
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
306
307
lo: flags=73<UP,LOOPBACK,RUNNING>  mtu 65536
308
        inet 127.0.0.1  netmask 255.0.0.0
309
        loop  txqueuelen 1  (Local Loopback)
310
        RX packets 0  bytes 0 (0.0 B)
311
        RX errors 0  dropped 0  overruns 0  frame 0
312
        TX packets 0  bytes 0 (0.0 B)
313
        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
314
</pre>
315
316
Now, make sure your hardware is available within the container:
317
318
<pre>
319
[root@f7e86148c1c2 tmp]# uhd_find_devices
320
# Device list will appear here
321
</pre>
322
323
And finally, start the transceiver:
324
325
<pre>
326
# You need to use IP address of the host
327
[root@f7e86148c1c2 tmp]# grgsm_trx --remote-addr 172.17.0.1
328
</pre>
329
330
and trxcon on the host side:
331
332 1 fixeria
<pre>
333 24 fixeria
$ cd osmocom-bb/src/host/trxcon/trxcon/
334
335
# You need to use IP address of the host
336
$ ./trxcon --trx-ip 172.17.0.2
337 1 fixeria
</pre>
338 24 fixeria
339
That's it!
340 22 fixeria
341 2 fixeria
h2. Related pages
342
343
* [[TRX Interface]]
344 10 fixeria
345
{{child_pages(TRX_Interface)}}
346 2 fixeria
347
h2. Project status
348
349
Known limitations (not implemented):
350
351 14 fixeria
* Automatic PHY delay measurement
352 2 fixeria
* AGC (Automatic Gain Control)
353
* Power measurement
354
355
Work in progress:
356 1 fixeria
357 16 fixeria
* Docker scripts (Dockerfiles)
358 2 fixeria
* GAPK based audio back-end
359 1 fixeria
* TCH/H implementation
360 16 fixeria
* Frequency Hopping
361 2 fixeria
362
Future plans:
363
364
* Extend supported hardware list (Soapy?)
365
* PC/SC physical SIM interface
366
* AMR (Adaptive Multi-Rate)
367
368
h2. Further reading / watching
369
370
https://media.ccc.de/v/34c3-8952-running_gsm_mobile_phone_on_sdr
371 15 fixeria
https://www.youtube.com/watch?v=nmqzr2-yF04
Add picture from clipboard (Maximum size: 48.8 MB)