Merge pull request 'Update SDR guides, Getting Started Guide and fix Sphinx warnings for release' (#29) from docs/sdr-guides-update into main

Reviewed-on: #29
Reviewed-by: muq <muq@noreply.localhost>

docs/source/conf.py

@@ -12,7 +12,7 @@ sys.path.insert(0, os.path.abspath(os.path.join('..', '..')))
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'ria-toolkit-oss'
-copyright = '2025, Qoherent Inc'
+copyright = '2026, Qoherent Inc'
 author = 'Qoherent Inc.'
 release = '0.1.5'
 

docs/source/examples/sdr/index.rst

@@ -1,4 +1,4 @@
-.. _examples:
+.. _sdr_examples:
 
 ############
 SDR Examples

docs/source/sdr_guides/blade.rst

@@ -1,77 +1,87 @@
-.. _blade:
+.. _blade:
-
+
-BladeRF
+BladeRF
-=======
+=======
-
+
-The BladeRF is a versatile software-defined radio (SDR) platform developed by Nuand. It is designed for a wide
+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
+range of applications, from wireless communication research to field deployments. BladeRF devices are known
-for their high performance, flexibility, and extensive open-source support, making them suitable for both
+for their high performance, flexibility, and extensive open-source support, making them suitable for both
-hobbyists and professionals. The BladeRF is based on the Analog Devices AD9361 RF transceiver, which provides
+hobbyists and professionals. The BladeRF is based on the Analog Devices AD9361 RF transceiver, which provides
-wide frequency coverage and high bandwidth.
+wide frequency coverage and high bandwidth.
-
+
-Supported Models
+Supported Models
-----------------
+----------------
-
+
-- **BladeRF 2.0 Micro xA4:** A compact model with a 49 kLE FPGA, ideal for portable applications.
+- **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 xA9:** A higher-end version of the Micro with a 115 kLE FPGA, offering more processing power in a small form factor.
-
+
-Key Features
+Key Features
-------------
+------------
-
+
-- **Frequency Range:** Typically from 47 MHz to 6 GHz, covering a wide range of wireless communication bands.
+- **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.
+- **Bandwidth:** Up to 56 MHz, allowing for wideband signal processing.
-- **FPGA:** Integrated FPGA (varies by model) for real-time processing and custom logic development.
+- **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.
+- **Connectivity:** USB 3.0 interface for high-speed data transfer, with options for GPIO, SPI, and other I/O.
-
+
-Hackability
+Hackability
------------
+-----------
-
+
-- **Expansion:** The BladeRF features GPIO, expansion headers, and add-on boards, allowing users to extend the
+- **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.
+  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
+- **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.
+  explore different frequency bands and optimize the bandwidth for their specific use cases.
-
+
-Limitations
+Limitations
------------
+-----------
-
+
-- The complexity of FPGA development may present a steep learning curve for users unfamiliar with hardware
+- The complexity of FPGA development may present a steep learning curve for users unfamiliar with hardware
-  description languages (HDL).
+  description languages (HDL).
-- Bandwidth is capped at 56 MHz, which might not be sufficient for ultra-wideband applications.
+- 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
+- USB 3.0 connectivity is required for optimal performance; using USB 2.0 will significantly limit data
-  transfer rates.
+  transfer rates.
-
+
-Set up instructions (Linux, Radioconda)
+Set up instructions (Linux)
----------------------------------------
+---------------------------
-
+
-1. Activate your Radioconda environment.
+No additional Python packages are required for BladeRF beyond the base RIA Toolkit OSS installation.
-
+
-  .. code-block:: bash
+1. Install the system library:
-
+
-     conda activate <your-env-name>
+  .. code-block:: bash
-
+
-2. Install the base dependencies and drivers (*Easy method*):
+    sudo apt install libbladerf-dev
-
+
-  .. code-block:: bash
+  For a more complete installation including CLI tools and FPGA images, use the Nuand PPA:
-
+
-    sudo add-apt-repository ppa:nuandllc/bladerf
+  .. code-block:: bash
-    sudo apt-get update
+
-    sudo apt-get install bladerf
+    sudo add-apt-repository ppa:nuandllc/bladerf
-    sudo apt-get install libbladerf-dev
+    sudo apt-get update
-    sudo apt-get install bladerf-fpga-hostedxa4  # Necessary for installation of bladeRF 2.0 Micro A4.
+    sudo apt-get install bladerf libbladerf-dev
-
+    sudo apt-get install bladerf-fpga-hostedxa4  # Necessary for BladeRF 2.0 Micro xA4
-3. Install a ``udev`` rule by creating a link into your Radioconda installation:
+
-
+2. Install udev rules:
-  .. code-block:: bash
+
-
+  For most users:
-     sudo ln -s $CONDA_PREFIX/lib/udev/rules.d/88-nuand-bladerf1.rules /etc/udev/rules.d/88-radioconda-nuand-bladerf1.rules
+
-     sudo ln -s $CONDA_PREFIX/lib/udev/rules.d/88-nuand-bladerf2.rules /etc/udev/rules.d/88-radioconda-nuand-bladerf2.rules
+  .. code-block:: bash
-     sudo ln -s $CONDA_PREFIX/lib/udev/rules.d/88-nuand-bootloader.rules /etc/udev/rules.d/88-radioconda-nuand-bootloader.rules
+
-     sudo udevadm control --reload
+    sudo udevadm control --reload
-     sudo udevadm trigger
+    sudo udevadm trigger
-
+
-Further Information
+  For **Radioconda** users, create symlinks from your conda environment instead:
--------------------
+
-
+  .. code-block:: bash
-- `Official BladeRF Website <https://www.nuand.com/>`_
+
-- `BladeRF GitHub Repository <https://github.com/Nuand/bladeRF>`_
+    sudo ln -s $CONDA_PREFIX/lib/udev/rules.d/88-nuand-bladerf1.rules /etc/udev/rules.d/88-radioconda-nuand-bladerf1.rules
-- `BladeRF Setup with Radioconda  <https://github.com/radioconda/radioconda-installer?tab=readme-ov-file#bladerf>`_
+    sudo ln -s $CONDA_PREFIX/lib/udev/rules.d/88-nuand-bladerf2.rules /etc/udev/rules.d/88-radioconda-nuand-bladerf2.rules
+    sudo ln -s $CONDA_PREFIX/lib/udev/rules.d/88-nuand-bootloader.rules /etc/udev/rules.d/88-radioconda-nuand-bootloader.rules
+    sudo udevadm control --reload
+    sudo udevadm trigger
+
+Further Information
+-------------------
+
+- `Official BladeRF Website <https://www.nuand.com/>`_
+- `BladeRF GitHub Repository <https://github.com/Nuand/bladeRF>`_
+- `BladeRF Setup with Radioconda  <https://github.com/radioconda/radioconda-installer?tab=readme-ov-file#bladerf>`_

docs/source/sdr_guides/hackrf.rst

@@ -1,83 +1,88 @@
-.. _hackrf:
+.. _hackrf:
-
+
-HackRF
+HackRF
-======
+======
-
+
-The HackRF One is a portable and affordable software-defined radio developed by Great Scott Gadgets. It is an
+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 
+open source hardware platform that is designed to enable test and development of modern and next generation
-radio technologies.
+radio technologies.
-
+
-The HackRF is based on the Analog Devices MAX2839 transceiver chip, which supports both transmission and 
+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 
+reception of signals across a wide frequency range, combined with a MAX5864 RF front-end chip and a
-RFFC5072 wideband synthesizer/VCO.
+RFFC5072 wideband synthesizer/VCO.
-
+
-Supported models
+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.
+- **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.
+- **Opera Cake for HackRF:** An antenna switching add-on board for HackRF One that is configured with command-line software.
-
+
-Key features
+Key features
-------------
+------------
-
+
-- **Frequency Range:** 1 MHz to 6 GHz.
+- **Frequency Range:** 1 MHz to 6 GHz.
-- **Bandwidth:** 2 MHz to 20 MHz.
+- **Bandwidth:** 2 MHz to 20 MHz.
-- **Connectivity:** USB 2.0 interface with support for power, data, and firmware updates.
+- **Connectivity:** USB 2.0 interface with support for power, data, and firmware updates.
-- **Software Support:** Compatible with GNU Radio, SDR#, and other SDR frameworks.
+- **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.
+- **Onboard Processing:** ARM-based LPC4320 processor for digital signal processing and interfacing over USB.
-
+
-Hackability
+Hackability
------------
+-----------
-
+
-.. todo::
+.. todo::
-
+
-   Add information regarding HackRF hackability
+   Add information regarding HackRF hackability
-
+
-Limitations
+Limitations
------------
+-----------
-    
+
-- Bandwidth is limited to 20 MHz.
+- Bandwidth is limited to 20 MHz.
-- USB 2.0 connectivity might limit data transfer rates compared to USB 3.0 or Ethernet-based SDRs.
+- USB 2.0 connectivity might limit data transfer rates compared to USB 3.0 or Ethernet-based SDRs.
-
+
-Set up instructions (Linux, Radioconda)
+Set up instructions (Linux)
----------------------------------------
+---------------------------
-
+
-1. Activate your Radioconda environment:
+HackRF is supported out of the box after installing RIA Toolkit OSS.
-
+
-  .. code-block:: bash
+1. Ensure ``libhackrf`` is installed at the system level. On most Ubuntu installations this is already
-
+   present. If not:
-     conda activate <your-env-name>
+
-
+  .. code-block:: bash
-2. Install the System Package (Ubuntu / Debian):
+
-
+    sudo apt install libhackrf-dev
-  .. code-block:: bash
+
-
+2. Install udev rules to allow non-root device access:
-     sudo apt-get update
+
-     sudo apt-get install hackrf
+  For most users:
-
+
-3. Install a ``udev`` rule by creating a link into your Radioconda installation:
+  .. code-block:: bash
-
+
-  .. code-block:: bash
+    sudo udevadm control --reload
-
+    sudo udevadm trigger
-     sudo ln -s $CONDA_PREFIX/lib/udev/rules.d/53-hackrf.rules /etc/udev/rules.d/53-radioconda-hackrf.rules
+
-     sudo udevadm control --reload
+  For **Radioconda** users, create a symlink from your conda environment instead:
-     sudo udevadm trigger
+
-
+  .. code-block:: bash
-  Make sure your user account belongs to the plugdev group in order to access your device:
+
-
+    sudo ln -s $CONDA_PREFIX/lib/udev/rules.d/53-hackrf.rules /etc/udev/rules.d/53-radioconda-hackrf.rules
-  .. code-block:: bash
+    sudo udevadm control --reload
-
+    sudo udevadm trigger
-     sudo usermod -a -G plugdev <user>
+
-
+  Make sure your user account belongs to the ``plugdev`` group in order to access your device:
-.. note::
+
-
+  .. code-block:: bash
-   You may have to restart your system for changes to take effect.
+
-
+    sudo usermod -a -G plugdev <user>
-Further information
+
--------------------
+.. note::
-
+
-- `Official HackRF Website <https://greatscottgadgets.com/hackrf/>`_
+   You may have to restart your system for group membership changes to take effect.
-- `HackRF Project Documentation <https://hackrf.readthedocs.io/en/latest/>`_
+
-- `HackRF Software Installation Guide <https://hackrf.readthedocs.io/en/latest/installing_hackrf_software.html>`_
+Further information
-- `HackRF GitHub Repository <https://github.com/greatscottgadgets/hackrf>`_
+-------------------
-- `HackRF Setup with Radioconda <https://github.com/radioconda/radioconda-installer?tab=readme-ov-file#hackrf>`_ 
+
+- `Official HackRF Website <https://greatscottgadgets.com/hackrf/>`_
+- `HackRF Project Documentation <https://hackrf.readthedocs.io/en/latest/>`_
+- `HackRF Software Installation Guide <https://hackrf.readthedocs.io/en/latest/installing_hackrf_software.html>`_
+- `HackRF GitHub Repository <https://github.com/greatscottgadgets/hackrf>`_
+- `HackRF Setup with Radioconda <https://github.com/radioconda/radioconda-installer?tab=readme-ov-file#hackrf>`_

docs/source/sdr_guides/pluto.rst

@@ -1,116 +1,123 @@
-.. _pluto:
+.. _pluto:
-
+
-PlutoSDR
+PlutoSDR
-========
+========
-
+
-The ADALM-PLUTO (PlutoSDR) is a portable and affordable software-defined radio developed by Analog Devices.
+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
+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.
+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
+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
+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.
+hands-on learning and rapid prototyping.
-
+
-Supported models
+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.
+- **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
+- **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.
+  to 6 GHz by applying firmware patches with unqualified RF performance.
-
+
-Key features
+Key features
-------------
+------------
-
+
-- **Frequency Range:** 325 MHz to 3.8 GHz (standard), expandable with modifications.
+- **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.
+- **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.
+- **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.
+- **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.
+- **Onboard Processing:** Integrated ARM Cortex-A9 processor for custom applications and signal processing.
-
+
-Hackability
+Hackability
-------------
+------------
-
+
-- **Frequency Range and Bandwidth:** The default frequency range of 325 MHz to 3.8 GHz can be expanded to
+- **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
+  approximately 70 MHz to 6 GHz, and the bandwidth can be increased from 20 MHz to 56 MHz by modifying
-  the device's firmware.
+  the device's firmware.
-- **2x2 MIMO:** On Rev C models, users can unlock 2x2 MIMO (Multiple Input Multiple Output) functionality by
+- **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.
+  wiring UFL to SMA connectors to the device's PCB, effectively turning the device into a dual-channel SDR.
-
+
-Limitations
+Limitations
------------
+-----------
-
+
-- Bandwidth is limited to 20 MHz by default, but can be increased to 56 MHz with modifications, which may
+- Bandwidth is limited to 20 MHz by default, but can be increased to 56 MHz with modifications, which may
-  affect stability.
+  affect stability.
-- USB 2.0 connectivity might limit data transfer rates compared to USB 3.0 or Ethernet-based SDRs.
+- USB 2.0 connectivity might limit data transfer rates compared to USB 3.0 or Ethernet-based SDRs.
-
+
-Set up instructions (Linux, Radioconda)
+Set up instructions (Linux)
----------------------------------------
+---------------------------
-
+
-1. Activate your Radioconda environment:
+The PlutoSDR is supported out of the box after installing RIA Toolkit OSS. The required Python package
-
+(``pyadi-iio``) is included in the toolkit's dependencies.
-  .. code-block:: bash
+
-
+1. Ensure ``libiio`` is installed at the system level. On most Ubuntu installations this is already present.
-    conda activate <your-env-name>
+   If not:
-
+
-2. Install system dependencies:
+  .. code-block:: bash
-
+
-  .. code-block:: bash
+    sudo apt install libiio-dev libiio-utils libiio0
-
+
-    sudo apt-get update
+.. note::
-    sudo apt-get install -y \
+
-          build-essential \
+   PlutoSDR devices are discoverable over both USB and network (mDNS). Network discovery uses Avahi — if
-          git \
+   ``avahi-daemon`` is not running, network discovery will be skipped but USB discovery still works.
-          libxml2-dev \
+
-          bison \
+2. Install a ``udev`` rule to allow non-root device access:
-          flex \
+
-          libcdk5-dev \
+  For most users:
-          cmake \
+
-          libusb-1.0-0-dev \
+  .. code-block:: bash
-          libavahi-client-dev \
+
-          libavahi-common-dev \
+    sudo udevadm control --reload
-          libaio-dev
+    sudo udevadm trigger
-
+
-3. Install a ``udev`` rule by creating a link into your Radioconda installation:
+  For **Radioconda** users, create a symlink from your conda environment instead:
-
+
-  .. code-block:: bash
+  .. code-block:: bash
-
+
-    sudo ln -s $CONDA_PREFIX/lib/udev/rules.d/90-libiio.rules /etc/udev/rules.d/90-radioconda-libiio.rules
+    sudo ln -s $CONDA_PREFIX/lib/udev/rules.d/90-libiio.rules /etc/udev/rules.d/90-radioconda-libiio.rules
-    sudo udevadm control --reload
+    sudo udevadm control --reload
-    sudo udevadm trigger
+    sudo udevadm trigger
-
+
-  Once you can talk to the hardware, you may want to perform the post-install steps detailed on the `PlutoSDR Documentation <https://wiki.analog.com/university/tools/pluto>`_.
+  Once you can communicate with the hardware, you may want to perform the post-install steps detailed on
-
+  the `PlutoSDR Documentation <https://wiki.analog.com/university/tools/pluto>`_.
-4. (Optional) Building ``libiio`` or ``libad9361-iio`` from source:
+
-
+3. (Optional) Building ``libiio`` or ``libad9361-iio`` from source:
-  This step is only required if you want the latest version of these libraries not provided in Radioconda.
+
-
+  This step is only required if you need a version not available via ``apt``. First install build
-  .. code-block:: bash
+  dependencies:
-
+
-    # Build libiio from source
+  .. code-block:: bash
-    cd ~
+
-    git clone --branch v0.23 https://github.com/analogdevicesinc/libiio.git
+    sudo apt-get install -y build-essential git libxml2-dev bison flex libcdk5-dev cmake \
-    cd libiio
+      libusb-1.0-0-dev libavahi-client-dev libavahi-common-dev libaio-dev
-    mkdir -p build
+
-    cd build
+  .. code-block:: bash
-    cmake -DPYTHON_BINDINGS=ON ..
+
-    make -j"$(nproc)"
+    # Build libiio from source
-    sudo make install
+    cd ~
-    sudo ldconfig
+    git clone --branch v0.23 https://github.com/analogdevicesinc/libiio.git
-
+    cd libiio
-  .. code-block:: bash
+    mkdir -p build
-
+    cd build
-    # Build libad9361-iio from source
+    cmake -DPYTHON_BINDINGS=ON ..
-    cd ~
+    make -j"$(nproc)"
-    git clone https://github.com/analogdevicesinc/libad9361-iio.git
+    sudo make install
-    cd libad9361-iio
+    sudo ldconfig
-    mkdir -p build
+
-    cd build
+  .. code-block:: bash
-    cmake ..
+
-    make -j"$(nproc)"
+    # Build libad9361-iio from source
-    sudo make install
+    cd ~
-
+    git clone https://github.com/analogdevicesinc/libad9361-iio.git
-Further information
+    cd libad9361-iio
--------------------
+    mkdir -p build
-
+    cd build
-- `PlutoSDR Documentation <https://wiki.analog.com/university/tools/pluto>`_
+    cmake ..
-- `PlutoSDR Setup with Radioconda <https://github.com/radioconda/radioconda-installer?tab=readme-ov-file#iio-pluto-sdr>`_ 
+    make -j"$(nproc)"
+    sudo make install
+
+Further information
+-------------------
+
+- `PlutoSDR Documentation <https://wiki.analog.com/university/tools/pluto>`_
+- `PlutoSDR Setup with Radioconda <https://github.com/radioconda/radioconda-installer?tab=readme-ov-file#iio-pluto-sdr>`_

docs/source/sdr_guides/rtlsdr.rst

@@ -30,71 +30,111 @@ Limitations
     - Sensitivity and performance can vary depending on the specific model and components.
     - Requires external software for signal processing and analysis.
 
-Set up instructions (Linux, Radioconda)
+Set up instructions (Linux)
----------------------------------------
+---------------------------
 
-1. Activate your Radioconda environment:
+1. If you previously had RTL-SDR drivers installed, purge them first:
-
-  .. code-block:: bash
-
-    conda activate <your-env-name>
-
-2. Purge drivers:
-
-If you already have other drivers installed, purge them from your system.
 
   .. code-block:: bash
 
     sudo apt purge ^librtlsdr
-    sudo rm -rvf /usr/lib/librtlsdr* 
+    sudo rm -rvf /usr/lib/librtlsdr*
-    sudo rm -rvf /usr/include/rtl-sdr* 
+    sudo rm -rvf /usr/include/rtl-sdr*
-    sudo rm -rvf /usr/local/lib/librtlsdr* 
+    sudo rm -rvf /usr/local/lib/librtlsdr*
-    sudo rm -rvf /usr/local/include/rtl-sdr* 
+    sudo rm -rvf /usr/local/include/rtl-sdr*
-    sudo rm -rvf /usr/local/include/rtl_* 
+    sudo rm -rvf /usr/local/include/rtl_*
     sudo rm -rvf /usr/local/bin/rtl_*
 
-3. Install RTL-SDR Blog drivers:
+2. Install build dependencies:
 
   .. code-block:: bash
 
-    sudo apt-get install libusb-1.0-0-dev git cmake pkg-config build-essential
+    sudo apt install libusb-1.0-0-dev git cmake pkg-config build-essential
-    git clone https://github.com/osmocom/rtl-sdr 
+
-    cd rtl-sdr
+3. Build ``librtlsdr`` from source:
-    mkdir build
+
-    cd build
+  The standard ``librtlsdr`` package available via ``apt`` is missing symbols required by the Python
-    cmake ../ -DINSTALL_UDEV_RULES=ON
+  bindings. Build from the **rtl-sdr-blog fork**:
+
+  .. code-block:: bash
+
+    git clone https://github.com/rtlsdrblog/rtl-sdr-blog.git
+    cd rtl-sdr-blog
+    mkdir build && cd build
+    cmake .. -DINSTALL_UDEV_RULES=ON
     make
     sudo make install
     sudo cp ../rtl-sdr.rules /etc/udev/rules.d/
     sudo ldconfig
 
-4. Blacklist the DVB-T modules that would otherwise claim the device:
+  .. important::
+
+     Do not use the osmocom ``rtl-sdr`` repository or the Ubuntu ``librtlsdr-dev`` apt package. Neither
+     provides the ``rtlsdr_set_dithering`` symbol that the Python bindings require.
+
+4. Blacklist the kernel DVB driver:
+
+  The kernel DVB-T driver (``dvb_usb_rtl28xxu``) claims the RTL-SDR device and prevents ``librtlsdr``
+  from accessing it.
+
+  For most users:
 
   .. code-block:: bash
+
+    echo 'blacklist dvb_usb_rtl28xxu' | sudo tee /etc/modprobe.d/blacklist-rtlsdr.conf
+    sudo modprobe -r dvb_usb_rtl28xxu
+
+  For **Radioconda** users, a blacklist configuration is already provided in your conda environment:
+
+  .. code-block:: bash
+
     sudo ln -s $CONDA_PREFIX/etc/modprobe.d/rtl-sdr-blacklist.conf /etc/modprobe.d/radioconda-rtl-sdr-blacklist.conf
     sudo modprobe -r $(cat $CONDA_PREFIX/etc/modprobe.d/rtl-sdr-blacklist.conf | sed -n -e 's/^blacklist //p')
 
-.. note::
+  If ``modprobe -r`` fails with "Module is in use", unplug the RTL-SDR dongle, run the command again,
+  then plug it back in. Alternatively, reboot — the blacklist takes effect on next boot.
 
-   In addition to the Radioconda blacklist file, some systems also require
+  .. note::
-   manually blacklisting the following DVB-T modules to prevent them from
-   claiming the device:
 
-     - ``dvb_usb_rtl28xxu``
+     Some systems also require blacklisting additional DVB-T modules. Add these entries to your
-     - ``rtl2832``
+     blacklist configuration if needed:
-     - ``rtl2830``
 
-   Add these entries to ``rtlsdr.conf`` (or create the file at
+       - ``rtl2832``
-   ``/etc/modprobe.d/rtlsdr.conf``) if they are not already present.
+       - ``rtl2830``
 
-5. Install a udev rule by creating a link into your radioconda installation:
+5. Reload udev rules:
+
+  For most users (rules are installed by the build step above):
 
   .. code-block:: bash
+
+    sudo udevadm control --reload
+    sudo udevadm trigger
+
+  For **Radioconda** users, create a symlink from your conda environment instead:
+
+  .. code-block:: bash
+
     sudo ln -s $CONDA_PREFIX/lib/udev/rules.d/rtl-sdr.rules /etc/udev/rules.d/radioconda-rtl-sdr.rules
     sudo udevadm control --reload
     sudo udevadm trigger
 
+6. Install Python packages:
+
+  .. code-block:: bash
+
+    pip install pyrtlsdr==0.3.0
+    pip install setuptools==69.5.1
+
+  .. note::
+
+     ``pyrtlsdr`` 0.4.0 references a ``rtlsdr_set_dithering`` symbol not present in standard
+     ``librtlsdr`` builds. Version 0.3.0 works correctly.
+
+     ``pyrtlsdr`` 0.3.0 depends on ``pkg_resources``, which was removed in ``setuptools`` >= 82.
+     Pinning to 69.5.1 ensures ``pkg_resources`` is available.
+
 Further Information
 -------------------
     - `RTL-SDR Official Website <https://www.rtl-sdr.com/>`_
-    - `RTL-SDR Documentation <https://www.rtl-sdr.com/rtl-sdr-quick-start-guide/>`_
+    - `RTL-SDR Documentation <https://www.rtl-sdr.com/rtl-sdr-quick-start-guide/>`_

docs/source/sdr_guides/thinkrf.rst

@@ -39,18 +39,48 @@ Limitations
 Set up instructions (Linux)
 ---------------------------------
 
-Install PyRF
+ThinkRF devices require the ``pyrf`` package, which is written in Python 2 syntax and must be patched
+after installation to work with Python 3.
+
+.. note::
+
+   ``lib2to3`` was fully removed in Python 3.13. ThinkRF support is currently limited to
+   **Python 3.12 and below**.
+
+1. Install ``lib2to3``:
+
+  On some distributions (including Ubuntu 24.04+), ``lib2to3`` is not included by default:
 
   .. code-block:: bash
 
-    pip install 'pyrf>=2.8.0'
+    sudo apt install python3-lib2to3
 
-Convert PyRF scripts to Python 3
+2. Install ``pyrf``:
 
   .. code-block:: bash
 
-    cd ../scripts
+    pip install pyrf
-    ./convert_pyrf_to_python3.sh
+
+3. Patch ``pyrf`` for Python 3:
+
+  The ``pyrf`` package contains Python 2 syntax throughout (e.g., ``dict.iteritems()``, ``print``
+  statements). Run the following to automatically convert the entire package to Python 3:
+
+  .. code-block:: bash
+
+    python -c "
+    from lib2to3.refactor import RefactoringTool, get_fixers_from_package
+    import pyrf, os
+    pyrf_path = os.path.dirname(pyrf.__file__)
+    fixers = get_fixers_from_package('lib2to3.fixes')
+    tool = RefactoringTool(fixers)
+    tool.refactor_dir(pyrf_path, write=True)
+    print('Done')
+    "
+
+  .. note::
+
+     This patches the entire ``pyrf`` package in place, which is required for the driver to fully load.
 
 Further Information
 -------------------

docs/source/sdr_guides/usrp.rst

@@ -1,92 +1,155 @@
-.. _usrp:
+.. _usrp:
-
+
-USRP
+USRP
-====
+====
-
+
-The USRP (Universal Software Radio Peripheral) product line is a series of software-defined radios (SDRs)
+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
+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.
+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
+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
+and the USRP Hardware Driver (UHD). The product line includes both entry-level models for hobbyists and
-advanced models for professional and research use.
+advanced models for professional and research use.
-
+
-Supported models
+Supported models
-----------------
+----------------
-
+
-- **USRP B200/B210:** Compact, single-board, full-duplex, with a wide frequency range.
+- **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 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 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 E310/E320:** Embedded devices with onboard processing capabilities.
-- **USRP B200mini:** Ultra-compact model for portable and embedded applications.
+- **USRP B200mini:** Ultra-compact model for portable and embedded applications.
-
+
-Key features
+Key features
-------------
+------------
-
+
-- **Frequency Range:** Typically covers from DC to 6 GHz, depending on the model and daughter boards used.
+- **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.
+- **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.
+- **Connectivity:** Includes USB 3.0, Ethernet, and PCIe interfaces depending on the model.
-- **Software Support:** Compatible with UHD, GNU Radio, and other SDR frameworks.
+- **Software Support:** Compatible with UHD, GNU Radio, and other SDR frameworks.
-
+
-Hackability
+Hackability
------------
+-----------
-
+
-- The UHD library is fully open source and can be modified to meet user untention.
+- 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.
+- Certain USRP models have "RFNoC" which streamlines the inclusion of custom FPGA processing in a USRP.
-
+
-Limitations
+Limitations
------------
+-----------
-
+
-- Some models may have limited bandwidth or processing capabilities.
+- Some models may have limited bandwidth or processing capabilities.
-- Compatibility with certain software tools may vary depending on the version of the UHD.
+- 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.
+- Price range can be a consideration, especially for high-end models.
-
+
-Set up instructions (Linux, Radioconda)
+Set up instructions (Linux)
----------------------------------------
+---------------------------
-
+
-1. Activate your Radioconda environment:
+USRP devices require the UHD (USRP Hardware Driver) library with Python bindings. There is no pip-installable
-
+UHD package — it must either be installed via conda or built from source.
-  .. code-block:: bash
+
-
+**Option A: Install via conda (recommended for conda environments)**
-     conda activate <your-env-name>
+
-
+  .. code-block:: bash
-2. Install UHD and Python bindings:
+
-
+    conda install conda-forge::uhd
-  .. code-block:: bash
+
-
+**Option B: Build from source (required for pip/venv environments)**
-     conda install conda-forge::uhd    
+
-
+  The Python bindings must target the same Python version used in your virtual environment.
-3. Download UHD images:
+
-
+  1. Install build dependencies:
-  .. code-block:: bash
+
-
+    .. code-block:: bash
-    uhd_images_downloader
+
-
+      sudo apt install cmake build-essential libboost-all-dev libusb-1.0-0-dev \
-4. Verify access to your device:
+        python3-dev python3-numpy libncurses-dev
-
+
-   .. code-block:: bash
+  2. Install the Mako template library into your virtual environment (used by UHD's build system):
-
+
-      uhd_find_devices
+    .. code-block:: bash
-
+
-   For USB devices only (e.g. B series), install a ``udev`` rule by creating a link into your Radioconda installation.
+      pip install mako
-
+
-   .. code-block:: bash
+  3. Clone and build UHD with your virtual environment activated:
-
+
-      sudo ln -s $CONDA_PREFIX/lib/uhd/utils/uhd-usrp.rules /etc/udev/rules.d/radioconda-uhd-usrp.rules
+    .. code-block:: bash
-      sudo udevadm control --reload
+
-      sudo udevadm trigger
+      git clone https://github.com/EttusResearch/uhd.git
-
+      cd uhd
-5. (Optional) Update firmware/FPGA images:
+      git checkout v4.7.0.0
-
+      cd host
-   .. code-block:: bash
+      mkdir build && cd build
-
+      cmake -DENABLE_PYTHON_API=ON -DPYTHON_EXECUTABLE=$(which python3) ..
-      uhd_usrp_probe
+      make -j$(nproc)
-
+      sudo make install
-   This will ensure your device is running the latest firmware and FPGA versions.
+      sudo ldconfig
-
+
-Further information
+    .. important::
--------------------
+
-
+       Run the ``cmake`` command with your virtual environment activated so ``$(which python3)`` points
-- `Official USRP Website <https://www.ettus.com/>`_
+       to the correct interpreter. Before running ``make``, verify the cmake output includes::
-- `USRP Documentation <https://kb.ettus.com/USRP_Hardware_Driver_and_Interfaces>`_
+
-- `USRP Setup with Radioconda <https://github.com/radioconda/radioconda-installer?tab=readme-ov-file#uhd-ettus-usrp>`_
+         --   * LibUHD - Python API          → must say "Enabling"
+         -- Python interpreter: .../your-venv/bin/python3
+
+       If "LibUHD - Python API" is not listed under enabled components, the Python bindings will not be
+       built. The build typically takes 10–30 minutes.
+
+  4. Copy the Python bindings into your virtual environment if ``import uhd`` fails after installation:
+
+    .. code-block:: bash
+
+      cp -r ~/uhd/host/build/python/uhd ~/.venv/lib/python3.XX/site-packages/
+
+    Replace ``python3.XX`` with your Python version (e.g., ``python3.12``).
+
+    .. note::
+
+       If you have a pre-existing UHD installation built against a different Python version, you will see
+       a circular import error. The bindings must match the Python version in your virtual environment exactly.
+
+**After either installation method:**
+
+1. Download UHD FPGA/firmware images:
+
+  .. code-block:: bash
+
+    uhd_images_downloader
+
+2. Verify device access:
+
+  .. code-block:: bash
+
+    uhd_find_devices
+
+  For USB devices (e.g. B-series), install a ``udev`` rule.
+
+  For most users:
+
+  .. code-block:: bash
+
+    sudo udevadm control --reload
+    sudo udevadm trigger
+
+  For **Radioconda** users, create a symlink from your conda environment instead:
+
+  .. code-block:: bash
+
+    sudo ln -s $CONDA_PREFIX/lib/uhd/utils/uhd-usrp.rules /etc/udev/rules.d/radioconda-uhd-usrp.rules
+    sudo udevadm control --reload
+    sudo udevadm trigger
+
+3. (Optional) Update firmware/FPGA images:
+
+  .. code-block:: bash
+
+    uhd_usrp_probe
+
+  This will ensure your device is running the latest firmware and FPGA versions.
+
+Further information
+-------------------
+
+- `Official USRP Website <https://www.ettus.com/>`_
+- `USRP Documentation <https://kb.ettus.com/USRP_Hardware_Driver_and_Interfaces>`_
+- `USRP Setup with Radioconda <https://github.com/radioconda/radioconda-installer?tab=readme-ov-file#uhd-ettus-usrp>`_

src/ria_toolkit_oss/sdr/hackrf.py

@@ -58,7 +58,7 @@ class HackRF(SDR):
         :param channel: The channel the HackRF is set to. (Not actually used)
         :type channel: int
         :param gain_mode: 'absolute' passes gain directly to the sdr,
-        'relative' means that gain should be a negative value, and it will be subtracted from the max gain (40).
+            'relative' means that gain should be a negative value, and it will be subtracted from the max gain (40).
         :type gain_mode: str
         """
         print("Initializing RX")

src/ria_toolkit_oss/sdr/usrp.py

@@ -54,7 +54,7 @@ class USRP(SDR):
         :param channel: The channel the USRP is set to.
         :type channel: int
         :param gain_mode: 'absolute' passes gain directly to the sdr,
-        'relative' means that gain should be a negative value, and it will be subtracted from the max gain.
+            'relative' means that gain should be a negative value, and it will be subtracted from the max gain.
         :type gain_mode: str
         :param rx_buffer_size: Internal buffer size for receiving samples. Defaults to 960000.
         :type rx_buffer_size: int
@@ -285,7 +285,7 @@ class USRP(SDR):
         :param channel: The channel the USRP is set to.
         :type channel: int
         :param gain_mode: 'absolute' passes gain directly to the sdr,
-        'relative' means that gain should be a negative value, and it will be subtracted from the max gain.
+            'relative' means that gain should be a negative value, and it will be subtracted from the max gain.
         :type gain_mode: str
         """