Differences

This shows you the differences between two versions of the page.

--- gnu_radio_docker_benchmark_example [2022/12/13 11:48] – [Submitting the task] lcardoso
+++ gnu_radio_docker_benchmark_example [2024/03/08 15:59] (current) – cmorin
@@ Line 8: / Line 8: @@
 ## Create your docker image
-Using docker, we will enable on your laptop an environment suitable for CorteXlab with gnuradio and needed software. Your goal is to develop this image (with new software and files) so you can run your experiment. It will only modify the environment of the image and not your laptop. Then you will be able to save and deploy the new image on cortexlab, without having to re-install everything and dealing with software compatibility and versioning.
+Using docker, we will enable on your laptop an environment suitable for CorteXlab with gnuradio and needed software. Your goal is to develop this image (with new software and files) so you can run your experiment. It will only modify the environment of the image and not your laptop. Then you will be able to save and deploy the new image on CorteXlab, without having to re-install everything and dealing with software compatibility and versioning.
 Therefore, you can retrieve and run the following image.
 <code>
-you@yourpc:~$ docker pull m1mbert/cxlb-gnuradio-3.7:1.0
+you@yourpc:~$ docker pull ghcr.io/cortexlab/cxlb-gnuradio-3.10:1.3
-you@yourpc:~$ docker run -dti --net=host --expose 2222 --privileged m1mbert/cxlb-gnuradio-3.7:1.0
+you@yourpc:~$ docker run -dti --net=host --expose 2222 --privileged ghcr.io/cortexlab/cxlb-gnuradio-3.10:1.3
 </code>
@@ Line 34: / Line 34: @@
 <code>
 root@yourpcwdocker:~$ git clone https://github.com/CorteXlab/examples.git
-root@yourpcwdocker:~$ ./examples/my_task/benchmark_rx.py --antenna="TX/RX" --rx-gain=25 -v -W 2M -f 2.49G
+root@yourpcwdocker:~$ ./examples/ofdm_benchmark/ofdm_rx_example.py -g 10 -b 4
 </code>
-Let's go over each one of the files in this example:
+Let's go over each one of the files in this `ofdm_benchmark` folder:
-  * ''benchmark\_tx.py'': the GNU Radio python script for the OFDM transmitter
+  * ''ofdm\_tx\_example.py'': the GNU Radio python script for the OFDM transmitter
-  * ''benchmark\_rx.py'': the GNU Radio python script for the OFDM receiver
+  * ''ofdm\_rx\_example.py'': the GNU Radio python script for the OFDM receiver
-  * ''transmit\_path.py'', ''receive\_path.py'' and ''uhd\_interface.py'': are helper codes for both benchmark python scripts
+  * ''ofdm\_rx\_example\_embedded\_packet\_comp.py'': Helper code for the receiver (code for the block computing BER)
-  * ''scenario.yaml'': a out-dated scenario description file (in yaml format) that we will not use here
+  * ''scenario.yaml'': a potential scenario description file (in yaml format) that we will not use here
 Here, this is all the modifications we need to do in order to prepare our experiment. When it is working properly, you can exit the container with Ctrl + d. Now, let's save our updated container as a new docker image. We can then push it on dockerhub (dockerhub is a repository of docker images, you need to create an account on it).
@@ Line 102: / Line 102: @@
   * ''image:'': This indicates which image to download from dockerhub and run on the node
   * ''command: /usr/sbin/sshd -p 2222 -D'': opens the container to a ssh connection. During the task, you will access the node through its container with ssh and launch the experiment yourself. This way you can view log in real time and relaunch the experiment with different parameters without having to create a new task
