Project

General

Profile

OsmoTRX » History » Version 76

pespin, 08/17/2018 03:24 PM

1 41 sylvain
{{>toc}}
2 1 ttsou
3 41 sylvain
h1. [[OsmoTRX]]
4 1 ttsou
5
6 41 sylvain
[[OsmoTRX]] is a software-defined radio transceiver that implements the Layer 1 physical layer of a BTS comprising the following 3GPP specifications:
7
* TS 05.01 "Physical layer on the radio path"
8
* TS 05.02 "Multiplexing and Multiple Access on the Radio Path"
9
* TS 05.04 "Modulation"
10
* TS 05.10 "Radio subsystem synchronization"
11 1 ttsou
12 49 neels
[[OsmoTRX]] is based on the transceiver code from the [[OsmoBTS:OpenBTS]] project, but setup to operate independently with the purpose of using with non-OpenBTS software and projects, while still maintaining backwards compatibility with [[OsmoBTS:OpenBTS]]. Currently there are numerous features contained in [[OsmoTRX:]] that extend the functionality of the [[OsmoBTS:OpenBTS]] transceiver. These features include enhanced support for various embedded platforms - notably ARM - and dual channel diversity support for the Fairwaves [[umtrx:]].
13 41 sylvain
14 73 pespin
h2. OsmoTRX user manuals and documentation
15
16
User Manual can be found "here":http://ftp.osmocom.org/docs/latest/osmotrx-usermanual.pdf.
17
VTY Reference can be found "here":http://ftp.osmocom.org/docs/latest/osmotrx-vty-reference.pdf.
18
19 65 laforge
h2. OsmoTRX in the Osmocom GSM architecture (old OsmoNITB case)
20 46 laforge
21
{{graphviz_link()
22
digraph G {
23
    rankdir = LR;
24
    SDR -> OsmoTRX [label="Raw Samples"];
25
    OsmoTRX -> OsmoBTS [label="bursts over UDP"];
26 1 ttsou
    OsmoBTS -> OsmoNITB [label="Abis/IP"];
27 65 laforge
    OsmoBTS -> OsmoPCU [label="pcu_sock"];
28
    OsmoPCU -> OsmoSGSN [label="Gb/IP"];
29
    OsmoTRX [color=red];
30
}
31
}}
32
33
h2. OsmoTRX in the Osmocom GSM architecture (new OsmoBSC+OsmoMSC case)
34
35
{{graphviz_link()
36
digraph G {
37
    rankdir = LR;
38
    SDR -> OsmoTRX [label="Raw Samples"];
39
    OsmoTRX -> OsmoBTS [label="bursts over UDP"];
40
    OsmoBTS -> OsmoBSC [label="Abis/IP"];
41
    OsmoBSC -> OsmoMSC [label="AoIP"];
42 46 laforge
    OsmoBTS -> OsmoPCU [label="pcu_sock"];
43
    OsmoPCU -> OsmoSGSN [label="Gb/IP"];
44
    OsmoTRX [color=red];
45
}
46
}}
47 41 sylvain
48 62 laforge
h2. RF Hardware support
49 41 sylvain
50 1 ttsou
51 74 pespin
Multiple RF devices are currently supported. These include USRP family products from Ettus Research, and the [[UmTRX:]] from Fairwaves, as well as LimeSDR devices from "Lime Microsystems":https://limemicro.com/ using "LimeSuite":https://github.com/myriadrf/LimeSuite.
52 62 laforge
53
more details (e.g. signal levels) are provided in the hardware specific pages:
54
{{child_pages(HardwareSupport)}}
55
56
h2. Embedded Platform Support
57
58
[[OsmoTRX]] has been tested on the multiple embedded platforms representing a wide range of device types. Low cost ARM devices are generally limited by memory and I/O as much CPU utilization.
59
60
Running a full or near full ARFCN configuration (7 simultaneous TCH channels with Combination V) may require running the GSM stack remotely, which can be configured at runtime on the command line. This limitation appears to be scheduling related more so than lack of CPU resources, and may be resolved at a later time.
61
62
|_.Platform|_.SoC*|_.Processor|_.SIMD/FPU|_.Testing Notes|
63
|ArndaleBoard|Samsung Exynos 5250|ARM Cortex-A15|NEON-VFPv4|7 TCH|
64
|BeagleBoard-xM|Texas Instruments OMAP3|ARM Cortex-A8|NEON|7 TCH, remote [[osmobts:]] stack|
65
|Ettus E100|Texas Instruments OMAP3|ARM Cortex-A8|NEON|7 TCH, remote [[osmobts:]] stack|
66
|Raspberry Pi|Broadcom BCM2835|ARM11|VFP|2 TCH, remote [[osmobts:]] stack|
67
|Shuttle PC|NA|Intel Atom D2550|SSE3|Dual channel, 15 TCH|
68
69
All embedded plaforms were tested with low-phase error modulator disabled. Use of the more accurate modulator on embedded platforms has not been extensively tested.
70
71
72
h2. Features
73
74 41 sylvain
*Intel SSE Support*
75 6 ttsou
* SSE3
76
* SSE4.1
77 20 ttsou
78 41 sylvain
On Intel processors, [[OsmoTRX]] makes heavy use of the Streaming SIMD Extensions (SSE) instruction set. Accelerated operations include pulse shape filtering, resampling, sequence correlation, and many other signal processing operations. SSE3 is the minimum requirement for accelerated use.
79 1 ttsou
80 20 ttsou
SSE3 is present in the majority of Intel processors since later versions of the Pentium 4 architecture and is also present on low power Atom processors. Support is automatically detected at build time. For additional performance information, please see the performance and benchmarks section.
81 29 ttsou
82 41 sylvain
*ARM Support*
83 1 ttsou
* NEON
84
* NEON-VFPv4
85 20 ttsou
86 41 sylvain
[[OsmoTRX]] runs on a variety of ARM processors with and without NEON coprocessors. Like SSE on Intel processors, NEON provides acceleration with SIMD vectorized instructions.
87 20 ttsou
88 1 ttsou
Tested popular architectures include ARM11 (Raspberry Pi), Cortex-A8 (!BeagleBoard), and Cortex-A15 (!ArndaleBoard). Loosely speaking, these platforms are representative of low cost embedded devices, mid-level handsets, and high-end smartphones respectively. Similarly, in order, these platforms include no NEON coprocessor, standard NEON, and NEON-VFPv4. The latter NEON variation, VFPv4, provides additional fused-multiply-accumulate (FMA) instructions useful for many DSP operations.
89
90 26 ttsou
NEON support must be enabled by the user at build time. For additional information, please see the configuration and performance and benchmarks sections.
91 37 ttsou
92 41 sylvain
*Dual Channel (UmTRX and B210)*
93 7 ttsou
94 1 ttsou
Two dual channel modes are available: standard dual channel mode and diversity. In standard dual channel mode, each RF
95 28 ttsou
path of the dual channel device supports a different ARFCN. Each path operates independently a
96 1 ttsou
nd operates similarly to two separate devices. GSM channel capacity in this mode is doubled. This option can be configured at run time from the command line.
97
98 41 sylvain
*Dual Channel Diversity (UmTRX, experimental)*
99 1 ttsou
100 28 ttsou
Diversity mode is similar to the standard dual channel mode except each antenna supports both ARFCN channels. In this case, the receiver sample bandwidth is widened to handle both ARFCN's and subsequently converted and demultiplexed into separate sample streams. Each GSM receive path is fed dual signals, where antenna selection diversity is performed by taking the stronger signal on a burst-by-burst basis. This diversity setup improves uplink reception performance in multipath fading environments.
101 16 ttsou
102 28 ttsou
Limitations are increased CPU utilization and that ARFCN spacing is restricted (currently at 400 kHz) by the receiver sampling bandwidth. Setting the ARFCN spacing beyond the sampling limit will disable the diversity path and operate in standard dual channel mode. This options can be configured at run time from the command line.
103 58 ipse
104 1 ttsou
*Uplink Burst Detection*
105 41 sylvain
106 1 ttsou
[[OsmoTRX]] utilizes an updated receive burst detection algorithm that provides greater sensitivity and reliability than the original [[OsmoBTS:OpenBTS]] approach, which relied on energy detection for the initial stage of burst acquisition.
107
108 50 neels
The limitation of the previous approach was that it was slow to adapt to highly transient power levels and false burst detection in challenging situations such as receiver saturation, which may occur in close range lab testing. The other issue was that a high degree of level tuning was often necessary to operate reliably.
109 41 sylvain
110 1 ttsou
The current receiver code addressed those limitations for improved performance in a wider variety of environments.
111 60 laforge
112 59 roh
*Low Phase Error Modulator*
113 41 sylvain
114 1 ttsou
The default GSM downlink signal is configured for low distortion using a linearized GMSK modulator. The implementation is based on a two pulse Laurent approximation of continuous phase modulated (CPM) signals. The baseband output signal measures with very low phase error and is capable of passing industry spectrum mask requirements. Please note that actual performance will depend strongly on the particular device in use.
115 41 sylvain
116
Theoretical details can be found in the report on "GMSK":http://tsou.cc/gsm/report_gmsk.pdf. Octave / Matlab code for "pulse generation":http://tsou.cc/gsm/laurent.m is also available.
117
118 1 ttsou
This option can be enabled or disabled at run time from the command line.
119
120 43 laforge
Very Low Phase Error (Ettus Research N200)
121
122
!osmo-trx-phase.gif!
123
124
Spectrum Mask (Ettus Research N200)
125
126 1 ttsou
!osmo-trx-spectrum.gif!
127
128 41 sylvain
h2. Mailing List
129 22 ttsou
130 1 ttsou
131 66 laforge
For development purposes, [[OsmoTRX:]] is discussed on the [[OpenBSC:]] mailing list at openbsc@lists.osmocom.org.
132 41 sylvain
133 66 laforge
Subscription information is available at http://lists.osmocom.org/mailman/listinfo/openbsc/.  Please make sure to read our [[cellular-infrastructure:MailingListRules]] before posting.
134 1 ttsou
135 41 sylvain
h2. GPRS support
136 1 ttsou
137 64 laforge
* [[OsmoTRX]] supports the GPRS (and EGPRS/EDGE) features of [[osmoPCU:]] and [[osmoBTS:]] as well as the remaining Osmocom stack, such as [[OsmoSGSN:]] and [[OpenGGSN:OsmoGGSN]]
138 61 laforge
* [[OsmoTRX]] does not support GPRS in combination with [[OsmoBTS:OpenBTS]].  For that, please use the transceiver supplied with [[OsmoBTS:OpenBTS]].
139 41 sylvain
140
h2. Source code
141
142
143 1 ttsou
The source code is available from git.osmocom.org (module osmo-trx).
144 18 ttsou
145
Public read-only access is available via
146 41 sylvain
<pre>
147 19 ttsou
$ git clone git://git.osmocom.org/osmo-trx
148 41 sylvain
</pre>
149 1 ttsou
You can browse it via cgit: http://cgit.osmocom.org/cgit/osmo-trx/
150
151 48 neels
h2. Dependencies
152 1 ttsou
153 48 neels
Install libusb-1.0 and libbost dev packages. On debian 8.4:
154 1 ttsou
155 48 neels
<pre>
156
sudo apt-get install --no-install-recommends libusb-1.0-0-dev libboost-dev
157
</pre>
158 41 sylvain
159 53 neels
h3. UHD
160 1 ttsou
161 48 neels
Unless using USRP1, you will need the Universal Hardware Driver (UHD),
162
which is available from Ettus Research or Fairwaves; the UHD implementation
163
must match your hardware:
164
165
* Ettus Research UHD for USRP devices
166 51 neels
* Fairwaves UHD with [[UmTRX:]]
167 48 neels
* USRP1 does not use the UHD driver, it is supported through the legacy libusrp driver provided in GNU Radio 3.4.2.
168
169 55 wirelesss
h3. UHD for Debian
170 48 neels
171 52 neels
When you are reading this, Debian packages for UHD may be sufficient for running osmo-trx and osmo-bts-trx.
172 48 neels
here are some of the packages that need to be installed:
173
174
<pre>
175 54 neels
sudo apt-get install libuhd-dev uhd-host
176 48 neels
</pre>
177 1 ttsou
178 55 wirelesss
*Troubleshooting:*
179
 
