Commit bd7d514d01105de0279b13cbe95aa7488568d4eb

Authored by Nicola Bui
1 parent cba74f65
Exists in master

alpha release commit

Showing 1 changed file with 44 additions and 127 deletions   Show diff stats
README.md
... ... @@ -59,7 +59,6 @@ sudo apt-get install build-essential git cmake libboost-system-dev libboost-test
59 59  
60 60 2. BladeRF installation (skip this if you use USRP )
61 61 https://github.com/Nuand/bladeRF/wiki/Getting-Started%3A-Linux
62   -
63 62 To activate the release PPA, simply:
64 63 ```
65 64 sudo add-apt-repository ppa:bladerf/bladerf
... ... @@ -69,7 +68,6 @@ sudo apt-get install bladerf libbladerf-dev bladerf-firmware-fx3 bladerf-fpga-ho
69 68  
70 69 3. Install srsgui
71 70 This is not mandatory for OWL to work, but is a nice tool and it helps testing srsLTE and OWL:
72   -
73 71 ```
74 72 git clone https://github.com/suttonpd/srsgui.git
75 73 cd srsgui
... ... @@ -94,20 +92,17 @@ cd build
94 92 cmake ../
95 93 make
96 94 ```
97   -
98 95 If everything succeeded you will find OWL's executables together with srsLTE's examples in the srsLTE/build/srslte/examples folder.
99 96  
100 97 Part 2 - Executable description:
101 98 --------------------------------
102 99 1. Inherited from srsLTE
103   -
104   -- cell_search
  100 + - cell_search
105 101 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
106 102 http://www.spectrummonitoring.com/frequencies
107 103 cell_search requires the band number and can also use the EARFCN numbers to narrow the search, please refer to this website for details:
108 104 http://niviuk.free.fr/lte_band.php
109   -
110   -- pdsch_ue
  105 + - pdsch_ue
111 106 emulate a UE trying to connecting to a given frequency, first looking for synchronization and, then, decoding control messages related to broadcast transmissions.
112 107 In addition, this program provide some useful statistics about synchronization and decoding success rate.
113 108 TIP: once you have the frequency of a base station you can run
... ... @@ -115,9 +110,8 @@ TIP: once you have the frequency of a base station you can run
115 110 ./pdsch_ue -f <freq>
116 111 ```
117 112 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.
118   -
119 113 2. OWL files
120   -- imdea_capture_sync
  114 + - imdea_capture_sync
121 115 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
122 116 Usage:
123 117 ```
... ... @@ -131,8 +125,7 @@ TIP: putting -o /dev/null creates no output, but allows to test the signal synch
131 125 Decoded MIB ... (good)
132 126 MIB not decoded ... (noise on the channel)
133 127 sync loss (bad)
134   -
135   -- imdea_cc_decoder
  128 + - imdea_cc_decoder
136 129 This program is the main part of OWL, where the control channel is decoded. It works both online and offline and pre-recorded traces.
137 130 Online usage:
138 131 ```
... ... @@ -140,44 +133,46 @@ Online usage:
140 133 ```
141 134 <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.
142 135 The output of the decoder is a tab separated list where each line represents a decoded message. The columns are as follows:
143   - 1. SFN: internal timing of LTE (1 every frame = 10 ms)
144   - 2. subframe index from 0 to 9 (1 subframe = 1 ms)
145   - 3. RNTI in decimal
146   - 4. Direction: 1 = downlink; 0 = uplink
147   - 5. MCS in 0 - 31
148   - 6. number of allocated resource blocks in 0 - 110
149   - 7. transport block size in bits
150   - 8. transport block size in bits (code word 0), -1 if n/a
151   - 9. transport block size in bits (code word 1), -1 if n/a
152   - 10. DCI message type. This version only scans for 0 (format 0), 2 (format 1a), 6 (format 2a)
153   - 11. new data indicator toggle for codeword 0
154   - 12. new data indicator toggle for codeword 1
155   - 13. HARQ process id
156   - 14. ncce location of the DCI message
157   - 15. aggregation level of the DCI message
158   - 16. CFI
159   - 17. DCI correctness check
160   -
  136 + 1. SFN: internal timing of LTE (1 every frame = 10 ms)
  137 + 2. subframe index from 0 to 9 (1 subframe = 1 ms)
  138 + 3. RNTI in decimal
  139 + 4. Direction: 1 = downlink; 0 = uplink
  140 + 5. MCS in 0 - 31
  141 + 6. number of allocated resource blocks in 0 - 110
  142 + 7. transport block size in bits
  143 + 8. transport block size in bits (code word 0), -1 if n/a
  144 + 9. transport block size in bits (code word 1), -1 if n/a
  145 + 10. DCI message type. This version only scans for 0 (format 0), 2 (format 1a), 6 (format 2a)
  146 + 11. new data indicator toggle for codeword 0
  147 + 12. new data indicator toggle for codeword 1
  148 + 13. HARQ process id
  149 + 14. ncce location of the DCI message
  150 + 15. aggregation level of the DCI message
  151 + 16. CFI
  152 + 17. DCI correctness check
161 153 Offline usage:
162   -$ ./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>
  154 +```
  155 +./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>
  156 +```
163 157 <input_trace_filename> a trace that you saved with imdea_capture_sync
164 158 <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
165 159 <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).
166 160 <cc_fix_filename> output file for the fine_tuner program. It specify one location to be checked per line. The columns are as follows:
167   -1. SFN
168   -2. subframe
169   -3. ncce
170   -4. L
171   -5. CFI
172   -
173   -- imdea_fine_tuner
  161 + 1. SFN
  162 + 2. subframe
  163 + 3. ncce
  164 + 4. L
  165 + 5. CFI
  166 + - imdea_fine_tuner
174 167 offline tool to post_process recorded trace to try to decode DCI messages in location that could not be decoded by imdea_cc_decoder.
175 168 Usage:
176   -$ ./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
  169 +```
  170 +./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
  171 +```
177 172 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)
178 173  
179 174 Part 3 - OWL setup and first use
180   -
  175 +--------------------------------
181 176 0. Install everything correctly!
182 177 1. Use a software defined radio capable of sampling at a LTE compliant sampling rate (30.72, 23.04, 15.36, 11.52).
183 178 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)
... ... @@ -188,98 +183,20 @@ Part 3 - OWL setup and first use
188 183 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.
189 184 8. At this point you should have <freq> <cell_num> <pci> <ports> <prb>
190 185 9. Try first the online decoder with the output on screen:
191   -$ ./imdea_cc_decoder -f <freq> -n <subframe_num> 2> /dev/null
192   -10. Try a capture, with subsequent decoding and fine tuning:
193   -$ ./imdea_capture_sync -f <freq> -l <cell_num> -n <subframe_num> -o <output_filename>
194   -$ ./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>
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   -$ sort -u <cc_out_filename> <cc_fixed_filename> -o <cc_total_filename> (to combine the output)
197   -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).
198   -12. Have fun!
199   -
200   -
201   -
202   -
203   -Download & Install Instructions
204   -=================================
205   -
206   -* Mandatory dependencies:
207   - * libfftw
208   -* Optional requirements:
209   - * srsgui: for real-time plotting. Download it here: https://github.com/srslte/srsgui
210   - * VOLK: if the VOLK library and headers are detected, they will be used for accelerating some signal processing functions.
211   - * Matlab/Octave: if found by CMake, MEX files will also be generated and installed. If you find any compilation issue with MEX and you don't need them, pass -DDisableMEX=ON to cmake to disable them.
212   -
213   -Download and build srsLTE:
214   -```
215   -git clone https://github.com/srsLTE/srsLTE.git
216   -cd srsLTE
217   -mkdir build
218   -cd build
219   -cmake ../
220   -make
221   -```
222   -
223   -The library can also be installed using the command ```sudo make install```.
224   -
225   -Running srsLTE Examples
226   -========================
227   -
228   -* SIB1 reception and UE measurement from commercial LTE networks:
229   -```
230   -lte/examples/pdsch_ue -f [frequency_in_Hz]
231   -```
232   -Where -f is the LTE channel frequency.
233   -
234   -* eNodeB to UE Downlink PHY test
235   -
236   -You will need two computers, each equipped with a USRP. At the transmitter side, run:
237   -
238   -```
239   -lte/examples/pdsch_enodeb -f [frequency_in_Hz] [-h for more commands]
240   -```
241   -
242   -At the receiver run:
243 186 ```
244   -lte/examples/pdsch_ue -r 1234 -f [frequency_in_Hz]
  187 +./imdea_cc_decoder -f <freq> -n <subframe_num> 2> /dev/null
