Merge pull request #33 from dnorthcote/master

Upgrade rfsoc-qpsk to v1.3

Author: jogomojo

.gitignore

@@ -1,15 +1,27 @@
-boards/ZCU111/rfsoc_pynq/
-.Xil
-vivado.jou
-vivado.log
-
-*.log
+# Ignore Other
 *.htm
-
 .ipynb_checkpoints
 .idea
+
+# Ignore Logs
+*.log
+
+# Ignore Simulink Files
+*.autosave
 *.slxc
+*\.hbs
+*\.Xil
+*\hdl_prj
 *\slprj
 *\wavedata
-*.autosave
-boards/ip/sysgen/tx/wavedata/AXI_QPSK_Tx.tcl
+
+# Ignore Vivado Files
+*.jou
+*vivado.txt
+*vivado.jou
+*vivado.log
+
+# Ignore ./rfstrath/rfstrath/
+**/rfsoc_qpsk/rfstrath
+**/rfsoc_qpsk/rfsoc_pynq
+**/rfsoc_qpsk/rfsoc_qpsk

README.md

@@ -1,56 +1,83 @@
-<img src="https://www.strath.ac.uk/media/1newwebsite/webteam/logos/xUoS_Logo_Horizontal.png.pagespeed.ic.M6gv_BmDx1.png" width="350">
+<img src="strathclyde_banner.png" width="100%">
 
