Project

General

Profile

OsmoTRX » History » Version 73

pespin, 08/17/2018 02:53 PM

1 41 sylvain
{{>toc}}
2 1 ttsou
3 41 sylvain
h1. [[OsmoTRX]]
4 1 ttsou
5 1 ttsou
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 41 sylvain
* TS 05.01 "Physical layer on the radio path"
8 41 sylvain
* TS 05.02 "Multiplexing and Multiple Access on the Radio Path"
9 41 sylvain
* TS 05.04 "Modulation"
10 41 sylvain
* 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 73 pespin
16 73 pespin
User Manual can be found "here":http://ftp.osmocom.org/docs/latest/osmotrx-usermanual.pdf.
17 73 pespin
VTY Reference can be found "here":http://ftp.osmocom.org/docs/latest/osmotrx-vty-reference.pdf.
18 73 pespin
19 65 laforge
h2. OsmoTRX in the Osmocom GSM architecture (old OsmoNITB case)
20 46 laforge
21 46 laforge
{{graphviz_link()
22 46 laforge
digraph G {
23 46 laforge
    rankdir = LR;
24 46 laforge
    SDR -> OsmoTRX [label="Raw Samples"];
25 46 laforge
    OsmoTRX -> OsmoBTS [label="bursts over UDP"];
26 1 ttsou
    OsmoBTS -> OsmoNITB [label="Abis/IP"];
27 65 laforge
    OsmoBTS -> OsmoPCU [label="pcu_sock"];
28 65 laforge
    OsmoPCU -> OsmoSGSN [label="Gb/IP"];
29 65 laforge
    OsmoTRX [color=red];
30 65 laforge
}
31 65 laforge
}}
32 65 laforge
33 65 laforge
h2. OsmoTRX in the Osmocom GSM architecture (new OsmoBSC+OsmoMSC case)
34 65 laforge
35 65 laforge
{{graphviz_link()
36 65 laforge
digraph G {
37 65 laforge
    rankdir = LR;
38 65 laforge
    SDR -> OsmoTRX [label="Raw Samples"];
39 65 laforge
    OsmoTRX -> OsmoBTS [label="bursts over UDP"];
40 65 laforge
    OsmoBTS -> OsmoBSC [label="Abis/IP"];
41 65 laforge
    OsmoBSC -> OsmoMSC [label="AoIP"];
42 46 laforge
    OsmoBTS -> OsmoPCU [label="pcu_sock"];
43 46 laforge
    OsmoPCU -> OsmoSGSN [label="Gb/IP"];
44 46 laforge
    OsmoTRX [color=red];
45 46 laforge
}
46 46 laforge
}}
47 41 sylvain
48 62 laforge
h2. RF Hardware support
49 41 sylvain
50 1 ttsou
51 62 laforge
Multiple RF devices are currently supported. These include USRP family products from Ettus Research, and the [[UmTRX:]] from Fairwaves.
52 62 laforge
53 62 laforge
more details (e.g. signal levels) are provided in the hardware specific pages:
54 62 laforge
{{child_pages(HardwareSupport)}}
55 62 laforge
56 62 laforge
57 62 laforge
h2. Embedded Platform Support
58 62 laforge
59 62 laforge
[[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.
60 62 laforge
61 62 laforge
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.
62 62 laforge
63 62 laforge
|_.Platform|_.SoC*|_.Processor|_.SIMD/FPU|_.Testing Notes|
64 62 laforge
|ArndaleBoard|Samsung Exynos 5250|ARM Cortex-A15|NEON-VFPv4|7 TCH|
65 62 laforge
|BeagleBoard-xM|Texas Instruments OMAP3|ARM Cortex-A8|NEON|7 TCH, remote [[osmobts:]] stack|
66 62 laforge
|Ettus E100|Texas Instruments OMAP3|ARM Cortex-A8|NEON|7 TCH, remote [[osmobts:]] stack|
67 62 laforge
|Raspberry Pi|Broadcom BCM2835|ARM11|VFP|2 TCH, remote [[osmobts:]] stack|
68 62 laforge
|Shuttle PC|NA|Intel Atom D2550|SSE3|Dual channel, 15 TCH|
69 62 laforge
70 62 laforge
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.
71 62 laforge
72 62 laforge
73 62 laforge
h2. Features
74 62 laforge
75 41 sylvain
*Intel SSE Support*
76 6 ttsou
* SSE3
77 6 ttsou
* SSE4.1
78 20 ttsou
79 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.
80 1 ttsou
81 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.
82 29 ttsou
83 41 sylvain
*ARM Support*
84 1 ttsou
* NEON
85 1 ttsou
* NEON-VFPv4
86 20 ttsou
87 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.
88 20 ttsou
89 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.
90 1 ttsou
91 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.
92 37 ttsou
93 41 sylvain
*Dual Channel (UmTRX and B210)*
94 7 ttsou
95 1 ttsou
Two dual channel modes are available: standard dual channel mode and diversity. In standard dual channel mode, each RF
96 28 ttsou
path of the dual channel device supports a different ARFCN. Each path operates independently a
97 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.
98 1 ttsou
99 41 sylvain
*Dual Channel Diversity (UmTRX, experimental)*
100 1 ttsou
101 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.
102 16 ttsou
103 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.
104 58 ipse
105 1 ttsou
*Uplink Burst Detection*
106 41 sylvain
107 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.
108 1 ttsou
109 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.
110 41 sylvain
111 1 ttsou
The current receiver code addressed those limitations for improved performance in a wider variety of environments.
112 60 laforge
113 59 roh
*Low Phase Error Modulator*
114 41 sylvain
115 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.
116 41 sylvain
117 41 sylvain
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.
118 41 sylvain
119 1 ttsou
This option can be enabled or disabled at run time from the command line.
120 1 ttsou
121 43 laforge
Very Low Phase Error (Ettus Research N200)
122 43 laforge
123 43 laforge
!osmo-trx-phase.gif!
124 43 laforge
125 43 laforge
Spectrum Mask (Ettus Research N200)
126 43 laforge
127 1 ttsou
!osmo-trx-spectrum.gif!
128 1 ttsou
129 41 sylvain
h2. Mailing List
130 22 ttsou
131 1 ttsou
132 66 laforge
For development purposes, [[OsmoTRX:]] is discussed on the [[OpenBSC:]] mailing list at openbsc@lists.osmocom.org.
133 41 sylvain
134 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.
135 1 ttsou
136 41 sylvain
h2. GPRS support
137 1 ttsou
138 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]]
139 61 laforge
* [[OsmoTRX]] does not support GPRS in combination with [[OsmoBTS:OpenBTS]].  For that, please use the transceiver supplied with [[OsmoBTS:OpenBTS]].
140 41 sylvain
141 41 sylvain
h2. Source code
142 41 sylvain
143 41 sylvain
144 1 ttsou
The source code is available from git.osmocom.org (module osmo-trx).
145 18 ttsou
146 18 ttsou
Public read-only access is available via
147 41 sylvain
<pre>
148 19 ttsou
$ git clone git://git.osmocom.org/osmo-trx
149 41 sylvain
</pre>
150 1 ttsou
You can browse it via cgit: http://cgit.osmocom.org/cgit/osmo-trx/
151 1 ttsou
152 48 neels
h2. Dependencies
153 1 ttsou
154 48 neels
Install libusb-1.0 and libbost dev packages. On debian 8.4:
155 1 ttsou
156 48 neels
<pre>
157 48 neels
sudo apt-get install --no-install-recommends libusb-1.0-0-dev libboost-dev
158 48 neels
</pre>
159 41 sylvain
160 53 neels
h3. UHD
161 1 ttsou
162 48 neels
Unless using USRP1, you will need the Universal Hardware Driver (UHD),
163 48 neels
which is available from Ettus Research or Fairwaves; the UHD implementation
164 48 neels
must match your hardware:
165 48 neels
166 48 neels
* Ettus Research UHD for USRP devices
167 51 neels
* Fairwaves UHD with [[UmTRX:]]
168 48 neels
* USRP1 does not use the UHD driver, it is supported through the legacy libusrp driver provided in GNU Radio 3.4.2.
169 48 neels
170 55 wirelesss
h3. UHD for Debian
171 48 neels
172 52 neels
When you are reading this, Debian packages for UHD may be sufficient for running osmo-trx and osmo-bts-trx.
173 48 neels
here are some of the packages that need to be installed:
174 48 neels
175 48 neels
<pre>
176 54 neels
sudo apt-get install libuhd-dev uhd-host
177 48 neels
</pre>
178 1 ttsou
179 55 wirelesss
*Troubleshooting:*
180 55 wirelesss
 
