Introduction
Jupyter notebooks are awesome and a great way to share code and research outputs. There are some notebooks already available for Pynq for the RFSoC that are great tools for learning the functionality or testing hardware designs. But what if you want to deploy a standalone application? Or want to share your code in a specific, interactable and convenient way with no cells in the way? This is where dashboards and tools like Voila can be of great help.
In this article we will outline some motivations on why you would want to use a dashboard for your visual RFSoC application, introduce one of the bigger dashboard packages for Python in Voila and show how it can be leveraged to create interactive applications on the latest Xilinx RFSoC board with Pynq.
Jupyter notebooks
Jupyter Notebooks are the de facto way of sharing python code these days amongst researchers and coders alike. It is easy to add structured text and explanations in markdown, add images and diagrams explaining what the code does, you can even export your notebook as a static html page which allows you to share your exciting cat detector results with persons who don’t have Jupyter, or even Python installed on their machine.
Jupyter notebooks also come with a rich library of widgets (like plots and sliders) that can be added for interactivity. You can see these in action in the RFSoC QPSK Transceiver demo notebook as shown below.
As mentioned earlier Jupyter Notebooks are a great way to share code, and, as is the case with Pynq, interact with not only the software components but hardware components as well. All from the convenience of your local python interpreter.
You may have noticed that in the demo shown above there is a whole lot of scopes and some radio control sliders. Obviously the notebook layout is not ideal when showing it off to someone not interested in the Python code or the ins and outs of how ipywidgets work. You have to scroll down past all the text to the power slider, then scroll back up to see how it affected the received signal… It’s all very tedious. Here’s where dashboards come in!
Why dashboards and Voila?
Dashboards allow us to write full blown web applications without any knowledge of JavaScript or HTML. On the user side, this allows them to play with your application without having to look at any of the code - this can be useful for newbies or high level decision makers. Creating a dashboard also prevents arbitrary code execution, and only allows the user to adjust parameters as intended by your design. This has good security implications in software, but we also operate in the hardware world - and with a piece of equipment as expensive as the RFSoC, you may want to put a limit on what people can do with your design.
The Pynq project is closely linked with the Jupyter ecosystem, and Voila offers the most seemless integration with existing work. It uses all the ipywidgets you have come to love and appreciate, which means that if you have an up-to-date Jupyter installation - you can use Voila straight out of the box.
Good for security
Dashboards prevent arbitrary code execution - this is good for software security, but in our case it may very well prevent damage to the board. Say, you have an RFSoC demo set up running a Jupyter Notebook at your stand in a tech conference, it’s within the realm of possibility that someone might want to try some python commands and send the drivers some instructions, causing a reload of the bitstream or some misconfiguration.
Now, even if the commands are completely fine technically and are doing what is intended, we can still make usage mistakes, such as settings oscillator clock frequencies ‘wrongly’. Believe it or not, the RFSoC is a very capable RF transmitter and it can very well blast out packets on the GSM, LTE, Wi-Fi or even GPS frequencies. This would cause mild annoyances at best, and legal troubles at worst. If your application is running as a dashboard, with no ability to change the transmitter frequency to a value outside your defined range, this will eliminate the possibility of someone accidentally jamming a cellular network.
Setting up Voila on a Pynq image
To get started you can follow the getting started guide on the pynq documentation site to get your board up and running. Also peruse the FAQ for debugging issues if any may arise.
Once you have the board set up the actual Voila setup is quite straightforward and painless on the Ubuntu operating system running on the Pynq 2.5 image. Couple pip install commands and you’re ready to go. In this case we needed to upgrade the Jupyter package to be compatible with the latest release of Voila.
bash$ pip3 install voila
bash$ pip3 install --upgrade jupyter
Once installed there are a few options on how to use it.
You can run Voila as a standalone application, much like a Jupyter Notebook, by running the command voila in the folder containing your notebooks. By default it will launch a server on localhost of the board on port 8866. If you are familiar with Jupyter Notebooks, then the standalone voila running in your browser will look very similar, just instead of opening the notebooks it will launch dashboard versions of them. You can use keyboard interrupt ctrl+c to stop it.
bash$ voila
[Voila] Using /tmp to store connection files
[Voila] Storing connection files in /tmp/voila_mh5kez0q.
[Voila] Serving static files from /usr/local/lib/python3.6/dist-packages/voila/static.
[Voila] Voila is running at:
http://localhost:8866/
[Voila] WARNING | No web browser found: could not locate runnable browser.
^C[Voila] Stopping...
A very convenient way to open dashboards is with the Jupyter server extension. This gets installed automagically with Voila, and can be run by adding /voila to your Jupyter server url, just like you would with Jupyter lab. E.g.
192.168.2.99:9090/voila
Onto the QPSK dashboard
First of all, to have access to the original QPSK Transceiver demo python libraries and bitstream, which you can find the github page and install their package. The Pynq 2.5 image will have all the dependencies required, which is why we are adding the --no-dependencies flag - this will install only the rfsoc-qpsk package.
bash$ pip3 install --upgrade --no-dependencies git+https://github.com/strath-sdr/rfsoc_qpsk.git
The dashboard (available gist) being shown off in this blog comes in the form of a custom jupyter notebook. In this basic version you have two scopes available - on the left you see a time plot of the pulse shaped data going into the transmitter, and, on the right, the QPSK constellation plot at the receiver of the RFSoC board.
Note how only the widgets are rendered, and all the code cells are omitted. This way, using the carrier frequency sliders, the user will never be able to transmit on a frequency not intended by the design. Everything is also much more conveniently laid out to fit into a single window, with no scrolling or back and forth necessary.
Theming for that modern look
Using themes is really easy with Voila. For example, if you want a nice dark theme, you can simply call the application with an additional --theme=dark flag.
bash$ voila RFSoC_QPSK_Loopback_Dashboard.ipynb --theme=dark
And well… Voila!
You got yourself dark theming capabilities out of the box. Just note that if you’re doing any custom widget work like our friends behind the RFSoC QPSK demo, who have kindly provided an option to enable dark theme on their widgets, you might have to perform some extra steps.
In our case, instantiating the overlay in Python with an extra dark_theme=True flag was enough to take care of the widgets.
Do note that all of these have to be run as root on the board. This will start a voila server by default at 192.168.2.99:8866 - your IP may differ if you changed the settings at some point.
Thanks for reading
In this blog we introduced the concept of dashboards and the benefits you might reap by introducing them to your PYNQ and RFSoC projects with tools like Voila.