Commit c0efb7b4a6f64ea4a6a50c7ff4f7a22ce96423e2

Authored by Nicola Bui
1 parent 439eba59
Exists in master

alpha release commit

Showing 1 changed file with 105 additions and 63 deletions   Show diff stats
README.md
... ... @@ -52,65 +52,84 @@ OWL is built on the srsLTE library by Software Radio Systems. Thus, if you are a
52 52  
53 53 Part 1 - Installation:
54 54 ----------------------
55   -1. Install dependencies:
56   - sudo apt-get install build-essential git cmake libboost-system-dev libboost-test-dev libboost-thread-dev libqwt-dev libqt4-dev libfftw3-dev
57   -2. BladeRF installation (skip this if you use USRP)
  55 +- Install dependencies:
58 56  
59   - please refer to https://github.com/Nuand/bladeRF/wiki/Getting-Started%3A-Linux for a complete installation guide
  57 +```sh
  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 +```
60 60  
61   - To activate the release PPA, simply:
  61 +- BladeRF installation (skip this if you use USRP)
62 62  
63   - sudo add-apt-repository ppa:bladerf/bladerf
64   - sudo apt-get update
65   - sudo apt-get install bladerf libbladerf-dev bladerf-firmware-fx3 bladerf-fpga-hostedx40
66   -3. Install srsgui
67   -This is not mandatory for OWL to work, but is a nice tool and it helps testing srsLTE and OWL:
  63 +please refer to https://github.com/Nuand/bladeRF/wiki/Getting-Started%3A-Linux for a complete installation guide
  64 +To activate the release PPA, simply:
  65 +```sh
  66 +$ sudo add-apt-repository ppa:bladerf/bladerf
  67 +$ sudo apt-get update
  68 +$ sudo apt-get install bladerf libbladerf-dev bladerf-firmware-fx3 bladerf-fpga-hostedx40
68 69 ```
69   -git clone https://github.com/suttonpd/srsgui.git
70   -cd srsgui
71   -mkdir build
72   -cd build
73   -cmake ../
74   -make
75   -sudo make install
  70 +
  71 +- Install srsgui
  72 +
  73 +This is not mandatory for OWL to work, but is a nice tool and it helps testing srsLTE and OWL:
  74 +```sh
  75 +$ git clone https://github.com/suttonpd/srsgui.git
  76 +$ cd srsgui
  77 +$ mkdir build
  78 +$ cd build
  79 +$ cmake ../
  80 +$ make
  81 +$ sudo make install
76 82 ```
77   -4. Install gnuradio
  83 +
  84 +- Install gnuradio
  85 +
78 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
  88 +$ sudo apt-get install gnuradio
79 89 ```
80   -sudo apt-get install gnuradio
81   -```
82   -5. Clone and install OWL
83   -```
84   -git clone git@git.networks.imdea.org:nicola_bui/imdeaowl.git
85   -mkdir build
86   -cd build
87   -cmake ../
88   -make
  90 +
  91 +- Clone and install OWL
  92 +
  93 +```sh
  94 +$ git clone git@git.networks.imdea.org:nicola_bui/imdeaowl.git
  95 +$ cd imdeaowl
  96 +$ mkdir build
  97 +$ cd build
  98 +$ cmake ../
  99 +$ make
89 100 ```
  101 +
90 102 If everything succeeded you will find OWL's executables together with srsLTE's examples in the srsLTE/build/srslte/examples folder.
91 103  
92 104 Part 2 - Executable description:
93 105 --------------------------------
94   -1. Inherited from srsLTE
95   - - cell_search
  106 +
  107 +**Inherited from srsLTE**
  108 +- cell_search
  109 +
96 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
97 111 http://www.spectrummonitoring.com/frequencies
98 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:
99 113 http://niviuk.free.fr/lte_band.php
100   - - pdsch_ue
  114 +
  115 +- pdsch_ue
  116 +
101 117 emulate a UE trying to connecting to a given frequency, first looking for synchronization and, then, decoding control messages related to broadcast transmissions.
102 118 In addition, this program provide some useful statistics about synchronization and decoding success rate.
103 119 TIP: once you have the frequency of a base station you can run
104   -```
105   -./pdsch_ue -f <freq>
  120 +```sh
  121 +$ ./pdsch_ue -f <freq>
106 122 ```
107 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.
108   -2. OWL files
  124 +
  125 +**OWL files**
  126 +
