Commit 439eba591bff6423a85cbe1e166abb6da0521605

Authored by Nicola Bui
1 parent b8d0be51
Exists in master

alpha release commit

Showing 1 changed file with 153 additions and 46 deletions   Show diff stats
README.txt
  1 +IMDEA-OWL
  2 +=========
  3 +
  4 +OWL stands for Online Watcher of LTE. imdeaOWL is a free and open-source LTE control channel decoder developed by IMDEA Networks Institute and based on srsLTE, an LTE library for SDR UE and eNodeB developed by SRS (www.softwareradiosystems.com). OWL provides blind (oblivious of the terminal identity) decoding of DCI messages on LTE PDCCH.
  5 +OWL is built on srsLTE v1.2 (https://github.com/srsLTE/srsLTE) and inherits its modularity and main features. It is entirely written in C and, if available in the system, uses the acceleration library VOLK distributed in GNURadio.
  6 +
  7 +The OWL software license is AGPLv3.
  8 +
  9 +OWL specific features:
  10 + * Compliant with DCI formats 0, 1, 1A, 1B, 1C, 1D, 2, 2A
  11 + * Obtains C-RNTIs values from PRACH and using blind decoding verification
  12 + * Maintains a list of active C-RNTIs for robustness and decoding speed
  13 + * Provide means for control channel power analysis (without actual decoding)
  14 +
  15 +OWL Missing Features:
  16 + * Carrier Aggregation
  17 + * Semi-Persistent Scheduling
  18 + * Uplink control channel decoding
  19 +
  20 +srsLTE inherited Features:
  21 + * LTE Release 8 compliant
  22 + * FDD configuration
  23 + * Tested bandwidths: 1.4, 3, 5, 10, 15 and 20 MHz
  24 + * Transmission mode 1 (single antenna) and 2 (transmit diversity)
  25 + * Cell search and synchronization procedure for the UE
  26 + * All DL channels/signals are supported for UE and eNodeB side: PSS, SSS, PBCH, PCFICH, PHICH, PDCCH, PDSCH
  27 + * All UL channels/signals are supported for UE side: PRACH, PUSCH, PUCCH, SRS
  28 + * Frequency-based ZF and MMSE equalizer
  29 + * Highly optimized Turbo Decoder available in Intel SSE4.1/AVX (+100 Mbps) and standard C (+25 Mbps)
  30 + * MATLAB and OCTAVE MEX library generation for many components
  31 + * UE receiver tested and verified with Amarisoft LTE 100 eNodeB and commercial LTE networks (Telefonica Spain, Three.ie and Eircom in Ireland)
  32 +
  33 +srsLTE Missing Features:
  34 + * Closed-loop power control
  35 + * Semi-Persistent Scheduling
  36 + * Aperiodic CQI reports
  37 +
  38 +Hardware
  39 +--------
  40 +
  41 +The library currently supports the Ettus Universal Hardware Driver (UHD) and the bladeRF driver. Thus, any hardware supported by UHD or bladeRF can be used. There is no sampling rate conversion, therefore the hardware should support 30.72 MHz clock in order to work correctly with LTE sampling frequencies and decode signals from live LTE base stations.
  42 +
  43 +We have tested the following hardware:
  44 + * USRP B210
  45 + * USRP X300
  46 + * bladeRF
  47 +
1 48 OWL installation and minimal use guide:
  49 +=======================================
2 50  
3   -OWL is built on the srsLTE library by Software Radio Systems. Thus, if you are already able to use srsLTE (at least pdsch_ue) OWL should run without many issues. However, this guide will give you the minimum set of information to install all the required software on a clean ubuntu 14.04 installation (it may work on different distribution, but it is not tested). Also, this guide include steps for the preferable installation of the Nuand BladeRF software. OWL is also tested on USRP x310, but the guide for a correct installation of the related UHD library is to be done in the next release.
  51 +OWL is built on the srsLTE library by Software Radio Systems. Thus, if you are already able to use srsLTE (at least pdsch_ue) OWL should run without many issues. However, this guide will give you the minimum set of information to install all the required software on a clean ubuntu 14.04+ installation. Also, this guide include steps for the preferable installation of the Nuand BladeRF software. OWL is also tested on USRP x310, but the guide for a correct installation of the related UHD library is to be done in the next release.
4 52  
5 53 Part 1 - Installation:
  54 +----------------------
  55 +- Install dependencies:
6 56  
7   -1.1 Install dependencies:
  57 +```sh
8 58 $ sudo apt-get install build-essential git cmake libboost-system-dev libboost-test-dev libboost-thread-dev libqwt-dev libqt4-dev libfftw3-dev
  59 +```
9 60  
10   -1.2 BladeRF installation (skip this if you use USRP )
11   -https://github.com/Nuand/bladeRF/wiki/Getting-Started%3A-Linux
  61 +- BladeRF installation (skip this if you use USRP)
12 62  
  63 +please refer to https://github.com/Nuand/bladeRF/wiki/Getting-Started%3A-Linux for a complete installation guide
13 64 To activate the release PPA, simply:
  65 +```sh
14 66 $ sudo add-apt-repository ppa:bladerf/bladerf
15 67 $ sudo apt-get update
16 68 $ sudo apt-get install bladerf libbladerf-dev bladerf-firmware-fx3 bladerf-fpga-hostedx40
  69 +```
  70 +
  71 +- Install srsgui
17 72  
18   -1.3 Install srsgui (this is not mandatory for OWL to work, but is a nice tool and it helps testing srsLTE and OWL):
  73 +This is not mandatory for OWL to work, but is a nice tool and it helps testing srsLTE and OWL:
  74 +```sh
19 75 $ git clone https://github.com/suttonpd/srsgui.git
20 76 $ cd srsgui
21 77 $ mkdir build
... ... @@ -23,40 +79,58 @@ $ cd build
23 79 $ cmake ../
24 80 $ make
25 81 $ sudo make install
  82 +```
  83 +
  84 +- Install gnuradio
26 85  
27   -1.4 Install gnuradio (only VOLK is needed, but the VOLK standalone installation usually fails and installing gnuradio in this way is usually fast and error-free. If you have problem with this, just try to have VOLK installed https://github.com/gnuradio/volk):
  86 +only VOLK is needed, but the VOLK standalone installation usually fails and installing gnuradio in this way is usually fast and error-free. If you have problem with this, just try to have VOLK installed https://github.com/gnuradio/volk):
  87 +```sh
28 88 $ sudo apt-get install gnuradio
  89 +```
29 90  
30   -1.5 Install OWL
31   -from inside the srsLTE folder do the following:
  91 +- Clone and install OWL
  92 +
  93 +```sh
  94 +$ git clone git@git.networks.imdea.org:nicola_bui/imdeaowl.git
  95 +$ cd imdeaowl
32 96 $ mkdir build
33 97 $ cd build
34 98 $ cmake ../
35 99 $ make
  100 +```
36 101  
37 102 If everything succeeded you will find OWL's executables together with srsLTE's examples in the srsLTE/build/srslte/examples folder.
38 103  
39 104 Part 2 - Executable description:
40   -2.1 Inherited from srsLTE
  105 +--------------------------------
41 106  
  107 +**Inherited from srsLTE**
42 108 - cell_search
  109 +
43 110 Scan a given LTE band trying to acquire synchronization with the base station. Please, refer to this website for the used frequencies in your country
44 111 http://www.spectrummonitoring.com/frequencies
45 112 cell_search requires the band number and can also use the EARFCN numbers to narrow the search, please refer to this website for details:
46 113 http://niviuk.free.fr/lte_band.php
47 114  
48 115 - pdsch_ue
  116 +
49 117 emulate a UE trying to connecting to a given frequency, first looking for synchronization and, then, decoding control messages related to broadcast transmissions.
50 118 In addition, this program provide some useful statistics about synchronization and decoding success rate.
51 119 TIP: once you have the frequency of a base station you can run
  120 +```sh
52 121 $ ./pdsch_ue -f <freq>
  122 +```
53 123 where <freq> is the base station central frequency in hertz, i.e. 1.8 GHz can be given as 1800e6 or 1.8e9. If the synchronization is successfull, pdsch_ue will plot the constellations of the control channel and the shared downlink channel (only broadcast messages). If the signal is clean, you should be able to see a QPSK constellation in both diagrams. In addition, the amplitude and phase channel responses are plotted together with the PSS synchronization. The last one is ok if it looks like a gaussian.
54 124  
55   -2.2 OWL files
  125 +**OWL files**
  126 +
56 127 - imdea_capture_sync
  128 +
57 129 This program capture a raw trace of the LTE channel synchronized on the beginning of the first subframe 0 detected. A very useful reference is http://www.sharetechnote.com/html/FrameStructure_DL.html
58 130 Usage:
  131 +```sh
59 132 $ ./imdea_capture_sync -f <freq> -l <cell_num> -n <subframe_num> -o <output_filename>
  133 +```
60 134 <freq> is the base station central frequency in hertz, i.e. 1.8 GHz can be given as 1800e6 or 1.8e9.
61 135 <cell_num> is in {0,1,2} and can be obtained from cell_search or pdsch_ue (see for reference http://www.sharetechnote.com/html/Handbook_LTE_PCI.html)
62 136 <subframe_num> is the number of subframes to be recorded in the trace. 1 subframe = 1 millisecond
... ... @@ -67,65 +141,98 @@ MIB not decoded ... (noise on the channel)
67 141 sync loss (bad)
68 142  
69 143 - imdea_cc_decoder
  144 +
70 145 This program is the main part of OWL, where the control channel is decoded. It works both online and offline and pre-recorded traces.
  146 +
71 147 Online usage:
  148 +```sh
72 149 $ ./imdea_cc_decoder -f <freq> -n <subframe_num> 1> <cc_out_filename> 2> /dev/null
  150 +```
73 151 <cc_out_filename> specifies where to save the decoded control channel messages. If omitted, the messages are printed to the stdout. Don't forget to redirect the stderr (2> /dev/null), which is used to produce the list of location to be checked by the fine-tuner.
74 152 The output of the decoder is a tab separated list where each line represents a decoded message. The columns are as follows:
75   -1. SFN: internal timing of LTE (1 every frame = 10 ms)
76   -2. subframe index from 0 to 9 (1 subframe = 1 ms)
77   -3. RNTI in decimal
78   -4. Direction: 1 = downlink; 0 = uplink
79   -5. MCS in 0 - 31
80   -6. number of allocated resource blocks in 0 - 110
81   -7. transport block size in bits
82   -8. transport block size in bits (code word 0), -1 if n/a
83   -9. transport block size in bits (code word 1), -1 if n/a
84   -10. DCI message type. This version only scans for 0 (format 0), 2 (format 1a), 6 (format 2a)
85   -11. new data indicator toggle for codeword 0
86   -12. new data indicator toggle for codeword 1
87   -13. HARQ process id
88   -14. ncce location of the DCI message
89   -15. aggregation level of the DCI message
90   -16. CFI
91   -17. DCI correctness check
  153 + 1. SFN: internal timing of LTE (1 every frame = 10 ms)
  154 + 2. subframe index from 0 to 9 (1 subframe = 1 ms)
  155 + 3. RNTI in decimal
  156 + 4. Direction: 1 = downlink; 0 = uplink
  157 + 5. MCS in 0 - 31
  158 + 6. number of allocated resource blocks in 0 - 110
  159 + 7. transport block size in bits
  160 + 8. transport block size in bits (code word 0), -1 if n/a
  161 + 9. transport block size in bits (code word 1), -1 if n/a
  162 + 10. DCI message type. This version only scans for 0 (format 0), 2 (format 1a), 6 (format 2a)
  163 + 11. new data indicator toggle for codeword 0
  164 + 12. new data indicator toggle for codeword 1
  165 + 13. HARQ process id
  166 + 14. ncce location of the DCI message
  167 + 15. aggregation level of the DCI message
  168 + 16. CFI
  169 + 17. DCI correctness check
92 170  
93 171 Offline usage:
  172 +```sh
94 173 $ ./imdea_cc_decoder -i <input_trace_filename> -l <cell_num> -c <pci> -P <ports> -p <prb> -z <rnti_out_filename> -Z <rnti_in_filename> 1> <cc_out_filename> 2> <cc_fix_filename>
  174 +```
95 175 <input_trace_filename> a trace that you saved with imdea_capture_sync
96 176 <pci> <ports> <prb> physical cell id, antenna ports and number of physical resourrce blocks of the LTE channel. All of these can be obtained using cell_search, pdsch_ue, imdea_capture_sync
97 177 <rnti_in_filename> <rnti_out_filename> are the rnti lists. They are optional; if not provided the tool generates a new list. If available it starts with the information given. The format is a vector of 65355 elements, which can be 0 (not used), 1 (used, but not used in the last 10 seconds), 2 (used in the last 10 seconds).
98 178 <cc_fix_filename> output file for the fine_tuner program. It specify one location to be checked per line. The columns are as follows:
99   -1. SFN
100   -2. subframe
101   -3. ncce
102   -4. L
103   -5. CFI
  179 + 1. SFN
  180 + 2. subframe
  181 + 3. ncce
  182 + 4. L
  183 + 5. CFI
104 184  
105 185 - imdea_fine_tuner
  186 +
106 187 offline tool to post_process recorded trace to try to decode DCI messages in location that could not be decoded by imdea_cc_decoder.
107 188 Usage:
  189 +```sh
108 190 $ ./imdea_fine_tuner -i <input_trace_filename> -l <cell_num> -c <pci> -P <ports> -p <prb> -z <cc_fix_filename> -Z <rnti_in_filename> 1> <cc_fixed_filename> 2> /dev/null
  191 +```
  192 +
109 193 it can only be used after imdea_cc_decoder on the output produced. imdea_fine_tuner generate <cc_fixed_filename> with the same format of <cc_out_filename> (see above)
110 194  
111 195 Part 3 - OWL setup and first use
112   -
113   -0. Install everything correctly!
114   -1. Use a software defined radio capable of sampling at a LTE compliant sampling rate (30.72, 23.04, 15.36, 11.52).
115   -2. srsLTE and OWL are heavy on the I/O. Try not to have read/write operations at the same time (different buffers may interfer). If overruns are detected, consider working on ramdisk (see https://wiki.archlinux.org/index.php/Tmpfs)
116   -3. Use a good antenna, capable of LTE frequencies. Check the bands used in your country on http://www.spectrummonitoring.com/frequencies
117   -4. Use cell_search to get the central frequencies of the available cell in the surrounding
118   -5. Try to get a map of the base station location and put your sniffer in a location where a line of sight with the antenna is available
119   -6. Use pdsch_ue and imdea_capture_sync to assess the signal quality
120   -7. Once you have a good signal, you should have pdsch_ue showing very clean QPSK constellations and imdea_capture_sync showing almost only "Decoded MIB ..." output.
121   -8. At this point you should have <freq> <cell_num> <pci> <ports> <prb>
122   -9. Try first the online decoder with the output on screen:
  196 +--------------------------------
  197 +
  198 +- Install everything correctly!
  199 +- Use a software defined radio capable of sampling at a LTE compliant sampling rate (30.72, 23.04, 15.36, 11.52).
  200 +- srsLTE and OWL are heavy on the I/O. Try not to have read/write operations at the same time (different buffers may interfer). If overruns are detected, consider working on ramdisk (see https://wiki.archlinux.org/index.php/Tmpfs)
  201 +- Use a good antenna, capable of LTE frequencies. Check the bands used in your country on http://www.spectrummonitoring.com/frequencies
  202 +- Use cell_search to get the central frequencies of the available cell in the surrounding
  203 +- Try to get a map of the base station location and put your sniffer in a location where a line of sight with the antenna is available
  204 +- Use pdsch_ue and imdea_capture_sync to assess the signal quality
  205 +- Once you have a good signal, you should have pdsch_ue showing very clean QPSK constellations and imdea_capture_sync showing almost only "Decoded MIB ..." output.
  206 +- At this point you should have <freq> <cell_num> <pci> <ports> <prb>
  207 +- Try first the online decoder with the output on screen:
  208 +
  209 +```sh
123 210 $ ./imdea_cc_decoder -f <freq> -n <subframe_num> 2> /dev/null
124   -10. Try a capture, with subsequent decoding and fine tuning:
  211 +```
  212 +
  213 +- Try a capture, with subsequent decoding and fine tuning:
  214 +
  215 +```sh
125 216 $ ./imdea_capture_sync -f <freq> -l <cell_num> -n <subframe_num> -o <output_filename>
126 217 $ ./imdea_cc_decoder -i <input_trace_filename> -l <cell_num> -c <pci> -P <ports> -p <prb> -z <rnti_out_filename> -Z <rnti_in_filename> 1> <cc_out_filename> 2> <cc_fix_filename>
127 218 $ ./imdea_fine_tuner -i <input_trace_filename> -l <cell_num> -c <pci> -P <ports> -p <prb> -z <cc_fix_filename> -Z <rnti_in_filename> 1> <cc_fixed_filename> 2> /dev/null
128 219 $ sort -u <cc_out_filename> <cc_fixed_filename> -o <cc_total_filename> (to combine the output)
129   -11. You can also use the recorded trace to obtain a spectrogram of the LTE transmission (in a future release, I will provide matlab and octave scripts to do that as well).
130   -12. Have fun!
  220 +```
  221 +
  222 +- You can also use the recorded trace to obtain a spectrogram of the LTE transmission (in a future release, I will provide matlab and octave scripts to do that as well).
  223 +- Have fun!
  224 +
  225 +Acknowledgements
  226 +================
  227 +
  228 +If you enjoyed using OWL, please acknowledge us in your publication(s) referring to:
131 229  
  230 +```tex
  231 +@inproceedings{bui2016owl,
  232 + title={{OWL: a Reliable Online Watcher for LTE Control Channel Measurements}},
  233 + author={Bui, Nicola and Widmer, Joerg},
  234 + booktitle = {ACM All Things Cellular (MobiCom Workshop)},
  235 + year = {2016},
  236 + month = {Nov.},
  237 + location = {New York, USA},
  238 +}
... ...