This tutorial executes an OFDM transmission between two nodes using docker in CorteXlab, transmitting dummy packets between them.

We base this tutorial on the example digital OFDM benchmark transmitter and receiver code present in GNU Radio. For more info on the OFDM benchmark, please refer to the GNU Radio documentation.

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.

you@yourpc:~$ docker pull ghcr.io/cortexlab/cxlb-gnuradio-3.10:1.3
you@yourpc:~$ docker run -dti --net=host --expose 2222 --privileged ghcr.io/cortexlab/cxlb-gnuradio-3.10:1.3

Access the docker container using ssh :

you@yourpc:~$ ssh -Xp 2222 root@localhost

Add this option to the run command if you want to use a USRP plugged in with a USB port on you local machine : -v /dev/bus/usb:/dev/bus/usb . Also, a new host key is created when running the container. The following command could be necessary to add the new key to the known hosts list before using ssh.

you@yourpc:~$ ssh-keygen -f "/home/[YOUR NAME]/.ssh/known_hosts" -R "[localhost]:2222"

When in the container, you need to set it up for your experiment, here a simple OFDM transmission that we can get from github. We can test it on our local machine before sending it to cortexlab (it won't work if you don't have an USRP available).

root@yourpcwdocker:~$ git clone https://github.com/CorteXlab/examples.git
root@yourpcwdocker:~$ ./examples/ofdm_benchmark/ofdm_rx_example.py -g 10 -b 4

Let's go over each one of the files in this ofdm_benchmark folder:

• ofdm_tx_example.py: the GNU Radio python script for the OFDM transmitter
• ofdm_rx_example.py: the GNU Radio python script for the OFDM receiver
• ofdm_rx_example_embedded_packet_comp.py: Helper code for the receiver (code for the block computing BER)
• 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).

you@yourpc:~$ docker ps -a 
you@yourpc:~$ docker commit [CONTAINER ID] [NEW IMAGE NAME] 
you@yourpc:~$ docker tag [NEW IMAGE NAME] [DOCKER USERNAME]/[NEW IMAGE NAME] 
you@yourpc:~$ docker login 
you@yourpc:~$ docker push [DOCKER USERNAME]/[NEW IMAGE NAME] 

For the following, the task will refer to the instructions given by Airlock, the scenario file and minus. The experiment will refer to the OFDM transmission.

Create on your machine a folder my_task and in it a file scenario.yaml which will indicate the nodes to use and how to use them. It should look like this :

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


# Scenario textual description
#   simple string (a one liner)
description: OFDM - Docker and Cortexlab

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

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

nodes:
  node14:
    container:
    - image: [DOCKER USERNAME]/[NEW IMAGE NAME]:latest
      command: /usr/sbin/sshd -p 2222 -D

  node16:
    container:
    - image: [DOCKER USERNAME]/[NEW IMAGE NAME]:latest 
      command: /usr/sbin/sshd -p 2222 -D

The file is self-explanatory, but for now let's ignore all but the indented lines following node14: and node16:. You'll have the opportunity to understand the rest better later on.

Let's go over each said line now:

• node14:: This opens the node14 declaration of options
• 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:

• 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:

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/

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.

nodes:
  node14:
    container:
    - image: [DOCKER USERNAME]/[NEW IMAGE NAME]:latest
      command: bash -lc "[PATH/TO]/ofdm_rx_example.py -g 10 -b 4 -r 2000000 -f 1234000000"
    passive: true

  node16:
    container:
    - image: [DOCKER USERNAME]/[NEW IMAGE NAME]:latest 
      command: bash -lc "[PATH/TO]/ofdm_tx_example.py -g 10 -b 4 -r 2000000 -f 1234000000"

• 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:
  • -g 10: This sets the receive gain of the USRP radio platform
  • -b 4: This sets the transmission to use 16QAM modulation (4 bits per symbol)
  • -r 2000000: this sets the bandwidth of the signal to 2 MHz
  • -f 1234000000: this sets the carrier frequency of the signal to 1.234 GHz
  • passive: true: the node 4 will be passive, meaning it will stop when all active nodes are finished

Note that, the rest of this tutorial uses the ssh method, not the one mentioned in the current section. 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.

You can now access the Airlock SSH server that will allow you to manage your task.

you@yourpc:~$ ssh -X -v [-i path/to/the/key] username@gw.cortexlab.fr

On airlock, before submitting the task to the nodes, we need first to put the task into a format that can be readily understood by Minus. Minus is the experiment controller code, responsible for doing the dirty stuff for you:

