From 751ac85dea5bd1f88e9b7ec34efb56c79a86578b Mon Sep 17 00:00:00 2001
From: David Northcote <42978178+dnorthcote@users.noreply.github.com>
Date: Mon, 1 Aug 2022 20:31:34 +0100
Subject: [PATCH] Initial commit
---
.gitattributes | 2 +
.gitignore | 22 +
LICENCE.md | 28 +
README.md | 72 +
open_jupyter_launcher.jpg | Bin 0 -> 40605 bytes
open_terminal_window.jpg | Bin 0 -> 24812 bytes
rfsoc_book/__init__.py | 0
rfsoc_book/__main__.py | 165 +
rfsoc_book/helper_functions.py | 441 +
.../notebooks/common/rfsoc_book_banner.jpg | Bin 0 -> 879637 bytes
.../notebooks/notebook_A/01_jupyter_lab.ipynb | 216 +
.../02_visualisation_and_analysis.ipynb | 656 ++
.../notebooks/notebook_A/04_overlays.ipynb | 475 +
.../RFSoC2x2_03_pynq_introduction.ipynb | 227 +
.../RFSoC4x2_03_pynq_introduction.ipynb | 227 +
.../boards/ZCU111_03_pynq_introduction.ipynb | 220 +
.../images/jupyter_lab_annotation.png | Bin 0 -> 77169 bytes
.../images/jupyterlab_select_manager.png | Bin 0 -> 22913 bytes
.../notebook_A/images/jupyterlab_shutdown.png | Bin 0 -> 18625 bytes
.../notebook_A/images/jupyterlab_toolbar.png | Bin 0 -> 8711 bytes
.../notebook_A/images/nco_block_diagram.png | Bin 0 -> 28215 bytes
.../notebook_A/images/nco_ip_integrator.png | Bin 0 -> 76530 bytes
.../images/pynq_rfsoc_framework.png | Bin 0 -> 61984 bytes
.../notebooks/notebook_B/01_sampling.ipynb | 453 +
.../notebook_B/02_quantisation.ipynb | 511 ++
.../notebook_B/03_adcs_and_dacs.ipynb | 589 ++
.../notebook_B/04_digital_filter_design.ipynb | 823 ++
.../images/Analogue_Digital_Signals.png | Bin 0 -> 119798 bytes
.../notebook_B/images/DAC_reconstruction.png | Bin 0 -> 34333 bytes
.../images/analogue_and_digital_signals.png | Bin 0 -> 121778 bytes
.../notebook_B/images/analogue_anti_alias.png | Bin 0 -> 52743 bytes
.../notebook_B/images/baseband_bandpass.png | Bin 0 -> 20897 bytes
.../images/filter_characteristics.svg | 1953 +++++
.../images/filter_impulse_responses.svg | 1177 +++
.../notebook_B/images/filter_responses.svg | 2387 +++++
.../images/ideal_filter_response.svg | 1071 +++
.../images/linear_phase_impulses.svg | 2392 +++++
.../notebook_B/images/linear_quantisers.png | Bin 0 -> 18408 bytes
.../images/nyquist_zones_examples.png | Bin 0 -> 26554 bytes
.../notebook_B/images/q_error_PDF.png | Bin 0 -> 3448 bytes
.../notebook_B/images/upsample_3.png | Bin 0 -> 148881 bytes
.../02_rfsoc_spectrum_analyser.ipynb | 334 +
.../notebook_C/03_fouriers_theorem.ipynb | 774 ++
.../notebook_C/04_investigating_the_dft.ipynb | 1391 +++
.../05_fast_fourier_transform.ipynb | 823 ++
.../RFSoC2x2_01_exploring_the_spectrum.ipynb | 422 +
.../RFSoC4x2_01_exploring_the_spectrum.ipynb | 422 +
.../ZCU111_01_exploring_the_spectrum.ipynb | 422 +
.../notebook_C/images/dab_radio_channels.png | Bin 0 -> 54191 bytes
.../notebook_C/images/digital_tv_uhf.png | Bin 0 -> 69292 bytes
.../notebooks/notebook_C/images/fft_a.png | Bin 0 -> 40531 bytes
.../notebooks/notebook_C/images/fft_b.png | Bin 0 -> 58265 bytes
.../notebooks/notebook_C/images/fft_c.png | Bin 0 -> 61154 bytes
.../notebook_C/images/fm_radio_channels.png | Bin 0 -> 55548 bytes
.../notebook_C/images/open_voila.png | Bin 0 -> 19474 bytes
.../notebook_C/images/rfsoc2x2_antenna.png | Bin 0 -> 529616 bytes
.../notebook_C/images/rfsoc4x2_antenna.jpg | Bin 0 -> 128701 bytes
.../images/spectrum_access_downlink.png | Bin 0 -> 62129 bytes
.../images/spectrum_access_downlink_2GHz.png | Bin 0 -> 51061 bytes
.../notebook_C/images/spectrum_analyser.png | Bin 0 -> 500092 bytes
.../notebook_C/images/zcu111_antenna.png | Bin 0 -> 1574694 bytes
.../notebook_D/01_baseband_modulation.ipynb | 267 +
.../notebooks/notebook_D/02_evm_and_ber.ipynb | 621 ++
.../notebook_D/03_pulse_shaping.ipynb | 684 ++
.../notebook_E/01_amplitude_modulation.ipynb | 629 ++
.../notebook_E/02_qam_modulation.ipynb | 615 ++
.../notebooks/notebook_E/03_complex_qam.ipynb | 674 ++
.../notebook_E/images/QAM_demodulation.svg | 1787 ++++
.../notebook_E/images/QAM_modulation.svg | 1554 ++++
.../images/amplitude_demodulation.svg | 7119 +++++++++++++++
.../images/amplitude_modulation.svg | 7738 +++++++++++++++++
.../images/complex_demodulation.svg | 1206 +++
.../notebook_E/images/complex_modulation.svg | 1172 +++
.../notebook_E/images/modulation.svg | 1533 ++++
.../notebook_F/01_frequency_planning.ipynb | 1132 +++
.../02_rfsoc_frequency_planner.ipynb | 146 +
.../notebook_G/02_rfsoc_radio_observe.ipynb | 408 +
.../03_rfsoc_radio_helloworld.ipynb | 495 ++
.../RFSoC2x2_01_rfsoc_radio_system.ipynb | 452 +
.../RFSoC4x2_01_rfsoc_radio_system.ipynb | 451 +
.../boards/ZCU111_01_rfsoc_radio_system.ipynb | 452 +
.../notebook_G/images/data_frame.png | Bin 0 -> 89330 bytes
.../images/multiboard_setup_rfsoc2x2.png | Bin 0 -> 2922365 bytes
.../images/multiboard_setup_rfsoc4x2.png | Bin 0 -> 324108 bytes
.../images/multiboard_setup_zcu111.png | Bin 0 -> 6431340 bytes
.../multiboard_setup_zcu111_rfsoc2x2.png | Bin 0 -> 4791673 bytes
.../notebooks/notebook_G/images/receiver.png | Bin 0 -> 50427 bytes
.../images/receiver_terminal_debug.jpg | Bin 0 -> 20831 bytes
.../notebook_G/images/rfsoc2x2_setup.jpg | Bin 0 -> 1198998 bytes
.../notebook_G/images/rfsoc4x2_setup.png | Bin 0 -> 602589 bytes
.../notebook_G/images/rx_coarse_spectrum.png | Bin 0 -> 35438 bytes
.../notebook_G/images/rx_decim_spectrum.png | Bin 0 -> 35006 bytes
.../images/rx_phasesync_constellation.png | Bin 0 -> 23487 bytes
.../notebook_G/images/rx_rrc_spectrum.png | Bin 0 -> 34784 bytes
.../images/rx_timesync_constellation.png | Bin 0 -> 23626 bytes
.../notebook_G/images/rx_timesync_time.png | Bin 0 -> 100475 bytes
.../notebook_G/images/small_cat_grey_0.jpg | Bin 0 -> 1001 bytes
.../notebook_G/images/small_cat_grey_1.jpg | Bin 0 -> 1035 bytes
.../notebook_G/images/small_cat_grey_2.jpg | Bin 0 -> 1044 bytes
.../notebook_G/images/small_cat_grey_3.jpg | Bin 0 -> 1022 bytes
.../notebook_G/images/system_overview.png | Bin 0 -> 50094 bytes
.../notebook_G/images/transmitter.png | Bin 0 -> 49907 bytes
.../notebook_G/images/tx_interp_spectrum.png | Bin 0 -> 31333 bytes
.../notebook_G/images/tx_interp_time.png | Bin 0 -> 41462 bytes
.../notebook_G/images/tx_rrc_spectrum.png | Bin 0 -> 47863 bytes
.../notebook_G/images/tx_rrc_time.png | Bin 0 -> 68103 bytes
.../images/tx_symbol_constellation.png | Bin 0 -> 23899 bytes
.../notebook_G/images/tx_symbol_time.png | Bin 0 -> 82716 bytes
.../notebook_G/images/zcu111_setup.png | Bin 0 -> 3352070 bytes
.../notebook_H/01_fec_first_principles.ipynb | 219 +
.../notebook_H/02_fec_encoding.ipynb | 650 ++
.../03_fec_channel_simulation.ipynb | 516 ++
.../notebook_H/04_fec_decoding.ipynb | 619 ++
.../05_fec_bit_error_analysis.ipynb | 661 ++
.../data/docsis_init_ranging_parity.csv | 80 +
.../data/docsis_init_ranging_rx.txt | 160 +
.../data/docsis_init_ranging_tx.txt | 10 +
.../notebook_H/images/ber_curves_design.svg | 1 +
.../images/ber_curves_design_hw.svg | 1 +
.../notebook_H/images/ctrl_status_dec.svg | 1 +
.../notebook_H/images/ctrl_status_fec.svg | 1 +
.../notebook_H/images/decoder_input.svg | 1 +
.../notebook_H/images/lower_triangle.svg | 63 +
.../notebook_H/images/nb_3_overview.svg | 1 +
.../scaled_symbol_mapping_boundaries.svg | 1 +
.../images/sdfec_decoder_block_design.svg | 1 +
.../images/sdfec_encoder_block_design.svg | 1 +
.../notebook_H/images/symbol_mapping.png | Bin 0 -> 117518 bytes
.../notebook_I/01_ofdm_fundamentals.ipynb | 1005 +++
.../02_ofdm_python_transceiver.ipynb | 795 ++
.../RFSoC2x2_03_rfsoc_ofdm_transceiver.ipynb | 211 +
.../RFSoC4x2_03_rfsoc_ofdm_transceiver.ipynb | 211 +
.../ZCU111_03_rfsoc_ofdm_transceiver.ipynb | 211 +
.../notebook_I/images/channel copy.svg | 71 +
.../notebook_I/images/filter copy.svg | 128 +
.../notebook_I/images/ofdm_architecture.png | Bin 0 -> 50640 bytes
.../images/ofdm_modulation_selector.png | Bin 0 -> 15923 bytes
.../notebook_I/images/ofdm_rx copy.svg | 71 +
.../notebook_I/images/ofdm_tx_1 copy.svg | 154 +
.../notebook_I/images/ofdm_tx_2 copy.svg | 64 +
.../notebook_I/images/ofdm_tx_3 copy.svg | 66 +
.../notebook_I/images/output_signal copy.svg | 83 +
.../notebook_I/images/rfsoc2x2_setup.png | Bin 0 -> 663493 bytes
.../notebook_I/images/rfsoc4x2_setup.png | Bin 0 -> 602589 bytes
.../notebook_I/images/zcu111_setup.png | Bin 0 -> 940002 bytes
rfsoc_book/package_list.txt | 5 +
setup.py | 27 +
147 files changed, 53919 insertions(+)
create mode 100644 .gitattributes
create mode 100644 .gitignore
create mode 100644 LICENCE.md
create mode 100644 README.md
create mode 100644 open_jupyter_launcher.jpg
create mode 100644 open_terminal_window.jpg
create mode 100644 rfsoc_book/__init__.py
create mode 100644 rfsoc_book/__main__.py
create mode 100644 rfsoc_book/helper_functions.py
create mode 100644 rfsoc_book/notebooks/common/rfsoc_book_banner.jpg
create mode 100644 rfsoc_book/notebooks/notebook_A/01_jupyter_lab.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_A/02_visualisation_and_analysis.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_A/04_overlays.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_A/boards/RFSoC2x2_03_pynq_introduction.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_A/boards/RFSoC4x2_03_pynq_introduction.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_A/boards/ZCU111_03_pynq_introduction.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_A/images/jupyter_lab_annotation.png
create mode 100644 rfsoc_book/notebooks/notebook_A/images/jupyterlab_select_manager.png
create mode 100644 rfsoc_book/notebooks/notebook_A/images/jupyterlab_shutdown.png
create mode 100644 rfsoc_book/notebooks/notebook_A/images/jupyterlab_toolbar.png
create mode 100644 rfsoc_book/notebooks/notebook_A/images/nco_block_diagram.png
create mode 100644 rfsoc_book/notebooks/notebook_A/images/nco_ip_integrator.png
create mode 100644 rfsoc_book/notebooks/notebook_A/images/pynq_rfsoc_framework.png
create mode 100644 rfsoc_book/notebooks/notebook_B/01_sampling.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_B/02_quantisation.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_B/03_adcs_and_dacs.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_B/04_digital_filter_design.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_B/images/Analogue_Digital_Signals.png
create mode 100644 rfsoc_book/notebooks/notebook_B/images/DAC_reconstruction.png
create mode 100644 rfsoc_book/notebooks/notebook_B/images/analogue_and_digital_signals.png
create mode 100644 rfsoc_book/notebooks/notebook_B/images/analogue_anti_alias.png
create mode 100644 rfsoc_book/notebooks/notebook_B/images/baseband_bandpass.png
create mode 100644 rfsoc_book/notebooks/notebook_B/images/filter_characteristics.svg
create mode 100644 rfsoc_book/notebooks/notebook_B/images/filter_impulse_responses.svg
create mode 100644 rfsoc_book/notebooks/notebook_B/images/filter_responses.svg
create mode 100644 rfsoc_book/notebooks/notebook_B/images/ideal_filter_response.svg
create mode 100644 rfsoc_book/notebooks/notebook_B/images/linear_phase_impulses.svg
create mode 100644 rfsoc_book/notebooks/notebook_B/images/linear_quantisers.png
create mode 100644 rfsoc_book/notebooks/notebook_B/images/nyquist_zones_examples.png
create mode 100644 rfsoc_book/notebooks/notebook_B/images/q_error_PDF.png
create mode 100644 rfsoc_book/notebooks/notebook_B/images/upsample_3.png
create mode 100644 rfsoc_book/notebooks/notebook_C/02_rfsoc_spectrum_analyser.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_C/03_fouriers_theorem.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_C/04_investigating_the_dft.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_C/05_fast_fourier_transform.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_C/boards/RFSoC2x2_01_exploring_the_spectrum.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_C/boards/RFSoC4x2_01_exploring_the_spectrum.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_C/boards/ZCU111_01_exploring_the_spectrum.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_C/images/dab_radio_channels.png
create mode 100644 rfsoc_book/notebooks/notebook_C/images/digital_tv_uhf.png
create mode 100644 rfsoc_book/notebooks/notebook_C/images/fft_a.png
create mode 100644 rfsoc_book/notebooks/notebook_C/images/fft_b.png
create mode 100644 rfsoc_book/notebooks/notebook_C/images/fft_c.png
create mode 100644 rfsoc_book/notebooks/notebook_C/images/fm_radio_channels.png
create mode 100644 rfsoc_book/notebooks/notebook_C/images/open_voila.png
create mode 100644 rfsoc_book/notebooks/notebook_C/images/rfsoc2x2_antenna.png
create mode 100644 rfsoc_book/notebooks/notebook_C/images/rfsoc4x2_antenna.jpg
create mode 100644 rfsoc_book/notebooks/notebook_C/images/spectrum_access_downlink.png
create mode 100644 rfsoc_book/notebooks/notebook_C/images/spectrum_access_downlink_2GHz.png
create mode 100644 rfsoc_book/notebooks/notebook_C/images/spectrum_analyser.png
create mode 100644 rfsoc_book/notebooks/notebook_C/images/zcu111_antenna.png
create mode 100644 rfsoc_book/notebooks/notebook_D/01_baseband_modulation.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_D/02_evm_and_ber.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_D/03_pulse_shaping.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_E/01_amplitude_modulation.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_E/02_qam_modulation.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_E/03_complex_qam.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_E/images/QAM_demodulation.svg
create mode 100644 rfsoc_book/notebooks/notebook_E/images/QAM_modulation.svg
create mode 100644 rfsoc_book/notebooks/notebook_E/images/amplitude_demodulation.svg
create mode 100644 rfsoc_book/notebooks/notebook_E/images/amplitude_modulation.svg
create mode 100644 rfsoc_book/notebooks/notebook_E/images/complex_demodulation.svg
create mode 100644 rfsoc_book/notebooks/notebook_E/images/complex_modulation.svg
create mode 100644 rfsoc_book/notebooks/notebook_E/images/modulation.svg
create mode 100644 rfsoc_book/notebooks/notebook_F/01_frequency_planning.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_F/02_rfsoc_frequency_planner.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_G/02_rfsoc_radio_observe.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_G/03_rfsoc_radio_helloworld.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_G/boards/RFSoC2x2_01_rfsoc_radio_system.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_G/boards/RFSoC4x2_01_rfsoc_radio_system.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_G/boards/ZCU111_01_rfsoc_radio_system.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_G/images/data_frame.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/multiboard_setup_rfsoc2x2.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/multiboard_setup_rfsoc4x2.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/multiboard_setup_zcu111.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/multiboard_setup_zcu111_rfsoc2x2.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/receiver.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/receiver_terminal_debug.jpg
create mode 100644 rfsoc_book/notebooks/notebook_G/images/rfsoc2x2_setup.jpg
create mode 100644 rfsoc_book/notebooks/notebook_G/images/rfsoc4x2_setup.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/rx_coarse_spectrum.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/rx_decim_spectrum.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/rx_phasesync_constellation.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/rx_rrc_spectrum.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/rx_timesync_constellation.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/rx_timesync_time.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/small_cat_grey_0.jpg
create mode 100644 rfsoc_book/notebooks/notebook_G/images/small_cat_grey_1.jpg
create mode 100644 rfsoc_book/notebooks/notebook_G/images/small_cat_grey_2.jpg
create mode 100644 rfsoc_book/notebooks/notebook_G/images/small_cat_grey_3.jpg
create mode 100644 rfsoc_book/notebooks/notebook_G/images/system_overview.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/transmitter.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/tx_interp_spectrum.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/tx_interp_time.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/tx_rrc_spectrum.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/tx_rrc_time.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/tx_symbol_constellation.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/tx_symbol_time.png
create mode 100644 rfsoc_book/notebooks/notebook_G/images/zcu111_setup.png
create mode 100644 rfsoc_book/notebooks/notebook_H/01_fec_first_principles.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_H/02_fec_encoding.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_H/03_fec_channel_simulation.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_H/04_fec_decoding.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_H/05_fec_bit_error_analysis.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_H/data/docsis_init_ranging_parity.csv
create mode 100644 rfsoc_book/notebooks/notebook_H/data/docsis_init_ranging_rx.txt
create mode 100644 rfsoc_book/notebooks/notebook_H/data/docsis_init_ranging_tx.txt
create mode 100644 rfsoc_book/notebooks/notebook_H/images/ber_curves_design.svg
create mode 100644 rfsoc_book/notebooks/notebook_H/images/ber_curves_design_hw.svg
create mode 100644 rfsoc_book/notebooks/notebook_H/images/ctrl_status_dec.svg
create mode 100644 rfsoc_book/notebooks/notebook_H/images/ctrl_status_fec.svg
create mode 100644 rfsoc_book/notebooks/notebook_H/images/decoder_input.svg
create mode 100644 rfsoc_book/notebooks/notebook_H/images/lower_triangle.svg
create mode 100644 rfsoc_book/notebooks/notebook_H/images/nb_3_overview.svg
create mode 100644 rfsoc_book/notebooks/notebook_H/images/scaled_symbol_mapping_boundaries.svg
create mode 100644 rfsoc_book/notebooks/notebook_H/images/sdfec_decoder_block_design.svg
create mode 100644 rfsoc_book/notebooks/notebook_H/images/sdfec_encoder_block_design.svg
create mode 100644 rfsoc_book/notebooks/notebook_H/images/symbol_mapping.png
create mode 100644 rfsoc_book/notebooks/notebook_I/01_ofdm_fundamentals.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_I/02_ofdm_python_transceiver.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_I/boards/RFSoC2x2_03_rfsoc_ofdm_transceiver.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_I/boards/RFSoC4x2_03_rfsoc_ofdm_transceiver.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_I/boards/ZCU111_03_rfsoc_ofdm_transceiver.ipynb
create mode 100644 rfsoc_book/notebooks/notebook_I/images/channel copy.svg
create mode 100644 rfsoc_book/notebooks/notebook_I/images/filter copy.svg
create mode 100644 rfsoc_book/notebooks/notebook_I/images/ofdm_architecture.png
create mode 100644 rfsoc_book/notebooks/notebook_I/images/ofdm_modulation_selector.png
create mode 100644 rfsoc_book/notebooks/notebook_I/images/ofdm_rx copy.svg
create mode 100644 rfsoc_book/notebooks/notebook_I/images/ofdm_tx_1 copy.svg
create mode 100644 rfsoc_book/notebooks/notebook_I/images/ofdm_tx_2 copy.svg
create mode 100644 rfsoc_book/notebooks/notebook_I/images/ofdm_tx_3 copy.svg
create mode 100644 rfsoc_book/notebooks/notebook_I/images/output_signal copy.svg
create mode 100644 rfsoc_book/notebooks/notebook_I/images/rfsoc2x2_setup.png
create mode 100644 rfsoc_book/notebooks/notebook_I/images/rfsoc4x2_setup.png
create mode 100644 rfsoc_book/notebooks/notebook_I/images/zcu111_setup.png
create mode 100644 rfsoc_book/package_list.txt
create mode 100644 setup.py
diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000..dfe0770
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..875e731
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,22 @@
+# Ignore Logs
+*.log
+
+# Ignore Simulink Files
+*.autosave
+*.slxc
+*\.hbs
+*\.Xil
+*\hdl_prj
+*\slprj
+*\wavedata
+
+# Ignore Vivado Files
+*.jou
+*vivado.txt
+
+# Ignore Jupyter
+*.ipynb_checkpoints
+**/__pycache__
+
+# Ignore ./rfstrath/rfstrath/
+**/rfstrath/rfstrath
diff --git a/LICENCE.md b/LICENCE.md
new file mode 100644
index 0000000..5b5e9bd
--- /dev/null
+++ b/LICENCE.md
@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2023, Strathclyde Academic Media
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+ list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+ this list of conditions and the following disclaimer in the documentation
+ and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+ contributors may be used to endorse or promote products derived from
+ this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a444c54
--- /dev/null
+++ b/README.md
@@ -0,0 +1,72 @@
+
+
+# Software Defined Radio with Zynq® UltraScale+ RFSoC
+This repository contains the companion Jupyter Notebooks for the Software Defined Radio with Zynq® UltraScale+ RFSoC book.
+
+To begin installing the Jupyter Notebooks on your system, click-on one of the options below.
+* [RFSoC Setup](#rfsoc-setup)
+* [Notebook Installation](#notebook-installation)
+
+## RFSoC Setup
+This repository is currently only compatible with [RFSoC-PYNQ v2.7](https://github.com/Xilinx/PYNQ/releases). Follow the steps below to setup the RFSoC platform for installing the companion Jupyter Notebooks.
+
+1. Currently, there are only 3 compatible RFSoC platforms. These are the [RFSoC4x2](http://rfsoc-pynq.io/), [ZCU111](https://www.xilinx.com/products/boards-and-kits/zcu111.html), and [RFSoC2x2](http://rfsoc-pynq.io/).
+
+2. Install PYNQ v2.7 onto an SD card and plug it in to your RFSoC platform.
+
+3. Your RFSoC platform requires internet access to install the companion Jupyter Notebooks. Follow the instructions [here](https://pynq.readthedocs.io/en/v3.0.0/getting_started/network_connection.html?highlight=internet) that assist with internet access.
+
+4. Navigate to JupyterLab by opening a browser (preferably Chrome) and connecting to `http://:9090/lab`.
+
+## Notebook Installation
+The companion Jupyter Notebooks can be installed on a computer or RFSoC platform. Follow the instructions below to install the notebooks through JupyterLab. If you haven't already, launch JupyterLab on your computer or RFSoC platform.
+
+1. We need to open a terminal in JupyterLab. Firstly, open a launcher window as given in the following figure.
+
+
+ 
+
+
+2. Now open a terminal in Jupyter as shown below:
+
+
+ 
+
+
+3. Install the RFSoC Book notebooks through PIP by executing the following command in the terminal.
+
+```sh
+pip install https://github.com/strath-sdr/RFSoC-Book/archive/v1.0.0.tar.gz
+```
+
+4. Run the following command in the Jupyter terminal window to install the notebooks and dependencies.
+
+```sh
+python -m rfsoc_book install
+```
+
+5. The RFSoC-Book notebooks are installed. Navigate to the JupyterLab workspace and you will find the notebooks in a folder named `rfsoc_book`.
+
+## Additional Commands
+The RFSoC Book module provides additional commands for those that would like to clean notebooks after use, or uninstall notebooks from their system.
+
+Notebooks can be reset by running the following command in the Jupyter terminal.
+
+```sh
+python -m rfsoc_book clean
+```
+
+To uninstall all notebooks and dependencies, run the command below in the Jupyter terminal.
+
+```sh
+python -m rfsoc_book uninstall
+```
+
+## Warning and Disclaimer
+The best efforts of the authors have been used to ensure that accurate and current information is presented in this repository. This includes researching the topics covered and developing examples. The material included is provided on an "as-is" basis in the best of faith, and the authors do not make any warranty of any kind, expressed, or implied, with regard to the documentation contained in this repository. The authors shall not be held liable for any loss or damage resulting directly or indirectly from any information or examples contained herein.
+
+---
+Copyright © 2023 Strathclyde Academic Media
+
+---
+---
diff --git a/open_jupyter_launcher.jpg b/open_jupyter_launcher.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..d143f0cccfa3d6f09a373e1f3a7708a3dae3bfef
GIT binary patch
literal 40605
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