181 52 neels
At the time of writing this (2016-12), for Debian 8 aka jessie you need to use the jessie-backports packages:
182 52 neels
183 52 neels
<pre>
184 52 neels
sudo -s
185 52 neels
echo "deb http://ftp.de.debian.org/debian jessie-backports main" > /etc/apt/sources.list.d/uhd.list
186 52 neels
apt-get update
187 52 neels
apt-get -t jessie-backports install libuhd-dev uhd-host
188 52 neels
</pre>
189 52 neels
190 52 neels
It may also be possible to use the pothos PPA instead:
191 48 neels
192 48 neels
<pre>
193 48 neels
sudo add-apt-repository ppa:guruofquality/pothos
194 48 neels
sudo apt-get update
195 48 neels
sudo apt install libboost-dev uhd
196 48 neels
</pre>
197 48 neels
198 53 neels
h3. Firmware
199 48 neels
200 48 neels
You also need to download the firmware using a script provided by the UHD package.
201 48 neels
Instructions suggest running the script as root, but this way is less dangerous:
202 48 neels
203 48 neels
<pre>
204 48 neels
sudo mkdir /usr/share/uhd
205 48 neels
sudo chown $USER: /usr/share/uhd
206 48 neels
/usr/lib/uhd/utils/uhd_images_downloader.py
207 48 neels
</pre>
208 48 neels
209 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:
210 63 pespin
<pre>
211 63 pespin
uhd_image_loader --args="type=b200"
212 63 pespin
</pre>
213 63 pespin
214 63 pespin
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:
215 63 pespin
<pre>
216 63 pespin
/usr/lib/uhd/utils/b2xx_fx3_utils --load-fw /usr/share/uhd/images/usrp_b200_fw.hex
217 63 pespin
</pre>
218 63 pespin
219 53 neels
h3. Group
220 48 neels
221 48 neels
You may need to add yourself to the usrp group:
222 48 neels
223 48 neels
<pre>
224 48 neels
sudo gpasswd -a $USER usrp
225 48 neels
# and re-login to acquire the group
226 48 neels
</pre>
227 48 neels
228 53 neels
h3. Verify
229 48 neels
230 48 neels
run uhd_find_devices to make sure b200 is available:
231 48 neels
232 48 neels
<pre>
233 48 neels
$ uhd_find_devices 
234 48 neels
linux; GNU C++ version 4.9.1; Boost_105500; UHD_003.007.003-0-unknown
235 48 neels
236 48 neels
--------------------------------------------------
237 48 neels
-- UHD Device 0
238 48 neels
--------------------------------------------------
239 48 neels
Device Address:
240 48 neels
    type: b200