180 52 neels
At the time of writing this (2016-12), for Debian 8 aka jessie you need to use the jessie-backports packages:
181
182
<pre>
183
sudo -s
184
echo "deb http://ftp.de.debian.org/debian jessie-backports main" > /etc/apt/sources.list.d/uhd.list
185
apt-get update
186
apt-get -t jessie-backports install libuhd-dev uhd-host
187
</pre>
188
189
It may also be possible to use the pothos PPA instead:
190 48 neels
191
<pre>
192
sudo add-apt-repository ppa:guruofquality/pothos
193
sudo apt-get update
194
sudo apt install libboost-dev uhd
195
</pre>
196
197 53 neels
h3. Firmware
198 48 neels
199
You also need to download the firmware using a script provided by the UHD package.
200
Instructions suggest running the script as root, but this way is less dangerous:
201
202
<pre>
203
sudo mkdir /usr/share/uhd
204
sudo chown $USER: /usr/share/uhd
205
/usr/lib/uhd/utils/uhd_images_downloader.py
206
</pre>
207
208 63 pespin
You can flash the FPGA data you just downloaded with the following command, setting type and other parameters accordingly to your hw. For instance for an Ettus B200:
209
<pre>
210
uhd_image_loader --args="type=b200"
211
</pre>
212
213
The uhd_image_loader claims it can update the firmware too, but at least on some versions it does nothing when asked to update firmware. If you see no output of firwmare being flashed, you can use this other command line to flash the firmware, adapting it to the firmware file of your HW:
214
<pre>
215
/usr/lib/uhd/utils/b2xx_fx3_utils --load-fw /usr/share/uhd/images/usrp_b200_fw.hex
216
</pre>
217
218 53 neels
h3. Group
219 48 neels
220
You may need to add yourself to the usrp group:
221
222
<pre>
223
sudo gpasswd -a $USER usrp
224
# and re-login to acquire the group
225
</pre>
226
227 53 neels
h3. Verify
228 48 neels
229
run uhd_find_devices to make sure b200 is available:
230
231
<pre>
232
$ uhd_find_devices 
233
linux; GNU C++ version 4.9.1; Boost_105500; UHD_003.007.003-0-unknown
234
235
--------------------------------------------------
236
-- UHD Device 0
237
--------------------------------------------------
238
Device Address:
239
    type: b200