245 188 ```
246   -
247   -At the transmitter console, it is possible to change the Modulation and Coding Scheme (MCS) by typing a new number (between 0 and 28) and pressing Enter.
248   -
249   -
250   -The output at the receiver should look something similar to the following video. In this example, we removed the transmitter and receiver antennas in the middle of the demonstration, showing how reception is still possible (despite with some erros).
251   -
252   -https://www.dropbox.com/s/txh1nuzdb0igq5n/demo_pbch.ogv
253   -
254   -![Screenshopt of the PBCH example output](pbch_capture.png "Screenshopt of the PBCH example output")
255   -
256   -* Video over Downlink PHY (eNodeB to UE)
257   -
258   -The previous example sends random bits to the UE. It is possible to open a TCP socket and stream video over the LTE PHY DL wireless connection. At the transmitter side, run the following command:
259   -
260   -```
261   -lte/examples/pdsch_enodeb -f [frequency_in_Hz] -u 2000 [-h for more commands]
262   -```
263   -
264   -The argument -u 2000 will open port 2000 for listening for TCP connections. Set a high-order MCS, like 16 by typing 16 in the eNodeB console and pressing Enter.
265   -
266   -```
267   -lte/examples/pdsch_ue -r 1234 -u 2001 -U 127.0.0.1 -f [frequency_in_Hz]
268   -```
269   -
270   -The arguments -u 2001 -U 127.0.0.1 will forward the data that was injected at the eNodeB to address:port indicated by the argument. Once you have the system running, you can transmit some useful data, like a video stream. At the transmitter side, run:
271   -
  189 +10. Try a capture, with subsequent decoding and fine tuning:
272 190 ```
273   -avconv -f video4linux2 -i /dev/video0 -c:v mp4 -f mpegts tcp://127.0.0.1:2000
  191 +./imdea_capture_sync -f <freq> -l <cell_num> -n <subframe_num> -o <output_filename>
  192 +./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>
  193 +./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
  194 +sort -u <cc_out_filename> <cc_fixed_filename> -o <cc_total_filename> (to combine the output)
274 195 ```
275   -to stream the video captured from the webcam throught the local host port 2000. At the receiver, run:
  196 +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).
  197 +12. Have fun!
276 198  
277   -```
278   -avplay tcp://127.0.0.1:2001?listen -analyzeduration 100 -loglevel verbose
279   -```
280   -to watch the video.
  199 +Acknowledgements
  200 +================
281 201  
282   -Support
283   -========
284 202  
285   -Mailing list: http://www.softwareradiosystems.com/mailman/listinfo/srslte-users
... ...