241 48 neels
    name: MyB210
242 48 neels
    serial: 1C0FFEE
243 48 neels
    product: B210
244 48 neels
</pre>
245 48 neels
246 48 neels
h2. Configuration and Build
247 48 neels
248 41 sylvain
First, run autoreconf to remake the build system files.
249 1 ttsou
<pre>
250 18 ttsou
$ autoreconf -i
251 41 sylvain
...
252 18 ttsou
</pre>
253 41 sylvain
254 18 ttsou
*Intel Platforms (All)*
255 1 ttsou
256 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.
257 18 ttsou
<pre>
258 1 ttsou
$ ./configure
259 1 ttsou
...
260 19 ttsou
checking whether mmx is supported... yes
261 18 ttsou
checking whether sse is supported... yes
262 18 ttsou
checking whether sse2 is supported... yes
263 18 ttsou
checking whether sse3 is supported... yes
264 18 ttsou
checking whether ssse3 is supported... yes
265 18 ttsou
checking whether sse4.1 is supported... yes
266 18 ttsou
checking whether sse4.2 is supported... yes
267 41 sylvain
...
268 18 ttsou
</pre>
269 41 sylvain
270 18 ttsou
*ARM Platforms with NEON*
271 41 sylvain
272 41 sylvain
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.
273 24 ttsou
<pre>
274 41 sylvain
$ ./configure --with-neon
275 1 ttsou
</pre>
276 41 sylvain
277 1 ttsou
*ARM Platforms with NEON-VFPv4*
278 41 sylvain
279 41 sylvain
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.
280 1 ttsou
<pre>
281 41 sylvain
$ ./configure --with-neon-vfpv4
282 1 ttsou
</pre>
283 41 sylvain
284 1 ttsou
*ARM Platforms without NEON*
285 41 sylvain
286 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.
287 1 ttsou
288 1 ttsou
Coming soon...
289 41 sylvain
290 1 ttsou
*Build and Install*
291 16 ttsou
292 16 ttsou
After configuration, installation is simple.
293 41 sylvain
294 16 ttsou
<pre>
295 16 ttsou
$ make
296 41 sylvain
$ sudo make install
297 16 ttsou
</pre>
298 16 ttsou
299 41 sylvain
h2. Running
300 16 ttsou
301 70 duo_kali
Normally simply start osmo-trx. (example configuration attached)
302 41 sylvain
303 56 wirelesss
<pre>
304 71 duo_kali
$ osmo-trx-uhd -C default.cfg
305 56 wirelesss
linux; GNU C++ version 5.3.1 20151219; Boost_105800; UHD_003.009.002-0-unknown
306 56 wirelesss
307 56 wirelesss
opening configuration table from path :memory:
308 56 wirelesss
Config Settings
309 56 wirelesss
   Log Level............... NOTICE
