diff --git a/docs/source/conf.py b/docs/source/conf.py index 3e59f96..25d2805 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -36,7 +36,12 @@ todo_include_todos = True templates_path = ['.templates'] exclude_patterns = [] -autodoc_mock_imports = ['uhd', 'adi', 'iio', 'rtlsdr'] +# These modules are required for SDR hardware support, but are not listed +# as Python dependencies in pyproject.toml because they must be installed +# separately (often with system-level drivers or vendor packages). +# We mock them here so Sphinx can build the documentation without requiring +# the actual hardware libraries to be present. +autodoc_mock_imports = ['uhd', 'adi', 'iio', 'rtlsdr', 'bladerf'] autodoc_default_options = { 'members': True, @@ -47,7 +52,9 @@ version_link = f"{sys.version_info.major}.{sys.version_info.minor}" intersphinx_mapping = {'python': (f'https://docs.python.org/{version_link}', None), 'numpy': ('https://numpy.org/doc/stable', None), 'scipy': ('https://docs.scipy.org/doc/scipy', None), - 'matplotlib': ('https://matplotlib.org/stable', None)} + 'pandas': ('https://pandas.pydata.org/pandas-docs/stable', None), + 'h5py': ('https://docs.h5py.org/en/stable', None), + 'plotly': ('https://plotly.com/python-api-reference', None)} def autodoc_process_docstring(app, what, name, obj, options, lines): diff --git a/docs/source/index.rst b/docs/source/index.rst index 48ba3e5..0e1e9d1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -5,6 +5,7 @@ RIA Toolkit OSS Documentation :maxdepth: 2 Introduction + SDR Guides Datatypes Package SDR Package IO Package diff --git a/docs/source/ria_toolkit_oss/sdr/examples/rx.rst b/docs/source/ria_toolkit_oss/sdr/examples/rx.rst new file mode 100644 index 0000000..5ec0975 --- /dev/null +++ b/docs/source/ria_toolkit_oss/sdr/examples/rx.rst @@ -0,0 +1,50 @@ +.. _rx: + +Rx Example +========== + +This example code for getting started with RIA Toolkit OSS SDR package. + +.. contents:: + :local: + +Introduction +------------ + +The following examples demonstrate how to initialize an SDR, record a signal, and transmit a custom waveform. +These examples assume familiarity with Python and SDR concepts. + +In this example, we use the [bladeRF](https://www.nuand.com/bladerf-1/). However, because +this package presents a common interface for all SDR devices, the same code can be used +to interface with additional supported radios. + +Example 1: Recording a Signal +----------------------------- + +In this example, we initialize the `Blade` SDR, configure it to record a signal for a specified duration. + +.. code-block:: python + + import time + + from ria_toolkit_oss.datatypes.recording import Recording + from ria_toolkit_oss.sdr.blade import Blade + + my_radio = Blade() + print(my_radio) + print(type(my_radio)) + + my_radio.init_rx( + sample_rate=1e6, + center_frequency=2.44e9, + gain=50, + channel=0, + ) + + rx_time = 0.01 + start = time.time() + my_rec = my_radio.record(rx_time=rx_time) + end = time.time() + + print(f"Total time: {end - start} seconds") + print(f"Length of the recording: {len(my_rec)} samples") \ No newline at end of file diff --git a/docs/source/ria_toolkit_oss/sdr/examples/tx.rst b/docs/source/ria_toolkit_oss/sdr/examples/tx.rst new file mode 100644 index 0000000..b053b32 --- /dev/null +++ b/docs/source/ria_toolkit_oss/sdr/examples/tx.rst @@ -0,0 +1,67 @@ +.. _tx: + +Tx Example +========== + +This example code for getting started with RIA Toolkit OSS SDR package. + +.. contents:: + :local: + +Introduction +------------ + +This example illustrates how to generate a custom chirp signal and transmit it using the ``Blade`` SDR. The waveform is +created using the ``numpy`` library and encapsulated in a ``Recording`` object. + +.. code-block:: python + + import time + + import numpy as np + from ria_toolkit_oss.datatypes.recording import Recording + from ria_toolkit_oss.sdr.blade import Blade + + # Parameters + num_samples = 1_000_000 # Total number of samples + num_chirps = 10 # Number of upchirps + sample_rate = 1e6 # Sample rate in Hz (arbitrary choice for normalization) + chirp_duration = num_samples // num_chirps / sample_rate # Duration of each chirp in seconds + f_start = 0 # Start frequency of the chirp (normalized) + f_end = 0.5 * sample_rate # End frequency of the chirp (normalized to Nyquist) + + # Generate IQ data as a series of chirps + t = np.linspace( + 0, chirp_duration, num_samples // num_chirps, endpoint=False + ) + chirp = np.exp( + 2j + * np.pi + * (t * f_start + (f_end - f_start) / (2 * chirp_duration) * t**2) + ) + iq_data = np.tile(chirp, num_chirps)[:num_samples].astype("complex64") + + # Wrap in Recording object + iq_data = Recording(data=iq_data) + + # Initialize and configure the radio + my_radio = Blade() + my_radio.init_tx( + sample_rate=sample_rate, + center_frequency=2.44e9, + gain=50, + channel=0, + ) + + # Transmit the recording + start = time.time() + my_radio.transmit_recording(recording=iq_data, tx_time=10) + end = time.time() + + print(f"Transmission complete. Total time: {end - start:.4f} seconds") + +Conclusion +---------- + +These examples provide a foundation for working with SDRs using the ``Blade`` class. By customizing the parameters, +you can adapt these scripts to various signal processing and SDR tasks. diff --git a/docs/source/ria_toolkit_oss/sdr/hackrf.rst b/docs/source/ria_toolkit_oss/sdr/hackrf.rst deleted file mode 100644 index 4487567..0000000 --- a/docs/source/ria_toolkit_oss/sdr/hackrf.rst +++ /dev/null @@ -1,46 +0,0 @@ -.. _hackrf: - -Intro to the HackRF -=================== - -The HackRF One is a portable and affordable software-defined radio developed by Great Scott Gadgets. It is an -open source hardware platform that is designed to enable test and development of modern and next generation -radio technologies. - -The HackRF is based on the Analog Devices MAX2839 transceiver chip, which supports both transmission and -reception of signals across a wide frequency range, combined with a MAX5864 RF front-end chip and a -RFFC5072 wideband synthesizer/VCO. - -Supported Models ----------------- - - HackRF One: The standard model with a frequency range of 1 MHz to 6 GHz and a bandwidth of up to 20 MHz. - - Opera Cake for HackRF: An antenna switching add-on board for HackRF One that is configured with command-line software. - -Key Features ------------- - - Frequency Range: 1 MHz to 6 GHz. - - Bandwidth: 2 MHz to 20 MHz. - - Connectivity: USB 2.0 interface with support for power, data, and firmware updates. - - Software Support: Compatible with GNU Radio, SDR#, and other SDR frameworks. - - Onboard Processing: ARM-based LPC4320 processor for digital signal processing and interfacing over USB. - -Hackability: ------------- -TODO - -Limitations ------------ - - Bandwidth is limited to 20 MHz. - - USB 2.0 connectivity might limit data transfer rates compared to USB 3.0 or Ethernet-based SDRs. - -Further Information -------------------- - - Official Website: https://greatscottgadgets.com/hackrf/ - - Documentation: https://hackrf.readthedocs.io/en/latest/ - - GitHub Repository: https://github.com/greatscottgadgets/hackrf - -Installation Instructions (Linux) ---------------------------------- -TODO - -From documentation: https://hackrf.readthedocs.io/en/latest/installing_hackrf_software.html diff --git a/docs/source/ria_toolkit_oss/sdr/pluto.rst b/docs/source/ria_toolkit_oss/sdr/pluto.rst deleted file mode 100644 index 59f68e2..0000000 --- a/docs/source/ria_toolkit_oss/sdr/pluto.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _pluto: - -Intro to the Pluto -================== - -The ADALM-PLUTO (PlutoSDR) is a portable and affordable software-defined radio developed by Analog Devices. -It is designed for learning, experimenting, and prototyping in the field of wireless communication. The PlutoSDR -is popular among students, educators, and hobbyists due to its versatility and ease of use. - -The PlutoSDR is based on the AD9363 transceiver chip, which supports both transmission and reception of signals -across a wide frequency range. The device is supported by a robust open-source ecosystem, making it ideal for -hands-on learning and rapid prototyping. - -Supported Models ----------------- - - ADALM-PLUTO: The standard model with a frequency range of 325 MHz to 3.8 GHz and a bandwidth of up to 20 MHz. - - Modified ADALM-PLUTO: Some users modify their PlutoSDR to extend the frequency range to approximately 70 MHz - to 6 GHz by applying firmware patches with unqualified RF performance. - -Key Features ------------- - - Frequency Range: 325 MHz to 3.8 GHz (standard), expandable with modifications. - - Bandwidth: Up to 20 MHz, can be increased to 56 MHz with firmware modifications. - - Connectivity: USB 2.0 interface with support for power, data, and firmware updates. - - Software Support: Compatible with GNU Radio, MATLAB, Simulink, and other SDR frameworks. - - Onboard Processing: Integrated ARM Cortex-A9 processor for custom applications and signal processing. - - Hackability: - - Frequency Range and Bandwidth: The default frequency range of 325 MHz to 3.8 GHz can be expanded to - approximately 70 MHz to 6 GHz, and the bandwidth can be increased from 20 MHz to 56 MHz by modifying - the device's firmware. - - 2x2 MIMO: On Rev C models, users can unlock 2x2 MIMO (Multiple Input Multiple Output) functionality by - wiring UFL to SMA connectors to the device's PCB, effectively turning the device into a dual-channel SDR. - -Limitations ------------ - - Bandwidth is limited to 20 MHz by default, but can be increased to 56 MHz with modifications, which may - affect stability. - - USB 2.0 connectivity might limit data transfer rates compared to USB 3.0 or Ethernet-based SDRs. - -Further Information -------------------- - - Documentation: https://wiki.analog.com/university/tools/pluto - -This module provides tools for interfacing with ADALM-PLUTO devices, allowing for configuration, data streaming, -signal processing, custom application development, and advanced hardware modifications. - -Installation Instructions (Linux) ---------------------------------- - -The pluto is generally usable with Pip. To build and install the drivers from source, see below: - -.. code-block:: bash - - sudo apt-get install build-essential git libxml2-dev bison flex libcdk5-dev cmake python3-pip libusb-1.0-0-dev libavahi-client-dev libavahi-common-dev libaio-dev - cd ~ - git clone --branch v0.23 https://github.com/analogdevicesinc/libiio.git - cd libiio - mkdir build - cd build - cmake -DPYTHON_BINDINGS=ON .. - make -j$(nproc) - sudo make install - sudo ldconfig - - cd ~ - git clone https://github.com/analogdevicesinc/libad9361-iio.git - cd libad9361-iio - mkdir build - cd build - cmake .. - make -j$(nproc) - sudo make install - pip install pyadi-iio diff --git a/docs/source/ria_toolkit_oss/sdr/ria_toolkit_oss.sdr.rst b/docs/source/ria_toolkit_oss/sdr/ria_toolkit_oss.sdr.rst index 071e881..cafc7cc 100644 --- a/docs/source/ria_toolkit_oss/sdr/ria_toolkit_oss.sdr.rst +++ b/docs/source/ria_toolkit_oss/sdr/ria_toolkit_oss.sdr.rst @@ -7,23 +7,21 @@ SDR Package (ria_toolkit_oss.sdr) :inherited-members: :show-inheritance: -Radio Classes -------------- +SDR Code Examples +----------------- -.. autoclass:: ria_toolkit_oss.sdr.hackrf.HackRF -.. autoclass:: ria_toolkit_oss.sdr.pluto.Pluto -.. autoclass:: ria_toolkit_oss.sdr.usrp.USRP - - -Additional Information ----------------------- +This section contains usage examples designed to help you get started with the RIA Toolkit OSS SDR package. .. toctree:: :maxdepth: 2 - Tx-Rx Example - Blade - HackRF - Pluto - USRP - RTL-SDR + Rx Example + Tx Example + +Radio Classes +------------- + +.. autoclass:: ria_toolkit_oss.sdr.usrp.USRP +.. autoclass:: ria_toolkit_oss.sdr.blade.Blade +.. autoclass:: ria_toolkit_oss.sdr.hackrf.HackRF +.. autoclass:: ria_toolkit_oss.sdr.pluto.Pluto diff --git a/docs/source/ria_toolkit_oss/sdr/rtl.rst b/docs/source/ria_toolkit_oss/sdr/rtl.rst deleted file mode 100644 index da7c3ef..0000000 --- a/docs/source/ria_toolkit_oss/sdr/rtl.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. _rtl: - -Intro to the RTL -================ - - RTL-SDR (RTL2832U Software Defined Radio) is a low-cost USB dongle originally designed for digital TV reception - that has been repurposed as a wideband software-defined radio. RTL-SDR devices are popular for hobbyist use due to - their affordability and wide range of applications. - - The RTL-SDR is based on the Realtek RTL2832U chipset, which features direct sampling and demodulation of RF - signals. These devices are commonly used for tasks such as listening to FM radio, monitoring aircraft traffic - (ADS-B), receiving weather satellite images, and more. - -Supported Models ----------------- - - Generic RTL-SDR Dongle: The most common variant, usually featuring an R820T or R820T2 tuner. - - RTL-SDR Blog V3: An enhanced version with additional features like direct sampling mode and a bias tee for - powering external devices. - -Key Features ------------- - - Frequency Range: Typically from 24 MHz to 1.7 GHz, depending on the tuner chip. - - Bandwidth: Limited to about 2.4 MHz, making it suitable for narrowband applications. - - Connectivity: USB 2.0 interface, plug-and-play on most platforms. - - Software Support: Compatible with SDR software like SDR#, GQRX, and GNU Radio. - -Limitations ------------ - - Narrow bandwidth compared to more expensive SDRs, which may limit some applications. - - Sensitivity and performance can vary depending on the specific model and components. - - Requires external software for signal processing and analysis. - -Further Information -------------------- - - Official Website: https://www.rtl-sdr.com/ - - Documentation: https://www.rtl-sdr.com/rtl-sdr-quick-start-guide/ - -This module provides tools for interfacing with RTL-SDR devices, allowing for tuning, data acquisition, and basic -signal processing. diff --git a/docs/source/ria_toolkit_oss/sdr/txrx.rst b/docs/source/ria_toolkit_oss/sdr/txrx.rst deleted file mode 100644 index 0ef244f..0000000 --- a/docs/source/ria_toolkit_oss/sdr/txrx.rst +++ /dev/null @@ -1,86 +0,0 @@ -.. _txrx: - -Rx-Tx Example -============= - -This section provides an overview of the example code for working with SDRs using the ``Blade`` class from the -`utils.sdr` module. The example can be used for other radios as well, as ``utils.sdr`` has a common set of interfaces. - -.. contents:: - :local: - -Introduction ------------- - -The following examples demonstrate how to initialize an SDR, record a signal, and transmit a custom waveform. -These examples assume familiarity with Python and SDR concepts. - -Example 1: Recording a Signal ------------------------------ - -In this example, we initialize the `Blade` SDR, configure it to record a signal for a specified duration, and then -visualize the recorded data. - -.. code-block:: python - - from utils.sdr.blade import Blade - from utils.data.recording import Recording - import time - - my_radio = Blade() - print(my_radio) - print(type(my_radio)) - my_radio.init_rx( - sample_rate=1e6, - center_frequency=2.44e9, - gain=50, - channel=0 - ) - rx_time = 0.01 - start = time.time() - my_rec = my_radio.record(rx_time=rx_time) - end = time.time() - print(f"Total time: {end-start} seconds") - print(len(my_rec)) - my_rec.view() - -Example 2: Transmitting a Custom Waveform ------------------------------------------ - -This example illustrates how to generate a custom chirp signal and transmit it using the ``Blade`` SDR. The waveform is -created using the ``numpy`` library and encapsulated in a ``Recording`` object. - -.. code-block:: python - - from utils.sdr.blade import Blade - from utils.data.recording import Recording - import time - import numpy as np - - num_samples = 1_000_000 # Total number of samples - num_chirps = 10 # Number of upchirps - sample_rate = 1e6 # Sample rate in Hz (arbitrary choice for normalization) - chirp_duration = num_samples // num_chirps / sample_rate # Duration of each chirp in seconds - f_start = 0 # Start frequency of the chirp (normalized) - f_end = 0.5 * sample_rate # End frequency of the chirp (normalized to Nyquist) - iq_data = np.tile(np.exp(2j * np.pi * (np.linspace(0, num_samples // num_chirps / sample_rate, num_samples // num_chirps, endpoint=False) * f_start + (f_end - f_start) / (2 * (num_samples // num_chirps / sample_rate)) * np.linspace(0, num_samples // num_chirps / sample_rate, num_samples // num_chirps, endpoint=False)**2)), num_chirps)[:num_samples].astype("complex64") - - iq_data = Recording(data=iq_data) - - my_radio = Blade() - my_radio.init_tx( - sample_rate=1e6, - center_frequency=2.44e9, - gain=50, - channel=0 - ) - start = time.time() - my_radio.transmit_recording(recording=iq_data, tx_time=10,) - end = time.time() - print(f"Total time: {end-start} seconds") - -Conclusion ----------- - -These examples provide a foundation for working with SDRs using the ``Blade`` class. By customizing the parameters, -you can adapt these scripts to various signal processing and SDR tasks. diff --git a/docs/source/ria_toolkit_oss/sdr/usrp.rst b/docs/source/ria_toolkit_oss/sdr/usrp.rst deleted file mode 100644 index a2e1c85..0000000 --- a/docs/source/ria_toolkit_oss/sdr/usrp.rst +++ /dev/null @@ -1,83 +0,0 @@ -.. _usrp: - -Intro to the USRP family -======================== - -The USRP (Universal Software Radio Peripheral) product line is a series of software-defined radios (SDRs) -developed by Ettus Research. These devices are widely used in academia, industry, and research for various -wireless communication applications, ranging from simple experimentation to complex signal processing tasks. - -USRP devices offer a flexible platform that can be used with various software frameworks, including GNU Radio -and the USRP Hardware Driver (UHD). The product line includes both entry-level models for hobbyists and -advanced models for professional and research use. - -Supported Models ----------------- - - USRP B200/B210: Compact, single-board, full-duplex, with a wide frequency range. - - USRP N200/N210: High-performance models with increased bandwidth and connectivity options. - - USRP X300/X310: High-end models featuring large bandwidth, multiple MIMO channels, and support for GPSDO. - - USRP E310/E320: Embedded devices with onboard processing capabilities. - - USRP B200mini: Ultra-compact model for portable and embedded applications. - -Key Features ------------- - - Frequency Range: Typically covers from DC to 6 GHz, depending on the model and daughter boards used. - - Bandwidth: Varies by model, up to 160 MHz in some high-end versions. - - Connectivity: Includes USB 3.0, Ethernet, and PCIe interfaces depending on the model. - - Software Support: Compatible with UHD, GNU Radio, and other SDR frameworks. - -Hackability ------------ - - The UHD library is fully open source and can be modified to meet user untention. - - Certain USRP models have "RFNoC" which streamlines the inclusion of custom FPGA processing in a USRP. - -Limitations ------------ - - Some models may have limited bandwidth or processing capabilities. - - Compatibility with certain software tools may vary depending on the version of the UHD. - - Price range can be a consideration, especially for high-end models. - -Further Information -------------------- - - Official Website: https://www.ettus.com/ - - Documentation: https://kb.ettus.com/USRP_Hardware_Driver_and_Interfaces - -Installation Instructions (Linux) ---------------------------------- - -Simple apt installations (may not work for all targets): - -.. code-block:: bash - - sudo apt-get install libuhd-dev uhd-host python3-uhd - -Simple build instructions: - -.. code-block:: bash - - sudo apt-get install git cmake libboost-all-dev libusb-1.0-0-dev python3-docutils python3-mako python3-numpy python3-requests python3-ruamel.yaml python3-setuptools build-essential - cd ~ - git clone https://github.com/EttusResearch/uhd.git - cd uhd/host - mkdir build - cd build - cmake -DENABLE_TESTS=OFF -DENABLE_C_API=OFF -DENABLE_MANUAL=OFF .. - make -j8 - sudo make install - sudo ldconfig - - -Getting UHD working in a python virtual environment: - -.. code-block:: bash - - python3 -m venv venv - pip install -r requirements.txt # If relevant - source venv/bin/activate - -Find your dist packages and add to `PYTHONPATH`. Example: - -.. code-block:: bash - - export PYTHONPATH='/usr/local/lib/python3.10/site-packages/' - export PYTHONPATH='/usr/local/lib/python3.10/dist-packages/:$PYTHONPATH' diff --git a/docs/source/ria_toolkit_oss/sdr/blade.rst b/docs/source/sdr_guides/blade.rst similarity index 51% rename from docs/source/ria_toolkit_oss/sdr/blade.rst rename to docs/source/sdr_guides/blade.rst index 630e7d7..8f9197e 100644 --- a/docs/source/ria_toolkit_oss/sdr/blade.rst +++ b/docs/source/sdr_guides/blade.rst @@ -1,7 +1,7 @@ .. _blade: -Intro to the BladeRF family -=========================== +BladeRF +======= The BladeRF is a versatile software-defined radio (SDR) platform developed by Nuand. It is designed for a wide range of applications, from wireless communication research to field deployments. BladeRF devices are known @@ -11,42 +11,39 @@ wide frequency coverage and high bandwidth. Supported Models ---------------- - - BladeRF 2.0 Micro xA4: A compact model with a 49 kLE FPGA, ideal for portable applications. - - BladeRF 2.0 Micro xA9: A higher-end version of the Micro with a 115 kLE FPGA, offering more processing power - in a small form factor. + +- **BladeRF 2.0 Micro xA4:** A compact model with a 49 kLE FPGA, ideal for portable applications. +- **BladeRF 2.0 Micro xA9:** A higher-end version of the Micro with a 115 kLE FPGA, offering more processing power in a small form factor. Key Features ------------ - - Frequency Range: Typically from 47 MHz to 6 GHz, covering a wide range of wireless communication bands. - - Bandwidth: Up to 56 MHz, allowing for wideband signal processing. - - FPGA: Integrated FPGA (varies by model) for real-time processing and custom logic development. - - Connectivity: USB 3.0 interface for high-speed data transfer, with options for GPIO, SPI, and other I/O. -Hackability: ------------- - - Expansion: The BladeRF features GPIO, expansion headers, and add-on boards, allowing users to extend the - functionality of the device for specific applications, such as additional RF front ends. - - Frequency and Bandwidth Modification: Advanced users can modify the BladeRF's settings and firmware to - explore different frequency bands and optimize the bandwidth for their specific use cases. +- **Frequency Range:** Typically from 47 MHz to 6 GHz, covering a wide range of wireless communication bands. +- **Bandwidth:** Up to 56 MHz, allowing for wideband signal processing. +- **FPGA:** Integrated FPGA (varies by model) for real-time processing and custom logic development. +- **Connectivity:** USB 3.0 interface for high-speed data transfer, with options for GPIO, SPI, and other I/O. + +Hackability +----------- + +- **Expansion:** The BladeRF features GPIO, expansion headers, and add-on boards, allowing users to extend the + functionality of the device for specific applications, such as additional RF front ends. +- **Frequency and Bandwidth Modification:** Advanced users can modify the BladeRF's settings and firmware to + explore different frequency bands and optimize the bandwidth for their specific use cases. Limitations ----------- - - The complexity of FPGA development may present a steep learning curve for users unfamiliar with hardware - description languages (HDL). - - Bandwidth is capped at 56 MHz, which might not be sufficient for ultra-wideband applications. - - USB 3.0 connectivity is required for optimal performance; using USB 2.0 will significantly limit data - transfer rates. -Further Information -------------------- - - Official Website: https://www.nuand.com/ - - Documentation: https://www.nuand.com/documentation/ - - GitHub Repository: https://github.com/Nuand/bladeRF +- The complexity of FPGA development may present a steep learning curve for users unfamiliar with hardware + description languages (HDL). +- Bandwidth is capped at 56 MHz, which might not be sufficient for ultra-wideband applications. +- USB 3.0 connectivity is required for optimal performance; using USB 2.0 will significantly limit data + transfer rates. -Installation Instructions (Linux) ---------------------------------- -Step 1: Install the base dependancies and drivers ('Easy method') +Set up instructions (Linux) +--------------------------- +Step 1: Install the base dependencies and drivers ('Easy method') .. code-block:: bash @@ -79,3 +76,10 @@ bladerf python bindings. cd libraries/libbladeRF_bindings/python sudo python3 setup.py bdist_wheel pip install dist/*.whl + +Further Information +------------------- + +- `Official Website `_ +- `BladeRF Documentation `_ +- `GitHub Repository `_ diff --git a/docs/source/sdr_guides/hackrf.rst b/docs/source/sdr_guides/hackrf.rst new file mode 100644 index 0000000..f7a1b8f --- /dev/null +++ b/docs/source/sdr_guides/hackrf.rst @@ -0,0 +1,56 @@ +.. _hackrf: + +HackRF +====== + +The HackRF One is a portable and affordable software-defined radio developed by Great Scott Gadgets. It is an +open source hardware platform that is designed to enable test and development of modern and next generation +radio technologies. + +The HackRF is based on the Analog Devices MAX2839 transceiver chip, which supports both transmission and +reception of signals across a wide frequency range, combined with a MAX5864 RF front-end chip and a +RFFC5072 wideband synthesizer/VCO. + +Supported models +---------------- + +- **HackRF One:** The standard model with a frequency range of 1 MHz to 6 GHz and a bandwidth of up to 20 MHz. +- **Opera Cake for HackRF:** An antenna switching add-on board for HackRF One that is configured with command-line software. + +Key features +------------ + +- **Frequency Range:** 1 MHz to 6 GHz. +- **Bandwidth:** 2 MHz to 20 MHz. +- **Connectivity:** USB 2.0 interface with support for power, data, and firmware updates. +- **Software Support:** Compatible with GNU Radio, SDR#, and other SDR frameworks. +- **Onboard Processing:** ARM-based LPC4320 processor for digital signal processing and interfacing over USB. + +Hackability +----------- + +.. todo:: + + Add information regarding HackRF hackability + +Limitations +----------- + +- Bandwidth is limited to 20 MHz. +- USB 2.0 connectivity might limit data transfer rates compared to USB 3.0 or Ethernet-based SDRs. + +Set up instructions (Linux) +--------------------------- + +`HackRF Software Installation Guide `_ + +.. todo:: + + Addition HackRF installation instructions + +Further information +------------------- + +- `Official Website `_ +- `Project Documentation `_ +- `GitHub Repository `_ diff --git a/docs/source/sdr_guides/index.rst b/docs/source/sdr_guides/index.rst new file mode 100644 index 0000000..de6df14 --- /dev/null +++ b/docs/source/sdr_guides/index.rst @@ -0,0 +1,17 @@ +.. _sdr_guides: + +########## +SDR Guides +########## + +This section contains guides for the various SDR devices supported by the toolkit. Each guide details the supported models, +their key capabilities and limitations, and any additional information needed for setup and configuration. + +.. toctree:: + :maxdepth: 2 + + BladeRF + HackRF + PlutoSDR + USRP + RTL-SDR diff --git a/docs/source/sdr_guides/pluto.rst b/docs/source/sdr_guides/pluto.rst new file mode 100644 index 0000000..f1cf70e --- /dev/null +++ b/docs/source/sdr_guides/pluto.rst @@ -0,0 +1,96 @@ +.. _pluto: + +PlutoSDR +======== + +The ADALM-PLUTO (PlutoSDR) is a portable and affordable software-defined radio developed by Analog Devices. +It is designed for learning, experimenting, and prototyping in the field of wireless communication. The PlutoSDR +is popular among students, educators, and hobbyists due to its versatility and ease of use. + +The PlutoSDR is based on the AD9363 transceiver chip, which supports both transmission and reception of signals +across a wide frequency range. The device is supported by a robust open-source ecosystem, making it ideal for +hands-on learning and rapid prototyping. + +Supported models +---------------- + +- **ADALM-PLUTO:** The standard model with a frequency range of 325 MHz to 3.8 GHz and a bandwidth of up to 20 MHz. +- **Modified ADALM-PLUTO:** Some users modify their PlutoSDR to extend the frequency range to approximately 70 MHz + to 6 GHz by applying firmware patches with unqualified RF performance. + +Key features +------------ + +- **Frequency Range:** 325 MHz to 3.8 GHz (standard), expandable with modifications. +- **Bandwidth:** Up to 20 MHz, can be increased to 56 MHz with firmware modifications. +- **Connectivity:** USB 2.0 interface with support for power, data, and firmware updates. +- **Software Support:** Compatible with GNU Radio, MATLAB, Simulink, and other SDR frameworks. +- **Onboard Processing:** Integrated ARM Cortex-A9 processor for custom applications and signal processing. + +Hackability +------------ + +- **Frequency Range and Bandwidth:** The default frequency range of 325 MHz to 3.8 GHz can be expanded to + approximately 70 MHz to 6 GHz, and the bandwidth can be increased from 20 MHz to 56 MHz by modifying + the device's firmware. +- **2x2 MIMO:** On Rev C models, users can unlock 2x2 MIMO (Multiple Input Multiple Output) functionality by + wiring UFL to SMA connectors to the device's PCB, effectively turning the device into a dual-channel SDR. + +Limitations +----------- + +- Bandwidth is limited to 20 MHz by default, but can be increased to 56 MHz with modifications, which may + affect stability. +- USB 2.0 connectivity might limit data transfer rates compared to USB 3.0 or Ethernet-based SDRs. + +Set up instructions (Linux) +--------------------------- + +The PlutoSDR Python API can be installed via pip. To build and install the drivers from source, see the instructions below: + +.. code-block:: bash + + # Install required packages + sudo apt-get update + sudo apt-get install -y \ + build-essential \ + git \ + libxml2-dev \ + bison \ + flex \ + libcdk5-dev \ + cmake \ + python3-pip \ + libusb-1.0-0-dev \ + libavahi-client-dev \ + libavahi-common-dev \ + libaio-dev + + # Clone and build libiio + cd ~ + git clone --branch v0.23 https://github.com/analogdevicesinc/libiio.git + cd libiio + mkdir -p build + cd build + cmake -DPYTHON_BINDINGS=ON .. + make -j"$(nproc)" + sudo make install + sudo ldconfig + + # Clone and build libad9361-iio + cd ~ + git clone https://github.com/analogdevicesinc/libad9361-iio.git + cd libad9361-iio + mkdir -p build + cd build + cmake .. + make -j"$(nproc)" + sudo make install + + # Install Python bindings + pip install pyadi-iio + +Further information +------------------- + +- `PlutoSDR Documentation `_ diff --git a/docs/source/sdr_guides/rtl.rst b/docs/source/sdr_guides/rtl.rst new file mode 100644 index 0000000..d11132a --- /dev/null +++ b/docs/source/sdr_guides/rtl.rst @@ -0,0 +1,40 @@ +.. _rtl: + +RTL-SDR +======= + +RTL-SDR (RTL2832U Software Defined Radio) is a low-cost USB dongle originally designed for digital TV reception +that has been repurposed as a wideband software-defined radio. RTL-SDR devices are popular for hobbyist use due to +their affordability and wide range of applications. + +The RTL-SDR is based on the Realtek RTL2832U chipset, which features direct sampling and demodulation of RF +signals. These devices are commonly used for tasks such as listening to FM radio, monitoring aircraft traffic +(ADS-B), receiving weather satellite images, and more. + +Supported Models +---------------- + +- **Generic RTL-SDR Dongle:** The most common variant, usually featuring an R820T or R820T2 tuner. +- **RTL-SDR Blog V3:** An enhanced version with additional features like direct sampling mode and a bias tee for + powering external devices. + +Key Features +------------ + +- **Frequency Range:** Typically from 24 MHz to 1.7 GHz, depending on the tuner chip. +- **Bandwidth:** Limited to about 2.4 MHz, making it suitable for narrowband applications. +- **Connectivity:** USB 2.0 interface, plug-and-play on most platforms. +- **Software Support:** Compatible with SDR software like SDR#, GQRX, and GNU Radio. + +Limitations +----------- + +- Narrow bandwidth compared to more expensive SDRs, which may limit some applications. +- Sensitivity and performance can vary depending on the specific model and components. +- Requires external software for signal processing and analysis. + +Further Information +------------------- + +- `Official Website `_ +- `RTL-SDR Quick Start Guide `_ diff --git a/docs/source/sdr_guides/usrp.rst b/docs/source/sdr_guides/usrp.rst new file mode 100644 index 0000000..b3f36a2 --- /dev/null +++ b/docs/source/sdr_guides/usrp.rst @@ -0,0 +1,80 @@ +.. _usrp: + +USRP +==== + +The USRP (Universal Software Radio Peripheral) product line is a series of software-defined radios (SDRs) +developed by Ettus Research. These devices are widely used in academia, industry, and research for various +wireless communication applications, ranging from simple experimentation to complex signal processing tasks. + +USRP devices offer a flexible platform that can be used with various software frameworks, including GNU Radio +and the USRP Hardware Driver (UHD). The product line includes both entry-level models for hobbyists and +advanced models for professional and research use. + +Supported models +---------------- + +- **USRP B200/B210:** Compact, single-board, full-duplex, with a wide frequency range. +- **USRP N200/N210:** High-performance models with increased bandwidth and connectivity options. +- **USRP X300/X310:** High-end models featuring large bandwidth, multiple MIMO channels, and support for GPSDO. +- **USRP E310/E320:** Embedded devices with onboard processing capabilities. +- **USRP B200mini:** Ultra-compact model for portable and embedded applications. + +Key features +------------ + +- **Frequency Range:** Typically covers from DC to 6 GHz, depending on the model and daughter boards used. +- **Bandwidth:** Varies by model, up to 160 MHz in some high-end versions. +- **Connectivity:** Includes USB 3.0, Ethernet, and PCIe interfaces depending on the model. +- **Software Support:** Compatible with UHD, GNU Radio, and other SDR frameworks. + +Hackability +----------- + +- The UHD library is fully open source and can be modified to meet user untention. +- Certain USRP models have "RFNoC" which streamlines the inclusion of custom FPGA processing in a USRP. + +Limitations +----------- + +- Some models may have limited bandwidth or processing capabilities. +- Compatibility with certain software tools may vary depending on the version of the UHD. +- Price range can be a consideration, especially for high-end models. + +Set up instructions (Linux) +--------------------------- + +1. Install the required system packages via APT: + +.. code-block:: bash + + sudo apt-get install libuhd-dev uhd-host python3-uhd + +2. Build and install UHD from source: + +.. code-block:: bash + + sudo apt-get install git cmake libboost-all-dev libusb-1.0-0-dev python3-docutils python3-mako python3-numpy python3-requests python3-ruamel.yaml python3-setuptools build-essential + cd ~ + git clone https://github.com/EttusResearch/uhd.git + cd uhd/host + mkdir build + cd build + cmake -DENABLE_TESTS=OFF -DENABLE_C_API=OFF -DENABLE_MANUAL=OFF .. + make -j8 + sudo make install + sudo ldconfig + + +3. Find your dist packages and add to `PYTHONPATH`. Example: + +.. code-block:: bash + + export PYTHONPATH='/usr/local/lib/python3.10/site-packages/' + export PYTHONPATH='/usr/local/lib/python3.10/dist-packages/:$PYTHONPATH' + +Further information +------------------- + +- `Official Website `_ +- `USRP Documentation `_ diff --git a/src/ria_toolkit_oss/sdr/__init__.py b/src/ria_toolkit_oss/sdr/__init__.py index 907b121..d89418e 100644 --- a/src/ria_toolkit_oss/sdr/__init__.py +++ b/src/ria_toolkit_oss/sdr/__init__.py @@ -1,10 +1,7 @@ """ -The SDR package provides a unified API for working with a variety of software-defined radios. +This package provides a unified API for working with a variety of software-defined radios. It streamlines tasks involving signal reception and transmission, as well as common administrative operations such as detecting and configuring available devices. - -To add support for a new radio, subclass the ``SDR`` interface and implement all abstract methods. If you experience difficulties, please -`contact us `_, we are happy to provide additional direction and/or help with the implementation details. """ __all__ = ["SDR"] diff --git a/src/ria_toolkit_oss/sdr/blade.py b/src/ria_toolkit_oss/sdr/blade.py index f7a3703..0e9b923 100644 --- a/src/ria_toolkit_oss/sdr/blade.py +++ b/src/ria_toolkit_oss/sdr/blade.py @@ -3,6 +3,7 @@ from typing import Optional import numpy as np from ria_toolkit_oss.datatypes import Recording +from ria_toolkit_oss.sdr import SDR from bladerf import _bladerf diff --git a/src/ria_toolkit_oss/sdr/sdr.py b/src/ria_toolkit_oss/sdr/sdr.py index a0fb392..7bfbfbf 100644 --- a/src/ria_toolkit_oss/sdr/sdr.py +++ b/src/ria_toolkit_oss/sdr/sdr.py @@ -12,7 +12,13 @@ from ria_toolkit_oss.datatypes.recording import Recording class SDR(ABC): """ - SDR object to interface with radio hardware. + This class defines a common interface (a template) for all SDR devices. + Each specific SDR implementation should subclass SDR and provide concrete implementations + for the abstract methods. + + To add support for a new radio, subclass this interface and implement all abstract methods. + If you experience difficulties, please `contact us `_, we are happy to + provide additional direction and/or help with the implementation details. """ def __init__(self):