From a68a325cb4867dad147c9b5113cd3eca6f7f1d94 Mon Sep 17 00:00:00 2001 From: muq Date: Tue, 21 Apr 2026 12:29:18 -0400 Subject: [PATCH] Update SDR guides and fix Sphinx warnings for release Fix Sphinx build errors: - Add missing blank lines in rtlsdr.rst code-block directives - Rename duplicate label in examples/sdr/index.rst - Fix field list indentation in usrp.py and hackrf.py docstrings Update SDR setup guides (all guides now cover both pip/venv and Radioconda): - rtlsdr: switch to rtl-sdr-blog fork (required for rtlsdr_set_dithering symbol), add pyrtlsdr==0.3.0 and setuptools==69.5.1 version pinning, preserve Radioconda blacklist and udev symlink paths alongside new steps - pluto: simplify primary path to apt install libiio, add Avahi network discovery note, preserve Radioconda udev symlink as alternative - hackrf: note out-of-box support, preserve Radioconda udev symlink - blade: note no extra Python packages needed, preserve Radioconda udev symlinks - usrp: add build-from-source path for pip/venv users with cmake flags, Python binding copy step, and version mismatch warning; keep conda install as primary option; preserve Radioconda udev symlink - thinkrf: add lib2to3 install step, Python <=3.12 restriction, and full Python 3 patching command to replace internal script reference Update copyright year to 2026 in conf.py --- docs/source/conf.py | 2 +- docs/source/examples/sdr/index.rst | 2 +- docs/source/sdr_guides/blade.rst | 164 ++++++++++--------- docs/source/sdr_guides/hackrf.rst | 171 ++++++++++---------- docs/source/sdr_guides/pluto.rst | 239 ++++++++++++++-------------- docs/source/sdr_guides/rtlsdr.rst | 110 +++++++++---- docs/source/sdr_guides/thinkrf.rst | 40 ++++- docs/source/sdr_guides/usrp.rst | 247 ++++++++++++++++++----------- src/ria_toolkit_oss/sdr/hackrf.py | 2 +- src/ria_toolkit_oss/sdr/usrp.py | 4 +- 10 files changed, 568 insertions(+), 413 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 1a3b6d0..f1f67e3 100644 --- a/docs/source/conf.py +++ b/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' diff --git a/docs/source/examples/sdr/index.rst b/docs/source/examples/sdr/index.rst index c563bee..c8cfda4 100644 --- a/docs/source/examples/sdr/index.rst +++ b/docs/source/examples/sdr/index.rst @@ -1,4 +1,4 @@ -.. _examples: +.. _sdr_examples: ############ SDR Examples diff --git a/docs/source/sdr_guides/blade.rst b/docs/source/sdr_guides/blade.rst index 41641b6..5a31456 100644 --- a/docs/source/sdr_guides/blade.rst +++ b/docs/source/sdr_guides/blade.rst @@ -1,77 +1,87 @@ -.. _blade: - -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 -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 -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. - -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. - -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. - -Set up instructions (Linux, Radioconda) ---------------------------------------- - -1. Activate your Radioconda environment. - - .. code-block:: bash - - conda activate - -2. Install the base dependencies and drivers (*Easy method*): - - .. code-block:: bash - - sudo add-apt-repository ppa:nuandllc/bladerf - sudo apt-get update - sudo apt-get install bladerf - sudo apt-get install libbladerf-dev - sudo apt-get install bladerf-fpga-hostedxa4 # Necessary for installation of bladeRF 2.0 Micro A4. - -3. Install a ``udev`` rule by creating a link into your Radioconda installation: - - .. code-block:: bash - - 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 - 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 `_ -- `BladeRF GitHub Repository `_ -- `BladeRF Setup with Radioconda `_ +.. _blade: + +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 +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 +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. + +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. + +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. + +Set up instructions (Linux) +--------------------------- + +No additional Python packages are required for BladeRF beyond the base RIA Toolkit OSS installation. + +1. Install the system library: + + .. code-block:: bash + + sudo apt install libbladerf-dev + + For a more complete installation including CLI tools and FPGA images, use the Nuand PPA: + + .. code-block:: bash + + sudo add-apt-repository ppa:nuandllc/bladerf + sudo apt-get update + sudo apt-get install bladerf libbladerf-dev + sudo apt-get install bladerf-fpga-hostedxa4 # Necessary for BladeRF 2.0 Micro xA4 + +2. Install udev rules: + + For most users: + + .. code-block:: bash + + sudo udevadm control --reload + sudo udevadm trigger + + For **Radioconda** users, create symlinks from your conda environment instead: + + .. code-block:: bash + + 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 + 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 `_ +- `BladeRF GitHub Repository `_ +- `BladeRF Setup with Radioconda `_ diff --git a/docs/source/sdr_guides/hackrf.rst b/docs/source/sdr_guides/hackrf.rst index 6f65a6d..934d6bf 100644 --- a/docs/source/sdr_guides/hackrf.rst +++ b/docs/source/sdr_guides/hackrf.rst @@ -1,83 +1,88 @@ -.. _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, Radioconda) ---------------------------------------- - -1. Activate your Radioconda environment: - - .. code-block:: bash - - conda activate - -2. Install the System Package (Ubuntu / Debian): - - .. code-block:: bash - - sudo apt-get update - sudo apt-get install hackrf - -3. Install a ``udev`` rule by creating a link into your Radioconda installation: - - .. code-block:: bash - - sudo ln -s $CONDA_PREFIX/lib/udev/rules.d/53-hackrf.rules /etc/udev/rules.d/53-radioconda-hackrf.rules - sudo udevadm control --reload - sudo udevadm trigger - - Make sure your user account belongs to the plugdev group in order to access your device: - - .. code-block:: bash - - sudo usermod -a -G plugdev - -.. note:: - - You may have to restart your system for changes to take effect. - -Further information -------------------- - -- `Official HackRF Website `_ -- `HackRF Project Documentation `_ -- `HackRF Software Installation Guide `_ -- `HackRF GitHub Repository `_ -- `HackRF Setup with Radioconda `_ +.. _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 is supported out of the box after installing RIA Toolkit OSS. + +1. Ensure ``libhackrf`` is installed at the system level. On most Ubuntu installations this is already + present. If not: + + .. code-block:: bash + + sudo apt install libhackrf-dev + +2. Install udev rules to allow non-root device access: + + 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/udev/rules.d/53-hackrf.rules /etc/udev/rules.d/53-radioconda-hackrf.rules + sudo udevadm control --reload + sudo udevadm trigger + + Make sure your user account belongs to the ``plugdev`` group in order to access your device: + + .. code-block:: bash + + sudo usermod -a -G plugdev + +.. note:: + + You may have to restart your system for group membership changes to take effect. + +Further information +------------------- + +- `Official HackRF Website `_ +- `HackRF Project Documentation `_ +- `HackRF Software Installation Guide `_ +- `HackRF GitHub Repository `_ +- `HackRF Setup with Radioconda `_ diff --git a/docs/source/sdr_guides/pluto.rst b/docs/source/sdr_guides/pluto.rst index 2eaa475..30aa348 100644 --- a/docs/source/sdr_guides/pluto.rst +++ b/docs/source/sdr_guides/pluto.rst @@ -1,116 +1,123 @@ -.. _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, Radioconda) ---------------------------------------- - -1. Activate your Radioconda environment: - - .. code-block:: bash - - conda activate - -2. Install system dependencies: - - .. code-block:: bash - - sudo apt-get update - sudo apt-get install -y \ - build-essential \ - git \ - libxml2-dev \ - bison \ - flex \ - libcdk5-dev \ - cmake \ - libusb-1.0-0-dev \ - libavahi-client-dev \ - libavahi-common-dev \ - libaio-dev - -3. Install a ``udev`` rule by creating a link into your Radioconda installation: - - .. code-block:: bash - - 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 trigger - - Once you can talk to the hardware, you may want to perform the post-install steps detailed on the `PlutoSDR Documentation `_. - -4. (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. - - .. code-block:: bash - - # Build libiio from source - 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 - - .. code-block:: bash - - # Build libad9361-iio from source - 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 - -Further information -------------------- - -- `PlutoSDR Documentation `_ -- `PlutoSDR Setup with Radioconda `_ \ No newline at end of file +.. _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 is supported out of the box after installing RIA Toolkit OSS. The required Python package +(``pyadi-iio``) is included in the toolkit's dependencies. + +1. Ensure ``libiio`` is installed at the system level. On most Ubuntu installations this is already present. + If not: + + .. code-block:: bash + + sudo apt install libiio-dev libiio-utils libiio0 + +.. note:: + + PlutoSDR devices are discoverable over both USB and network (mDNS). Network discovery uses Avahi — if + ``avahi-daemon`` is not running, network discovery will be skipped but USB discovery still works. + +2. Install a ``udev`` rule to allow non-root device access: + + 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/udev/rules.d/90-libiio.rules /etc/udev/rules.d/90-radioconda-libiio.rules + sudo udevadm control --reload + sudo udevadm trigger + + Once you can communicate with the hardware, you may want to perform the post-install steps detailed on + the `PlutoSDR Documentation `_. + +3. (Optional) Building ``libiio`` or ``libad9361-iio`` from source: + + This step is only required if you need a version not available via ``apt``. First install build + dependencies: + + .. code-block:: bash + + sudo apt-get install -y build-essential git libxml2-dev bison flex libcdk5-dev cmake \ + libusb-1.0-0-dev libavahi-client-dev libavahi-common-dev libaio-dev + + .. code-block:: bash + + # Build libiio from source + 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 + + .. code-block:: bash + + # Build libad9361-iio from source + 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 + +Further information +------------------- + +- `PlutoSDR Documentation `_ +- `PlutoSDR Setup with Radioconda `_ diff --git a/docs/source/sdr_guides/rtlsdr.rst b/docs/source/sdr_guides/rtlsdr.rst index d93212e..23d69eb 100644 --- a/docs/source/sdr_guides/rtlsdr.rst +++ b/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: - - .. code-block:: bash - - conda activate - -2. Purge drivers: - -If you already have other drivers installed, purge them from your system. +1. If you previously had RTL-SDR drivers installed, purge them first: .. code-block:: bash sudo apt purge ^librtlsdr - sudo rm -rvf /usr/lib/librtlsdr* - sudo rm -rvf /usr/include/rtl-sdr* - sudo rm -rvf /usr/local/lib/librtlsdr* - sudo rm -rvf /usr/local/include/rtl-sdr* - sudo rm -rvf /usr/local/include/rtl_* + sudo rm -rvf /usr/lib/librtlsdr* + sudo rm -rvf /usr/include/rtl-sdr* + sudo rm -rvf /usr/local/lib/librtlsdr* + sudo rm -rvf /usr/local/include/rtl-sdr* + 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 - git clone https://github.com/osmocom/rtl-sdr - cd rtl-sdr - mkdir build - cd build - cmake ../ -DINSTALL_UDEV_RULES=ON + sudo apt install libusb-1.0-0-dev git cmake pkg-config build-essential + +3. Build ``librtlsdr`` from source: + + The standard ``librtlsdr`` package available via ``apt`` is missing symbols required by the Python + 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 - manually blacklisting the following DVB-T modules to prevent them from - claiming the device: + .. note:: - - ``dvb_usb_rtl28xxu`` - - ``rtl2832`` - - ``rtl2830`` + Some systems also require blacklisting additional DVB-T modules. Add these entries to your + blacklist configuration if needed: - Add these entries to ``rtlsdr.conf`` (or create the file at - ``/etc/modprobe.d/rtlsdr.conf``) if they are not already present. + - ``rtl2832`` + - ``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 `_ - - `RTL-SDR Documentation `_ \ No newline at end of file + - `RTL-SDR Documentation `_ diff --git a/docs/source/sdr_guides/thinkrf.rst b/docs/source/sdr_guides/thinkrf.rst index 83e5779..962793c 100644 --- a/docs/source/sdr_guides/thinkrf.rst +++ b/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 - ./convert_pyrf_to_python3.sh + pip install pyrf + +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 ------------------- diff --git a/docs/source/sdr_guides/usrp.rst b/docs/source/sdr_guides/usrp.rst index e4aa614..aad4fd7 100644 --- a/docs/source/sdr_guides/usrp.rst +++ b/docs/source/sdr_guides/usrp.rst @@ -1,92 +1,155 @@ -.. _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, Radioconda) ---------------------------------------- - -1. Activate your Radioconda environment: - - .. code-block:: bash - - conda activate - -2. Install UHD and Python bindings: - - .. code-block:: bash - - conda install conda-forge::uhd - -3. Download UHD images: - - .. code-block:: bash - - uhd_images_downloader - -4. Verify access to your device: - - .. code-block:: bash - - uhd_find_devices - - For USB devices only (e.g. B series), install a ``udev`` rule by creating a link into your Radioconda installation. - - .. 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 - -5. (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 `_ -- `USRP Documentation `_ -- `USRP Setup with Radioconda `_ +.. _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) +--------------------------- + +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. + +**Option A: Install via conda (recommended for conda environments)** + + .. code-block:: bash + + conda install conda-forge::uhd + +**Option B: Build from source (required for pip/venv environments)** + + The Python bindings must target the same Python version used in your virtual environment. + + 1. Install build dependencies: + + .. code-block:: bash + + sudo apt install cmake build-essential libboost-all-dev libusb-1.0-0-dev \ + python3-dev python3-numpy libncurses-dev + + 2. Install the Mako template library into your virtual environment (used by UHD's build system): + + .. code-block:: bash + + pip install mako + + 3. Clone and build UHD with your virtual environment activated: + + .. code-block:: bash + + git clone https://github.com/EttusResearch/uhd.git + cd uhd + git checkout v4.7.0.0 + cd host + mkdir build && cd build + cmake -DENABLE_PYTHON_API=ON -DPYTHON_EXECUTABLE=$(which python3) .. + make -j$(nproc) + sudo make install + sudo ldconfig + + .. important:: + + Run the ``cmake`` command with your virtual environment activated so ``$(which python3)`` points + to the correct interpreter. Before running ``make``, verify the cmake output includes:: + + -- * 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 `_ +- `USRP Documentation `_ +- `USRP Setup with Radioconda `_ diff --git a/src/ria_toolkit_oss/sdr/hackrf.py b/src/ria_toolkit_oss/sdr/hackrf.py index 79e00a7..d602322 100644 --- a/src/ria_toolkit_oss/sdr/hackrf.py +++ b/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") diff --git a/src/ria_toolkit_oss/sdr/usrp.py b/src/ria_toolkit_oss/sdr/usrp.py index 70bbc46..e6c4a9f 100644 --- a/src/ria_toolkit_oss/sdr/usrp.py +++ b/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 """ -- 2.34.1