CorteXlab's Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
# GNU Radio benchmark, interactive command execution

If you haven't already, please follow the [[running_your_first_experiment | first tutorial]]

This tutorial builds on the previous one to more interactively control the execution of the commands on the nodes.

## Preliminary steps

We will be using the same experiment code, in a slightly different way.
So first, ensure that you are connected to airlock, as seen before.
And ensure you have booked the platform, with the nodes 14 and 16 as we will be using them.

In the previously made 'Tutorials' folder, let's make a new one to contain this tutorial's files:

<code>
you@srvairlock:~$ cd Tutorials
you@srvairlock:~/Tutorials mkdir Tuto_2
you@srvairlock:~/Tutorials cd Tuto_2
</code>

And let's gather the code to execute.

<code>
you@srvairlock:~/Tutorials/Tuto_2 git clone https://github.com/CorteXlab/examples.git
you@srvairlock:~/Tutorials/Tuto_2 ls examples
my_task  ofdm_benchmark  README.md  test_fft_web
</code>

We could have simply modified the contents of the previous tutorial, but, that way, you can get back to it more easily if you need to.

Again, we will be using the contents of the ofdm_benchmark folder:

<code>
you@srvairlock:~/Tutorials/Tuto_2 cd examples/ofdm_benchmark
you@srvairlock:~/Tutorials/Tuto_2/examples/ofdm_benchmark ls
ofdm_example_loopback.grc  ofdm_example_rx.grc  ofdm_example_tx.grc  ofdm_rx_example_embedded_packet_comp.py  ofdm_rx_example.py  ofdm_tx_example.py  scenario.yaml
</code>

## The scenario

Let's open the existing scenario file using nano (or some installed text editor that you may prefer):

<code>
you@srvairlock:~/Tutorials/Tuto_2/examples/ofdm_benchmark nano scenario.yaml
</code>

And edit the file so it looks like this : 

<code>
# Example scenario description file
#
#   All lines starting with "#" and empty lines are ignored


# Scenario textual description
#   simple string (a one liner)
description: OFDM base scenario for CorteXlab, interactive commands over ssh

# Experiment maximum duration
#   Time after which the experiment is forced to stop
#   integer (seconds)
duration: 600

# Node list
#
#   format:
#
#   nodes:
#     (machine):
#       command: (entry point script relative to the task root)

nodes:
  node14:
    container:
    - image: ghcr.io/cortexlab/cxlb-gnuradio-3.10:1.5
      command: /usr/sbin/sshd -p 2222 -D

  node16:
    container:
    - image: ghcr.io/cortexlab/cxlb-gnuradio-3.10:1.5
      command: /usr/sbin/sshd -p 2222 -D
</code>

Let's go over the changed elements compared to previous tutorial:
 * ''description'': This line just allows us to name or describe our task file
 * ''duration: 600'': We specify that the task will run for 10mn (600s). That will give us time to access the nodes, and interact with it comfortably.
 * ''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.

Once this is done, you can save the file to disk by pressing Ctrl+X to exit, followed by Y to save the current state.

## Creating and submitting the task file
As before, we can prepare the task file:

<code>
you@srvairlock:~/Tutorials/Tuto_2/examples/ofdm_benchmark cd ..
you@srvairlock:~/Tutorials/Tuto_2/examples minus task create ofdm_benchmark
</code>

And submit it for execution:

<code>
you@srvairlock:~/Tutorials/Tuto_2/examples minus task submit ofdm_benchmark.task
2541
</code>


## Run the experiment

Now the nodes we want to use are up and running. We can access them with ssh to run our experiment. To do so, open two new terminals (one per node), access Airlock and run the following command, here for node 14 : 

<code>
you@srvairlock:~$ ssh -p 2222 root@mnode14
</code>

You are now connected to the node. You can then run the command for each node to start the experiment : 

<code>
# From node 14
root@mnode14:~/ /cortexlab/homes/[username]/Tutorials/Tuto_2/examples/ofdm_benchmark/ofdm_tx_example.py -g 15 -b 4 -r 1000000 -f 1250000000
	
# From node 16
root@mnode16:~/ /cortexlab/homes/[username]/Tutorials/Tuto_2/examples/ofdm_benchmark/ofdm_rx_example.py -g 15 -b 4 -r 1000000 -f 1250000000
</code>

## Collecting and analyzing the output

Generally the OFDM example experiment will take a few minutes to run. On the terminal accessing the node 14 (receiver) with ssh, you will see the following :

<code>
[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

...
</code>

Here, we can directly see the standard output that was logged in the ''results/task\_XXXX/node\_16/task_XXXX_container_0.log.stdout'' file.
And we can stop the execution with ''Ctrl+C'' and restart it as we wish, and change the arguments like frequency or gain.
On the other hand, this output will not be recorded in the 'results' folder since we are getting it directly.

## Conclusion

You have now seen how to setup a task to allow you to run commands directly and manually on the nodes.
This operation mode is mostly useful for final tests and tweaks to an experiment, with a quicker feedback loop.

For "production" experiments, and especially ones with many participating nodes, it is better to specify the commands in the scenario file as seen in previous tutorial, as the platform handles the simultaneous start of every node.