In this tutorial we will use the gr-bokehgui module to have a time, frequency and spectrogram visualization of the signal transmitted in the platform in real time.

For that, we will modify not only the scenario file as before, but also the running GNU Radio flowgraphs used for the experiment.

Since we will modify GNU Radio flowgraphs, graphically, you will need to have access to a working GNU Radio installation with the additional gr-bokehgui module installed. For that, you can either:

• Have a running X11 server on your computer. On Linux/MacOS, you have nothing to do, you already have one. On Windows, you need to install an X server such as VcXsrv or Xming. That way, we will be able to directly use the GNU Radio installed inside the experiment's Docker Image. This is the method we will mainly describe here as it does not require you to install anything (on Linux) on your machine.
• Install GNU Radio 3.10 on your computer, adding gr-bokehgui following the instructions written on the readme of that module. A good crossplatform option is to use Radioconda. This is the recommended way to properly work on actual experiments because you can work on the flowgraph offline, without having to book the platform.
• Have docker running on your computer, run a container based on the ghcr.io/cortexlab/cxlb-gnuradio-3.10:1.4 image that we provide, and run GNU Radio Companion from inside of it. This is something that we will delve into more in next tutorial, and can be good when working with more complex setups such as with additional libraries and dependencies.

We will be starting from the same point as for the previous tutorial, and building upon it.

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 copy the one from the previous tutorial:

you@srvairlock:~$ cd Tutorials
you@srvairlock:~/Tutorials cp -r Tuto_2 Tuto_3
you@srvairlock:~/Tutorials cd Tuto_3/examples

Let's open the existing scenario file:

you@srvairlock:~/Tutorials/Tuto_3/examples nano ofdm_benchmark/scenario.yaml

And simply increase the duration to 900 or 1200 so we have enough time to work in.

and now we can create and submit the task

you@srvairlock:~/Tutorials/Tuto_3/examples minus task create ofdm_benchmark
you@srvairlock:~/Tutorials/Tuto_3/examples minus task submit ofdm_benchmark.task
2542

Once the task is running, we connect to the node with the bokehgui image directly from you local computer. This is because we need to forward the bokehgui data-stream directly from the node to your local computer. This command, to be run in another terminal, will connect you to the node and set up the jump through Airlock (It may start working after a few tens of seconds once it's properly started):

you@yourpc:~$ ssh -X -J username@gw.cortexlab.fr root@mnode16 -p 2222 -L localhost:5006:localhost:5006

We have introduces a few new options to the ssh command: * -X: This will enable X server forwarding, meaning that we will be able to display remotely the GNU Radio Companion window that we will start inside of the node. This option is required only if you are on Linux/MacOS or you have installed a X server on Windows. * -J username@gw.cortexlab.fr: This instruct SSH to Jump through the Airlock gateway * -L localhost:5006:localhost:5006: This forwards the port 5006 between your own computer and the remode system, allowing your browser to later access the running gr-bokehgui server.

We also need to connect to node 14 that we will use as transmitter without modification and without visualisation. Let's open a new (third) terminal, and connect to it:

you@yourpc:~$ ssh -J username@gw.cortexlab.fr root@mnode14 -p 2222

On node 16 (or on your own computer if you don't have an X server running), let's open GNU Radio Companion:

root@mnode16:~$ gnuradio-companion

This should open a window that look like this:

And we can open the ofdm_example_rx.grc file:

As we are opening this file from our home folder on the gateway, when we save it, it will be recorded even after the task finishes.

And now we can see the full reception flowgraph with all its blocks. You can resize the window, and pan/scroll/zoom to look around the graph.

Feel free to take some time to look at the graph to see what it does.

We will now add the elements to visualise.

We will add a couple of things: * A Waterfall to look at the received frequency spectrum * A Time Sink to look at the received bit sequence

And we will add a couple of widgets to control the receiver's parameters while it's running: * A Slider for center frequency * A slider for gain

You will find the blocks to add in the right side panel containing the block library, in the Bokeh GUI section

You can also type Ctrl+F and type to search a block name

So first, add a Waterfall Sink right at the beginning of the flowgraph, connected to UHD USRP Source block, and fill in its parameters by double clicking on it. The main one to change here is the placement param to specify where the plot will appear in the browser.

Now add a Time Sink at the end, following a Char to float to convert the sample types to one that can be displayed.

That's it for the plots

We can now add the Sliders to play with some of the parameters during execution These can be placed anywhere in the canvas. Before opening the block's parameters, make sure to disable the freq and gain Parameter blocks at the top by right clicking on them and selecting Disable.

Now fill in the parameters as follow:

The very last step before execution is to set the flowgraph's option to use Bokeh GUI, for that open the Options block at the top left corner, and select Bokeh GUI:

You can now press play to run the modified flowgraph. You will probably encounter this warning window, just ignore it and hit OK:

If you had done these modifications on your own computer, simply hit the Generate button, just left to the Play button to generate a python script to execute and copy it with scp on airlock. And execute it, just like we did in previous tutorial.

Now that the bokehgui flowgraph is running, you can access the visualization tool available at the following address on your local computer internet browser :

http://localhost:5006/bokehgui

You should see our two sliders, Waterfall, and an empty Time plot. That one is empty because there are no decoded bits as we haven't started the transmitter.

You can play with the gain silder to see what that changes.

Let's now start the transmitter:

# From node 14
root@mnode14:~/ /cortexlab/homes/[username]/Tutorials/Tuto_3/examples/ofdm_benchmark/ofdm_tx_example.py -g 15 -b 4 -r 1000000 -f 1350000000

You now should see something displayed in the Time Sink, and prints in the console resembling what we had in previous tutorials. If not, make sure you haven't changed the frequency slider.

You may not see much difference in the waterfall display (maybe a line once in a while) because packets are not transmitted very often and there is a high chance the Waterfall display misses them. To ensure you can see it, you can change the transmission period to something like 1ms using the -t option:

# From node 14
root@mnode14:~/ /cortexlab/homes/[username]/Tutorials/Tuto_3/examples/ofdm_benchmark/ofdm_tx_example.py -g 15 -b 4 -r 1000000 -f 1350000000 -t 0.001

Note that this will probably flood your console and cause GNU Radio Companion to stop responding. To remedy that, simply stop the transmitter (Ctrl+C) and wait a bit for prints to stop.

Feel free to play with the sliders and displays.

Congratulations, you can now visualize any signal transmitted within the CorteXlab platform ! Feel free to replace the OFDM transmission with your project…

Also, if the setup of the present bokehgui flowgraph doesn't suit your need, you can pull the docker image and upgrade it. You can also integrate bokehgui blocks to your existing project.

The gr-bokehgui library is available here.