+The same reasoning applies for node 16.
+This is the scenario at hand:
-We will use the ssh method for this example, but know that you can also use the ''command'' option in a different way, by directly giving the parameters of you experience and not going through ssh. The idea is that when you're developing an experiment, you will go through trials and errors, parameter tweakings, and working interactively through ssh is the best option, When the experiment is running well and you want to reproduce it several times, on the other hand, it's best to automatize everything, so that you don't need to ssh to each node and run commands manually. It's also possible, for example, that you adjust interactively a receiver first, and when it's done, you run it automatically, and you keep the interactive sessions only for adjusting and tuning the emitter node(s).
+  * **Node14** will behave as the **OFDM receiver**
+  * **Node16** will behave as the **OFDM transmitter**
+For more info on where these nodes are located inside the platform, please check the node position map at the home of this wiki.
+Assuming your account has been correctly created, you can now copy the folder with the scenario file into the Airlock SSH front-end:
+<code>
+you@yourpc:~$ scp -v [-i path/to/your/key] [-r] path/to/local/file/my_task username@gw.cortexlab.fr:/cortexlab/homes/[YOUR CORTEXLAB USERNAME]/workspace/
+</code>
+### Non interactive scenario (No SSH)
+The example of this tutorial demonstrates an ssh connection to the nodes. But know that you can also use the ''command'' option in a different way, by directly giving the parameters of your experience and not going through ssh. When developing an experiment (trials and errors, parameter tweaking, ...), working interactively through ssh is more practical. But when the experiment is running well and you want to reproduce it several times, it is best to automatize, so that you don't need to ssh to each node and run commands manually. It's also possible, for example, that you adjust interactively a receiver first, and when it's done, you run it automatically, and you keep the interactive sessions only for adjusting and tuning the emitter node(s).
+In this situation, you might want to directly call the program to run on the nodes via the ''command'' option, with a scenario file looking like the following.
 <code>
@@ Line 111: / Line 128: @@
     container:
     - image: [DOCKER USERNAME]/[NEW IMAGE NAME]:latest
-      command: ./benchmark_rx.py --antenna="TX/RX" --rx-gain=25 -v -W 2M -f 2.49G
+      command: bash -lc "[PATH/TO]/ofdm_rx_example.py -g 10 -b 4 -r 2000000 -f 1234000000"
-      passive: true
+    passive: true
   node16:
     container:
     - image: [DOCKER USERNAME]/[NEW IMAGE NAME]:latest
-      command: ./benchmark_tx.py --antenna="TX/RX" --tx-amplitude=0.2 -v -W 2M -f 2.49G
+      command: bash -lc "[PATH/TO]/ofdm_tx_example.py -g 10 -b 4 -r 2000000 -f 1234000000"
 </code>
- * ''command: ./benchmark\_rx.py --antenna="TX/RX" --rx-gain=25 -v -W 2M -f 2.49G'': states the command to run on node14. Details of the parameters are:
+ * ``command: bash -lc "[PATH/TO]/ofdm\_rx\_example.py -g 10 -b 4 -r 2000000 -f 1234000000"``: states the command to run on node14. Details of the parameters are:
-    * ''--antenna="TX/RX"'': this indicates which antenna connector to use on the USRP radio platform connected to the node
+    * ''-g 10'': This sets the receive gain of the USRP radio platform
-    * ''--rx-gain=25'': this sets the receive gain of the USRP radio platform
+    * ''-b 4'': This sets the transmission to use 16QAM modulation (4 bits per symbol)
-    * ''-v'': this puts the script in verbose mode, printing debug information
+    * ''-r 2000000'': this sets the bandwidth of the signal to 2 MHz
-    * ''-W 2M'': this sets the bandwidth of the signal to 2 MHz
+    * ''-f 1234000000'': this sets the carrier frequency of the signal to 1.234 GHz
-    * ''-f 2.49G'': this sets the carrier frequency of the signal to 2.49 GHz
   * ''passive: true'': the node 4 will be passive, meaning it will stop when all active nodes are finished
-Same reasoning follows for the section on node6. So this is the scenario at hand:
-  * **Node14** behaves as the **OFDM receiver**
+Note that, **the rest of this tutorial uses the ssh method**, not the one mentioned in the current section.
-  * **Node16** behaves as the **OFDM transmitter**
+Also note that the command must point to the file to be executed, either with a relative path, from the ''WORKDIR'' defined in your docker image (here it is ''/root''), or with an absolute path.
-For more info on where these nodes are located inside the platform, please check the node position map at the home of this wiki.
-Assuming your account has been correctly created, you can now copy the folder with the scenario file into the Airlock SSH front-end:
-<code>
-you@yourpc:~$ scp -P 2269 -v [-i path/to/your/key] [-r] path/to/local/file/my_task username@gw.cortexlab.fr:/cortexlab/homes/[YOUR CORTEXLAB USERNAME]/workspace/
-</code>
 ## Access Airlock