240
    name: MyB210
241
    serial: 1C0FFEE
242
    product: B210
243
</pre>
244
245
h2. Configuration and Build
246
247 41 sylvain
First, run autoreconf to remake the build system files.
248 1 ttsou
<pre>
249 18 ttsou
$ autoreconf -i
250 41 sylvain
...
251 18 ttsou
</pre>
252 41 sylvain
253 18 ttsou
*Intel Platforms (All)*
254 1 ttsou
255 41 sylvain
Intel SSE support is automatically detected on Intel x86 platforms. No user intervention is necessary. The general configuration defaults to the low phase error modulator. Atom users may wish to use the low-CPU utilization modulator, which can be later enabled from the command line at runtime.
256 18 ttsou
<pre>
257 1 ttsou
$ ./configure
258
...
259 19 ttsou
checking whether mmx is supported... yes
260 18 ttsou
checking whether sse is supported... yes
261
checking whether sse2 is supported... yes
262
checking whether sse3 is supported... yes
263
checking whether ssse3 is supported... yes
264
checking whether sse4.1 is supported... yes
265
checking whether sse4.2 is supported... yes
266 41 sylvain
...
267 18 ttsou
</pre>
268 41 sylvain
269 18 ttsou
*ARM Platforms with NEON*
270 41 sylvain
271
Many popular ARM development boards fall under this category including BeagleBoard, PandaBoard, and Ettus E100 USRP. This option will disable the low phase error modulator, which can be re-enabled at runtime. NEON support must be manually enabled.
272 24 ttsou
<pre>
273 41 sylvain
$ ./configure --with-neon
274 1 ttsou
</pre>
275 41 sylvain
276 1 ttsou
*ARM Platforms with NEON-VFPv4*
277 41 sylvain
278
Currently very few development platforms support this instruction set, which is seen mainly in high end smartphones and tablets. Available development boards are ArndaleBoard and ODROID-XU. This option will disable the low phase error modulator, which can be re-enabled at runtime. NEON-VFPv4 support must be manually enabled.
279 1 ttsou
<pre>
280 41 sylvain
$ ./configure --with-neon-vfpv4
281 1 ttsou
</pre>
282 41 sylvain
283 1 ttsou
*ARM Platforms without NEON*
284 41 sylvain
285 1 ttsou
This configuration mainly targets the Raspberry Pi. ARM platforms without NEON vector units are almost always very slow processors, and generally not very suitable for running [[OsmoTRX]]. Running [[OsmoTRX]] on a Raspberry Pi, however, is possible along with limited TCH (voice) channel support. Currently this configuration requires minor code changes.
286
287
Coming soon...
288 41 sylvain
289 75 pespin
*Choosing your target device*
290
291
Different SDR boards are managed using different software or libraries, usually provided by the vendor. As a result, different @osmo-trx@ binaries can be built based on which device one targets. For instance, if support for LimeSDR is required, one must use the @osmo-trx-lms@ binary, whereas if a UHD device is targeted, @osmo-trx-uhd must be used, and so on. Build of different @osmo-trx@ binaries is controlled at configure time:
292
<pre>
293
      --with-uhd              enable UHD based transceiver