310 56 wirelesss
   Device args............. 
311 56 wirelesss
   TRX Base Port........... 5700
312 56 wirelesss
   TRX Address............. 127.0.0.1
313 56 wirelesss
   Channels................ 1
314 56 wirelesss
   Tx Samples-per-Symbol... 4
315 56 wirelesss
   Rx Samples-per-Symbol... 1
316 56 wirelesss
   EDGE support............ Disabled
317 56 wirelesss
   Reference............... Internal
318 56 wirelesss
   C0 Filler Table......... Disabled
319 56 wirelesss
   Multi-Carrier........... Disabled
320 56 wirelesss
   Diversity............... Disabled
321 56 wirelesss
   Tuning offset........... 0
322 56 wirelesss
   RSSI to dBm offset...... 0
323 56 wirelesss
   Swap channels........... 0
324 56 wirelesss
325 56 wirelesss
-- Detected Device: B200
326 56 wirelesss
-- Loading FPGA image: /usr/share/uhd/images/usrp_b200_fpga.bin... done
327 56 wirelesss
-- Operating over USB 2.
328 56 wirelesss
-- Detecting internal GPSDO.... No GPSDO found
329 56 wirelesss
-- Initialize CODEC control...
330 56 wirelesss
-- Initialize Radio control...
331 56 wirelesss
-- Performing register loopback test... pass
332 56 wirelesss
-- Performing CODEC loopback test... pass
333 56 wirelesss
-- Asking for clock rate 16.000000 MHz... 
334 56 wirelesss
-- Actually got clock rate 16.000000 MHz.
335 56 wirelesss
-- Performing timer loopback test... pass
336 56 wirelesss
-- Setting master clock rate selection to 'automatic'.
337 56 wirelesss
-- Asking for clock rate 26.000000 MHz... 
338 56 wirelesss
-- Actually got clock rate 26.000000 MHz.
339 56 wirelesss
-- Performing timer loopback test... pass
340 56 wirelesss
-- Setting B200 4/1 Tx/Rx SPS
341 56 wirelesss
-- Transceiver active with 1 channel(s)
342 56 wirelesss
</pre>
343 56 wirelesss
344 72 duo_kali
[[OsmoTRX]] can be configured with a variety of options as an example you can find at doc/examples of osmo-trx folder.
345 16 ttsou
346 16 ttsou
347 41 sylvain
348 38 ttsou
349 1 ttsou
h2. [[OsmoTRX]] with [[OsmoBTS:OpenBTS]]
350 49 neels
351 38 ttsou
352 38 ttsou
[[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.
353 41 sylvain
354 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.
355 41 sylvain
356 41 sylvain
<pre>
357 71 duo_kali
$ osmo-trx-uhd -C default.cfg -f
358 41 sylvain
</pre>
359 17 ttsou
360 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.
361 35 ttsou
362 1 ttsou
h2. Authors
363 41 sylvain
364 1 ttsou
365 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)