-You can now access the Airlock SSh server that will allow you to manage your task.
+You can now access the Airlock SSH server that will allow you to manage your task.
 <code>
@@ Line 183: / Line 190: @@
 I a new browser window open the [CorteXlab web app](http://xp.cortexlab.fr/app). It will open in your current reservation list if you have any.
-{{ ::screenshot_2022-12-13_at_11.46.27.png?nolink&600 |}}
+{{ ::screenshot_2022-12-13_at_11.46.27.png?nolink&700 |}}
-<code>
+Use the "Book the testbed" button in the lower left corner.
-you@srvairlock:~/workspace$ oarsub -l nodes=BEST,walltime=0:30:00 -I
-</code>
-(If you're running your reservation in a container reservation):
+You'll get to a screen that looks like this:
-<code>
-you@srvairlock:~/workspace$ oarsub -t inner=<id of container> -l {"network_address in ('mnode4.cortexlab.fr', 'mnode6.cortexlab.fr')"}/nodes=2,walltime=0:30:00 -I
+{{ ::screenshot_2022-12-13_at_11.50.28.png?nolink&700 |}}
-</code>
+Now let's create the reservation!
+Under "Book the testbed" select the date of your reservation:
+{{ ::screenshot_2022-12-13_at_11.52.34.png?nolink&700 |}}
+And using the clock icon select the start time of your reservation by dragging the clock pointers:
+{{ ::screenshot_2022-12-13_at_11.53.07.png?nolink&100 |}} and {{ ::screenshot_2022-12-13_at_11.53.18.png?nolink&100 |}}
+Now, in the duration, select the end of your reservation the same way as above.
+Finally select the nodes in the map of CorteXlab by clicking on the ones required for your experiment such that their color changes to orange. Since we're using 14 and 16, those are the ones to be selected:
+{{ ::screenshot_2022-12-13_at_12.39.54.png?nolink&700 |}}
+Finally click on the "Book the testbed" button. If your reservation works (no conflicting options were chosen), you should be brought back to the reservations page, and a new line highlighted in yellow will appear with the number of your reservation.
-(Be sure that no one else is using the same node as you)
-This will run a 30 minute job and open a sub-shell in which you can run minus tasks. This sub-shell will be killed after 30 minutes, and if you leave the shell earlier, it will terminate the corresponding oar job. More documentation on oar can be found [[reserve|here]]. You can also monitor the current jobs in the [gantt web interface](http://xp.cortexlab.fr/drawgantt/).
-We then submit the minus task:
+Back to the airlock terminal screen, we now can submit the minus task:
 <code>
 you@srvairlock:~/workspace$ minus task submit my_task.task
-Task with id 15 enqueued user <login>.
 </code>
@@ Line 241: / Line 261: @@
 <code>
 # From node 14
-root@mnode14:~/ ./examples/my_task/benchmark_rx.py --antenna="TX/RX" --rx-gain=25 -v -W 2M -f 2.49G
+root@mnode14:~/ ./examples/ofdm_benchmark/ofdm_rx_example.py -g 10 -b 4 -r 2000000 -f 1234000000
 # From node 16
-root@mnode16:~/ ./examples/my_task/benchmark_tx.py --antenna="TX/RX" --tx-amplitude=0.2 -v -W 2M -f 2.49G
+root@mnode16:~/ ./examples/ofdm_benchmark/ofdm_tx_example.py -g 10 -b 4 -r 2000000 -f 1234000000
 </code>
@@ Line 252: / Line 272: @@
 <code>
-linux; GNU C++ version 4.7.2; Boost_104900; UHD_003.007.001-84-gd99ce4ef
+[INFO] [UHD] linux; GNU C++ version 12.2.0; Boost_107400; UHD_4.6.0.0-3-g080b1baa
+[INFO] [USRP2] Opening a USRP2/N-Series device...
+[INFO] [USRP2] Current recv frame size: 1472 bytes
+[INFO] [USRP2] Current send frame size: 1472 bytes
+[WARNING] [UDP] The send buffer could not be resized sufficiently.
+Target sock buff size: 2500000 bytes.
+Actual sock buff size: 1048576 bytes.
+See the transport application notes on buffer resizing.
+Please run: sudo sysctl -w net.core.wmem_max=2500000
+[WARNING] [UDP] The send buffer could not be resized sufficiently.
+Target sock buff size: 2500000 bytes.
+Actual sock buff size: 1048576 bytes.
+See the transport application notes on buffer resizing.
+Please run: sudo sysctl -w net.core.wmem_max=2500000
+[WARNING] [UDP] The send buffer could not be resized sufficiently.
+Target sock buff size: 2500000 bytes.
+Actual sock buff size: 1048576 bytes.
+See the transport application notes on buffer resizing.
+Please run: sudo sysctl -w net.core.wmem_max=2500000
+[INFO] [MULTI_USRP]     1) catch time transition at pps edge
+[INFO] [MULTI_USRP]     2) set times next pps (synchronously)
+Packet Comparator0 :info: Received packet num 1 with a BER of 0.0445
+Packet Comparator0 :info: Received packet num 2 with a BER of 0.0388
+Packet Comparator0 :info: Received packet num 3 with a BER of 0.0357
+Packet Comparator0 :info: Received packet num 4 with a BER of 0.0367
+Packet Comparator0 :info: Received packet num 5 with a BER of 0.0409
+Packet Comparator0 :info: Received packet num 6 with a BER of 0.0656
+Packet Comparator0 :info: Received packet num 7 with a BER of 0.0596
+Packet Comparator0 :info: Received packet num 8 with a BER of 0.0419
+Packet Comparator0 :info: Received packet num 9 with a BER of 0.0435
+Packet Comparator0 :info: Received packet num 10 with a BER of 0.0667
+Packet Comparator0 :info: Received packet num 11 with a BER of 0.0375
+Packet Comparator0 :info: Received packet num 12 with a BER of 0.0378
--- Opening a USRP2/N-Series device...
--- Current recv frame size: 1472 bytes
--- Current send frame size: 1472 bytes
--- Detecting internal GPSDO.... Found an internal GPSDO
--- found
--- Setting references to the internal GPSDO
--- Initializing time to the internal GPSDO
-UHD Receiver:
-UHD Args:
-Freq:         2.49GHz
-LO Offset:    0Hz
-Gain:         25.000000 dB
-Sample Rate:  2Msps
-Antenna:      TX/RX
-Subdev Sec:   None
-Clock Source: None
-Using Volk machine: avx_64_mmx_orc
-OFDM Demodulator:
-Modulation Type: bpsk
-FFT length:      512
-Occupied Tones:  200
-CP length:       128
-Warning: failed to enable realtime scheduling
-ok: False 	 pktno: 169 	 n_rcvd: 1 	 n_right: 0
-ok: False 	 pktno: 170 	 n_rcvd: 2 	 n_right: 0
-ok: False 	 pktno: 171 	 n_rcvd: 3 	 n_right: 0
-ok: False 	 pktno: 173 	 n_rcvd: 4 	 n_right: 0
-ok: False 	 pktno: 174 	 n_rcvd: 5 	 n_right: 0
-ok: False 	 pktno: 175 	 n_rcvd: 6 	 n_right: 0
-ok: False 	 pktno: 176 	 n_rcvd: 7 	 n_right: 0
-ok: False 	 pktno: 177 	 n_rcvd: 8 	 n_right: 0
-ok: False 	 pktno: 178 	 n_rcvd: 9 	 n_right: 0
-ok: False 	 pktno: 179 	 n_rcvd: 10 	 n_right: 0
-ok: False 	 pktno: 180 	 n_rcvd: 11 	 n_right: 0
-ok: False 	 pktno: 181 	 n_rcvd: 12 	 n_right: 0
-ok: False 	 pktno: 182 	 n_rcvd: 13 	 n_right: 0
-ok: False 	 pktno: 185 	 n_rcvd: 14 	 n_right: 0
-ok: False 	 pktno: 186 	 n_rcvd: 15 	 n_right: 0
-ok: False 	 pktno: 191 	 n_rcvd: 16 	 n_right: 0
-ok: False 	 pktno: 192 	 n_rcvd: 17 	 n_right: 0
-ok: False 	 pktno: 197 	 n_rcvd: 18 	 n_right: 0
-ok: False 	 pktno: 203 	 n_rcvd: 19 	 n_right: 0
 ...
 </code>
 Let's try to understand it:
-  * The first 9 lines correspond to the UHD messages
+  * The first 21 lines correspond to the UHD messages
-  * The next 16 lines correspond to the GNU Radio messages and radio configuration parameters
+  * The lines starting with ''Packet Comparator0 :info: Recieved packet'' indicate reception of a properly formatted packet. It provides two additionnal bits of information:
-  * There might be a warning message about realtime scheduling that can be safely ignored
+    * Packet number. This should increase regularly. Missing elements in the sequence indicate packet loss
-  * The lines starting with ''ok: False        pktno: 169      n\_rcvd: 1       n\_right: 0'' are from the receiver trying to decode the OFDM packets. Let's further inspect these lines:
+    * Bit Error Rate. Computed only on the current packet
-    * ''ok: False'': means the packet was incorrectly decoded, i.e., it failed to pass the checksum
-    * ''pktno: 169'': is the sequence number seen at the receiver
-    * ''n\_rcvd: 1'': is the number of received packets
-    * ''n\_right: 0'': is the number of correctly received packets
-As can be seen, there's a local oscillator (LO) mismatch between both nodes that complicates the decoding process.
 If you decide to directly run your experiment in the ''scenario.yaml'', as explained before, Minus will take care of copying the results and output messages back to your home folder in airlock, so that you can analyze it.
@@ Line 323: / Line 325: @@
 you@srvairlock:~/results$ cd task_XXXX
 you@srvairlock:~/results/task_XXXX $ ls
-node14.tgz  node16.tgz
+node14  node16
 </code>
-So we see that we have a folder for each task and inside each folder one compressed file per participant node. Let's extract one of those files and see what's inside:
+So we see that we have a folder for each task and inside each folder one folder per participant node.
 <code>
-you@srvairlock:~/results/task_XXXX$ tar -zxf node14.tgz
-you@srvairlock:~/results/task_XXXX$ ls
-node14  node14.tgz  node16.tgz
 you@srvairlock:~/results/task_XXXX$ cd node14
 you@srvairlock:~/results/task_XXXX/node14$ ls
-benchmark_rx.py  receive_path.pyc  stdout.txt        uhd_interface.pyc
+task_XXXX_container_0               task_XXXX_container_0.create.stdout task_XXXX_container_0.kill.stdout
-benchmark_tx.py  scenario.yaml     transmit_path.py
+task_XXXX_container_0.log.stdout    task_XXXX_container_0.start.stdout  task_XXXX_container_0.wait.stdout
-receive_path.py  stderr.txt        uhd_interface.py
+task_XXXX_container_0.create.stderr task_XXXX_container_0.kill.stderr   task_XXXX_container_0.log.stderr
+task_XXXX_container_0.start.stderr  task_XXXX_container_0.wait.stderr
 </code>
-We see that all of the files we used to create the task are inside, but we have some new files. The *.pyc files are the python compiled files and we can safely ignore them. The other two are:
+We see a series of .stdout and .stderr files. These are log files corresponding to all the steps in the life of a task:
+  * create: Downloading of image file
+  * start: Start of container
+  * log: Execution of specified command inside of the container
+  * wait: Waiting period before closure
+  * kill: Task cleanup
+Create, start, wait, and Kill should not have anything in their .stderr logs.
+The most interesting files for a user are the .log file, since they capture the execution of the user specified command, and are very useful to debug your code.
+The `task_XXXX_container_0` folder contains all the files that have changed during the execution of the container.
+Here, it only contains internal cache and log files that are not useful to us, but if your task records data in a file, it will show up here.
-  * ''stdout.txt'': all output messages from your GNU Radio python script are written here. These include GNU Radio messages as well as all "print"s you include in your code. Seeing the contents of this file is useful to assert its correct operation.
-  * ''stderr.txt'': all error messages are printed here. If you see strange things on the ''stdout.txt'' or nothing at all, it might be interesting to take a look at the ''stderr.txt'' to debug your code.
 ## What next?