294
      --with-usrp1            enable USRP1 gnuradio based transceiver
295
      --with-lms              enable LimeSuite based transceiver
296
</pre>
297
298 1 ttsou
*Build and Install*
299 16 ttsou
300
After configuration, installation is simple.
301 41 sylvain
302 16 ttsou
<pre>
303
$ make
304 41 sylvain
$ sudo make install
305 16 ttsou
</pre>
306
307 41 sylvain
h2. Running
308 16 ttsou
309 76 pespin
Normally simply start @osmo-trx-uhd@ or similar, based on your target device. You only need to remember to pass a suitable config file.
310
[[OsmoTRX]] can be configured with a variety of options. You can find examples for several different devices under @doc/examples@ of @osmo-trx.git@ directory.
311
See section [[OsmoTRX#OsmoTRX-user-manuals-and-documentation|"OsmoTRX user manuals and documentation"]] where you can find links to the VTY reference.
312 41 sylvain
313 56 wirelesss
<pre>
314 71 duo_kali
$ osmo-trx-uhd -C default.cfg
315 56 wirelesss
linux; GNU C++ version 5.3.1 20151219; Boost_105800; UHD_003.009.002-0-unknown
316
317
opening configuration table from path :memory:
318
Config Settings
319
   Log Level............... NOTICE
320
   Device args............. 
321
   TRX Base Port........... 5700
322
   TRX Address............. 127.0.0.1
323
   Channels................ 1
324
   Tx Samples-per-Symbol... 4
325
   Rx Samples-per-Symbol... 1
326
   EDGE support............ Disabled
327
   Reference............... Internal
328
   C0 Filler Table......... Disabled
329
   Multi-Carrier........... Disabled
330
   Diversity............... Disabled
331
   Tuning offset........... 0
332
   RSSI to dBm offset...... 0
333
   Swap channels........... 0
334
335
-- Detected Device: B200
336
-- Loading FPGA image: /usr/share/uhd/images/usrp_b200_fpga.bin... done
337
-- Operating over USB 2.
338
-- Detecting internal GPSDO.... No GPSDO found
339
-- Initialize CODEC control...
340
-- Initialize Radio control...
341
-- Performing register loopback test... pass
342
-- Performing CODEC loopback test... pass
343
-- Asking for clock rate 16.000000 MHz... 
344
-- Actually got clock rate 16.000000 MHz.
345
-- Performing timer loopback test... pass
346
-- Setting master clock rate selection to 'automatic'.
347
-- Asking for clock rate 26.000000 MHz... 
348
-- Actually got clock rate 26.000000 MHz.
349
-- Performing timer loopback test... pass
350 16 ttsou
-- Setting B200 4/1 Tx/Rx SPS
351
-- Transceiver active with 1 channel(s)
352 41 sylvain
</pre>
353 38 ttsou
354 1 ttsou
h2. [[OsmoTRX]] with [[OsmoBTS:OpenBTS]]
355 49 neels
356 38 ttsou
357
[[OsmoTRX]] is fully compatible with [[OsmoBTS:OpenBTS]] for voice and SMS services. Due to differences in handing of GPRS, [[OsmoTRX]] does not support GPRS when used with [[OsmoBTS:OpenBTS]], however, GPRS with the Osmocom stack is supported.
358 41 sylvain
359 49 neels
For use with [[OsmoBTS:OpenBTS]], enable the filler table option "Enable C0 filler table", which enables [[OsmoBTS:OpenBTS]] style idle bursts and retransmissions.
360 41 sylvain
361
<pre>
362 71 duo_kali
$ osmo-trx-uhd -C default.cfg -f
363 41 sylvain
</pre>
364 17 ttsou
365 49 neels
The [[OsmoTRX]] transceiver should be started before running [[OsmoBTS:OpenBTS]]. No symbolic link to './transceiver' should exist in the [[OsmoBTS:OpenBTS]] directory. This prevents [[OsmoBTS:OpenBTS]] from starting its own transceiver instance.
366 35 ttsou
367 1 ttsou
h2. Authors
368 41 sylvain
369 1 ttsou
370 57 ttsou
[[OsmoTRX]] is currently maintained by Tom Tsou and Alexander Chemeris among others. The code is derived from the [[OsmoBTS:OpenBTS]] project, which was originally developed by David Burgess and Harvind Samra at Range Networks.
Add picture from clipboard (Maximum size: 48.8 MB)