109 127 - imdea_capture_sync
  128 +
110 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
111 130 Usage:
112   -```
113   -./imdea_capture_sync -f <freq> -l <cell_num> -n <subframe_num> -o <output_filename>
  131 +```sh
  132 +$ ./imdea_capture_sync -f <freq> -l <cell_num> -n <subframe_num> -o <output_filename>
114 133 ```
115 134 <freq> is the base station central frequency in hertz, i.e. 1.8 GHz can be given as 1800e6 or 1.8e9.
116 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)
... ... @@ -120,11 +139,14 @@ TIP: putting -o /dev/null creates no output, but allows to test the signal synch
120 139 Decoded MIB ... (good)
121 140 MIB not decoded ... (noise on the channel)
122 141 sync loss (bad)
  142 +
123 143 - imdea_cc_decoder
  144 +
124 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 +
125 147 Online usage:
126   -```
127   -./imdea_cc_decoder -f <freq> -n <subframe_num> 1> <cc_out_filename> 2> /dev/null
  148 +```sh
  149 +$ ./imdea_cc_decoder -f <freq> -n <subframe_num> 1> <cc_out_filename> 2> /dev/null
128 150 ```
129 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.
130 152 The output of the decoder is a tab separated list where each line represents a decoded message. The columns are as follows:
... ... @@ -145,9 +167,10 @@ The output of the decoder is a tab separated list where each line represents a d
145 167 15. aggregation level of the DCI message
146 168 16. CFI
147 169 17. DCI correctness check
  170 +
148 171 Offline usage:
149   -```
150   -./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>
  172 +```sh
  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>
151 174 ```
152 175 <input_trace_filename> a trace that you saved with imdea_capture_sync
153 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
... ... @@ -158,39 +181,58 @@ Offline usage:
158 181 3. ncce
159 182 4. L
160 183 5. CFI
161   - - imdea_fine_tuner
  184 +
  185 +- imdea_fine_tuner
  186 +
162 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.
163 188 Usage:
  189 +```sh
  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
164 191 ```
165   -./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
166   -```
  192 +
167 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)
168 194  
169 195 Part 3 - OWL setup and first use
170 196 --------------------------------
171   -0. Install everything correctly!
172   -1. Use a software defined radio capable of sampling at a LTE compliant sampling rate (30.72, 23.04, 15.36, 11.52).
173   -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)
174   -3. Use a good antenna, capable of LTE frequencies. Check the bands used in your country on http://www.spectrummonitoring.com/frequencies
175   -4. Use cell_search to get the central frequencies of the available cell in the surrounding
176   -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
177   -6. Use pdsch_ue and imdea_capture_sync to assess the signal quality
178   -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.
179   -8. At this point you should have <freq> <cell_num> <pci> <ports> <prb>
180   -9. Try first the online decoder with the output on screen:
181   -```
182   -./imdea_cc_decoder -f <freq> -n <subframe_num> 2> /dev/null
183   -```
184   -10. Try a capture, with subsequent decoding and fine tuning:
  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
  210 +$ ./imdea_cc_decoder -f <freq> -n <subframe_num> 2> /dev/null
185 211 ```
186   -./imdea_capture_sync -f <freq> -l <cell_num> -n <subframe_num> -o <output_filename>
187   -./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>
188   -./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
189   -sort -u <cc_out_filename> <cc_fixed_filename> -o <cc_total_filename> (to combine the output)
  212 +
  213 +- Try a capture, with subsequent decoding and fine tuning:
  214 +
  215 +```sh
  216 +$ ./imdea_capture_sync -f <freq> -l <cell_num> -n <subframe_num> -o <output_filename>
  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>
  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
  219 +$ sort -u <cc_out_filename> <cc_fixed_filename> -o <cc_total_filename> (to combine the output)
190 220 ```
191   -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).
192   -12. Have fun!
  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!
193 224  
194 225 Acknowledgements
195 226 ================
196   -If
  227 +
  228 +If you enjoyed using OWL, please acknowledge us in your publication(s) referring to:
  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 +}
... ...