Table of Contents
FIT/CorteXlab 101
We will introduce the usage of FIT/CorteXlab through a simple OFDM transmission between two nodes in FIT/CorteXlab's experiment room, transmitting dummy packets between them.
Division of resources will be according to the table below:
Group | SSH login | Nodes to use | Frequency | TCP Port | Connected | Leader |
---|---|---|---|---|---|---|
1 | tuto1 | node 3 and node 4 | 2.400GHz | 6663 | X | Djibrilla |
2 | cadjih | node 7 and node 8 | 2.410GHz | 6664 | X | Cedric |
3 | hezzeddine | node 13 and node 14 | 2.420GHz | 6665 | X | Ezzeddine |
4 | dadja | node 17 and node 18 | 2.430GHz | 6666 | X | Dadja |
5 | tuto4 | node 23 and node 24 | 2.440GHz | 6667 | X | Satya |
6 | ymestrah | node 25 and node 27 | 2.450GHz | 6668 | X | Yasser |
7 | tuto7 | node 28 and node 32 | 2.460GHz | 6669 | X | Thomas |
8 | amayouche | node 33 and node 34 | 2.470GHz | 6670 | X | Abdou |
9 | aparis | node 37 and node 38 | 2.480GHz | 6671 | X | Antoine |
10 | lmroueh | node 16 and node 35 | 2.490GHz | 6672 | X | Lina |
11 | gcallebaut | node 6 and node 9 | 2.500GHz | 6673 | X | Gilles |
First Part: OFDM Transmission and Reception
This first part of the tutorial is based on the example digital OFDM benchmark transmitter and receiver code present in the vanilla GNU Radio. For more info on the OFDM benchmark, please refer to the GNU Radio documentation.
Start your virtual FIT/CorteXlab work environment
To speed up things, the tutorial will be run from inside your virtual FIT/CorteXlab work environment, the virtual machine you've installed before, in the Prerequisites section.
Assuming you have correctly followed the steps described in that section, you can now fire up VirtualBox
Log into the virtual machine with username:cxlbusr
and with an empty password
Once the LXDE interface is fired up, open an LXTerminal
from the Start Menu > System tools
We're now ready to start
Logging into the SSH front-end
You can start by logging into the serveur “airlock” SSH front-end with the following command:
you@your-pc:~$ ssh -X -v <your-login>@airlock
If everything goes well you should get the FIT/CorteXlab welcome screen and an srvairlock prompt.
Cloning the example task
An example task is provided in the FIT/CorteXlab GitHub repositories. It is kept up-to-date and well prepared to run. First let us prepare to clone the example task.
your-login@srvairlock:~$ git clone https://github.com/CorteXlab/examples.git your-login@srvairlock:~$ cd examples your-login@srvairlock:~/examples$ cd my_task
Inspecting the example task
Let's get inside and see what it's all about:
your-login@srvairlock:~/examples/my_task$ ls benchmark_rx.py receive_path.py transmit_path.py benchmark_tx.py scenario.yaml uhd_interface.py
Let's go over each one of these files:
benchmark_tx.py
: the GNU Radio python script for the OFDM transmitterbenchmark_rx.py
: the GNU Radio python script for the OFDM receivertransmit_path.py
,receive_path.py
anduhd_interface.py
: are helper codes for both benchmark python scriptsscenario.yaml
: a scenario description file (in yaml format), which assigns the roles of “transmitter” and “receiver” to a set of nodes
Now, let's inspect the scenario description file, to understand what will happen during this experiment:
your-login@srvairlock:~/examples/my_task$ less scenario.yaml
Which will give you this:
# Example scenario description file # # All lines starting with "#" and empty lines are ignored # Scenario textual description # simple string (a one liner) description: CorteXlab Tutorial 1 # 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: node4: command: ./benchmark_rx.py --antenna="TX/RX" --rx-gain=25 -v -W 2M -f 2.49G passive: true node6: command: ./benchmark_tx.py --antenna="TX/RX" --tx-amplitude=0.2 -v -W 2M -f 2.49G
The file is self-explanatory, but for now let's ignore all but the indented lines following node4:
and node6:
. You'll have the opportunity to understand the rest better later on.
Let's go over each said line now:
node4:
: This opens the node4 declaration of optionscommand: ./benchmark_rx.py –antenna=“TX/RX” –rx-gain=25 -v -W 2M -f 2.49G
: states the command to run on node4. Details of the parameters are:–antenna=“TX/RX”
: this indicates which antenna connector to use on the USRP radio platform connected to the node–rx-gain=25
: this sets the receive gain of the USRP radio platform-v
: this puts the script in verbose mode, printing debug information-W 2M
: this sets the bandwidth of the signal to 2 MHz-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:
- Node4 behaves as the OFDM receiver
- Node6 behaves 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.
Changing the scenario file
We'll need to change the scenario file in order to reflect the nodes that your group is going to use. Please refer to the table at the top for the two nodes and the frequency you're going to use. Use your preferred unix editor to edit the file:
your-login@srvairlock:~/examples/my_task$ pico scenario.yaml
Change node4
and node6
to the two nodes that have been assigned to your group. The order is not of importance. We will also change the default frequency of 2.49G
to the one assigned to your group.
Be sure that the file remains the same aside from those three changes. Any syntax error on the files will produce an error when processed by FIT/CorteXlab.
For the task to take a while longer, we will also need to change the number of packets to transmit. For the transmitter node's parameters (line command: ./benchmark_tx.py
) add at the end of the line the option -M 10
.
Save the file ctrl+X
and then Y
for the pico
editor.
Creating the task file
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 synchronously
- Waiting until everything finishes, and stop stubborn code from running forever
- Copying results, error and output messages to srvairlock, 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:
your-login@srvairlock:~/examples/my_task$ cd .. your-login@srvairlock:~/examples$
And now, instruct Minus to create a task file:
your-login@srvairlock:~/examples$ minus task create my_task your-login@srvairlock:~/examples$ 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.
Reserving the platform
We are now finally ready to give the task to Minus, so that it can operate its magic. However we need to reserve our resources, so that we guarantee that no one else will use it. The resources we will need to reserve are the nodes that were assigned to your group, the same ones that you typed into the scenario file.
For the purposes of this tutorial, a shared reservation has been done in advance. This parent reservation's 'id' will be given to you by the tutorial instructors. We will need to create a child reservation inside of the parent one.
To reserve your nodes in the FIT/CorteXlab room, use this following command. Please replace mnode4
and mnode6
with the node numbers assigned to your group. Bear in mind that the preceding letter 'm' should be kept!
your-login@srvairlock:~/examples$ oarsub -t inner=<id of container> -l {"network_address in ('mnode4.cortexlab.fr', 'mnode6.cortexlab.fr')"}/nodes=2,walltime=1:00:00 -I
This will run a 1 hour job and open a subshell in which you can run minus tasks. This subshell will be killed after 1 hour, and if you leave the shell earlier, it will terminate the corresponding oar job. More documentation on oar can be found here.
Among the reservation messages OAR outputs, the system will give you a reservation 'id'. Be sure to write your's down. It can be used for stopping the job if necessary.
You can check if the job was properly created as well as monitor the current jobs in the gantt web interface.
Submitting the task
We are finally ready to submit the minus task:
your-login@srvairlock:~/examples$ minus task submit my_task.task 15
You'll see that Minus 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.
Using Minus to check the task's status
Minus can also help you check the status of the testbed:
your-login@srvairlock:~/examples$ 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 tasknum tasks waiting
: This is the number of tasks currently awaiting in the queuenum 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.
If you wish the see all tasks in the waiting queue, use the option -w
with the same command:
your-login@srvairlock:~/examples$ minus testbed status -w
Debugging your task
If your task didn't run, or finished too fast, then there might have been a problem with its execution. There are several ways to debug the Minus' problems. Lets concentrate on the easiest one: minus logs.
To view all minus logs execute this command:
your-login@srvairlock:~/examples$ minus log
All Minus' log messages can be seen, including the server logs as well as the node logs. Any non-gnuradio related problems with your task can be seen in these logs.
Collecting and analyzing the output
Generally the OFDM example task will take a few minutes to run. Once it is finished, Minus will take care of copying the results and output messages back to your home folder in srvairlock, so that you can analyze it.
All results are stored by task number in the results folder, inside your home folder.
Let's go and have a look at them. In the lines below, replace <your task number> by the task 'id' provided by minus:
your-login@srvairlock:~/examples$ cd ../results your-login@srvairlock:~/results$ cd task_<your task number> your-login@srvairlock:~/results/task_#$ ls node4.tgz node6.tgz your-login@srvairlock:~/results/task_#$
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:
your-login@srvairlock:~/results/task_#$ tar -zxf node4.tgz your-login@srvairlock:~/results/task_#$ ls node4 node4.tgz node6.tgz your-login@srvairlock:~/results/task_#$ cd node4 your-login@srvairlock:~/results/task_#/node4$ ls benchmark_rx.py receive_path.pyc stdout.txt uhd_interface.pyc benchmark_tx.py scenario.yaml transmit_path.py receive_path.py stderr.txt uhd_interface.py
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:
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 thestdout.txt
or nothing at all, it might be interesting to take a look at thestderr.txt
to debug your code.
Let's take a look inside both, starting with the stdout.txt
:
your-login@srvairlock:~/results/task_15/node4$ less stdout.txt
For the node which was configured as a receiver (refer to the scenario.yaml), you should get a long file that looks more or less like this:
linux; GNU C++ version 4.7.2; Boost_104900; UHD_003.007.001-84-gd99ce4ef -- 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 ...
Let's try to understand it:
- The first 9 lines correspond to the UHD messages
- The next 16 lines correspond to the GNU Radio messages and radio configuration parameters
- There might be a warning message about realtime scheduling that can be safely ignored
- 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:ok: False
: means the packet was incorrectly decoded, i.e., it failed to pass the checksumpktno: 169
: is the sequence number seen at the receivern_rcvd: 1
: is the number of received packetsn_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.
You can also look into the stderr.txt:
your-login@srvairlock:~/results/task_15/node4$ less stderr.txt
What next?
Congratulations! You have finished your first tutorial on FIT/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.