Differences

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

--- bokehgui_for_cortexlab [2022/02/22 10:20] – aparis
+++ bokehgui_for_cortexlab [2025/05/16 16:59] (current) – cmorin
@@ Line 1: / Line 1: @@
 # Eyes and ears inside CorteXlab
-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. We will not try to demodulate the signal, this is just a visualization tool.
+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.
-Here, we will transmit an OFDM signal using the docker image you used for the previous tutorial. However you can replace it by any project of your own, we just need a signal to visualize.
+For that, we will modify not only the scenario file as before, but also the running GNU Radio flowgraphs used for the experiment.
-## Update your scenario
+## Opening remarks/Requirements
-A running docker image with the gr-bokehgui module is available at ''amauryparis/cxlb_bokehgui''. You don't have to pull any image on your local computer to make changes to the project as in the previous tutorial.
+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](https://github.com/gnuradio/gr-bokehgui) module installed.
+For that, you can either:
-As previously stated, we will use the OFDM transmission used in the first tutorial to have a signal to visualize.
+ * 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.
-Therefore you can find your OFDM scenario file, add a new node (here the 17) and set it to use the ''amauryparis/cxlb_bokehgui'' image with an ssh access, as follow.
+ * [Install GNU Radio 3.10](https://wiki.gnuradio.org/index.php?title=InstallingGR) on your computer, adding gr-bokehgui following the instructions written on the readme of that module. A good crossplatform option is to use [Radioconda](https://github.com/ryanvolz/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.
+## Preliminary steps
-<code>
+We will be starting from the same point as for the previous tutorial, and building upon it.
-# Example scenario description file
-#
-#   All lines starting with "#" and empty lines are ignored
+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.
-# Scenario textual description
-#   simple string (a one liner)
-description: OFDM - Docker and Cortexlab
-# Experiment maximum duration
+In the previously made 'Tutorials' folder, let's make copy the one from the previous tutorial:
-#   Time after which the experiment is forced to stop
-#   integer (seconds)
-duration: 300
-# Node list
+<code>
-#
+you@srvairlock:~$ cd Tutorials
-#   format:
+you@srvairlock:~/Tutorials cp -r Tuto_2 Tuto_3
-#
+you@srvairlock:~/Tutorials cd Tuto_3/examples
-#   nodes:
+</code>
-#     (machine):
-#       command: (entry point script relative to the task root)
-nodes:
+## The scenario
-  node14:
-    container:
-    - image: [YOUR DOCKER USERNAME]/[OFDM IMAGE NAME]:latest
-      command: /usr/sbin/sshd -p 2222 -D
-  node16:
+Let's open the existing scenario file:
-    container:
-    - image: [YOUR DOCKER USERNAME]/[OFDM NEW IMAGE NAME]:latest
-      command: /usr/sbin/sshd -p 2222 -D
-  node17:
+<code>
-    container:
+you@srvairlock:~/Tutorials/Tuto_3/examples nano ofdm_benchmark/scenario.yaml
-    - image: amauryparis/cxlb_bokehgui
-      command: /usr/sbin/sshd -p 2222 -D
 </code>
-You should directly modify the scenario file located on Airlock. You can access Airlock by using the following command :
+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
 <code>
-you@yourpc:~$ ssh -X -v [-i path/to/the/key] username@gw.cortexlab.fr
+you@srvairlock:~/Tutorials/Tuto_3/examples minus task create ofdm_benchmark
+you@srvairlock:~/Tutorials/Tuto_3/examples minus task submit ofdm_benchmark.task
 </code>
-You can now create and submit you task using ''minus'' commands.
-If you are unclear on how to do it and on the purpose of the scenario file, we recommend going back to the first tutorial.
 ## Connect to the Bokehgui node
-Once the task is running, we connect to the node with the bokehgui image directly from you local computer, not from the airlock server as for the OFDM node. 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  :
+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):
 <code>
-you@yourpc:~$ ssh -X -v [-i path/to/the/key -J username@gw.cortexlab.fr root@mnode17 -p 2222 -L localhost:5006:localhost:5006
+you@yourpc:~$ ssh -X -J username@gw.cortexlab.fr root@mnode16 -p 2222 -L localhost:5006:localhost:5006
 </code>
-On the node, you will find two files, the GRC flowgraph and the python executable of the project.
+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.
-{{ :grc_flowgraph_bokehgui.png?600 |}}
+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 can ran the python executable with the following command :
+<code>
+you@yourpc:~$ ssh -J username@gw.cortexlab.fr root@mnode14 -p 2222
+</code>
+On node 16 (or on your own computer if you don't have an X server running), let's open GNU Radio Companion:
 <code>
-root@mnode17:~# ./cxlb_bokehgui.py
+root@mnode16:~$ gnuradio-companion
 </code>
-**Remarq** : The sample rate is set at 35kHz by default but can be modified by updating the python file using ''apt''. The same procedure can be used to change the default frequency and gain.
+This should open a window that look like this:
+{{ :remote_grc_just_started.png?600 |}}
+And we can open the ''ofdm\_example\_rx.grc'' file:
+{{ :remote_grc_opening_rx.png?600 |}}
+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.
+{{ :remote_grc_opened_rx.png?600 |}}
+Feel free to take some time to look at the graph to see what it does.
+## Add the gr-bokehgui blocks
+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
+{{ :remote_grc_bokeh_waterfall_select.png?600 |}}
+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.
+{{ :remote_grc_waterfall_params.png?600 |}}
+Now add a ''Time Sink'' at the end, following a ''Char to float'' to convert the sample types to one that can be displayed.
+{{ :remote_grc_time_sink_params.png?600 |}}
+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:
+{{ :remote_grc_freq_slider.png?600 |}}
+{{ :remote_grc_gain_slider_params.png?600 |}}
+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'':
+{{ :remote_grc_options.png?300 |}}
+You can now press play to run the modified flowgraph.
+You will probably encounter this warning window, just ignore it and hit OK:
+{{ :xterm_warning.png?200 |}}
+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](https://www.cortexlab.fr/doku.php?id=exp_upload) on airlock.
+And execute it, just like we did in previous tutorial.
+## Visualize your signal
 Now that the bokehgui flowgraph is running, you can access the visualization tool available at the following address on your local computer internet browser :
 <code>
-http://localhost:5006/bokehgui?bokeh-session-id=cxlb_bokehgui
+http://localhost:5006/bokehgui
 </code>
-All time, frequency and waterfall visualization tool are now up and running. However, they are just displaying noise at this time.
+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.
-## Start the OFDM transmission
+{{ :bokeh_browser_no_signal.png?600 |}}
-To start the OFDM transmission, you can access the OFDM node from airlock as follow :
+You can play with the gain silder to see what that changes.
+Let's now start the transmitter:
 <code>
-username@srvairlock:~$ ssh -p 2222 root@mnode16
+# 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
 </code>
-Then you can run the following command to start the OFDM transmitter flowgraph :
+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.
+{{ :bokeh_browser_w_signal.png?600 |}}
+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:
 <code>
-./examples/my_task/benchmark_tx.py --antenna="TX/RX" --tx-amplitude=0.2 -v -W 2M -f 2.49G
+# 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
 </code>
-## Visualize your signal
+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.
-You can go back to your browser and have a look at your signal.
-{{ :signal_vis.png?600 |}}
+Feel free to play with the sliders and displays.
-## What's next ?
+## Conclusion
 Congratulations, you can now visualize any signal transmitted within the CorteXlab platform ! Feel free to replace the OFDM transmission with your project...