• Firing up the right nodes to be used
• Copying the code onto the nodes
• Starting everything at the same instant
• Waiting until everything finishes, and stop stubborn code from running forever
• Copying results, error and output messages to airlock, so that you can access it
• Turning off everything and cleaning up

Let's prepare the task, but first we need to go back to the folder containing the task:

you@srvairlock:~/ cd /cortexlab/homes/[YOUR CORTEXLAB USERNAME]/workspace/

And now, instruct Minus to create a task file:

you@srvairlock:~/workspace$ minus task create my_task
you@srvairlock:~/workspace$ ls
my_task  my_task.task

And now we have a new file called my_task.task which is ready to be submitted. Warning, do not leave a slash after the directory task name (i.e. my_task ) or the command will fail.

Now we need to give the task to Minus, so that it can operate its magic.

First we need to reserve the CorteXlab room:

I a new browser window open the CorteXlab web app. It will open in your current reservation list if you have any.

Use the “Book the testbed” button in the lower left corner.

You'll get to a screen that looks like this:

Now let's create the reservation!

Under “Book the testbed” select the date of your reservation:

And using the clock icon select the start time of your reservation by dragging the clock pointers:

and

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:

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.

Back to the airlock terminal screen, we now can submit the minus task:

you@srvairlock:~/workspace$ minus task submit my_task.task
15

You'll see that Minus recognizes you as the submitter of the task and gives you a task number (15 in this example). You'll want to write down the number of the task as it will be important for checking its status or to abort it, if necessary.

Bear in mind that your task has been put on a queue and will await running tasks and other scheduled tasks to start, so it may take a while before it runs.

Minus can also help you check the status of the queue:

you@srvairlock:~/workspace$ minus testbed status
num total tasks:   2540
num tasks waiting: 0
num tasks running: 0
tasks currently running:
  (none)

These information are returned:

• num total tasks: This is the number of the last created task
• num tasks waiting: This is the number of tasks currently awaiting in the queue
• num tasks running: This is the number of tasks currently executing (most of the time, there can only be one task running at the same time. Only in special situations, such as demos, tutorials, can several users run tasks concurrently).
• tasks currently running: This is a detailed list of tasks currently running.

Now the node we want to use are up and running with the docker image we set up earlier. We can access them with ssh to run our experiment. To do so, open a new terminal per node you want to use, here two, access Airlock and run the following command, here for node 14 :

you@srvairlock:~/workspace$ ssh -p 2222 root@mnode14

You are now connected to the node with the docker environment you set up earlier. You can then run the command for each node to start the experiment :

# From node 14
root@mnode14:~/ ./examples/ofdm_benchmark/ofdm_rx_example.py -g 10 -b 4 -r 2000000 -f 1234000000
	
# From node 16
root@mnode16:~/ ./examples/ofdm_benchmark/ofdm_tx_example.py -g 10 -b 4 -r 2000000 -f 1234000000

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 :

[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

...

Let's try to understand it:

• The first 21 lines correspond to the UHD messages
• The lines starting with Packet Comparator0 :info: Recieved packet indicate reception of a properly formatted packet. It provides two additionnal bits of information:
  • Packet number. This should increase regularly. Missing elements in the sequence indicate packet loss
  • Bit Error Rate. Computed only on the current packet

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.

All results are stored by task number in the results folder. Let's go and have a look at them:

you@srvairlock:~/workspace $ cd ../results
you@srvairlock:~/results$ ls
task_XXXX
you@srvairlock:~/results$ cd task_XXXX
you@srvairlock:~/results/task_XXXX $ ls
node14  node16

So we see that we have a folder for each task and inside each folder one folder per participant node.

you@srvairlock:~/results/task_XXXX$ cd node14
you@srvairlock:~/results/task_XXXX/node14$ ls
task_XXXX_container_0               task_XXXX_container_0.create.stdout task_XXXX_container_0.kill.stdout  
task_XXXX_container_0.log.stdout    task_XXXX_container_0.start.stdout  task_XXXX_container_0.wait.stdout
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

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.

Congratulations! You have finished your first tutorial on CorteXlab. Please, feel free to change the example task and try out different configurations, carrier frequencies, bands, and so on. You can always resubmit this task to test out different kinds of configurations.

One good example of what to do is to nudge the carrier frequency of approximately +/- 20 KHz and see if the decoding process works better.

To learn mode advanced concepts around creating and managing tasks on CorteXlab, please continue the tutorials.