-# RFSoC QPSK Transceiver 
+# RFSoC QPSK Transceiver
+This repository is only compatible with [PYNQ images v2.6](https://github.com/Xilinx/PYNQ/releases) for the [ZCU111](https://www.xilinx.com/products/boards-and-kits/zcu111.html) and [RFSoC2x2](http://rfsoc-pynq.io/).
 
 ## Introduction
 This repo contains all the files needed to build and run the RFSoC QPSK demonstrator that was published in [IEEE Access](https://ieeexplore.ieee.org/document/9139483) and was presented at both [FPL](https://fpl2018.org/) and [XDF](http://www.xilinx.com/xdf) conferences in 2018. The design is a full QPSK transceiver, which transmits and receives randomly-generated pulse-shaped symbols with full carrier and timing synchronisation. [PYNQ](https://github.com/xilinx/pynq) is used to visualise the data at both the DAC and ADC side of the RFSoC data converters, as well as visualising various DSP stages throughout the transmit and receive signal path.
 
 <p align="center">
-  <img src="https://github.com/strath-sdr/rfsoc_qpsk/blob/master/img/constellation_small.gif" width="400" height="400" />
+  <img src="demonstration.gif" width="787" height="513" />
 <p/>
 
 ## Quick Start
+Follow the instructions below to install the QPSK demonstrator on your development board. **You will need to give your board access to the internet**.
+* Power on your RFSoC2x2 or ZCU111 development board with an SD Card containing a fresh PYNQ v2.6 image.
+* Navigate to Jupyter Labs by opening a browser (preferably Chrome) and connecting to `http://<board_ip_address>:9090/lab`.
+* We need to open a terminal in Jupyter Lab. Firstly, open a launcher window as shown in the figure below:
 
-This repository is only compatible with [PYNQ images v2.5 and greater](https://github.com/Xilinx/PYNQ/releases) for [ZCU111](https://www.xilinx.com/products/boards-and-kits/zcu111.html).
+<p align="center">
+  <img src="../master/open_jupyter_launcher.jpg" width="50%" height="50%" />
+<p/>
 
-Connect to the board with **Jupyter Lab** in a browser (not Jupyter Notebook) @ `http://<IP address>/lab`. 
+* Now open a terminal in Jupyter as illustrated below:
 
-Open a terminal in Jupyter Lab. If you are using PYNQ v2.6, run the following command:
-```sh
-pip3 install git+https://github.com/strath-sdr/rfsoc_qpsk --no-deps
-```
+<p align="center">
+  <img src="../master/open_terminal_window.jpg" width="50%" height="50%" />
+<p/>
+
+Now follow the board specific instructions as follows.
+
+## RFSoC2x2 Setup
+Your RFSoC2x2 development board does not come preinstalled with the QPSK demonstrator package (rfsoc-qpsk). You can install it by executing the command below in the terminal.
 
-If you are using PYNQ v2.5, simply specify the target branch as shown in the command below:
 ```sh
-pip3 install git+https://github.com/strath-sdr/rfsoc_qpsk@pynq_v2.5.0 --no-deps
+pip3 install git+https://github.com/strath-sdr/rfsoc_qpsk
 ```
 
-The notebook should now be available in the `rfsoc_qpsk/` folder.
-Use Chrome if possible — the rendering performance is important.
+Once installation has complete, you will find the QPSK demonstrator notebooks located in the jupyter home workspace in the `qpsk-demonstrator` folder.
+
+This repository uses Voila to create simple web applications using Jupyter notebooks. Your RFSoC2x2 development board should already be preinstalled with a version of Voila and no further setup is required.
 
 ## ZCU111 Setup
-We use DAC2 from tile 229 to transmit and ADC0 from tile 224 to receive. These correspond to connections J5 and J4 on the HW-FMC-XM500 daughter board respectively. SW6 on the ZCU111 must be set to boot from SD card (as shown in the image below).
+The ZCU111 PYNQ image already comes preinstalled with the QPSK demonstrator package. To use this repository correctly you should force reinstall the rfsoc-qpsk package by executing the following command in the terminal:
 
-<p align="center">
-<img src="https://github.com/strath-sdr/rfsoc_qpsk/blob/master/img/rfsoc_setup.png" width="800">
-<p/>
+```sh
+pip3 install --force-reinstall --no-deps git+https://github.com/strath-sdr/rfsoc_qpsk
+```
+
+Once installation has complete, you will find the QPSK demonstrator notebooks located in the jupyter home workspace in the `qpsk-demonstrator` folder.
+
+This repository uses Voila to create simple web applications using Jupyter notebooks. If you would like to use Voila on your ZCU111 development board, simply follow the instructions outlined in this [blog post](https://strath-sdr.github.io/pynq/linux/zynq/fpga/voila/2021/02/22/install-voila-on-pynq-v2-6.html).
 
 ## Using the Project Files
-All software builds have been tested on Microsoft Windows 10.
-#### Requirements
+The following software is required to use the project files in this repository.
 - Vivado Design Suite 2020.1
 - System Generator for DSP
-- MATLAB 2020a
+- MATLAB R2020a
 
 ### System Generator
 The Tx and Rx IPs are in separate directories in `rfsoc_qpsk/boards/sysgen/` that can be opened using the appropriate System Generator dialogue. Due to the large amount of decimation and interpolation in both IPs, simulating the output can take an extraordinarily long time. A less extreme multirate system would simulate much faster! 
 
 ### Vivado
-This project can be built with Vivado from the command line:
+This project can be built with Vivado from the command line. Open Vivado 2020.1 and execute the following into the tcl console:
+
+```sh
+cd /<repository-location>/boards/<board-name>/rfsoc_qpsk/
+```
+
+Now that we have moved into the correct directory, make the Vivado project by running the make commands below sequentially.
+
+```sh
+make project
+make block_design
+make bitstream_file
+```
+
+Alternatively, you can run the entire project build by executing the following into the tcl console:
 ```sh
-cd rfsoc_qpsk/boards/ZCU111/
-vivado -mode batch -nojournal -nolog -source write_project.tcl
+make all
 ```
 
 ## License 
-[BSD 3-Clause](https://github.com/strath-sdr/rfsoc_qpsk/blob/master/LICENSE)
+[BSD 3-Clause](../../blob/master/LICENSE)

boards/RFSoC2x2/rfsoc_qpsk/Makefile

@@ -0,0 +1,13 @@
+overlay_name := rfsoc_qpsk
+design_name := block_design
+
+all: project block_design bitstream_file
+
+project:
+	vivado -mode batch -source make_project.tcl -notrace
+
+block_design:
+	vivado -mode batch -source make_block_design.tcl -notrace
+
+bitstream_file:
+	vivado -mode batch -source make_bitstream.tcl -notrace