Commit 4e877adc2a5c76bf30d52664897b9d2d909b375b

Authored by Nicola Bui
1 parent 30c90337
Exists in master

changed readme

Showing 1 changed file with 37 additions and 38 deletions   Show diff stats
README.md
... ... @@ -49,21 +49,22 @@ We have tested the following hardware:
49 49 * USRP B210
50 50 * USRP X300
51 51 * bladeRF
  52 + * limeSDR
52 53  
53 54 OWL installation and minimal use guide:
54 55 =======================================
55 56  
56   -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.
  57 +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.
57 58  
58 59 Part 1 - Installation:
59 60 ----------------------
60 61 - Install dependencies:
61 62  
62 63 ```sh
63   -$ sudo apt-get install build-essential git cmake libboost-system-dev libboost-test-dev libboost-thread-dev libqwt-dev libqt4-dev libfftw3-dev
  64 +$ sudo apt-get install build-essential git cmake libboost-system-dev libboost-test-dev libboost-thread-dev libqwt-dev libqt4-dev libfftw3-dev libsctp-dev libconfig-dev libconfig++-dev
64 65 ```
65 66  
66   -- BladeRF installation (skip this if you use USRP)
  67 +- BladeRF installation (optional)
67 68  
68 69 please refer to https://github.com/Nuand/bladeRF/wiki/Getting-Started%3A-Linux for a complete installation guide
69 70 To activate the release PPA, simply:
... ... @@ -73,7 +74,28 @@ $ sudo apt-get update
73 74 $ sudo apt-get install bladerf libbladerf-dev bladerf-firmware-fx3 bladerf-fpga-hostedx40
74 75 ```
75 76  
76   -- Install srsgui
  77 +- USRP installation (optional)
  78 +
  79 +please refer to https://files.ettus.com/manual/page_install.html for a complete installation guide
  80 +To activate the release PPA, simply:
  81 +```sh
  82 +$ sudo add-apt-repository ppa:ettusresearch/uhd
  83 +$ sudo apt-get update
  84 +$ sudo apt-get install libuhd-dev libuhd003 uhd-host
  85 +```
  86 +
  87 +- LimeSDR installation (optional)
  88 +
  89 +please refer to https://wiki.myriadrf.org/Lime_Suite for a complete installation guide
  90 +To activate the release PPA, simply:
  91 +```sh
  92 +sudo add-apt-repository -y ppa:myriadrf/drivers
  93 +sudo apt-get update
  94 +sudo apt-get install limesuite limesuite-udev limesuite-images
  95 +sudo apt-get install soapysdr soapysdr-module-lms7 libsoapysdr-dev
  96 +```
  97 +
  98 +- Install srsgui (optional)
77 99  
78 100 This is not mandatory for OWL to work, but is a nice tool and it helps testing srsLTE and OWL:
79 101 ```sh
... ... @@ -147,13 +169,13 @@ sync loss (bad)
147 169  
148 170 - imdea_cc_decoder
149 171  
150   -This program is the main part of OWL, where the control channel is decoded. It works both online and offline and pre-recorded traces.
  172 +This program is the main part of OWL, where the control channel is decoded. It works both online and offline and pre-recorded traces. The imdea_cc_decoder is automatically set for the graphic output (see the screenshot below). To disable it, just add -d to the command line.
151 173  
152 174 Online usage:
153 175 ```sh
154   -$ ./imdea_cc_decoder -f <freq> -n <subframe_num> 1> <cc_out_filename> 2> /dev/null
  176 +$ ./imdea_cc_decoder -f <freq> -n <subframe_num> 1> <cc_out_filename>
155 177 ```
156   -&lt;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.
  178 +&lt;cc_out_filename> specifies where to save the decoded control channel messages. If omitted, the messages are printed to the stdout. To have OWL output the undecod control messages on stderr you have to enable the LOG_ERRORS symbols in ue_dl.h
157 179 The output of the decoder is a tab separated list where each line represents a decoded message. The columns are as follows:
158 180 1. SFN: internal timing of LTE (1 every frame = 10 ms)
159 181 2. subframe index from 0 to 9 (1 subframe = 1 ms)
... ... @@ -187,31 +209,6 @@ $ ./imdea_cc_decoder -i &lt;input_trace_filename&gt; -l &lt;cell_num&gt; -c &lt;pci&gt; -P &lt;ports&gt;
187 209 4. L
188 210 5. CFI
189 211  
190   -- imdea_fine_tuner
191   -
192   -offline tool to post_process recorded trace to try to decode DCI messages in location that could not be decoded by imdea_cc_decoder.
193   -Usage:
194   -```sh
195   -$ ./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
196   -```
197   -
198   -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)
199   -
200   -- imdea_cc_decoder_graph
201   -
202   -This program is identical to imdea_cc_decoder, but in addition it displays five graphs:
203   -1. a spectrograph of the received power
204   -2. average downlink frame resource usage
205   -3. average downlink frame data rate
206   -4. average uplink frame resource usage
207   -5. average uplink frame data rate
208   -
209   -Online usage:
210   -```sh
211   -$ ./imdea_cc_decoder_graph -f <freq> &> /dev/null
212   -```
213   -Both stderr and stdout are redirected to /dev/null, because they will produce the same output as imdea_cc_decoder does. Below an example of the obtained graphs.
214   -
215 212 ![alt text](capture.png "Graphical Decoder")
216 213  
217 214 Part 3 - OWL setup and first use
... ... @@ -229,19 +226,21 @@ Part 3 - OWL setup and first use
229 226 - Try first the online decoder with the output on screen:
230 227  
231 228 ```sh
232   -$ ./imdea_cc_decoder -f <freq> -n <subframe_num> 2> /dev/null
  229 +$ ./imdea_cc_decoder -f <freq> -n <subframe_num> -d
  230 +```
  231 +
  232 +To have the graphical demo with no texttual output
  233 +```sh
  234 +$ ./imdea_cc_decoder -f <freq> -n <subframe_num> > /dev/null
233 235 ```
234 236  
235   -- Try a capture, with subsequent decoding and fine tuning:
  237 +- Try a capture, with subsequent decoding
236 238  
237 239 ```sh
238 240 $ ./imdea_capture_sync -f <freq> -l <cell_num> -n <subframe_num> -o <output_filename>
239   -$ ./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>
240   -$ ./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
241   -$ sort -u <cc_out_filename> <cc_fixed_filename> -o <cc_total_filename> (to combine the output)
  241 +$ ./imdea_cc_decoder -i <input_trace_filename> -l <cell_num> -c <pci> -P <ports> -p <prb> -z <rnti_out_filename> -Z <rnti_in_filename> -d 1> <cc_out_filename>
242 242 ```
243 243  
244   -- 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).
245 244 - Have fun!
246 245  
247 246 Acknowledgements
... ...