Merge pull request #1801 from greatscottgadgets/antoinevg/fpga-control-timeout

libhackrf: Set a 500ms timeout for changing fpga bitstream

.github/ISSUE_TEMPLATE/technical-support.yml

@@ -1,22 +1,11 @@
 name: Technical Support Request
 description: File a technical support request
 labels: ["technical support"]
-assignees:
-  - straithe
 body:
   - type: markdown
     attributes:
       value: |
         Thank you for taking the time to fill out this technical support request form! Please note that technical support requests can expect a response time of two weeks.  
-  - type: dropdown
-    id: troubleshooting-documentation
-    attributes: 
-      label: Have you read the HackRF [troubleshooting documentation](https://hackrf.readthedocs.io/en/latest/troubleshooting.html)?
-      options:
-        - "no"
-        - "yes"        
-    validations:
-      required: true
   - type: textarea
     id: expected-outcome
     attributes:

.github/workflows/build.yml

@@ -9,150 +9,286 @@ on:
     - cron: 1 12 * * 1
 
 env:
-  WIN_LIBUSB_INC: -DLIBUSB_INCLUDE_DIR=C:/vcpkg/installed/x64-windows/include/libusb-1.0
-  WIN_LIBUSB_LIB: -DLIBUSB_LIBRARIES=C:/vcpkg/installed/x64-windows/lib/libusb-1.0.lib
-  WIN_FFTW_INC: -DFFTW_INCLUDES=C:/vcpkg/installed/x64-windows/include
-  WIN_FFTW_LIB: -DFFTW_LIBRARIES=C:/vcpkg/installed/x64-windows/lib/fftw3f.lib
-  WIN_PTHREAD_INC: -DTHREADS_PTHREADS_INCLUDE_DIR=C:/vcpkg/installed/x64-windows/include
-  WIN_PTHREAD_LIB: -DTHREADS_PTHREADS_WIN32_LIBRARY=C:/vcpkg/installed/x64-windows/lib/pthreadvc3.lib
+
+  # Override OSX architecture detection. Required for CMake versions < 3.19.2.
+  CMAKE_OSX_ARCHITECTURES: arm64
 
 jobs:
   host:
     strategy:
       matrix:
-        os: ['macos-latest', 'ubuntu-latest', 'windows-latest']
+        os: ['macos', 'ubuntu', 'windows']
+        cmake: ['3.10.0', '3.21.7', '4.2.6', 'latest']
+        compiler: ['gcc', 'msvc']
+        exclude:
+          # MSVC only runs on Windows.
+          - os: 'macos'
+            compiler: 'msvc'
+          - os: 'ubuntu'
+            compiler: 'msvc'
+          # We can't use the oldest CMake versions on Windows.
+          - os: 'windows'
+            cmake: '3.10.0'
+          # The in-between CMake versions aren't so intersting with GCC.
+          - compiler: 'gcc'
+            cmake: '3.21.7'
+          - compiler: 'gcc'
+            cmake: '4.2.6'
+        include:
+          # Shell selection
+          - os: 'macos'
+            shell: 'bash'
+          - os: 'ubuntu'
+            shell: 'bash'
+          - os: 'windows'
+            compiler: 'msvc'
+            shell: 'pwsh'
+          - os: 'windows'
+            compiler: 'gcc'
+            shell: 'msys2'
+          # MSVC version selection
+          - cmake: '3.21.7'
+            msvc: '17.14'
+          - cmake: '4.2.6'
+            msvc: 'latest'
+          - cmake: 'latest'
+            msvc: 'latest'
+          # CMake generator selection
+          - os: 'macos'
+            generator: 'Unix Makefiles'
+          - os: 'ubuntu'
+            generator: 'Unix Makefiles'
+          - compiler: 'msvc'
+            cmake: '3.21.7'
+            generator: 'Visual Studio 17 2022'
+          - compiler: 'msvc'
+            cmake: '4.2.6'
+            generator: 'Visual Studio 18 2026'
+          - compiler: 'msvc'
+            cmake: 'latest'
+            generator: 'Visual Studio 18 2026'
+          - os: 'windows'
+            compiler: 'gcc'
+            generator: 'MSYS Makefiles'
+          # Additional CMake arguments
+          - os: 'windows'
+            compiler: 'msvc'
+            cmake_args: >-
+              -DPKG_CONFIG_EXECUTABLE=C:/vcpkg/installed/x64-windows/tools/pkgconf/pkgconf.exe
+              -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake
+              --install-prefix=$env:GITHUB_WORKSPACE/install
+          - os: 'windows'
+            compiler: 'gcc'
+            cmake_args: >-
+              --install-prefix=/usr/local
+          # CMake 3.10 uses --build with --target install
+          - cmake: '3.10.0'
+            install_cmd: --build
+            install_args: --target install
+          # Later versions just use --install
+          - cmake: '3.21.7'
+            install_cmd: --install
+          - cmake: '4.2.6'
+            install_cmd: --install
+          - cmake: 'latest'
+            install_cmd: --install
+          # We need sudo on MacOS and Ubuntu only
+          - os: macos
+            sudo: sudo
+          - os: ubuntu
+            sudo: sudo
+
 
       # Don't cancel all builds when one fails
       fail-fast: false
-    runs-on: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}-latest
+
+    defaults:
+      run:
+        shell: '${{ matrix.shell }} {0}'
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v6
+
+    - name: Setup cmake
+      uses: lukka/get-cmake@latest
+      with:
+        cmakeVersion: ${{ matrix.cmake }}
+      if: matrix.shell != 'msys2'
+
+    - name: Install MSVC (Windows)
+      uses: k3DW/setup-msvc@v1
+      with:
+        vs-version: ${{ matrix.msvc }}
+      if: matrix.compiler == 'msvc' && matrix.msvc != 'latest'
 
     - name: Install dependencies (macOS)
       run: brew install fftw
-      if: matrix.os == 'macos-latest'
+      if: matrix.os == 'macos'
 
     - name: Install dependencies (Ubuntu)
       run: |
         sudo apt update
         sudo apt install libfftw3-dev libusb-1.0-0-dev
-      if: matrix.os == 'ubuntu-latest'
+      if: matrix.os == 'ubuntu'
 
     - name: Install dependencies (Windows)
-      run: vcpkg install --triplet=x64-windows libusb fftw3 pthreads
-      if: matrix.os == 'windows-latest'
+      run: vcpkg install --triplet=x64-windows libusb fftw3 pthreads pkgconf
+      if: matrix.os == 'windows' && matrix.shell != 'msys2'
 
-    - name: Create Build Environment
-      run: cmake -E make_directory ${{runner.workspace}}/host/build
+    - name: Setup MSYS (Windows)
+      if: matrix.os == 'windows' && matrix.shell == 'msys2'
+      uses: msys2/setup-msys2@v2
+      with:
+        msystem: UCRT64
+        install: >-
+          git
+          make
+          mingw-w64-ucrt-x86_64-cmake
+          mingw-w64-ucrt-x86_64-toolchain
+          mingw-w64-ucrt-x86_64-libusb
+          mingw-w64-ucrt-x86_64-fftw
 
-    - name: Configure CMake
-      working-directory: ${{runner.workspace}}/host/build
-      run: cmake $GITHUB_WORKSPACE/host/ -DCMAKE_BUILD_TYPE=Release
-      if: matrix.os != 'windows-latest'
+    # Build libhackrf and hackrf-tools together
 
-    - name: Configure CMake (Windows)
-      working-directory: ${{runner.workspace}}/host/build
-      run: cmake $env:GITHUB_WORKSPACE/host/ $env:WIN_LIBUSB_INC $env:WIN_LIBUSB_LIB $env:WIN_FFTW_INC $env:WIN_FFTW_LIB $env:WIN_PTHREAD_INC $env:WIN_PTHREAD_LIB
-      if: matrix.os == 'windows-latest'
+    - name: Configure & Build
+      run: |
+        cmake -E make_directory host/build
+        cd host/build
+        cmake .. -G "${{ matrix.generator }}" -DCMAKE_BUILD_TYPE=Release ${{matrix.cmake_args}}
+        cmake --build . --config Release
 
-    - name: Build
-      working-directory: ${{runner.workspace}}/host/build
-      run: cmake --build . --config Release
+    # Build libhackrf ONLY
 
-    - name: Create Build Environment (libhackrf)
-      run: cmake -E make_directory ${{runner.workspace}}/host/libhackrf/build
-
-    - name: Configure CMake (libhackrf)
-      working-directory: ${{runner.workspace}}/host/libhackrf/build
-      run: cmake $GITHUB_WORKSPACE/host/libhackrf/ -DCMAKE_BUILD_TYPE=Release
-      if: matrix.os != 'windows-latest'
-
-    - name: Configure CMake (libhackrf, Windows)
-      working-directory: ${{runner.workspace}}/host/libhackrf/build
-      run: cmake $env:GITHUB_WORKSPACE/host/libhackrf/ $env:WIN_LIBUSB_INC $env:WIN_LIBUSB_LIB $env:WIN_PTHREAD_INC $env:WIN_PTHREAD_LIB
-      if: matrix.os == 'windows-latest'
-
-    - name: Build (libhackrf)
-      working-directory: ${{runner.workspace}}/host/libhackrf/build
-      run: cmake --build . --config Release
+    - name: Configure & Build (libhackrf)
+      run: |
+        cmake -E make_directory host/libhackrf/build
+        cd host/libhackrf/build
+        cmake .. -G "${{ matrix.generator }}" -DCMAKE_BUILD_TYPE=Release ${{ matrix.cmake_args }}
+        cmake --build . --config Release
 
     - name: Install (libhackrf)
-      working-directory: ${{runner.workspace}}/host/libhackrf/build
       run: |
-        sudo cmake --install . --config Release
-      if: matrix.os != 'windows-latest'
+        ${{ matrix.sudo }} cmake ${{ matrix.install_cmd }} host/libhackrf/build ${{ matrix.install_args }} --config Release
 
-    - name: Install (libhackrf, Windows)
-      working-directory: ${{runner.workspace}}/host/libhackrf/build
+    # Build hackrf-tools ONLY
+
+    - name: Configure & Build (hackrf-tools)
       run: |
-        cmake --install . --config Release --prefix=$env:GITHUB_WORKSPACE/install
-      if: matrix.os == 'windows-latest'
+        cmake -E make_directory host/hackrf-tools/build
+        cd host/hackrf-tools/build
+        cmake .. -G "${{ matrix.generator }}" -DCMAKE_BUILD_TYPE=Release ${{ matrix.cmake_args }}
+        cmake --build . --config Release
 
-    - name: Create Build Environment (hackrf-tools)
-      run: cmake -E make_directory ${{runner.workspace}}/host/hackrf-tools/build
-
-    - name: Configure CMake (hackrf-tools)
-      working-directory: ${{runner.workspace}}/host/hackrf-tools/build
-      run: cmake $GITHUB_WORKSPACE/host/hackrf-tools/ -DCMAKE_BUILD_TYPE=Release
-      if: matrix.os != 'windows-latest'
-
-    - name: Configure CMake (hackrf-tools, Windows)
-      working-directory: ${{runner.workspace}}/host/hackrf-tools/build
+    - name: Install (hackrf-tools)
       run: |
-        cmake $env:GITHUB_WORKSPACE/host/hackrf-tools/ $env:WIN_FFTW_INC $env:WIN_FFTW_LIB -DLIBHACKRF_INCLUDE_DIR=$env:GITHUB_WORKSPACE/install/include/libhackrf -DLIBHACKRF_LIBRARIES=$env:GITHUB_WORKSPACE/install/bin/hackrf.lib
-      if: matrix.os == 'windows-latest'
+        ${{ matrix.sudo }} cmake ${{ matrix.install_cmd }} host/hackrf-tools/build ${{ matrix.install_args }}
 
-    - name: Build (hackrf-tools)
-      working-directory: ${{runner.workspace}}/host/hackrf-tools/build
-      run: cmake --build . --config Release
-      # This step should work on Windows too, but currently MSVC fails to find
-      # hackrf.h, despite us having installed it and specified its location in
-      # the previous steps above.
-      if: matrix.os != 'windows-latest'
+    # Publish the contents of install/bin (which should be the combination libhackrf and host-tools) for Windows
+    - name: Publish Artifacts (Windows)
+      uses: actions/upload-artifact@v4
+      with:
+        name: hackrf-tools-windows
+        path: ${{github.workspace}}/install/bin
+      if: matrix.os == 'windows' && matrix.cmake == 'latest' && matrix.shell == 'pwsh'
 
   firmware:
     strategy:
       matrix:
-        os: ['macos-latest', 'ubuntu-latest']
-        board: ['HACKRF_ONE', 'JAWBREAKER', 'RAD1O']
+        os: ['macos', 'ubuntu', 'windows']
+        board: ['HACKRF_ONE', 'JAWBREAKER', 'RAD1O', 'PRALINE', 'UNIVERSAL']
+        cmake: ['3.12.0', 'latest']
+        exclude:
+          - os: 'windows'
+            cmake: '3.12.0'
+          # GitHub doesn't give us many macOS runners, so don't build for every board.
+          # We just need to know that building firmware works on macOS. Use PRALINE
+          # since that's the most complicated one due to FPGA bitstreams.
+          - os: 'macos'
+            board: 'HACKRF_ONE'
+          - os: 'macos'
+            board: 'JAWBREAKER'
+          - os: 'macos'
+            board: 'RAD1O'
 
       # Don't cancel all builds when one fails
       fail-fast: false
-    runs-on: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}-latest
 
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v6
       with:
         submodules: true
 
+    - name: Setup cmake
+      uses: lukka/get-cmake@latest
+      with:
+        cmakeVersion: ${{ matrix.cmake }}
+      if: matrix.os != 'windows'
+
+    - name: Install Arm GNU Toolchain
+      uses: carlosperate/arm-none-eabi-gcc-action@v1
+      if: matrix.os != 'windows'
+
     - name: Install dependencies (macOS)
       run: |
-        brew tap armmbed/formulae
-        brew install arm-none-eabi-gcc dfu-util
-        pip3 install PyYAML
-      if: matrix.os == 'macos-latest'
+        brew install dfu-util
+        python3 -m venv environment && source environment/bin/activate
+        python3 -m pip install PyYAML
+      if: matrix.os == 'macos'
 
     - name: Install dependencies (Ubuntu)
       run: |
-        sudo apt install dfu-util gcc-arm-none-eabi
-      if: matrix.os == 'ubuntu-latest'
+        python3 -m venv environment && source environment/bin/activate
+        python3 -m pip install PyYAML
+        sudo apt install dfu-util
+      if: matrix.os == 'ubuntu'
 
     - name: Build libopencm3
       shell: bash
       working-directory: ${{github.workspace}}/firmware/libopencm3/
-      run: make
+      run: |
+        source ../../environment/bin/activate
+        make
+      if: matrix.os != 'windows'
 
     - name: Create Build Environment
-      run: cmake -E make_directory ${{runner.workspace}}/firmware/build
+      run: cmake -E make_directory ${{github.workspace}}/firmware/build
+      if: matrix.os != 'windows'
 
     - name: Configure CMake
       shell: bash
-      working-directory: ${{runner.workspace}}/firmware/build
+      working-directory: ${{github.workspace}}/firmware/build
       run: cmake $GITHUB_WORKSPACE/firmware/ -DCMAKE_BUILD_TYPE=Release -DBOARD=${{ matrix.board }}
+      if: matrix.os != 'windows'
 
     - name: Build
-      working-directory: ${{runner.workspace}}/firmware/build
+      working-directory: ${{github.workspace}}/firmware/build
       shell: bash
-      run: cmake --build . --config Release
+      run: |
+        source ../../environment/bin/activate
+        cmake --build . --config Release
+      if: matrix.os != 'windows'
 
+    - name: Setup MSYS (Windows)
+      if: matrix.os == 'windows'
+      uses: msys2/setup-msys2@v2
+      with:
+        msystem: UCRT64
+        update: true
+        install: >-
+          git
+          make
+          mingw-w64-ucrt-x86_64-arm-none-eabi-gcc
+          mingw-w64-ucrt-x86_64-cmake
+          mingw-w64-ucrt-x86_64-dfu-util
+          mingw-w64-ucrt-x86_64-python-yaml
+
+    - name: Build with MSYS (Windows)
+      if: matrix.os == 'windows'
+      shell: msys2 {0}
+      run: |
+        mkdir firmware/build
+        cd firmware/build
+        cmake -G "MSYS Makefiles" -DCMAKE_BUILD_TYPE=Release -DBOARD=${{ matrix.board }} ..
+        make

.github/workflows/clang-format-check.yml

@@ -16,7 +16,7 @@ jobs:
           - check: 'firmware/hackrf_usb'
             exclude: ''
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v6
     - name: Run clang-format-action
       uses: jidicula/clang-format-action@v4.6.2
       with:

.github/workflows/includes-check.yml

@@ -0,0 +1,96 @@
+name: Check includes
+on: [push, pull_request]
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  includes-check:
+    runs-on: ubuntu-latest
+    container:
+      image: "debian:13"
+      options: --user 0
+    strategy:
+      matrix:
+        board: ['HACKRF_ONE', 'JAWBREAKER', 'RAD1O', 'PRALINE', 'UNIVERSAL']
+        cmake: ['3.12.0', 'latest']
+
+      # Don't cancel all builds when one fails
+      fail-fast: false
+
+    steps:
+
+    - name: Make it work on debian
+      run: |
+        apt update
+        apt install -y git python3 python3-pip python3-venv nodejs unzip
+        # actions/checkout insists on putting the checkout in the
+        # working directory rather than ${{ github.workspace }}.
+        #
+        # This may just be because the 'runner' user does not exist
+        # in the docker image at startup.
+        #
+        # also see: https://github.com/actions/runner/issues/878
+        useradd -ms /bin/bash runner
+        ln -s /__w /home/runner/work
+
+    - name: Checkout repository
+      uses: actions/checkout@v6
+      with:
+        submodules: true
+
+    - name: Setup cmake
+      uses: lukka/get-cmake@latest
+      with:
+        cmakeVersion: ${{ matrix.cmake }}
+
+    - name: Install Arm GNU Toolchain
+      uses: carlosperate/arm-none-eabi-gcc-action@v1
+
+    - name: Install dependencies
+      run: |
+        python3 -m venv environment && source environment/bin/activate
+        python3 -m pip install PyYAML
+        apt install -y iwyu
+        iwyu --version
+
+    - name: Build libopencm3
+      working-directory: ${{github.workspace}}/firmware/libopencm3/
+      run: |
+        source ../../environment/bin/activate
+        make
+
+    - name: Create Build Environment
+      run: cmake -E make_directory ${{github.workspace}}/firmware/build
+
+    - name: Configure CMake
+      working-directory: ${{github.workspace}}/firmware/build
+      run: cmake ${{github.workspace}}/firmware/ -DCMAKE_BUILD_TYPE=Release -DBOARD=${{ matrix.board }} -DCHECK_INCLUDES=1
+
+    - name: Build
+      working-directory: ${{github.workspace}}/firmware/build
+      run: |
+        source ../../environment/bin/activate
+        output="$(cmake --build . --config Release 2>&1)"
+        while IFS= read -r line
+        do
+            if [[ "${line}" == "Warning: include-what-you-use"* ]]; then
+                exit_code=1
+                dump=1
+                echo
+            elif [[ "${line}" == "---" ]]; then
+                dump=0
+                echo
+            fi
+            if [[ ${dump} == "1" ]]; then
+                echo "${line}"
+            fi
+        done <<< ${output}
+        if [[ ${exit_code} == "1" ]]; then
+            echo "Includes check failed for board target: ${{ matrix.board }}"
+        else
+            echo "Includes check succeeded for board target: ${{ matrix.board }}"
+        fi
+        echo $(include-what-you-use --version)
+        exit ${exit_code}

.gitignore

@@ -6,6 +6,7 @@
 *.srec
 host/build/
 host/**/build
+install/
 
 # Operating system spew
 .DS_Store

.readthedocs.yaml

@@ -0,0 +1,24 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools 
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+   configuration: docs/source/conf.py
+
+# Build PDF for docs
+formats:
+  - pdf
+
+python:
+  install:
+    - requirements: docs/requirements.txt

Dockerfile

@@ -1,12 +1,18 @@
-# Sandbox test environment for HackRF
-FROM ubuntu:20.04
-CMD ["/bin/bash"]
+# Environment for HackRF HIL testing with Jenkins CI
+FROM ubuntu:22.04
+USER root
 
-# Override interactive installations and install prerequisites
+# Copy usb hub script from Jenkins' container
+COPY --from=gsg-jenkins /startup/hubs.py /startup/hubs.py
+COPY --from=gsg-jenkins /startup/.hubs /startup/.hubs
+RUN ln -s /startup/hubs.py /usr/local/bin/hubs
+
+# Override interactive installations and install software dependencies
 ENV DEBIAN_FRONTEND=noninteractive
 RUN apt-get update && apt-get install -y \
     build-essential \
     cmake \
+    curl \
     dfu-util \
     gcc-arm-none-eabi \
     git \
@@ -15,13 +21,19 @@ RUN apt-get update && apt-get install -y \
     pkg-config \
     python3 \
     python3-pip \
-    python-is-python3 \
+    python3-yaml \
+    usbutils \
     && rm -rf /var/lib/apt/lists/*
-RUN pip3 install git+https://github.com/CapableRobot/CapableRobot_USBHub_Driver --upgrade
 
-# Serial numbers for EUT and TESTER devices connected to the test server
-ENV EUT=RunningFromRAM
-ENV TESTER=0000000000000000325866e629a25623
+# Install USB hub PPPS dependencies
+RUN pip3 install numpy python-dotenv git+https://github.com/CapableRobot/CapableRobot_USBHub_Driver --upgrade
+RUN curl -L https://github.com/mvp/uhubctl/archive/refs/tags/v2.5.0.tar.gz > uhubctl-2.5.0.tar.gz \
+    && mkdir uhubctl-2.5.0 \
+    && tar -xvzf uhubctl-2.5.0.tar.gz -C uhubctl-2.5.0 --strip-components 1 \
+    && rm uhubctl-2.5.0.tar.gz \
+    && cd uhubctl-2.5.0 \
+    && make \
+    && make install
 
 # Inform Docker that the container is listening on port 8080 at runtime
 EXPOSE 8080

Jenkinsfile

@@ -1,40 +1,130 @@
+import org.jenkinsci.plugins.workflow.steps.FlowInterruptedException
+
+def docker_args = '''--group-add=20 --group-add=46 --device-cgroup-rule="c 189:* rmw" \
+                    --device-cgroup-rule="c 166:* rmw" -v /dev/bus/usb:/dev/bus/usb \
+                    -v /tmp/req_pipe:/tmp/req_pipe -v /tmp/res_pipe:/tmp/res_pipe'''
+
+def h1_test = '''python3 ci-scripts/hackrf_test.py --ci --log log \
+                    --hostdir host/build/hackrf-tools/src/ \
+                    --fwupdate firmware/hackrf_usb/build/ \
+                    --tester 0000000000000000325866e629a25623 \
+                    --eut RunningFromRAM --unattended --rev r4'''
+
+def hpro_test = '''python3 ci-scripts/hackrf_pro_test.py --ci --log log \
+                    --hostdir host/build/hackrf-tools/src \
+                    --fwupdate firmware/hackrf_usb/build \
+                    --tester 0000000000000000a06063c82338145f \
+                    --eut RunningFromRAM -p --rev r1.2'''
+
 pipeline {
-    agent {
-        dockerfile {
-            args '--group-add=46 --device-cgroup-rule="c 189:* rmw" -v /dev/bus/usb:/dev/bus/usb'
-        }
-    }
+    agent any
     stages {
-        stage('Build (Host)') {
+        stage('Build Docker Image') {
+            options {
+                timeout(time: 20, unit: 'MINUTES')
+            }
             steps {
-                sh './ci-scripts/install-host.sh'
+                sh 'docker build -t hackrf https://github.com/greatscottgadgets/hackrf.git'
             }
         }
-        stage('Build (Firmware)') {
+        stage('Test HackRF One with BOARD=HACKRF_ONE') {
+            agent {
+                docker {
+                    image 'hackrf'
+                    reuseNode true
+                    args docker_args
+                }
+            }
+            options {
+                timeout(time: 20, unit: 'MINUTES')
+            }
             steps {
-                sh './ci-scripts/install-firmware.sh'
+                runCommand("Install Host Tools", './ci-scripts/install_host.sh', 3, 1, 'MINUTES')
+                runCommand("Build HackRF One Firmware", './ci-scripts/build_firmware.sh HACKRF_ONE', 3, 1, 'MINUTES')
+                lock('HIL_hubs') {
+                    script {
+                        allOff()
+                        runTest("Check Host", 'h1_eut', './ci-scripts/test_host.sh')
+                        runTest("HackRF One HIL Test", 'h1_tester h1_eut', h1_test)
+                        runTest("SGPIO Debug Test", 'h1_eut', 'python3 ci-scripts/test_sgpio_debug.py')
+                    }
+                }
             }
         }
-        stage('Test') {
+        stage('Test HackRF One with BOARD=UNIVERSAL') {
+            agent {
+                docker {
+                    image 'hackrf'
+                    reuseNode true
+                    args docker_args
+                }
+            }
+            options {
+                timeout(time: 20, unit: 'MINUTES')
+            }
             steps {
-                sh './ci-scripts/configure-hubs.sh --off'
-                retry(3) {
-                    sh './ci-scripts/test-host.sh'
+                runCommand("Install Host Tools", './ci-scripts/install_host.sh', 3, 1, 'MINUTES')
+                runCommand("Build Universal Firmware", './ci-scripts/build_firmware.sh UNIVERSAL', 3, 1, 'MINUTES')
+                lock('HIL_hubs') {
+                    script {
+                        allOff()
+                        runTest("Check Host", 'h1_eut', './ci-scripts/test_host.sh')
+                        runTest("HackRF One HIL Test", 'h1_tester h1_eut', h1_test)
+                        runTest("SGPIO Debug Test", 'h1_eut', 'python3 ci-scripts/test_sgpio_debug.py')
+                    }
                 }
-                retry(3) {
-                    sh './ci-scripts/test-firmware-program.sh'
+
+            }
+        }
+        stage('Test HackRF Pro with BOARD=PRALINE') {
+            agent {
+                docker {
+                    image 'hackrf'
+                    reuseNode true
+                    args "$docker_args"
+                }
+            }
+            options {
+                timeout(time: 20, unit: 'MINUTES')
+            }
+            steps {
+                runCommand("Install Host Tools", './ci-scripts/install_host.sh', 3, 1, 'MINUTES')
+                runCommand("Build Praline Firmware", './ci-scripts/build_firmware.sh PRALINE', 3, 1, 'MINUTES')
+                lock('HIL_hubs') {
+                    script {
+                        allOff()
+                        runTest("Check Host", 'hpro_eut', './ci-scripts/test_host.sh')
+                        runTest("HackRF Pro HIL Test", 'hpro_tester hpro_eut', hpro_test)
+                    }
+                }
+            }
+        }
+        stage('Test HackRF Pro with BOARD=UNIVERSAL') {
+            agent {
+                docker {
+                    image 'hackrf'
+                    reuseNode true
+                    args "$docker_args"
+                }
+            }
+            options {
+                timeout(time: 20, unit: 'MINUTES')
+            }
+            steps {
+                runCommand("Install Host Tools", './ci-scripts/install_host.sh', 3, 1, 'MINUTES')
+                runCommand("Build Universal Firmware", './ci-scripts/build_firmware.sh UNIVERSAL', 3, 1, 'MINUTES')
+                lock('HIL_hubs') {
+                    script {
+                        allOff()
+                        runTest("Check Host", 'hpro_eut', './ci-scripts/test_host.sh')
+                        runTest("HackRF Pro HIL Test", 'hpro_tester hpro_eut', hpro_test)
+                    }
                 }
-                sh './ci-scripts/test-firmware-flash.sh'
-                sh 'python3 ci-scripts/test-debug.py'
-                sh 'python3 ci-scripts/test-transfer.py tx'
-                sh 'python3 ci-scripts/test-transfer.py rx'
             }
         }
     }
     post {
         always {
-            sh './ci-scripts/configure-hubs.sh --reset'
-            sh 'rm -rf testing-venv/'
             cleanWs(cleanWhenNotBuilt: false,
                     deleteDirs: true,
                     disableDeferredWipeout: true,
@@ -42,3 +132,46 @@ pipeline {
         }
     }
 }
+
+def allOff() {
+    // Allow up to 3 retries, 20 seconds each, for the USB hub port power server to respond appropriately
+    runCommand('USB hub port power server command', "hubs all off", 3, 20, 'SECONDS')
+}
+
+def reset(devices) {
+    // Allow up to 3 retries, 20 seconds each, for the USB hub port power server to respond appropriately
+    runCommand('USB hub port power server command', "hubs ${devices} reset", 3, 20, 'SECONDS')
+}
+
+def runCommand(title, cmd, retries, time, unit) {
+    retry(retries) {
+        try {
+            timeout(time: time, unit: unit) {
+                sh "${cmd}"
+            }
+        } catch (FlowInterruptedException err) {
+            // Check if the cause was specifically an exceeded timeout
+            def cause = err.getCauses().get(0)
+            if (cause instanceof org.jenkinsci.plugins.workflow.steps.TimeoutStepExecution.ExceededTimeout) {
+                echo "${title} timeout reached."
+                throw err // Re-throw the exception to fail the build
+            } else {
+                echo "Build interrupted for another reason."
+                throw err // Re-throw the exception to fail the build
+            }
+        } catch (Exception err) {
+            echo "An unrelated error occurred: ${err.getMessage()}"
+            throw err
+        }
+    }
+}
+
+def runTest(title, devices, cmd) {
+    retry(3) {
+        // reset() retains it's own internal retries
+        reset(devices)
+        sh 'sleep 1s'
+        // run the test with 0 internal retries and 3 external retries to ensure resets between runs
+        runCommand(title, cmd, 0, 5, 'MINUTES')
+    }
+}

Readme.md

@@ -15,7 +15,7 @@ Information on HackRF and purchasing HackRF: https://greatscottgadgets.com/hackr
 
 # Documentation
 
-Documentation for HackRF can be viewed on [Read the Docs](https://hackrf.readthedocs.io/en/latest/). The raw documenation files for HackRF are in the [docs folder](https://github.com/mossmann/hackrf/tree/master/docs) in this repository and can be built locally by installing [Sphinx Docs](https://www.sphinx-doc.org/en/master/usage/installation.html) and running `make html`. Documentation changes can be submitted through pull request and suggestions can be made as GitHub issues. 
+Documentation for HackRF can be viewed on [Read the Docs](https://hackrf.readthedocs.io/en/latest/). The raw documentation files for HackRF are in the [docs folder](https://github.com/mossmann/hackrf/tree/master/docs) in this repository and can be built locally by installing [Sphinx Docs](https://www.sphinx-doc.org/en/master/usage/installation.html) and running `make html`. Documentation changes can be submitted through pull request and suggestions can be made as GitHub issues. 
 
 To create a PDF of the HackRF documentation from the HackRF repository while on Ubuntu:
 * run `sudo apt install latexmk texlive-latex-extra`
@@ -27,7 +27,7 @@ To create a PDF of the HackRF documentation from the HackRF repository while on
 
 # Getting Help
 
-Before asking for help with HackRF, check to see if your question is listed in the [FAQ](https://hackrf.readthedocs.io/en/latest/faq.html).
+Before asking for help with HackRF, check to see if your question is listed on the [troubleshooting page](https://hackrf.readthedocs.io/en/latest/troubleshooting.html).
 
 For assistance with HackRF general use or development, please look at the [issues on the GitHub project](https://github.com/greatscottgadgets/hackrf/issues). This is the preferred place to ask questions so that others may locate the answer to your question in the future.
 

appveyor.yml

@@ -1,52 +0,0 @@
-os: Visual Studio 2017
-clone_depth: 1
-
-configuration:
-  - Release
-
-init:
-  - C:\"Program Files (x86)"\"Microsoft Visual Studio 14.0"\VC\vcvarsall.bat %PLATFORM%
-install:
-  # Dependencies for libHackRF
-  - appveyor DownloadFile "https://github.com/libusb/libusb/releases/download/v1.0.22/libusb-1.0.22.7z" -FileName "C:\libusb.7z"
-  - 7z x -y "C:\libusb.7z" -o"C:\libusb"
-  - appveyor DownloadFile "http://mirrors.kernel.org/sourceware/pthreads-win32/pthreads-w32-2-9-1-release.zip" -FileName "C:\pthreads-w32-release.zip"
-  - 7z x -y "C:\pthreads-w32-release.zip" -o"C:\pthreads"
-  - appveyor DownloadFile "http://ftp.gnome.org/pub/gnome/binaries/win32/dependencies/pkg-config_0.26-1_win32.zip" -FileName "C:\pkg-config_win32.zip"
-  - 7z x -y "C:\pkg-config_win32.zip" -o"C:\pkg-config"
-  # FFTW for hackrf_sweep
-  - curl -fsS -o "C:\fftw-3.3.5.zip" "ftp://ftp.fftw.org/pub/fftw/fftw-3.3.5-dll64.zip"
-  - 7z x -y "C:\fftw-3.3.5.zip" -o"C:\fftw"
-  - cd c:\fftw
-  - ps: lib /machine:x64 /def:libfftw3f-3.def
-  # ARM GCC for firmware builds
-  # - appveyor DownloadFile "https://developer.arm.com/-/media/Files/downloads/gnu-rm/6-2017q2/gcc-arm-none-eabi-6-2017-q2-update-win32.zip" -FileName "C:\gcc-arm-none-eabi-win32.zip"
-  # - 7z x -y "C:\gcc-arm-none-eabi-win32.zip" -o"C:\gcc-arm-none-eabi"
-  # - set PATH=%PATH%;c:\gcc-arm-none-eabi\bin
-
-build_script:
-  # Host library and tools
-  - mkdir c:\projects\hackrf\host\build
-  - cd c:\projects\hackrf\host\build
-  - cmake -G "Visual Studio 14 2015 Win64" \
-    -DLIBUSB_LIBRARIES="C:\libusb\MS64\dll\libusb-1.0.lib" \
-    -DLIBUSB_INCLUDE_DIR="C:\libusb\include\libusb-1.0" \
-    -DTHREADS_PTHREADS_INCLUDE_DIR=c:\pthreads\Pre-built.2\include \
-    -DTHREADS_PTHREADS_WIN32_LIBRARY=c:\pthreads\Pre-built.2\lib\x64\pthreadVC2.lib \
-    -DPKG_CONFIG_EXECUTABLE="C:\pkg-config\bin\pkg-config.exe" \
-    -DFFTW_INCLUDES=C:\fftw \
-    -DFFTW_LIBRARIES=C:\fftw\libfftw3f-3.lib \
-    ..
-  - msbuild HackRF.sln /logger:"C:\Program Files\AppVeyor\BuildAgent\Appveyor.MSBuildLogger.dll"
-  # Firmware
-  # - cd c:\projects\hackrf\
-  # - git submodule init
-  # - git submodule update
-  # - '%CYG_BASH% -lc "cd $APPVEYOR_BUILD_FOLDER && firmware/appveyor.sh"'
-
-after_build:
-  - 7z a %APPVEYOR_BUILD_FOLDER%\HackRF-Windows-%APPVEYOR_REPO_COMMIT%.zip %APPVEYOR_BUILD_FOLDER%\host\build\libhackrf\src\Release\* %APPVEYOR_BUILD_FOLDER%\host\build\hackrf-tools\src\Release\* 
-
-artifacts:
-  - path: HackRF-Windows-%APPVEYOR_REPO_COMMIT%.zip
-    name: HackRF-Windows-%APPVEYOR_REPO_COMMIT%

ci-scripts/build_firmware.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+set -e
+git submodule init
+git submodule update
+cd firmware/hackrf_usb
+rm -rf build
+cmake -DBOARD=$1 -B build
+cmake --build build
+cd ../..

ci-scripts/configure-hubs.sh

@@ -1,3 +0,0 @@
-#!/bin/bash
-usbhub --disable-i2c --hub D9D1 power state --port 1,2,3,4 $1
-usbhub --disable-i2c --hub 624C power state --port 1,2,3,4 $1

ci-scripts/install-firmware.sh

@@ -1,8 +0,0 @@
-#!/bin/bash
-git submodule init
-git submodule update
-mkdir firmware/hackrf_usb/build
-cd firmware/hackrf_usb/build
-cmake ..
-make
-cd ../../..

ci-scripts/install-host.sh

@@ -1,6 +0,0 @@
-#!/bin/bash
-mkdir host/build
-cd host/build
-cmake ..
-make
-cd ../..

ci-scripts/install_host.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+set -e
+cd host
+cmake -B build
+cmake --build build
+cd ..

ci-scripts/test-firmware-flash.sh

@@ -15,4 +15,4 @@ then
 else
     echo "Unknown error"
     exit $EXIT_CODE
-fi
+fi

ci-scripts/test-firmware-program.sh

@@ -1,7 +1,6 @@
 #!/bin/bash
-usbhub --disable-i2c --hub D9D1 power state --port 2 --reset
-sleep 1s
 dfu-util --device 1fc9:000c --alt 0 --download firmware/hackrf_usb/build/hackrf_usb.dfu
+sleep 1s
 EXIT_CODE="$?"
 if [ "$EXIT_CODE" == "0" ]
 then
@@ -16,6 +15,6 @@ then
     echo "dfu-util installation failed! Exiting.."
     exit $EXIT_CODE
 else
-    echo "god have mercy on your soul"
+    echo "Unhandled exception"
     exit $EXIT_CODE
-fi
+fi

ci-scripts/test-transfer.py

@@ -2,9 +2,10 @@
 import subprocess
 import time
 import sys
+from os import environ
 
-EUT     = "RunningFromRAM"
-TESTER  = "0000000000000000325866e629a25623"
+EUT     = environ.get('EUT')
+TESTER  = environ.get('TESTER')
 PASS, FAIL = range(2)
 
 
@@ -87,8 +88,7 @@ def check_signal(freq, bins):
 
 def main():
     write_bytes()
-    tester_hub_on = subprocess.Popen(["usbhub", "--disable-i2c", "--hub", "624C",
-                                      "power", "state", "--port", "2", "--reset"])
+    tester_hub_on = subprocess.Popen(["hubs", "hackrf", "reset"])
     tester_hub_on.wait()
     time.sleep(1)
     eut_clkout_on       = subprocess.Popen(["host/build/hackrf-tools/src/hackrf_clock",

ci-scripts/test_host.sh

@@ -1,6 +1,4 @@
-#!/bin/bash 
-usbhub --disable-i2c --hub D9D1 power state --port 2 --reset
-sleep 1s
+#!/bin/bash
 host/build/hackrf-tools/src/hackrf_info
 EXIT_CODE="$?"
 if [ "$EXIT_CODE" == "1" ]
@@ -18,4 +16,4 @@ then
 else
     echo "god have mercy on your soul"
     exit $EXIT_CODE
-fi
+fi

ci-scripts/test_sgpio_debug.py

@@ -0,0 +1,87 @@
+#!/usr/bin/python3
+import os
+import sys
+import subprocess
+from pathlib import Path
+
+FILENAME = f"/tmp/rx_100kB_{str(os.getpid())}"
+
+
+def program_device():
+    # build new firmware with SGPIO_DEBUG mode enabled
+    print("Programming device...")
+    fw_dir  = os.getcwd() + "/firmware/hackrf_usb/build"
+    del_dir = subprocess.run(["rm", "-rf", "firmware/hackrf_usb/build"])
+    mk_dir  = subprocess.run(["mkdir", "firmware/hackrf_usb/build"])
+    cmake   = subprocess.run(["cmake", "-D", "SGPIO_DEBUG=1", ".."],
+                             cwd=fw_dir, stdout=subprocess.DEVNULL)
+    make    = subprocess.run(["make"],
+                             cwd=fw_dir, stdout=subprocess.DEVNULL)
+    program = subprocess.run(["./ci-scripts/test-firmware-program.sh"],
+                             stdout=subprocess.DEVNULL)
+
+
+def capture():
+    shortfall_count = -1
+    capture_tries = 0
+
+    while shortfall_count != 0:
+        print("Capturing data...")
+        rx_100kB = subprocess.run(["host/build/hackrf-tools/src/hackrf_transfer",
+                                    "-r", FILENAME, "-d", "RunningFromRAM",
+                                    "-n", "50000", "-s", "20000000"],
+                                    capture_output=True, encoding="UTF-8")
+        print(rx_100kB.stdout)
+        print(rx_100kB.stderr)
+        print(f"Wrote capture data to file: {FILENAME}")
+
+        debug_state_proc = subprocess.run(["host/build/hackrf-tools/src/hackrf_debug", "--state"],
+                                            capture_output=True, encoding="UTF-8")
+        print(debug_state_proc.stdout)
+        print(debug_state_proc.stderr)
+        capture_tries += 1
+        debug_state = debug_state_proc.stdout.split("\n")
+        shortfalls_line = [s for s in debug_state if s.startswith("Number of shortfalls")]
+        shortfall_count = [int(c) for c in shortfalls_line[0].split() if c.isdigit()][0]
+
+        if capture_tries == 10:
+            print("Unable to transmit data with 0 shortfalls. " \
+            "This is not indicative of a device failure. " \
+            "Likely an issue with the testing infrastructure.")
+            sys.exit(1)
+
+
+def check_bytes():
+    print(f"Checking length of {FILENAME}")
+    rx_data = Path(FILENAME).read_bytes()
+    if len(rx_data) != 100000: # file should be 100k bytes when using 50k samples
+        print(f"ERROR: Only {str(len(rx_data))} bytes found in file, expected 100k.")
+        sys.exit(1)
+    else:
+        print("Correct file size found.")
+
+    # check that each byte = prev_byte + 1 except at wraparound bounds
+    print("Checking bytes...")
+    for i in range(1, len(rx_data)):
+        if rx_data[i-1] != rx_data[i] - 1:
+            if not (rx_data[i] == 0 and rx_data[i-1] == 255):
+                print(f"ERROR: Incorrect data value found at location {str(i)} in {FILENAME}:")
+                # print up to 5 values starting from at most 1 value before error occurence
+                j = -1
+                while j < 4:
+                    if i + j < len(rx_data) and i + j > -1:
+                        print(f"{str(i+j)} : {str(rx_data[i+j])}")
+                    j = j + 1
+                sys.exit(1)
+    print("Successfully validated all bytes in file.\nSGPIO debug test passed.")
+
+
+def main():
+    program_device()
+    capture()
+    check_bytes()
+
+
+if __name__ == "__main__":
+    main()
+

docs/requirements.txt

@@ -1,4 +1,4 @@
-sphinx==1.8.5
-sphinx_rtd_theme==1.0.0
-readthedocs-sphinx-search==0.1.1
-jinja2==3.0.0
+sphinx==7.2.6
+sphinx_rtd_theme==2.0.0
+readthedocs-sphinx-search==0.3.2
+jinja2==3.1.6

docs/source/LPC43XX_SGPIO_Configuration.rst

@@ -13,11 +13,8 @@ In the current HackRF design, there is a CPLD which manages the interface betwee
 
 
 
-Frequently Asked Questions
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
 Why not use GPDMA to transfer samples through SGPIO?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 It would be great if we could, as that would free up lots of processor time. Unfortunately, the GPDMA scheme in the LPC43xx does not seem to support peripheral-to-memory and memory-to-peripheral transfers with the SGPIO peripheral.
 

docs/source/enclosure_options.rst

@@ -1,8 +1,8 @@
 Enclosure Options
 ~~~~~~~~~~~~~~~~~
 
-The commercial version of HackRF One from Great Scott Gadgets ships with an injection molded plastic enclosure, but it is designed to fit two optional enclosures:
+Commercial versions of both HackRF Pro and HackRF One from Great Scott Gadgets ship with an injection molded plastic enclosure but are also designed to fit two optional enclosures:
 
-    * Hammond 1455J1201: HackRF One fits this extruded aluminum enclosure and other similar models from Hammond Manufacturing. In order to use the enclosure's end plates, you will have to drill them. An end plate template can be found in the HackRF One KiCad layout.
+    * Hammond 1455J1201: Both HackRF Pro and HackRF One fit this extruded aluminum enclosure and other similar models from Hammond Manufacturing. In order to use the enclosure's end plates, you will have to drill them. An end plate template can be found in the HackRF One KiCad layout.
 
-    * Acrylic sandwich: You can also use a laser cut acrylic enclosure with HackRF One. This is a good option for access to the expansion headers. A design can be found in the HackRF One hardware directory. Use any laser cutting service or purchase from a `reseller <http://greatscottgadgets.com/acrylic_case/>`__.
+    * Acrylic sandwich: You can also use a laser cut acrylic enclosure with either HackRF Pro or HackRF One. This is a good option for access to the expansion headers. A design can be found in the HackRF hardware directory. Use any laser cutting service or purchase from a `reseller <https://greatscottgadgets.com/hackrf/acrylic-case/>`__.

docs/source/expansion_interface.rst

@@ -1,55 +1,7 @@
 Expansion Interface
 ~~~~~~~~~~~~~~~~~~~
 
-The HackRF One expansion interface consists of headers P9, P20, P22, and P28. These four headers are installed on the commercial HackRF One from Great Scott Gadgets.
-
-
-
-P9 Baseband 
-^^^^^^^^^^^
-
-A direct analog interface to the high speed dual ADC and dual DAC.
-
-.. list-table :: 
-  :header-rows: 1
-  :widths: 1 1 
-
-  * - Pin
-    - Function
-  * - 1     
-    - GND
-  * - 2   
-    - GND
-  * - 3
-    - GND
-  * - 4   
-    - RXBBQ-
-  * - 5   
-    - RXBBI-
-  * - 6   
-    - RXBBQ+
-  * - 7   
-    - RXBBI+
-  * - 8   
-    - GND
-  * - 9   
-    - GND
-  * - 10  
-    - TXBBI-
-  * - 11  
-    - TXBBQ+
-  * - 12  
-    - TXBBI+
-  * - 13  
-    - TXBBQ-
-  * - 14  
-    - GND
-  * - 15  
-    - GND
-  * - 16  
-    - GND
-
-
+The common HackRF expansion interface consists of headers P20, P22, and P28. These headers are present on both HackRF Pro and HackRF One, and support hardware add-ons including PortaPack and Opera Cake.
 
 P20 GPIO
 ^^^^^^^^
@@ -65,15 +17,15 @@ Providing access to GPIO, ADC, RTC, and power.
   * - 1   
     - VBAT
   * - 2   
-    - RTC_ALARM
+    - RTC_ALARM (One) / PB_5 (Pro)
   * - 3   
-    - VCC
+    - VCC (One) / 3V3AUX (Pro)
   * - 4   
     - WAKEUP
   * - 5   
     - GPIO3_8
   * - 6   
-    - GPIO3_0
+    - GPIO3_0 (One) / GPIO3_9 (Pro)
   * - 7   
     - GPIO3_10
   * - 8   
@@ -121,7 +73,7 @@ I2S, SPI, I2C, UART, GPIO, and clocks.
   * - Pin     
     - Function
   * - 1   
-    - CLKOUT
+    - CLKOUT (One) / P2 (Pro)
   * - 2   
     - CLKIN
   * - 3   
@@ -133,21 +85,21 @@ I2S, SPI, I2C, UART, GPIO, and clocks.
   * - 6   
     - I2C1_SDA
   * - 7   
-    - SPIFI_MISO
+    - SPIFI_MISO (One) / PB_1 (Pro)
   * - 8   
-    - SPIFI_SCK
+    - SPIFI_SCK (One) / PB_3 (Pro)
   * - 9   
-    - SPIFI_MOSI
+    - SPIFI_MOSI (One) / PA_4 (Pro)
   * - 10  
     - GND
   * - 11  
-    - VCC
+    - VCC (One) / 3V3AUX (Pro)
   * - 12  
-    - I2S0_RX_SCK
+    - I2S0_RX_SCK (One) / PA_3 (Pro)
   * - 13  
-    - I2S_RX_SDA
+    - I2S0_RX_SDA (One) / I2S0_TX_SDA (Pro)
   * - 14  
-    - I2S0_RX_MCLK
+    - I2S0_RX_MCLK (One) / PB_0 (Pro)
   * - 15  
     - I2S0_RX_WS
   * - 16  
@@ -169,7 +121,7 @@ I2S, SPI, I2C, UART, GPIO, and clocks.
   * - 24  
     - SDA
   * - 25  
-    - CLK6
+    - CLK6 (One) / AUX_CLK2 (Pro)
   * - 26  
     - SCL
 
@@ -187,7 +139,7 @@ SDIO, GPIO, clocks, and CPLD.
   * - Pin     
     - Function
   * - 1   
-    - VCC
+    - VCC (One) / 3V3AUX (Pro)
   * - 2   
     - GND
   * - 3   
@@ -211,25 +163,69 @@ SDIO, GPIO, clocks, and CPLD.
   * - 12  
     - GND
   * - 13  
-    - GCK2
+    - GCK2 (One) / P5_6 (Pro)
   * - 14  
-    - GCK1
+    - GCK1 (One) / P5_7 (Pro)
   * - 15  
-    - B1AUX14 (trigger output)
+    - Trigger out: B1AUX14 (One) / TRIGGER.OUT (Pro)
   * - 16  
-    - B1AUX13 (trigger input)
+    - Trigger in: B1AUX13 (One) / TRIGGER.IN (Pro)
   * - 17  
     - CPLD_TCK
   * - 18  
-    - BANK2F3M2
+    - BANK2F3M2 (One) / PE_0 (Pro)
   * - 19  
-    - CPLD_TDI
+    - CPLD_TDI (One) / I2S0_RX_SDA (Pro)
   * - 20  
-    - BANK2F3M6
+    - BANK2F3M6 (One) / P9_1 (Pro)
   * - 21  
-    - BANK2F3M12
+    - BANK2F3M12 (One) / P5_3 (Pro)
   * - 22  
-    - BANK2F3M4
+    - BANK2F3M4 (One) / P1_7 (Pro)
+
+P9 Baseband (HackRF One)
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+A direct analog interface to the high speed dual ADC and dual DAC.
+
+.. list-table ::
+  :header-rows: 1
+  :widths: 1 1
+
+  * - Pin
+    - Function
+  * - 1
+    - GND
+  * - 2
+    - GND
+  * - 3
+    - GND
+  * - 4
+    - RXBBQ-
+  * - 5
+    - RXBBI-
+  * - 6
+    - RXBBQ+
+  * - 7
+    - RXBBI+
+  * - 8
+    - GND
+  * - 9
+    - GND
+  * - 10
+    - TXBBI-
+  * - 11
+    - TXBBQ+
+  * - 12
+    - TXBBI+
+  * - 13
+    - TXBBQ-
+  * - 14
+    - GND
+  * - 15
+    - GND
+  * - 16
+    - GND
 
 Additional unpopulated headers and test points are available for test and development, but they may be incompatible with some enclosure or expansion options.
 

docs/source/external_clock_interface.rst

@@ -1,12 +1,26 @@
-===========================================
-External Clock Interface (CLKIN and CLKOUT)
-===========================================
+========================
+External Clock Interface
+========================
 
 .. _external_clock_interface:
 
-HackRF One produces a 10 MHz clock signal on CLKOUT. The signal is a 3.3 V, 10 MHz square wave intended for a high impedance load.
+HackRF Pro
+~~~~~~~~~~
 
-The CLKIN port on HackRF One is a high impedance input that expects 3.3 V square wave at 10 MHz. Do not exceed 3.3 V or drop below 0 V on this input. Do not connect a clock signal at a frequency other than 10 MHz (unless you modify the firmware to support this). You may directly connect the CLKOUT port of one HackRF One to the CLKIN port of another HackRF One.
+HackRF Pro has two configurable SMA ports, P1 and P2. By default, P1 is configured as CLKIN and P2 as CLKOUT. The default behaviour of these signals is as described for HackRF One below.
+
+A second CLKIN signal is available on header P22 pin 2. Unlike HackRF One, HackRF Pro's P22_CLKIN is a separate signal from P1_CLKIN. To enable P22_CLKIN instead of P1_CLKIN use ``hackrf_clock -c p22``.
+
+Various internal signals can be connected to P1 or P2 instead of the default CLKIN and CLKOUT signals. Use ``hackrf_clock -1`` or ``hackrf_clock -2`` to select a different signal.
+
+HackRF One
+~~~~~~~~~~
+
+HackRF One produces a 10 MHz clock signal on the CLKOUT SMA port. The signal is a 3.3 V, 10 MHz square wave intended for a high impedance load.
+
+The CLKIN SMA port on HackRF One is a high impedance input that expects 3.3 V square wave at 10 MHz. Do not exceed 3.3 V or drop below 0 V on this input. Do not connect a clock signal at a frequency other than 10 MHz (unless you modify the firmware to support this). You may directly connect the CLKOUT port of one HackRF One to the CLKIN port of another HackRF.
+
+The CLKIN signal is also connected to header P22 pin 2. Unlike HackRF Pro, HackRF One has only one CLKIN signal shared between P22 pin 2 and the CLKIN port. Do not connect input signals to both CLKIN and P22 pin 2 simultaneously.
 
 HackRF One uses CLKIN instead of the internal crystal when a clock signal is detected on CLKIN. The switch to or from CLKIN only happens when a transmit or receive operation begins.
 

docs/source/faq.rst

@@ -1,156 +0,0 @@
-.. _faq:
-
-================================================
-FAQ
-================================================
-
-
-What is the Transmit Power of HackRF?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF One's absolute maximum TX power varies by operating frequency:
-
-    * 1 MHz to 10 MHz: 5 dBm to 15 dBm, generally increasing as frequency increases (see this `blog post <https://greatscottgadgets.com/2015/05-15-hackrf-one-at-1-mhz/>`__)
-    * 10 MHz to 2170 MHz: 5 dBm to 15 dBm, generally decreasing as frequency increases
-    * 2170 MHz to 2740 MHz: 13 dBm to 15 dBm
-    * 2740 MHz to 4000 MHz: 0 dBm to 5 dBm, decreasing as frequency increases
-    * 4000 MHz to 6000 MHz: -10 dBm to 0 dBm, generally decreasing as frequency increases
-
-Through most of the frequency range up to 4 GHz, the maximum TX power is between 0 and 10 dBm. The frequency range with best performance is 2170 MHz to 2740 MHz.
-
-Overall, the output power is enough to perform over-the-air experiments at close range or to drive an external amplifier. If you connect an external amplifier, you should also use an external bandpass filter for your operating frequency.
-
-Before you transmit, know your laws. HackRF One has not been tested for compliance with regulations governing transmission of radio signals. You are responsible for using your HackRF One legally.
-
-
-----
-
-
-What is the Receive Power of HackRF?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The maximum RX power of HackRF One is -5 dBm. Exceeding -5 dBm can result in permanent damage!
-
-In theory, HackRF One can safely accept up to 10 dBm with the front-end RX amplifier disabled. However, a simple software or user error could enable the amplifier, resulting in permanent damage. It is better to use an external attenuator than to risk damage.
-
-
-----
-
-
-What is the minimum signal power level that can be detected by HackRF?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-This isn't a question that can be answered for a general purpose SDR platform such as HackRF. Any answer would be very specific to a particular application. For example, an answerable question might be: What is the minimum power level in dBm of modulation M at frequency F that can be detected by HackRF One with software S under configuration C at a bit error rate of no more than E%? Changing any of those variables (M, F, S, C, or E) would change the answer to the question. Even a seemingly minor software update might result in a significantly different answer. To learn the exact answer for a specific application, you would have to measure it yourself.
-
-HackRF's concrete specifications include operating frequency range, maximum sample rate, and dynamic range in bits. These specifications can be used to roughly determine the suitability of HackRF for a given application. Testing is required to finely measure performance in an application. Performance can typically be enhanced significantly by selecting an appropriate antenna, external amplifier, and/or external filter for the application.
-
-
-----
-
-
-Is HackRF full-duplex?
-~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF One is a half-duplex transceiver. This means that it can transmit or receive but not both at the same time.
-
-
-----
-
-
-Why isn't HackRF One full-duplex?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF One is designed to support the widest possible range of SDR applications in a single, low cost, portable device. Many applications do not require full-duplex operation. Full-duplex support would have made HackRF larger and more expensive, and it would have required an external power supply. Since full-duplex needs can be met by simply using a second HackRF One, it made sense to keep the device small, portable, and low cost for everyone who does not require full-duplex operation.
-
-
-----
-
-
-How could the HackRF One design be changed to make it full-duplex?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The HackRF One hardware design is actually full-duplex (at lower sample rates) from the USB connection through the ADC/DAC. The RF section is the only part of the design that cannot support full-duplex operation. The easiest way to make HackRF One full-duplex would be to create an add-on board that duplicates the RF section and also provides an external power input (from a wall wart, for example) for the additional power required. This would also require software effort; the firmware, CPLD, libhackrf, and other host software would all need work to support full-duplex operation.
-
-If you were to try to redesign the RF section on HackRF One to support full-duplex, the main thing to focus on would be the MAX2837 (intermediate frequency transceiver). This part is half-duplex, so you would either need two of them or you would have to redesign the RF section to use something other than the MAX2837, likely resulting in a radically different design. If you used two MAX2837s you might be able to use one RFFC5071 instead of two RFFC5072s.
-
-
-----
-
-
-Are those connectors SMA or RP-SMA?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Some connectors that appear to be SMA are actually RP-SMA. If you connect an RP-SMA antenna to HackRF One, it will seem to connect snugly but won't function at all because neither the male nor female side has a center pin. RP-SMA connectors are most common on 2.4 GHz antennas and are popular on Wi-Fi equipment. Adapters are available.
-
-
-----
-
-
-.. _bigspike:
-
-What is the big spike in the center of my received spectrum?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If you see a large spike in the center of your FFT display regardless of the frequenecy you are tuned to, you are seeing a DC offset (or component or bias). The term "DC" comes from "Direct Current" in electronics. It is the unchanging aspect of a signal as opposed to the "alternating" part of the signal (AC) that changes over time. Take, for example, the signal represented by the digital sequence:
-
-.. code-block:: sh
-
-	-2, -1, 1, 6, 8, 9, 8, 6, 1, -1, -2, -1, 1, 6, 8, 9, 8, 6, 1, -1, -2, -1, 1, 6, 8, 9, 8, 6, 1, -1
-
-This periodic signal contains a strong sinusoidal component spanning from -2 to 9. If you were to plot the spectrum of this signal, you would see one spike at the frequency of this sinusoid and a second spike at 0 Hz (DC). If the signal spanned from values -2 to 2 (centered around zero), there would be no DC offset. Since it is centered around 3.5 (the number midway between -2 and 9), there is a DC component.
-
-Samples produced by HackRF are measurements of radio waveforms, but the measurement method is prone to a DC bias introduced by HackRF. It's an artifact of the measurement system, not an indication of a received radio signal. DC offset is not unique to HackRF; it is common to all quadrature sampling systems.
-
-There was a bug in the HackRF firmware (through release 2013.06.1) that made the DC offset worse than it should have been. In the worst cases, certain Jawbreakers experienced a DC offset that drifted to a great extreme over several seconds of operation. This bug has been fixed. The fix reduces DC offset but does not do away with it entirely. It is something you have to live with when using any quadrature sampling system like HackRF.
-
-A high DC offset is also one of a few symptoms that can be caused by a software version mismatch. A common problem is that people run an old version of gr-osmosdr with newer firmware.
-
-
-----
-
-
-What gain controls are provided by HackRF?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF (both Jawbreaker and One) provides three different analog gain controls on RX and two on TX.
-
-The three RX gain controls are at these stages:
-
-- RF ("amp", 0 or ~11 dB)
-- IF ("lna", 0 to 40 dB in 8 dB steps)
-- baseband ("vga", 0 to 62 dB in 2 dB steps)
- 
-The two TX gain controls are at these stages:
-
-- RF (0 or ~11 dB)
-- IF (0 to 47 dB in 1 dB steps)
-
-Note: in some documents, the RF gain was erroneously quoted to be 14 dB. The confusion was based on the fact that the MGA-81563 amplifier is advertised as a "14 dBm" amplifier, but that specifies its output power, not its amplification. See `Martin Ling's comment on issue #1059 <https://github.com/greatscottgadgets/hackrf/issues/1059#issuecomment-1060038293>`__ for some details!
-
-----
-
-
-Why is the RF gain setting restricted to two values?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF has two RF amplifiers close to the antenna port, one for TX and one for RX. These amplifiers have two settings: on or off. In the off state, the amps are completely bypassed. They nominally provide around 11 dB of gain when on, but the actual amount of gain varies by frequency. In general, expect less gain at higher frequencies. For fine control of gain, use the IF and/or baseband gain options.
-
-
-----
-
-
-Why are the LEDs on HackRF different colours?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Each LED is a single color. There are no multi-colored LEDs on HackRF One. Adjacent LEDs are different colors in order to make them easier to distinguish from one another. The colors do not mean anything.
-
-
-----
-
-
-Where can I purchase HackRF?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF is designed and manufactured by Great Scott Gadgets. We do not sell low volumes of HackRFs to people individually; instead we have agreements with specific resellers. Please see our reseller list on the Great Scott Gadgets website for availability: `http://greatscottgadgets.com/hackrf/ <http://greatscottgadgets.com/hackrf/>`__. 
-
-HackRF is open source hardware, so you can also build your own.

docs/source/firmware_development_setup.rst

@@ -4,4 +4,4 @@ Firmware Development Setup
 
 Firmware build instructions are included in the repository under firmware/README:
 
-`https://github.com/mossmann/hackrf/blob/master/firmware/README <https://github.com/mossmann/hackrf/blob/master/firmware/README>`__
+`https://github.com/greatscottgadgets/hackrf/blob/master/firmware/README <https://github.com/greatscottgadgets/hackrf/blob/master/firmware/README>`__

docs/source/gateware.rst

@@ -0,0 +1,118 @@
+================================================
+Gateware
+================================================
+
+One of the significant hardware changes in :ref:`HackRF Pro <hackrf_pro>` is the replacement of the CPLD with a FPGA. While the older CPLD primarily provided glue logic between the MCU and RF front end, the FPGA in HackRF Pro introduces more logic and DSP capability. This enables offloading digital signal processing tasks from the MCU.
+
+FPGAs are highly flexible devices whose behavior is defined by *gateware*: hardware descriptions that configure the internal logic fabric. HackRF Pro gateware is written in `Amaranth HDL <https://amaranth-lang.org/>`__, a Python-based hardware description language.
+
+The specific FPGA device used in HackRF Pro is the Lattice iCE40UP5K, which features 
+5280 LUT4s and 8 dedicated DSP (multiply-accumulate) blocks. We rely on the `open-source iCE40 FPGA toolchain <https://github.com/YosysHQ/icestorm>`__ to build the required bitstreams that are bundled in the firmware.
+
+All gateware source code lives under `firmware/fpga/` in the HackRF repository. Top-level designs reside in `firmware/fpga/top/` and are the primary entry points for different operational modes.
+
+By default, a standard gateware configuration is loaded at boot. However, the firmware can dynamically reconfigure the FPGA at runtime to switch between different gateware variants.
+
+
+Standard gateware
+~~~~~~~~~~~~~~~~~
+
+The standard gateware is used by default when the firmware has not requested an alternative bitstream.
+
+The standard gateware provides a balanced configuration optimized for general-purpose operation. It implements configurable digital signal processing paths for the reception and transmission paths, capable of (limited) frequency translation and supporting a wide range of sample rates.
+
+Block diagram
+^^^^^^^^^^^^^
+
+.. image:: ../images/gateware-basic-block-diagram.png
+        :align: center
+
+.. image:: ../images/gateware-standard-dsp-chain.png
+        :align: center
+        :width: 75%
+
+Features
+^^^^^^^^
+* 8-bit I, 8-bit Q data format
+* Receiver signal chain:
+    * Optional DC offset removal (DC blocker)
+    * Configurable fs/4 shifter (quarter sample rate): bypass, shift up or shift down
+    * Configurable decimation rates: 1x, 2x, 4x, 8x, 16x, 32x
+* Transmitter signal chain:
+    * Configurable interpolation rates: 1x, 2x, 4x, 8x, 16x, 32x
+* SPI control interface for register configuration
+* Double data rate (DDR) interface to RF transceiver
+* Interface to MCU (SGPIO)
+
+
+Half-precision gateware
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The half-precision gateware reduces sample width to 4 bits per I/Q component, enabling higher throughput within the constraints of the USB interface (up to 40 Msps).
+
+This configuration is intended for applications where bandwidth is more critical than dynamic range, such as wideband spectrum monitoring.
+
+Block diagram
+^^^^^^^^^^^^^
+
+.. image:: ../images/gateware-basic-block-diagram.png
+        :align: center
+
+.. image:: ../images/gateware-halfprec-dsp-chain.png
+        :align: center
+        :width: 75%
+
+Features
+^^^^^^^^
+* 4-bit I, 4-bit Q data format
+* Receiver signal chain:
+    * Optional DC offset removal (DC blocker)
+    * Round to 4-bit I/Q
+* Transmitter signal chain:
+    * Extend width to 8-bit I/Q
+* SPI control interface for register configuration
+* Double data rate (DDR) interface to RF transceiver
+* Interface to MCU (SGPIO)
+
+Extended-precision gateware (RX and TX)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The extended-precision gateware increases internal signal processing precision and output sample width to improve signal quality. The main drawback is that the minimum decimation or interpolation factor is 16x. Due to increased logic requirements, this gateware is split in two top-level designs (RX and TX).
+
+Samples are 16-bit I/Q, while the effective number of bits (ENOB) depends on the selected configuration and typically ranges between 9 and 11 bits.
+
+The increased dynamic range of the output makes it particularly useful for weak and/or narrowband signals.
+
+Block diagram (RX)
+^^^^^^^^^^^^^^^^^^
+
+.. image:: ../images/gateware-rx-only-basic-block-diagram.png
+        :align: center
+
+.. image:: ../images/gateware-ext-prec-rx-dsp-chain.png
+        :align: center
+        :width: 75%
+
+Block diagram (TX)
+^^^^^^^^^^^^^^^^^^
+
+.. image:: ../images/gateware-tx-only-basic-block-diagram.png
+        :align: center
+
+.. image:: ../images/gateware-ext-prec-tx-dsp-chain.png
+        :align: center
+        :width: 75%
+
+Features
+^^^^^^^^
+* 16-bit I, 16-bit Q data format
+* Receiver signal chain (RX extended-precision gateware):
+    * Optional DC offset removal (DC blocker)
+    * Configurable mixer (in fs/128 steps)
+    * Configurable decimation rates: 16x, 32x, 64x, 128x
+* Transmitter signal chain (TX extended-precision gateware):
+    * Configurable interpolation rates: 16x, 32x, 64x, 128x
+* SPI control interface for register configuration
+* Double data rate (DDR) interface to RF transceiver
+* Interface to MCU (SGPIO)
+

docs/source/getting_help.rst

@@ -1,9 +1,11 @@
-================================================
+============
 Getting Help
-================================================
+============
 
-Before asking for help with HackRF, check to see if your question is listed in the :ref:`FAQ <faq>` or has already been answered in `GitHub issues <https://github.com/mossmann/hackrf/issues>`__ or the `mailing list archives <https://pairlist9.pair.net/pipermail/hackrf-dev/>`__.
+Before asking for help with HackRF, check to see if your question is answered in this documentation, listed in the :ref:`Troubleshooting <troubleshooting>` page, or addressed in the `HackRF GitHub repository issues <https://github.com/greatscottgadgets/hackrf/issues>`__.
 
-For assistance with HackRF use or development, please look at the `issues on the GitHub project <https://github.com/mossmann/hackrf/issues>`__. This is the preferred place to ask questions so that others may locate the answer to your question in the future.
+For assistance with HackRF general use or development, please look at the `issues on the GitHub project <https://github.com/greatscottgadgets/hackrf/issues>`__. This is the preferred place to ask questions so that others may locate the answer to your question in the future.
 
-Many users spend time in the `#hackrf channel on Discord <https://discord.gg/rsfMw3rsU8>`__. 
+We invite you to join our community discussions on `Discord <https://discord.gg/rsfMw3rsU8>`__. Note that while technical support requests are welcome here, we do not have support staff on duty at all times. Be sure to also submit an issue on GitHub if you’ve found a bug or if you want to ensure that your request will be tracked and not overlooked.
+
+If you wish to see past discussions and questions about HackRF, you may also view the `mailing list archives <https://pairlist9.pair.net/pipermail/hackrf-dev/>`__.

docs/source/getting_started_hackrf_gnuradio.rst

@@ -1,69 +0,0 @@
-================================================
-Getting Started with HackRF and GNU Radio
-================================================
-
-We recommend getting started by watching the `Software Defined Radio with HackRF <https://greatscottgadgets.com/sdr/>`__ video series. This series will introduce you to HackRF One, software including GNU Radio, and teach you the fundamentals of Digital Signal Processing (DSP) needed to take full advantage of the power of Software Defined Radio (SDR). Additional helpful information follows.
-
-.. _try_pentoo:
-
-Try Your HackRF with Pentoo Linux
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The easiest way to get started with your HackRF and ensure that it works is to use Pentoo, a Linux distribution with full support for HackRF and GNU Radio. Download the latest Pentoo .iso image from one of the mirrors listed at `http://pentoo.ch/downloads/ <https://pentoo.ch/downloads>`__. Then burn the .iso to a DVD or use `UNetbootin <http://unetbootin.sourceforge.net/>`__ to install the .iso on a USB flash drive. Boot your computer using the DVD or USB flash drive to run Pentoo. Do this natively, not in a virtual machine. (Unfortunately high speed USB operation invariably fails when people try to run HackRF from a virtual machine.)
-
-Once Pentoo is running, you can immediately use it to :ref:`update firmware <updating_firmware>` on your HackRF or use other HackRF command line tools. For a walkthrough, watch `SDR with HackRF, Lesson 5: HackRF One <http://greatscottgadgets.com/sdr/5/>`__.
-
-To verify that your HackRF is detected, type ``hackrf_info`` at the command line. It should produce a few lines of output including "Found HackRF board." The 3V3, 1V8, RF, and USB LEDs should all be illuminated and are various colors.
-
-You can type ``startx`` at the command line to launch a desktop environment. Accept the "default config" in the first dialog box. The desktop environment is useful for GNU Radio Companion and other graphical applications but is not required for basic operations such as firmware updates.
-
-Now you can use programs such as gnuradio-companion or gqrx to start experimenting with your HackRF. Try the Examples below. If you are new to GNU Radio, an excellent place to start is with the `SDR with HackRF <http://greatscottgadgets.com/sdr/>`__ video series or with the `GNU Radio guided tutorials <https://wiki.gnuradio.org/index.php/Tutorials>`__.
-
-**Alternative: GNU Radio Live SDR Environment**
-
-The `GNU Radio Live SDR Environment <https://wiki.gnuradio.org/index.php/GNU_Radio_Live_SDR_Environment>`__ is another nice bootable Linux .iso with support for HackRF and, of course, GNU Radio.
-
-Software Setup
-~~~~~~~~~~~~~~
-
-As mentioned above, the best way to get started with HackRF is to use Pentoo Linux. Eventually you may want to install software to use HackRF with your favorite operating system.
-
-If your package manager includes the most recent release of libhackrf and gr-osmosdr, then use it to install those packages in addition to GNU Radio. Otherwise, the recommended way to install these tools is by using `PyBOMBS <https://github.com/gnuradio/pybombs>`__.
-
-See the :ref:`Operating System Tips <operating_system_tips>` page for information on setting up HackRF software on particular Operating Systems and Linux distributions.
-
-If you have any trouble, make sure that things work when booted to Pentoo. This will allow you to easily determine if your problem is being caused by hardware or software, and it will give you a way to see how the software is supposed to function.
-
-Examples
-~~~~~~~~
-
-A great way to get started with HackRF is the `SDR with HackRF <http://greatscottgadgets.com/sdr/>`__ video series. Additional examples follow:
-
-Testing the HackRF
-
-   #.  Plug in the HackRF
-   #.  run the hackrf_info command ``$ hackrf_info``
-
-If everything is OK, you should see something similar to the following:
-
-.. code-block:: sh
-
-    hackrf_info version: 2017.02.1
-    libhackrf version: 2017.02.1 (0.5)
-    Found HackRF
-    Index: 0
-    Serial number: 0000000000000000################
-    Board ID Number: 2 (HackRF One)
-    Firmware Version: 2017.02.1 (API:1.02)
-    Part ID Number: 0x######## 0x########
-
-**FM Radio Example**
-
-This Example was derived from the following works:
-
-    * `RTL-SDR FM radio receiver with GNU Radio Companion <http://www.instructables.com/id/RTL-SDR-FM-radio-receiver-with-GNU-Radio-Companion/>`__
-    * `How To Build an FM Receiver with the USRP in Less Than 10 Minutes <https://www.youtube.com/watch?v=KWeY2yqwVA0>`__
-
-    #. Download the FM Radio Receiver python file `here <https://raw.githubusercontent.com/rrobotics/hackrf-tests/master/fm_radio/fm_radio_rx.py>`__
-    #. Run the file ``$ python ./fm_radio_rx.py``
-    #. You can find the GNU Radio Companion source file `here <https://raw.githubusercontent.com/rrobotics/hackrf-tests/master/fm_radio/fm_radio_rx.grc>`__

docs/source/hackrf_connectors.rst

@@ -0,0 +1,7 @@
+==========
+Connectors
+==========
+
+The connectors on both HackRF Pro and HackRF One are SMA.
+
+**Note:** SMA connectors and RP-SMA connectors are visually very similar. If you connect an RP-SMA antenna to a HackRF, it will seem to connect snugly but won't function at all because neither the male nor female side has a center pin. RP-SMA connectors are most common on 2.4 GHz antennas and are popular on Wi-Fi equipment. Adapters are available.

docs/source/hackrf_minimum_requirements.rst

@@ -0,0 +1,9 @@
+============================================
+Minimum Host System Requirements for HackRF
+============================================
+
+HackRF requires you to supply 500 mA at 5 V DC to your HackRF via the USB port. If your host computer has difficulty meeting this requirement, you may need to use a powered USB hub.
+
+There is no specific minimum CPU requirement for the host computer when using a HackRF, but SDR is generally a CPU-intensive application. If you have a slower CPU, you may be unable to run certain SDR software or you may only be able to operate at lower sample rates.
+
+Most users will want to stream data to or from the HackRF at high speeds. This requires that the host computer supports Hi-Speed USB. Some Hi-Speed USB hosts are better than others, and you may have multiple host controllers on your computer. If you have difficulty operating your HackRF at high sample rates (10 Msps to 20 Msps), try using a different USB port on your computer. If possible, arrange things so that the HackRF is the only device on the bus.

docs/source/hackrf_one.rst

@@ -2,12 +2,15 @@
 HackRF One
 ================================================
 
+.. _hackrf_one:
+
 .. image:: ../images/HackRF-One-fd0-0009.jpeg
   :alt: HackRF One
 
-HackRF One is the current hardware platform for the HackRF project. It is a Software Defined Radio peripheral capable of transmission or reception of radio signals from 1 MHz to 6 GHz. Designed to enable test and development of modern and next generation radio technologies, HackRF One is an open source hardware platform that can be used as a USB peripheral or programmed for stand-alone operation.
-
+HackRF One was the first production hardware platform for the HackRF project. It is a Software Defined Radio peripheral capable of transmission or reception of radio signals from 1 MHz to 6 GHz. Designed to enable test and development of modern and next generation radio technologies, HackRF One is an open source hardware platform that can be used as a USB peripheral or programmed for stand-alone operation.
 
+| `Product page <https://greatscottgadgets.com/hackrf/one/>`_
+| `Where to buy <https://greatscottgadgets.com/hackrf/one/#purchasing>`_
 
 Features
 ~~~~~~~~
@@ -25,4 +28,37 @@ Features
     * pin headers for expansion
     * portable
     * open source
-    
+
+
+Maximum input power
+~~~~~~~~~~~~~~~~~~~
+
+The maximum input power of HackRF One is -5 dBm. Exceeding -5 dBm can result in permanent damage!
+
+In theory, HackRF One can safely accept up to 10 dBm with the front-end RX amplifier disabled. However, a simple software or user error could enable the amplifier, resulting in permanent damage. It is better to use an external attenuator than to risk damage.
+
+
+Minimum detectable input power
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This isn't a question that can be answered for a general purpose SDR platform such as HackRF. Any answer would be very specific to a particular application. For example, an answerable question might be: What is the minimum power level in dBm of modulation M at frequency F that can be detected by HackRF One with software S under configuration C at a bit error rate of no more than E%? Changing any of those variables (M, F, S, C, or E) would change the answer to the question. Even a seemingly minor software update might result in a significantly different answer. To learn the exact answer for a specific application, you would have to measure it yourself.
+
+HackRF's concrete specifications include operating frequency range, maximum sample rate, and dynamic range in bits. These specifications can be used to roughly determine the suitability of HackRF for a given application. Testing is required to finely measure performance in an application. Performance can typically be enhanced significantly by selecting an appropriate antenna, external amplifier, and/or external filter for the application.
+
+
+Typical maximum transmit power
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+HackRF One's maximum TX power varies by operating frequency:
+
+    * 1 MHz to 10 MHz: 5 dBm to 15 dBm, generally increasing as frequency increases (see this `blog post <https://greatscottgadgets.com/2015/05-15-hackrf-one-at-1-mhz/>`__)
+    * 10 MHz to 2170 MHz: 5 dBm to 15 dBm, generally decreasing as frequency increases
+    * 2170 MHz to 2740 MHz: 13 dBm to 15 dBm
+    * 2740 MHz to 4000 MHz: 0 dBm to 5 dBm, decreasing as frequency increases
+    * 4000 MHz to 6000 MHz: -10 dBm to 0 dBm, generally decreasing as frequency increases
+
+Through most of the frequency range up to 4 GHz, the maximum TX power is between 0 and 10 dBm. The frequency range with best performance is 2170 MHz to 2740 MHz.
+
+Overall, the output power is enough to perform over-the-air experiments at close range or to drive an external amplifier. If you connect an external amplifier, you should also use an external bandpass filter for your operating frequency.
+
+Before you transmit, know your laws. HackRF One has not been tested for compliance with regulations governing transmission of radio signals. You are responsible for using your HackRF One legally.

docs/source/hackrf_pro.rst

@@ -0,0 +1,52 @@
+================================================
+HackRF Pro
+================================================
+
+.. _hackrf_pro:
+
+.. image:: ../images/hackrf-pro-preliminary-photo.jpg
+  :alt: HackRF Pro
+
+HackRF Pro is the current hardware platform for the HackRF project. It is a Software Defined Radio peripheral capable of transmission or reception of radio signals from 100 kHz to 6 GHz. HackRF Pro is designed to be backwards compatible with software and hardware developed for use with
+:ref:`HackRF One <hackrf_one>`,
+whilst introducing many new features and improvements.
+
+| `Product page <https://greatscottgadgets.com/hackrf/pro/>`_
+| `Where to buy <https://greatscottgadgets.com/hackrf/pro/#purchasing>`_
+
+Features
+~~~~~~~~
+
+    * 100 kHz to 6 GHz operating frequency
+    * Tunable from 0 Hz to 7.1 GHz
+    * Half-duplex transceiver
+    * Up to 20 million samples per second
+    * 8-bit quadrature samples (8-bit I and 8-bit Q)
+    * Compatible with GNU Radio, SDR#, and more
+    * Software-configurable RX and TX gain and baseband filter
+    * Software-controlled RF port power (50 mA at 3.3 V)
+    * SMA RF connector
+    * SMA clock input and output for synchronization and triggering
+    * Convenient buttons for programming
+    * Internal pin headers for expansion
+    * High-Speed USB 2.0 with Type-C connector
+    * USB-powered
+    * Open source hardware
+
+Compared to HackRF One, HackRF Pro introduces a host of new and updated features, including:
+
+    * Wider operating frequency range
+    * Improved RF performance with flatter frequency response
+    * Modern USB Type-C connector
+    * Built-in TCXO crystal oscillator for superior timing stability
+    * Logic upgrade from a CPLD to a power-efficient FPGA
+    * Elimination of the DC spike
+    * Extended-precision mode with 16-bit samples for low sample rates (typical ENOB: 9-11)
+    * Half-precision mode with 4-bit samples at up to 40 Msps
+    * More RAM and flash memory for custom firmware
+    * Installed shielding around the radio section
+    * Trigger input and output accessible through clock connectors
+    * Cutout in the PCB provides space for future add-ons
+    * Improved power management
+    * Enhanced RF port protection
+    * Facility to hardware-disable transmit mode

docs/source/hackrf_projects_mentions.rst

@@ -9,6 +9,7 @@ Have you done something cool with HackRF or mentioned HackRF in one of your pres
 * `LEGO car <http://ossmann.blogspot.com/2013/06/hackrf-lego-car.html>`__ (Michael Ossmann)
 * `wireless microphones <http://www.sharebrained.com/2013/06/15/wireless-microphones-and-hackrf/>`__ (Jared Boone)
 * `Tesla Charging Port Opener <https://github.com/rgerganov/tesla-opener>`__ (Radoslav Gerganov)
+* `Hacking my smart tooth brush <https://kuenzi.dev/toothbrush/>`__ (Cyrill Künzi)
 
 
 

docs/source/hackrf_sweep.rst

@@ -1,119 +0,0 @@
-================================================
-hackrf_sweep
-================================================
-
-Usage
-~~~~~
-
-.. code-block:: sh 
-
-    [-h] # this help
-    [-d serial_number] # Serial number of desired HackRF
-    [-a amp_enable] # RX RF amplifier 1=Enable, 0=Disable
-    [-f freq_min:freq_max] # minimum and maximum frequencies in MHz
-    [-p antenna_enable] # Antenna port power, 1=Enable, 0=Disable
-    [-l gain_db] # RX LNA (IF) gain, 0-40dB, 8dB steps
-    [-g gain_db] # RX VGA (baseband) gain, 0-62dB, 2dB steps
-    [-w bin_width] # FFT bin width (frequency resolution) in Hz, 2445-5000000
-    [-1] # one shot mode
-    [-N num_sweeps] # Number of sweeps to perform
-    [-B] # binary output
-    [-I] # binary inverse FFT output
-    -r filename # output file
-
-
-
-Output fields
-~~~~~~~~~~~~~
-
-``date, time, hz_low, hz_high, hz_bin_width, num_samples, dB, dB, ...``
-
-Running ``hackrf_sweep -f 2400:2490`` gives the following example results:
-
-.. list-table :: 
-  :header-rows: 1
-  :widths: 1 1 1 1 1 1 1 1 1 1 1
-
-  * - Date 	
-    - Time 	
-    - Hz Low 	
-    - Hz High 	
-    - Hz bin width 	
-    - Num Samples 	
-    - dB 	
-    - dB 	
-    - dB 	
-    - dB 	
-    - dB
-  * - 2019-01-03 	
-    - 11:57:34.967805 	
-    - 2400000000 	
-    - 2405000000 	
-    - 1000000.00 	
-    - 20 	
-    - -64.72 	
-    - -63.36 	
-    - -60.91 	
-    - -61.74 	
-    - -58.58
-  * - 2019-01-03 	
-    - 11:57:34.967805 	
-    - 2410000000 	
-    - 2415000000 	
-    - 1000000.00 	
-    - 20 	
-    - -69.22 	
-    - -60.67 	
-    - -59.50 	
-    - -61.81 	
-    - -58.16
-  * - 2019-01-03 	
-    - 11:57:34.967805 	
-    - 2405000000 	
-    - 2410000000 	
-    - 1000000.00 	
-    - 20 	
-    - -61.19 	
-    - -70.14 	
-    - -60.10 	
-    - -57.91 	
-    - -61.97
-  * - 2019-01-03 	
-    - 11:57:34.967805 	
-    - 2415000000 	
-    - 2420000000 	
-    - 1000000.00 	
-    - 20 	
-    - -72.93 	
-    - -79.14 	
-    - -68.79 	
-    - -70.71 	
-    - -82.78
-  * - 2019-01-03 	
-    - 11:57:34.967805 	
-    - 2420000000 	
-    - 2425000000 	
-    - 1000000.00 	
-    - 20 	
-    - -67.57 	
-    - -61.61 	
-    - -57.29 	
-    - -61.90 	
-    - -70.19
-  * - 2019-01-03 	
-    - 11:57:34.967805 	
-    - 2430000000 	
-    - 2435000000 	
-    - 1000000.00 	
-    - 20 	
-    - -56.04 	
-    - -59.58 	
-    - -66.24 	
-    - -66.02 	
-    - -62.12
-
-Each sweep across the entire specified frequency range is given a single time stamp.
-
-The fifth column tells you the width in Hz (1 MHz in this case) of each frequency bin, which you can set with ``-w``. The sixth column is the number of samples analyzed to produce that row of data.
-
-Each of the remaining columns shows the power detected in each of several frequency bins. In this case there are five bins, the first from 2400 to 2401 MHz, the second from 2401 to 2402 MHz, and so forth.

docs/source/hackrf_tools.rst

@@ -0,0 +1,139 @@
+============
+HackRF Tools
+============
+
+Great Scott Gadgets provides some commandline tools for interacting with HackRF. 
+    * **hackrf_info** Read device information from HackRF such as serial number and firmware version.
+
+    * **hackrf_transfer** Send and receive signals using HackRF. Input/output files are 8-bit signed quadrature samples.
+
+    * **hackrf_sweep**, a command-line spectrum analyzer.
+
+    * **hackrf_clock** Read and write clock input and output configuration.
+
+    * **hackrf_operacake** Configure Opera Cake antenna switch connected to HackRF.
+
+    * **hackrf_spiflash** A tool to write new firmware to HackRF. See: :ref:`Updating Firmware <updating_firmware>`.
+
+    * **hackrf_debug** Read and write registers and other low-level configuration for debugging.
+
+
+
+hackrf_sweep
+~~~~~~~~~~~~
+
+Usage
+^^^^^
+
+.. code-block:: sh 
+
+    [-h] # this help
+    [-d serial_number] # Serial number of desired HackRF
+    [-a amp_enable] # RX RF amplifier 1=Enable, 0=Disable
+    [-f freq_min:freq_max] # minimum and maximum frequencies in MHz
+    [-p antenna_enable] # Antenna port power, 1=Enable, 0=Disable
+    [-l gain_db] # RX LNA (IF) gain, 0-40dB, 8dB steps
+    [-g gain_db] # RX VGA (baseband) gain, 0-62dB, 2dB steps
+    [-w bin_width] # FFT bin width (frequency resolution) in Hz, 2445-5000000
+    [-1] # one shot mode
+    [-N num_sweeps] # Number of sweeps to perform
+    [-B] # binary output
+    [-I] # binary inverse FFT output
+    -r filename # output file
+
+
+
+Output fields
+^^^^^^^^^^^^^
+
+``date, time, hz_low, hz_high, hz_bin_width, num_samples, dB, dB, ...``
+
+Running ``hackrf_sweep -f 2400:2490`` gives the following example results:
+
+.. list-table :: 
+  :header-rows: 1
+  :widths: 1 1 1 1 1 1 1 1 1 1 1
+
+  * - Date  
+    - Time  
+    - Hz Low    
+    - Hz High   
+    - Hz bin width  
+    - Num Samples   
+    - dB    
+    - dB    
+    - dB    
+    - dB    
+    - dB
+  * - 2019-01-03    
+    - 11:57:34.967805   
+    - 2400000000    
+    - 2405000000    
+    - 1000000.00    
+    - 20    
+    - -64.72    
+    - -63.36    
+    - -60.91    
+    - -61.74    
+    - -58.58
+  * - 2019-01-03    
+    - 11:57:34.967805   
+    - 2410000000    
+    - 2415000000    
+    - 1000000.00    
+    - 20    
+    - -69.22    
+    - -60.67    
+    - -59.50    
+    - -61.81    
+    - -58.16
+  * - 2019-01-03    
+    - 11:57:34.967805   
+    - 2405000000    
+    - 2410000000    
+    - 1000000.00    
+    - 20    
+    - -61.19    
+    - -70.14    
+    - -60.10    
+    - -57.91    
+    - -61.97
+  * - 2019-01-03    
+    - 11:57:34.967805   
+    - 2415000000    
+    - 2420000000    
+    - 1000000.00    
+    - 20    
+    - -72.93    
+    - -79.14    
+    - -68.79    
+    - -70.71    
+    - -82.78
+  * - 2019-01-03    
+    - 11:57:34.967805   
+    - 2420000000    
+    - 2425000000    
+    - 1000000.00    
+    - 20    
+    - -67.57    
+    - -61.61    
+    - -57.29    
+    - -61.90    
+    - -70.19
+  * - 2019-01-03    
+    - 11:57:34.967805   
+    - 2430000000    
+    - 2435000000    
+    - 1000000.00    
+    - 20    
+    - -56.04    
+    - -59.58    
+    - -66.24    
+    - -66.02    
+    - -62.12
+
+Each sweep across the entire specified frequency range is given a single time stamp.
+
+The fifth column tells you the width in Hz (1 MHz in this case) of each frequency bin, which you can set with ``-w``. The sixth column is the number of samples analyzed to produce that row of data.
+
+Each of the remaining columns shows the power detected in each of several frequency bins. In this case there are five bins, the first from 2400 to 2401 MHz, the second from 2401 to 2402 MHz, and so forth.

docs/source/hackrfs_buttons.rst

@@ -1,11 +1,13 @@
-====================
-HackRF One's Buttons
-====================
+=======
+Buttons
+=======
 
-The RESET button resets the microcontroller. This is a reboot that should result in a USB re-enumeration.
+This information is applicable to both HackRF Pro and HackRF One.
 
-The DFU button invokes a USB DFU bootloader located in the microcontroller's ROM. This bootloader makes it possible to unbrick a HackRF One with damaged firmware because the ROM cannot be overwritten.
+The **RESET button** resets the microcontroller. This is a reboot that should result in a USB re-enumeration.
 
-To invoke DFU mode: Press and hold the DFU button. While holding the DFU button, reset the HackRF One either by pressing and releasing the RESET button or by powering on the HackRF One. Release the DFU button.
+The **DFU button** invokes a USB DFU bootloader located in the microcontroller's ROM. This bootloader makes it possible to unbrick a HackRF with damaged firmware because the ROM cannot be overwritten.
 
-The DFU button only invokes the bootloader during reset. This means that it can be used for other functions by custom firmware.
+The DFU button only invokes the bootloader during reset. This means that it can be used for other functions by custom firmware.
+
+To invoke DFU mode: Press and hold the DFU button. While holding the DFU button, reset the HackRF either by pressing and releasing the RESET button or by powering on the HackRF. Release the DFU button.

docs/source/hardware_components.rst

@@ -2,35 +2,17 @@
 Hardware Components
 ================================================
 
-Major parts used in HackRF One:
-
-* `MAX2837 2.3 to 2.7 GHz transceiver <https://www.analog.com/en/products/max2837.html>`__
-    * `Datasheet <https://www.analog.com/media/en/technical-documentation/data-sheets/max2837.pdf>`__
-* `MAX2839 2.3 to 2.7 GHz transceiver <https://www.analog.com/en/products/max2839.html>`__
-    * `Datasheet <https://www.analog.com/media/en/technical-documentation/data-sheets/max2839.pdf>`__
-    * substitution for MAX2837.
-* `MAX5864 ADC/DAC <https://www.analog.com/en/products/max5864.html>`__
-    * `Datasheet <https://www.analog.com/media/en/technical-documentation/data-sheets/MAX5864.pdf>`__
-* `Si5351 clock generator <http://www.silabs.com/products/clocksoscillators/clock-generator/Pages/lvcmos-clocks-5-outputs.aspx>`__
-    * `AN619: Manually Generating an Si5351 Register Map <http://www.silabs.com/Support%20Documents/TechnicalDocs/AN619.pdf>`__
-    * `Datasheet <http://www.silabs.com/Support%20Documents/TechnicalDocs/Si5351.pdf>`__ - see AN619 for the complete register map.
-    * `Other Documentation <http://www.silabs.com/products/clocksoscillators/clock-generators-and-buffers/Pages/clock+vcxo.aspx>`__ - includes application notes, user guides, and white papers.
-* CoolRunner-II CPLD
-* `LPC43xx ARM Cortex-M4 microcontroller <http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/lpc-arm-cortex-m-mcus/lpc-dual-core-cortex-m0-m4f/lpc4300:MC_1403790133078>`__
-    * `User Manual <http://www.nxp.com/documents/user_manual/UM10503.pdf>`__
-    * `Datasheet <http://www.nxp.com/documents/data_sheet/LPC4350_30_20_10.pdf>`__
-    * `Other Documentation (LPC4330FBD144) <http://www.nxp.com/products/microcontrollers/cortex_m4/lpc4300/LPC4330FBD144.html#documentation>`__ - includes errata and application notes.
-    * `ARM-standard JTAG/SWD connector pinout <http://www.keil.com/support/man/docs/ulink2/ulink2_hw_connectors.htm>`__
-    * `BSDL file for the LPC43xx (For boundary scan) <http://www.lpcware.com/system/files/LPC18xx_43xx%20BSDL%20files%2020121127_0.zip>`__
-* `RFFC5072 mixer/synthesizer <http://www.rfmd.com/store/rffc5072-1.html>`__
-    * `Datasheet <http://www.rfmd.com/CS/Documents/RFFC5071_2DS.pdf>`__
-    * `Other Documentation <http://www.rfmd.com/store/rffc5072-1.html>`__ ; click "Technical Documents" - includes programming guides and application notes.
-* `W25Q80BV 8M-bit Flash <https://www.winbond.com/resource-files/w25q80bv%20revk%2020151203.pdf>`__
-
-
 Block Diagrams
 ~~~~~~~~~~~~~~
 
+HackRF Pro Block Diagram
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ../images/block-diagram-pro.png
+        :align: center
+
+|
+
 HackRF One r1-r8 Block Diagram
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -44,3 +26,40 @@ HackRF One r9 Block Diagram
 
 .. image:: ../images/block-diagram-r9.png
         :align: center
+
+|
+
+Key Components
+~~~~~~~~~~~~~~
+
+Major parts used in HackRF:
+
+* `MAX2831 2.3 to 2.6 GHz transceiver <https://www.analog.com/en/products/max2831.html>`__
+    * Used on HackRF Pro.
+    * `Datasheet <https://www.analog.com/media/en/technical-documentation/data-sheets/MAX2831-MAX2832.pdf>`__
+
+* `MAX2837 2.3 to 2.7 GHz transceiver <https://www.analog.com/en/products/max2837.html>`__
+    * Used on HackRF One (except revision r9), Jawbreaker and rad1o.
+    * `Datasheet <https://www.analog.com/media/en/technical-documentation/data-sheets/max2837.pdf>`__
+* `MAX2839 2.3 to 2.7 GHz transceiver <https://www.analog.com/en/products/max2839.html>`__
+    * Substitution for MAX2837, used on HackRF One revision r9.
+    * `Datasheet <https://www.analog.com/media/en/technical-documentation/data-sheets/max2839.pdf>`__
+* `MAX5864 ADC/DAC <https://www.analog.com/en/products/max5864.html>`__
+    * `Datasheet <https://www.analog.com/media/en/technical-documentation/data-sheets/MAX5864.pdf>`__
+* `Si5351 clock generator <http://www.silabs.com/products/clocksoscillators/clock-generator/Pages/lvcmos-clocks-5-outputs.aspx>`__
+    * `AN619: Manually Generating an Si5351 Register Map <http://www.silabs.com/Support%20Documents/TechnicalDocs/AN619.pdf>`__
+    * `Datasheet <http://www.silabs.com/Support%20Documents/TechnicalDocs/Si5351.pdf>`__ - see AN619 for the complete register map.
+    * `Other Documentation <http://www.silabs.com/products/clocksoscillators/clock-generators-and-buffers/Pages/clock+vcxo.aspx>`__ - includes application notes, user guides, and white papers.
+* `ice40 UltraPlus FPGA <https://www.latticesemi.com/en/Products/FPGAandCPLD/iCE40UltraPlus>`__ (HackRF Pro)
+* CoolRunner-II CPLD (all other platforms)
+* `LPC43xx ARM Cortex-M4 microcontroller <http://www.nxp.com/products/microcontrollers-and-processors/arm-processors/lpc-arm-cortex-m-mcus/lpc-dual-core-cortex-m0-m4f/lpc4300:MC_1403790133078>`__
+    * `User Manual <http://www.nxp.com/documents/user_manual/UM10503.pdf>`__
+    * `Datasheet <http://www.nxp.com/documents/data_sheet/LPC4350_30_20_10.pdf>`__
+    * `Other Documentation (LPC4330FBD144) <http://www.nxp.com/products/microcontrollers/cortex_m4/lpc4300/LPC4330FBD144.html#documentation>`__ - includes errata and application notes.
+    * `ARM-standard JTAG/SWD connector pinout <http://www.keil.com/support/man/docs/ulink2/ulink2_hw_connectors.htm>`__
+    * `BSDL file for the LPC43xx (For boundary scan) <http://www.lpcware.com/system/files/LPC18xx_43xx%20BSDL%20files%2020121127_0.zip>`__
+* `RFFC5072 mixer/synthesizer <http://www.rfmd.com/store/rffc5072-1.html>`__
+    * `Datasheet <http://www.rfmd.com/CS/Documents/RFFC5071_2DS.pdf>`__
+    * `Other Documentation <http://www.rfmd.com/store/rffc5072-1.html>`__ ; click "Technical Documents" - includes programming guides and application notes.
+* `W25Q32 32M-bit Flash <https://www.winbond.com/resource-files/W25Q32JV%20RevJ%2012242024%20Plus.pdf>`__ (HackRF Pro)
+* `W25Q80BV 8M-bit Flash <https://www.winbond.com/resource-files/w25q80bv%20revk%2020151203.pdf>`__ (all other platforms)

docs/source/hardware_triggering.rst

@@ -1,35 +1,61 @@
+.. _hardware_triggering:
+
 ===================
 Hardware Triggering
 ===================
 
-HackRF One transmit and receive operations can be synchronized with another HackRF One or with other external equipment by using the trigger input and output on pin header P28. Triggering provides time synchronization with error of less than one sample period.
+HackRF transmit and receive operations can be synchronized with another HackRF or with other external equipment by using the trigger input and output. Triggering provides time synchronization with error of less than one sample period.
 
+HackRF Pro has two configurable SMA ports, P1 and P2, which can be set up to provide both clock synchronization and triggering.
+
+HackRF One has CLKIN and CLKOUT ports for clock synchronization, but hardware triggering requires opening the case to access the P28 header.
 
 Clock Synchronization
 ~~~~~~~~~~~~~~~~~~~~~
 
-When triggering one HackRF One from another, it is often desirable to first ensure that the two devices share a common frequency reference. This has an added benefit of grounding the HackRFs to each other, eliminating one of the wires required for triggering. See :ref:`External Clock Interface <external_clock_interface>` for instructions.
+When triggering one HackRF from another, it is often desirable to first ensure that the two devices share a common frequency reference. This has an added benefit of grounding the HackRFs to each other, eliminating one of the wires required for triggering. See :ref:`External Clock Interface <external_clock_interface>` for instructions.
 
-Either HackRF One may serve as the clock source for the other regardless of which is providing the trigger output.
+Either HackRF may serve as the clock source for the other regardless of which is providing the trigger output.
+
+Usage
+~~~~~
+
+Use ``hackrf_info`` to discover the serial numbers of both HackRFs. Using the serial number of the HackRF to be triggered, use ``hackrf_transfer -H`` to set up a triggered operation. For example:
+
+* ``hackrf_transfer -H -d <serial number> -a 0 -l 32 -g 32 -r rx1.cs8``
+
+The command will print "Waiting for trigger..." until a trigger signal is detected on the device's trigger input.
+
+In another terminal, use the serial number of the triggering HackRF One to initiate an operation to take place at the same time as the triggered operation. For example:
+
+* ``hackrf_transfer -d <serial number> -a 0 -l 32 -g 32 -r rx2.cs8``
+
+Note that no special argument is required to activate the trigger output.
+
+Both ``hackrf_transfer`` commands will start sampling RF signals at the same time, accurate to less than one sample period.
 
 
-Requirements
-~~~~~~~~~~~~
+Additional Devices
+~~~~~~~~~~~~~~~~~~
+
+Multiple HackRFs may be triggered by a single HackRF. Ensure that all the devices share a common ground and then connect one device's trigger output to the trigger inputs of the other devices (with jumpers connected via a breadboard, for example).
+
+Equipment other than a HackRF may be connected to a HackRF's trigger input or output. The trigger signal is a 3.3 V pulse that triggers on the rising edge.
+
+HackRF One Triggering Requirements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 To connect two HackRF Ones for triggering you will need:
 
     * a male-to-male jumper wire for 0.1" pin headers
     * an SMA cable for clock synchronization or a second jumper wire
 
-
 .. _open_your_hackrf_one:
 
 Open Your HackRF One
 ~~~~~~~~~~~~~~~~~~~~
 
-The HackRF One case has small plastic clips holding it together. These may be damaged when the case is opened, but typically the case can still be used after such damage. Please follow the instructions in `this video <https://www.youtube.com/watch?v=zuXJtpTSEJM>`__ by `Jared Boone <https://twitter.com/sharebrained>`__.
-
-Open the enclosures of both HackRF Ones to access their pin headers.
+If your HackRF Ones are not bare boards, you will need to open up their cases to access the pin headers on the HackRF Ones. Each HackRF One case has small plastic clips holding it together. These clips may be damaged when the case is opened, but typically the case can still be used after such damage. Please follow the instructions in `this video <https://www.youtube.com/watch?v=zuXJtpTSEJM>`__ by `Jared Boone <https://twitter.com/sharebrained>`__ to open your HackRF One cases.
 
 
 Identify the Trigger Pins
@@ -49,32 +75,6 @@ First ensure that the two devices share a common ground. This may be accomplishe
 Next use a jumper wire to connect P28 pin 15 (trigger output) on one HackRF One to P28 pin 16 (trigger input) on the other HackRF One.
 
 
-Usage
-~~~~~
-
-Use ``hackrf_info`` to discover the serial numbers of both HackRF Ones. Using the serial number of the HackRF One to be triggered, use ``hackrf_transfer -H`` to set up a triggered operation. For example:
-
-* ``hackrf_transfer -H -d <serial number> -a 0 -l 32 -g 32 -r rx1.cs8``
-
-The command will print "Waiting for trigger..." until a trigger signal is detected on the device's trigger input.
-
-In another terminal, use the serial number of the triggering HackRF One to initiate an operation to take place at the same time as the triggered operation. For example:
-
-* ``hackrf_transfer -d <serial number> -a 0 -l 32 -g 32 -r rx2.cs8``
-
-Note that no special argument is required to activate the trigger output.
-
-Both ``hackrf_transfer`` commands will start sampling RF signals at the same time, accurate to less than one sample period.
-
-
-Additional Devices
-~~~~~~~~~~~~~~~~~~
-
-Multiple HackRF Ones may be triggered by a single HackRF One. Ensure that all the devices share a common ground and then connect one device's trigger output to the trigger inputs of the other devices (with jumpers connected via a breadboard, for example).
-
-Equipment other than a HackRF One may be connected to a HackRF One's trigger input or output. The trigger signal is a 3.3 V pulse that triggers on the rising edge.
-
-
 References
 ~~~~~~~~~~
 

docs/source/index.rst

@@ -6,23 +6,36 @@ Welcome to HackRF's documentation!
    :maxdepth: 2
    :caption: User Documentation
 
-   hackrf_one
-   jawbreaker   
-   faq
-   troubleshooting
    getting_help
-   tips_tricks
+   troubleshooting
+   synchronization_checklist
    hackrf_projects_mentions
 
 .. toctree::
    :maxdepth: 2
-   :caption: Software
+   :caption: Hardware Platforms
 
-   installing_hackrf_software
-   getting_started_hackrf_gnuradio
-   software_support
-   libhackrf_api
-   hackrf_sweep
+   hackrf_pro
+   hackrf_one
+   rad1o
+   jawbreaker
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Hardware Information
+
+   hackrf_minimum_requirements
+   list_of_hardware_revisions
+   hardware_components 
+   leds 
+   hackrfs_buttons
+   hackrf_connectors
+   external_clock_interface
+   expansion_interface
+   hardware_triggering
+   enclosure_options    
+   usb_cables
+   rf_shield_installation   
 
 .. toctree::
    :maxdepth: 2
@@ -35,16 +48,21 @@ Welcome to HackRF's documentation!
 
 .. toctree::
    :maxdepth: 2
-   :caption: Hardware
+   :caption: Software
 
-   list_of_hardware_revisions
-   hardware_components
-   enclosure_options   
-   hackrfs_buttons
-   external_clock_interface
-   expansion_interface
-   hardware_triggering
-   rf_shield_installation
+   installing_hackrf_software
+   hackrf_tools
+   software_support
+   sampling_rate
+   setting_gain
+   virtual_machines
+
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Gateware
+
+   gateware
 
 .. toctree::
    :maxdepth: 2
@@ -56,4 +74,5 @@ Welcome to HackRF's documentation!
    opera_cake_board_addressing
    opera_cake_port_configuration
    opera_cake_modes_of_operation
-        
+
+ 

docs/source/installing_hackrf_software.rst

@@ -1,8 +1,12 @@
 .. _operating_system_tips:
 
-================================================
+==========================
 Installing HackRF Software
-================================================
+==========================
+
+HackRF software includes HackRF Tools and libhackrf. HackRF Tools are the commandline utilities that let you interact with your HackRF. libhackrf is a low level library that enables software on your computer to operate with HackRF. 
+
+
 
 Install Using Package Managers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -58,17 +62,23 @@ OS X (10.5+): MacPorts
 Windows: Binaries
 +++++++++++++++++
 
-Binaries are provided as part of the PothosSDR project, they can be downloaded `here <http://downloads.myriadrf.org/builds/PothosSDR/?C=M;O=D>`__.
+Windows users can use `radioconda <https://github.com/ryanvolz/radioconda>`__ to get the required binaries installed.
+
+Alternatively, binaries are available as build artifacts under the 'Actions'-tab on github `here <https://github.com/greatscottgadgets/hackrf/actions>`__ (GitHub Login needed).
+
+
 
 -----------
 
+
+
 Installing From Source
 ~~~~~~~~~~~~~~~~~~~~~~
 
 Linux / OS X / \*BSD: Building HackRF Software From Source
 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
-Acquire the source for the HackRF tools from either a `release archive <https://github.com/mossmann/hackrf/releases>`__ or git: ``git clone https://github.com/mossmann/hackrf.git``
+Acquire the source for the HackRF tools from either a `release archive <https://github.com/greatscottgadgets/hackrf/releases>`__ or git: ``git clone https://github.com/greatscottgadgets/hackrf.git``
 
 Once you have the source downloaded, the host tools can be built as follows:
 
@@ -84,60 +94,32 @@ Once you have the source downloaded, the host tools can be built as follows:
 
 If you have HackRF hardware, you may need to :ref:`update the firmware <updating_firmware>` to match the host tools versions.
 
-
-
-Windows: Prerequisites for Cygwin, MinGW, or Visual Studio
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-
-    * cmake-2.8.12.1 or later from http://www.cmake.org/cmake/resources/software.html
-    * libusbx-1.0.18 or later from http://sourceforge.net/projects/libusbx/files/latest/download?source=files
-    * fftw-3.3.5 or later from http://www.fftw.org/install/windows.html
-    * Install Windows driver for HackRF hardware or use Zadig see http://sourceforge.net/projects/libwdi/files/zadig
-        * If you want to use Zadig select HackRF USB device and just install/replace it with WinUSB driver.
-
-Note for Windows build: You shall always execute hackrf-tools from Windows command shell and not from Cygwin or MinGW shell because on Cygwin/MinGW Ctrl+C is not managed correctly and especially for hackrf_transfer the Ctrl+C (abort) will not stop correctly and will corrupt the file.
-
-
-
-Windows: Installing HackRF Software via Cygwin
-++++++++++++++++++++++++++++++++++++++++++++++
-
-.. code-block :: sh
-
-	mkdir host/build
-	cd host/build
-	cmake ../ -G "Unix Makefiles" -DCMAKE_LEGACY_CYGWIN_WIN32=1 -DLIBUSB_INCLUDE_DIR=/usr/local/include/libusb-1.0/
-	make
-	make install
-
-
-
-Windows: Installing HackRF Software via MinGW
+Windows: Building HackRF Software From Source
 +++++++++++++++++++++++++++++++++++++++++++++
 
-.. code-block :: sh
+Install `Visual Studio Community <https://visualstudio.microsoft.com/vs/community/>`__ (2015 or later) and `CMake <https://cmake.org/>`__ (at least version 3.21.4).
 
-	mkdir host/build
-	cd host/build
-	cmake ../ -G "MSYS Makefiles" -DLIBUSB_INCLUDE_DIR=/usr/local/include/libusb-1.0/
-	make
-	make install
+Install library dependencies using `vcpkg <https://vcpkg.io/en/>`__:
 
+.. code-block :: winbatch
 
+	git clone https://github.com/microsoft/vcpkg
+	cd vcpkg
+	bootstrap-vcpkg.bat
+	vcpkg install libusb fftw3 pthreads pkgconf
 
-Windows: Installing HackRF Software via Visual Studio 2015 x64
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+Open the Visual Studio Developer Command Prompt, and change to the directory where you unpacked the HackRF source.
 
-Create library definition for MSVC to link to ``C:\fftw-3.3.5-dll64> lib /machine:x64 /def:libfftw3f-3.def``
+The following steps assume you installed vcpkg in ``C:\vcpkg``.
 
-.. code-block :: sh
+Configure CMake and build the code:
 
-	c:\hackrf\host\build> cmake ../ -G "Visual Studio 14 2015 Win64" \
-	-DLIBUSB_INCLUDE_DIR=c:\libusb-1.0.21\libusb \
-	-DLIBUSB_LIBRARIES=c:\libusb-1.0.21\MS64\dll\lib\libusb-1.0.lib \
-	-DTHREADS_PTHREADS_INCLUDE_DIR=c:\pthreads-w32-2-9-1-release\Pre-built.2\include \
-	-DTHREADS_PTHREADS_WIN32_LIBRARY=c:\pthreads-w32-2-9-1-release\Pre-built.2\lib\x64\pthreadVC2.lib \
-	-DFFTW_INCLUDES=C:\fftw-3.3.5-dll64 \
-	-DFFTW_LIBRARIES=C:\fftw-3.3.5-dll64\libfftw3f-3.lib
+.. code-block :: winbatch
 
-CMake will produce a solution file named ``HackRF.sln`` and a series of project files which can be built with msbuild as follows: ``c:\hackrf\host\build> msbuild HackRF.sln``
+	set PKG_CONFIG=C:\vcpkg\installed\x64-windows\tools\pkgconf\pkgconf.exe
+	set PKG_CONFIG_PATH=C:\vcpkg\installed\x64-windows\lib\pkgconfig
+	set CMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake
+	cmake -B host\build host
+	cmake --build host\build
+
+CMake will generate a ``HackRF.sln`` project file which you can open in Visual Studio for editing and development.

docs/source/jawbreaker.rst

@@ -1,10 +1,16 @@
-================================================
+==========
 Jawbreaker
-================================================
+==========
 
 HackRF Jawbreaker is the beta test hardware platform for the HackRF project.
 
 
+.. image:: ../images/jawbreaker.JPG
+  :alt: Jawbreaker
+
+(Jawbreaker picture provided by `fd0 <https://github.com/fd0>`__ with Creative Commons License CC BY 3.0.)
+
+
 
 Features
 ~~~~~~~~
@@ -20,53 +26,48 @@ Features
 
 
 
-Set your Jawbreaker Free!
-~~~~~~~~~~~~~~~~~~~~~~~~~
+Hardware Documentation
+~~~~~~~~~~~~~~~~~~~~~~
 
-Jawbreaker has an SMA antenna connector but also includes a built-in PCB antenna intended for operation near 900 MHz. It isn't a very good antenna. Seriously. A paperclip stuck into the SMA connector would probably be better. You can free your Jawbreaker to operate with better antennas by cutting the PCB trace to the PCB antenna with a knife. This enables the SMA connector to be used without interference from the PCB antenna.
-
-A video that demonstrates the antenna modification is on YouTube: `HackRF Antenna Modification <http://youtu.be/B2gwgNoqMxI>`__
-
-The trace to be cut is between the two solder pads inside a box labeled R44 in the `assembly diagram <https://github.com/mossmann/hackrf/blob/master/doc/hardware/jawbreaker-assembly.pdf?raw=true>`__. There is an arrow pointing to it printed on the board.
-
-Due to a manufacturing error, there is solder on R44. R44 may appear as a single solder blob. If you have a soldering iron and solder wick/braid, use a soldering iron and fine solder wick to remove as much solder as you can from the two R44 pads. Then, use a pen knife to gently cut away the area between the two R44 pads. Make multiple, gentle cuts, instead of one or two forceful cuts. As you cut, you'll break through the black solder mask, then the copper trace between the pads, and stop when you reach fiberglass. Remove the copper trace completely, so just the two R44 pads remain. Use a multimeter or continuity tester to verify that the two R44 pads are no longer connected.
-
-If you don't have a soldering iron, you can cut through the copper trace and the solder blob all at once, but it requires a bit more effort.
-
-The only reason not to do this is if you want to try Jawbreaker but don't have any antenna with an SMA connector (or adapter).
-
-If you want to restore the PCB antenna for some reason, you can install a 10 nF capacitor or a 0 ohm resistor on the R44 pads or you may be able to simply create a solder bridge.
-
-
-
-SMA, not RP-SMA
-~~~~~~~~~~~~~~~
-
-Some connectors that appear to be SMA are actually RP-SMA. If you connect an RP-SMA antenna to Jawbreaker, it will seem to connect snugly but won't function at all because neither the male nor female side has a center pin. RP-SMA connectors are most common on 2.4 GHz antennas and are popular on Wi-Fi equipment.
+Schematic diagram, assembly diagram, and bill of materials can be found at `https://github.com/greatscottgadgets/hackrf/tree/master/hardware <https://github.com/greatscottgadgets/hackrf/tree/master/hardware>`__
 
 
 
 Transmit Power
 ~~~~~~~~~~~~~~
 
-The maximum TX power varies by operating frequency:
+The maximum TX power for Jawbreaker varies by operating frequency:
 
     * 30 MHz to 100 MHz: 5 dBm to 15 dBm, increasing as frequency decreases
     * 100 MHz to 2300 MHz: 0 dBm to 10 dBm, increasing as frequency decreases
-    * 2300 MHz to 2700 MHz: 10 dBm to 15 dBm
+    * 2170 MHz to 2740 MHz: 10 dBm to 15 dBm
     * 2700 MHz to 4000 MHz: -5 dBm to 5 dBm, increasing as frequency decreases
     * 4000 MHz to 6000 MHz: -15 dBm to 0 dBm, increasing as frequency decreases
 
 Overall, the output power is enough to perform over-the-air experiments at close range or to drive an external amplifier. If you connect an external amplifier, you should also use an external bandpass filter for your operating frequency.
 
-Before you transmit, know your laws. Jawbreaker has not been tested for compliance with regulations governing transmission of radio signals. You are responsible for using your Jawbreaker legally.
+Before you transmit, know the laws for the region you are transmitting in. Jawbreaker has not been tested for compliance with regulations governing transmission of radio signals. You are responsible for using your Jawbreaker legally.
 
 
 
-Hardware Documentation
-~~~~~~~~~~~~~~~~~~~~~~
+SMA, not RP-SMA
+~~~~~~~~~~~~~~~
 
-Schematic diagram, assembly diagram,and bill of materials can be found at `https://github.com/mossmann/hackrf/tree/master/doc/hardware <https://github.com/mossmann/hackrf/tree/master/doc/hardware>`__
+The connectors on Jawbreaker are SMA, not RP-SMA. SMA connectors and RP-SMA connectors look extremely similar, the difference is that SMA connectors have a center pin. RP-SMA connectors are common on 2.4 GHz antennas and are popular on Wi-Fi equipment. If you connect an RP-SMA antenna to Jawbreaker, it will seem to connect snugly but won't function at all because neither the male nor female side has a center pin. 
+
+
+
+Recommended PCB and Antenna Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Jawbreaker has an SMA antenna connector and it also includes a built-in PCB antenna intended for operation near 900 MHz. The built-in PCB antenna isn't a very good antenna. A paperclip stuck into the SMA connector of the Jawbreaker is likely to be better. We recommend that you free your Jawbreaker to operate with better antennas by cutting the PCB trace to the PCB antenna with a knife. This enables the SMA connector to be used without interference from the PCB antenna.
+
+
+The trace to be cut is between the two solder pads inside a box labeled R44. There is an arrow printed on the board that points to the R44 box. A video that demonstrates the antenna modification is on YouTube: `HackRF Antenna Modification <http://youtu.be/B2gwgNoqMxI>`__.
+
+Due to a manufacturing error, there is solder on the pads in box R44 that you should try to remove before you cut the trace. R44 may appear as a single solder blob. If you have a soldering iron and solder wick/braid, use a soldering iron and fine solder wick to remove as much solder as you can from the two R44 pads. Then, use a pen knife to gently cut away the area between the two R44 pads. Make multiple, gentle cuts, instead of one or two forceful cuts. As you cut, you'll break through the black solder mask, then the copper trace between the pads, and stop when you reach fiberglass. Remove the copper trace completely, so just the two R44 pads remain. Use a multimeter or continuity tester to verify that the two R44 pads are no longer connected. If you don't have a soldering iron, you can cut through the copper trace and the solder blob all at once, but it requires a bit more effort. The only reason not to cut the PCB trace is if you want to try Jawbreaker but don't have any antenna with an SMA connector (or adapter).
+
+If you want to restore the PCB antenna for some reason, you can install a 10 nF capacitor or a 0 ohm resistor on the R44 pads or you may be able to simply create a solder bridge.
 
 
 
@@ -536,14 +537,14 @@ Cut P17 short (trace) to enable external clock input. If short is cut, a jumper
 More
 ^^^^
 
-Additional headers are available. See the `board files <https://github.com/mossmann/hackrf/tree/master/hardware/jawbreaker>`__ for additional details.
+Additional headers are available. See the `board files <https://github.com/greatscottgadgets/hackrf/tree/master/hardware/jawbreaker>`__ for additional details.
 
 
 
 Differences between Jawbreaker and HackRF One
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Jawbreaker was the beta platform that preceded HackRF One. HackRF One incorporates the following changes and enhancements:
+Jawbreaker was the beta platform that preceded HackRF One. HackRF One incorporates the following changes and enhancements (at minimum):
 
     * Antenna port: No modification is necessary to use the SMA antenna port on HackRF One.
     * PCB antenna: Removed.

docs/source/leds.rst

@@ -0,0 +1,20 @@
+====
+LEDs
+====
+
+HackRF Pro
+~~~~~~~~~~
+
+When HackRF Pro is plugged in to a USB host, four LEDs should turn on: MCU, FPGA, RF, and USB. The MCU LED indicates that the primary internal power supply is working properly and that firmware is running. The FPGA and RF LEDs indicate that firmware has switched on additional internal power supplies. The USB LED indicates that the HackRF Pro is communicating with the host over USB.
+
+HackRF One
+~~~~~~~~~~
+
+When HackRF One is plugged in to a USB host, four LEDs should turn on: 3V3, 1V8, RF, and USB. The 3V3 LED indicates that the primary internal power supply is working properly. The 1V8 and RF LEDs indicate that firmware is running and has switched on additional internal power supplies. The USB LED indicates that the HackRF One is communicating with the host over USB.
+
+Both versions
+~~~~~~~~~~~~~
+
+The RX and TX LEDs indicate that a receive or transmit operation is currently in progress.
+
+Each LED is a single color. There are no multi-colored LEDs on either HackRF One or HackRF Pro. Adjacent LEDs are different colors in order to make them easier to distinguish from one another. The colors do not mean anything.

docs/source/libhackrf_api.rst

@@ -1,575 +0,0 @@
-================================================
-libhackRF API
-================================================
-
-
-
-This document describes the functions, data structures and constants that libHackRF provides. It should be used as a reference for using libHackRF and the HackRF hardware.
-
-If you are writing a generic SDR application, i.e. not tied to the HackRF hardware, we strongly recommend that you use either gr-osmosdr or SoapySDR to provide support for the broadest possible range of software defined radio hardware.
-
-For example usage of many of these functions, see the `hackrf_transfer <https://github.com/mossmann/hackrf/blob/master/host/hackrf-tools/src/hackrf_transfer.c>`__ tool.
-
-
-
-Setup, Initialization and Shutdown
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF Init
-^^^^^^^^^^^
-
-Initialize libHackRF, including global libUSB context to support multiple HackRF hardware devices.
-
-**Syntax:** ``int hackrf_init()``
-
-**Returns:** A value from the hackrf_error constants listed below.
-
-
-
-HackRF Open
-^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_open(hackrf_device** device)``
-
-**Returns:** A value from the hackrf_error constants listed below.
-
-
-
-HackRF Device List
-^^^^^^^^^^^^^^^^^^
-
-Retrieve a list of HackRF devices attached to the system. This function finds all devices, regardless of permissions or availability of the hardware.
-
-**Syntax:** ``hackrf_device_list_t* hackrf_device_list()``
-
-**Returns:** A pointer to a hackrf_device_list_t struct, a list of HackRF devices attached to the system. The contents of the hackrf_device_list_t struct are decribed in the data structures section below.
-
-
-
-
-HackRF Device List Open
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Open and acquire a handle on a device from the hackrf_device_list_t struct.
-
-**Syntax:** ``int hackrf_device_list_open(hackrf_device_list_t* list, int idx, hackrf_device** device)``
-
-**Params:**
-
-``list`` - A pointer to a hackrf_device_list_t returned by ``hackrf_device_list()``
-
-``idx`` - The list index of the HackRF device to open
-
-``device`` - Output location for hackrf_device pointer. Only valid when return value is HACKRF_SUCCESS.
-
-**Returns:** A value from the hackrf_error constants listed below.
-
-
-
-HackRF Device List Free
-^^^^^^^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``void hackrf_device_list_free(hackrf_device_list_t* list)``
-
-**Params:**
-
-``list`` - A pointer to a hackrf_device_list_t returned by ``hackrf_device_list()``
-
-
-
-
-HackRF Open By Serial
-^^^^^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_open_by_serial(const char* const desired_serial_number, hackrf_device** device)``
-
-**Returns:**
-
-
-
-HackRF Close
-^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_close(hackrf_device* device)``
-
-**Returns:** A value from the hackrf_error constants listed below.
-
-
-
-HackRF Exit
-^^^^^^^^^^^
-
-Cleanly shutdown libHackRF and the underlying USB context. This does not stop in progress transfers or close the HackRF hardware. ``hackrf_close()`` should be called before this to cleanly close the connection to the hardware.
-
-**Syntax:** ``int hackrf_exit()``
-
-**Returns:** A value from the hackrf_error constants listed below.
-
-
-
-Using the Radio
-~~~~~~~~~~~~~~~
-
-HackRF Start Rx
-^^^^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_start_rx(hackrf_device*, hackrf_sample_block_cb_fn, void* rx_ctx)``
-
-**Params:**
-
-**Returns:** A value from the hackrf_error constants listed below.
-
-
-
-
-HackRF Stop Rx
-^^^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_stop_rx(hackrf_device*)``
-
-**Params:**
-
-**Returns:** A value from the hackrf_error constants listed below.
-
-
-
-
-HackRF Start Tx
-^^^^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_start_tx(hackrf_device*, hackrf_sample_block_cb_fn, void* tx_ctx)``
-
-**Params:**
-
-**Returns:** A value from the hackrf_error constants listed below.
-
-
-
-HackRF Stop Tx
-^^^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_stop_tx(hackrf_device*)``
-
-**Params:**
-
-**Returns:** A value from the hackrf_error constants listed below.
-
-
-
-HackRF Set Baseband Filter Bandwidth
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_set_baseband_filter_bandwidth(hackrf_device*, const uint32_t bandwidth_hz)``
-
-**Params:**
-
-**Returns:** A value from the hackrf_error constants listed below.
-
-
-
-HackRF Compute Baseband Filter BW
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Compute best default value depending on sample rate (auto filter).
-
-**Syntax:** ``uint32_t hackrf_compute_baseband_filter_bw(const uint32_t bandwidth_hz)``
-
-**Params:**
-
-**Returns:** A valid baseband filter width available from the Maxim MAX2837 frontend used by the radio.
-
-
-
-
-HackRF Compute Baseband Filter BW Round Down LT
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Compute nearest freq for bw filter (manual filter)
-
-**Syntax:** ``uint32_t hackrf_compute_baseband_filter_bw_round_down_lt(const uint32_t bandwidth_hz)``
-
-**Params:**
-
-**Returns:** A valid baseband filter width available from the Maxim MAX2837 frontend used by the radio.
-
-
-
-Reading and Writing Registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-These low level functions are intended for debugging purposes only.
-
-
-HackRF MAX2837 Read
-^^^^^^^^^^^^^^^^^^^
-
-Read register values from the MAX2837 Baseband IC.
-
-**Syntax:** ``int hackrf_max2837_read(hackrf_device* device, uint8_t register_number, uint16_t* value)``
-
-**Params:**
-
-**Returns:**
-
-
-
-HackRF MAX2837 Write
-^^^^^^^^^^^^^^^^^^^^
-
-Write register values to the MAX2837 Baseband IC.
-
-**Syntax:** ``int hackrf_max2837_write(hackrf_device* device, uint8_t register_number, uint16_t value)``
-
-**Params:**
-
-**Returns:**
-
-
-
-HackRF Si5351C Read
-^^^^^^^^^^^^^^^^^^^
-
-Read register values from the Si5351C clock generator IC.
-
-**Syntax:** ``int hackrf_si5351c_read(hackrf_device* device, uint16_t register_number, uint16_t* value)``
-
-**Params:**
-
-**Returns:**
-
-
-
-HackRF Si5351C Write
-^^^^^^^^^^^^^^^^^^^^
-
-Write register values to the Si5351C clock generator IC.
-
-**Syntax:** ``int hackrf_si5351c_write(hackrf_device* device, uint16_t register_number, uint16_t value)``
-
-**Params:**
-
-**Returns:**
-
-
-
-HackRF RFFC5071 Read
-^^^^^^^^^^^^^^^^^^^^
-
-Read register values from the RFFC5071 mixer IC.
-
-**Syntax:** ``int hackrf_rffc5071_read(hackrf_device* device, uint8_t register_number, uint16_t* value)``
-
-**Params:**
-
-**Returns:**
-
-
-
-HackRF RFFC5071 Write
-^^^^^^^^^^^^^^^^^^^^^
-
-Write register values to the RFFC5071 mixer IC.
-
-**Syntax:** ``int hackrf_rffc5071_write(hackrf_device* device, uint8_t register_number, uint16_t value)``
-
-**Params:**
-
-**Returns:**
-
-
-
-Updating Firmware
-~~~~~~~~~~~~~~~~~
-
-HackRF CPLD Write
-^^^^^^^^^^^^^^^^^
-
-A bitstream is written to the CPLD by the firmware during normal operation (since release 2021.03.1). This function writes a bitstream to the CPLD's flash which is not necessary for normal use. The device will need to be reset by physically pressing the reset button after hackrf_cpld_write.
-
-**Syntax:** ``int hackrf_cpld_write(hackrf_device* device, unsigned char* const data, const unsigned int total_length)``
-
-**Params:**
-
-**Returns:**
-
-
-
-
-HackRF SPI Flash Erase
-^^^^^^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_spiflash_erase(hackrf_device* device)``
-
-**Params:**
-
-**Returns:**
-
-
-
-HackRF SPI Flash Write
-^^^^^^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_spiflash_write(hackrf_device* device, const uint32_t address, const uint16_t length, unsigned char* const data)``
-
-**Params:**
-
-**Returns:**
-
-
-
-HackRF SPI Flash Read
-^^^^^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_spiflash_read(hackrf_device* device, const uint32_t address, const uint16_t length, unsigned char* data)``
-
-**Params:**
-
-**Returns:**
-
-
-
-Board Identifiers
-~~~~~~~~~~~~~~~~~
-
-HackRF Board ID Read
-^^^^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_board_id_read(hackrf_device* device, uint8_t* value)``
-
-**Params:**
-
-**Returns:**
-
-
-
-HackRF Version String Read
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_version_string_read(hackrf_device* device, char* version, uint8_t length)``
-
-**Params:**
-
-**Returns:**
-
-
-
-HackRF Board Part ID Serial Number Read
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``int hackrf_board_partid_serialno_read(hackrf_device* device, read_partid_serialno_t* read_partid_serialno)``
-
-**Params:**
-
-**Returns:**
-
-
-
-Miscellaneous
-~~~~~~~~~~~~~
-
-HackRF Error Name
-^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``const char* hackrf_error_name(enum hackrf_error errcode)``
-
-**Params:**
-
-**Returns:**
-
-
-
-HackRF Board ID Name
-^^^^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``const char* hackrf_board_id_name(enum hackrf_board_id board_id)``
-
-**Params:**
-
-**Returns:**
-
-
-
-HackRF USB Board ID Name
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``const char* hackrf_usb_board_id_name(enum hackrf_usb_board_id usb_board_id)``
-
-**Params:**
-
-**Returns:**
-
-
-
-HackRF Filter Path Name
-^^^^^^^^^^^^^^^^^^^^^^^
-
-**Syntax:** ``const char* hackrf_filter_path_name(const enum rf_path_filter path)``
-
-**Params:**
-
-**Returns:**
-
-
-
-Data Structures
-~~~~~~~~~~~~~~~
-
-``typedef struct hackrf_device hackrf_device``
-
-.. code-block :: sh
-
-	typedef struct {
-		hackrf_device* device;
-		uint8_t* buffer;
-		int buffer_length;
-		int valid_length;
-		void* rx_ctx;
-		void* tx_ctx;
-	} hackrf_transfer;
-
-.. code-block :: sh
-
-	typedef struct {
-		uint32_t part_id[2];
-		uint32_t serial_no[4];
-	} read_partid_serialno_t;
-
-.. code-block :: sh
-
-	typedef struct {
-		char **serial_numbers;
-		enum hackrf_usb_board_id *usb_board_ids;
-		int *usb_device_index;
-		int devicecount;
-		
-		void **usb_devices;
-		int usb_devicecount;
-	} hackrf_device_list_t;
-
-``typedef int (*hackrf_sample_block_cb_fn)(hackrf_transfer* transfer)``
-
-
-
-Enumerations
-~~~~~~~~~~~~
-
-Supported board versions
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-These values identify the board type of the connected hardware. This value can be used as an indicator of capabilities, such as frequency range, bandwidth or antenna port power.
-
-.. list-table :: 
-  :header-rows: 1
-  :widths: 1 1 1 1 
-
-  * - Board 	
-    - Frequency range 	
-    - Sample Rate
-    - Antenna port power
-  * - HackRF One 	
-    - 1 MHz–6 GHz
-    - 20 Msps
-    - Yes
-  * - Jawbreaker 	
-    - 10 MHz–6 GHz
-    - 20 Msps
-    - No
-  * - rad1o 	
-    - 50 MHz–4 GHz
-    - 20 Msps
-    - No
-  * - Jellybean 	
-    - N/A 	
-    - 20 Msps
-    - No
-
-Most boards will identify as HackRF One, Jawbreaker, or rad1o. Jellybean was a pre-production revision of HackRF that is no longer supported. No hardware device should intentionally report itself with an unrecognized or undetected board ID.
-
-.. code-block :: sh
-
-	enum hackrf_board_id {
-		BOARD_ID_JELLYBEAN  = 0,
-		BOARD_ID_JAWBREAKER = 1,
-		BOARD_ID_HACKRF1_OG = 2,
-		BOARD_ID_RAD1O = 3,
-		BOARD_ID_HACKRF1_R9 = 4,
-		BOARD_ID_UNRECOGNIZED = 0xFE,
-		BOARD_ID_UNDETECTED = 0xFF,
-	};
-
-
-
-USB Product IDs
-^^^^^^^^^^^^^^^
-
-.. code-block :: sh
-
-	enum hackrf_usb_board_id {
-		USB_BOARD_ID_JAWBREAKER = 0x604B,
-		USB_BOARD_ID_HACKRF_ONE = 0x6089,
-		USB_BOARD_ID_RAD1O = 0xCC15,
-		USB_BOARD_ID_INVALID = 0xFFFF,
-	};
-
-
-
-Transceiver Mode
-^^^^^^^^^^^^^^^^
-
-HackRF can operate in four main transceiver modes: Receive, Transmit, Signal Source, and Sweep. There is also a CPLD update mode which is used to write firmware images to the CPLD flash.
-
-The transceiver mode can be changed with ``hackrf_set_transceiver_mode`` with the value parameter set to one of the following:
-
-.. code-block:: sh
-
-	enum transceiver_mode_t {
-		HACKRF_TRANSCEIVER_MODE_OFF = 0,
-		HACKRF_TRANSCEIVER_MODE_RECEIVE = 1,
-		HACKRF_TRANSCEIVER_MODE_TRANSMIT = 2,
-		HACKRF_TRANSCEIVER_MODE_SS = 3,
-		TRANSCEIVER_MODE_CPLD_UPDATE = 4,
-		TRANSCEIVER_MODE_RX_SWEEP = 5,
-	};
-
-Receive mode (TRANSCEIVER_MODE_RX) is used to stream samples from the radio to the host system. Use ``hackrf_set_freq`` to set the center frequency of receiver and ``hackrf_set_sample_rate`` to set the sample rate (effective bandwidth).
-
-Transmit mode (TRANSCEIVER_MODE_TX) is used to stream samples from the host to the radio.
-
-See `hackrf_transfer <https://github.com/mossmann/hackrf/blob/master/host/hackrf-tools/src/hackrf_transfer.c>`__ for an example of setting transmit and receive mode and transferring data over USB.
-
-
-
-Function return values
-^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block::sh
-
-	enum hackrf_error {
-		HACKRF_SUCCESS = 0,
-		HACKRF_TRUE = 1,
-		HACKRF_ERROR_INVALID_PARAM = -2,
-		HACKRF_ERROR_NOT_FOUND = -5,
-		HACKRF_ERROR_BUSY = -6,
-		HACKRF_ERROR_NO_MEM = -11,
-		HACKRF_ERROR_LIBUSB = -1000,
-		HACKRF_ERROR_THREAD = -1001,
-		HACKRF_ERROR_STREAMING_THREAD_ERR = -1002,
-		HACKRF_ERROR_STREAMING_STOPPED = -1003,
-		HACKRF_ERROR_STREAMING_EXIT_CALLED = -1004,
-		HACKRF_ERROR_USB_API_VERSION = -1005,
-		HACKRF_ERROR_NOT_LAST_DEVICE = -2000,
-		HACKRF_ERROR_OTHER = -9999,
-	};
-
-
-
-RF Filter Path
-^^^^^^^^^^^^^^
-
-.. code-block:: sh
-
-	enum rf_path_filter {
-		RF_PATH_FILTER_BYPASS = 0,
-		RF_PATH_FILTER_LOW_PASS = 1,
-		RF_PATH_FILTER_HIGH_PASS = 2,
-	};

docs/source/list_of_hardware_revisions.rst

@@ -1,37 +1,52 @@
 ================================================
-List of Hardware Revisions
+Hardware Revisions
 ================================================
 
+Hardware revisions exist mainly to deal with changes in component availability. Each revision of a product meets the same performance specifications that are measured in the factory.
+
+HackRF Pro
+~~~~~~~~~~
+
+The initial production revision of HackRF Pro is r1.2.1.
+
+HackRF One
+~~~~~~~~~~
+
 HackRF One r1–r4
-~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^
 
 The first revision of HackRF One shipped by Great Scott Gadgets starting in 2014 was labeled r1. Subsequent manufacturing runs incremented the revision number up to r4 without modification to the hardware design. Manufacturing years: 2014–2020
 
 HackRF One r5
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 This experimental revision has not been manufactured.
 
 HackRF One r6
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 SKY13350 RF switches were replaced by SKY13453. Although the SKY13453 uses simplified control logic, it did not require a firmware modification. Hardware revision detection pin straps were added. Manufacturing year: 2020
 
 HackRF One r7
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 SKY13453 RF switches were reverted to SKY13350. USB VBUS detection resistor values were updated. Manufacturing year: 2021
 
 HackRF One r8
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 SKY13350 RF switches were replaced by SKY13453. Manufacturing years: 2021–2022
 
 HackRF One r9
-~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 MAX2837 was replaced by MAX2839. Si5351C was replaced by Si5351A with additional clock distribution. A series diode was added to the antenna port power supply. Manufacturing year: 2023
 
+HackRF One r10
+^^^^^^^^^^^^^^
+
+This revision is based on r8, reverting most of the changes made in r9. A series diode was added to the antenna port power supply. Manufacturing year: 2024
+
 Hardware Revision Identification
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/source/opera_cake_hardware.rst

@@ -2,6 +2,13 @@
 Hardware
 ========
 
+Block Diagram
+~~~~~~~~~~~~~
+
+.. image:: ../images/operacake-block-diagram.png
+  :alt: Opera Cake Block Diagram
+
+
 Banks
 ~~~~~
 
@@ -15,4 +22,4 @@ Opera Cake has two primary ports, A0 and B0, each of which can be switched to an
 LEDs
 ~~~~
 
-Port selections are indicated by LEDs next to each port's connector. Port A0 and the secondary port connected to A0 are indicated with a green LED. Port B0 and the secondary port connected to B0 are indicated with a yellow LED.
+Port selections are indicated by LEDs next to each port's connector. Port A0 and the secondary port connected to A0 are indicated with a green LED. Port B0 and the secondary port connected to B0 are indicated with a yellow LED.

docs/source/rad1o.rst

@@ -0,0 +1,16 @@
+=====
+rad1o
+=====
+
+rad1o is the badge from the 2015 Chaos Communication Camp.
+
+The rad1o badge contains a full-featured SDR (software defined radio) half-duplex transceiver, operating in a frequency range of about 50 MHz - 4000 MHz, and is software compatible to the HackRF.
+
+.. image:: ../images/rad1o_8.jpg
+  :alt: rad1o 
+
+(rad1o picture provided by Christoph Krichenbauer with Creative Commons License CC-BY-NC_SA)
+
+More information can be found at the `rad1o badge wiki <https://rad1o.badge.events.ccc.de/start>`__
+
+Compared to HackRF One, the rad1o badge uses a different mixer (MAX2871) with a reduced frequency range.

docs/source/rf_shield_installation.rst

@@ -2,6 +2,8 @@
 RF Shield Installation Instructions
 ===============================================
 
+HackRF Pro ships with an RF shield as standard.
+
 Official Great Scott Gadgets HackRF Ones do not come from the factory with an RF shield installed around the radio section of the PCB. They do, however, have pads in place so that one may be installed if a user has a reason and an inclination to do so. The reason that they do not come preinstalled is that early testing revealed that the RF shield did little to improve the performance of the HackRF One. The recommended RF shield is the BMI-S-230-F-R (frame) with the BMI-S-230-C (shield). A two part RF shield is recommended because the shield section can be removed to allow access to the RF section of the HackRF One. This can be important if it becomes necessary to probe any part of the RF section, or to replace any parts of the RF section. However, even with a two part RF shield, it can be difficult to access the RF section of the HackRF One in certain situations. The following steps are a basic set of instructions for installing a RF shield on a HackRF One.
 
 **CAUTION: Soldering a RF shield onto a HackRF One comes with a certain amount of risk. Beyond the inherent risks of soldering itself, this process may damage the HackRF One and no warranty is available to cover damage incurred from this process. If you do choose to install a RF shield on your HackRF One please proceed with caution.**

docs/source/sampling_rate.rst

@@ -0,0 +1,14 @@
+Sampling Rate and Baseband Filters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using a sampling rate of less than 8MHz is not recommended. Partly, this is because the MAX5864 (ADC/DAC chip) isn't specified to operate at less than 8MHz, and therefore, no promises are made by Maxim about how it performs. But more importantly, the baseband filter in the MAX2837 has a minimum bandwidth of 1.75MHz. It can't provide enough filtering at 2MHz sampling rate to remove substantial signal energy in adjacent spectrum (more than +/-1MHz from the tuned frequency). The MAX2837 datasheet suggests that at +/-1MHz, the filter provides only 4dB attenuation, and at +/-2MHz (where a signal would alias right into the center of your 2MHz spectrum), it attenuates about 33dB. That's significant. Here's a picture:
+
+.. image:: ../images/max2837-1m75bw-at-2m.png
+	:align: center
+
+At 8MHz sampling rate, and using the minimum 1.75MHz bandwidth filter, this is the response:
+
+.. image:: ../images/max2837-1m75bw-at-8m.png
+	:align: center
+
+You can see that the attenuation is more than 60dB at +/-2.8MHz, which is more than sufficient to remove significant adjacent spectrum interference before the ADC digitizes the baseband. If using this configuration to get a 2MHz sampling rate, use a GNU Radio block after the 8MHz source that performs a 4:1 decimation with a decently sharp low pass filter (complex filter with a cut-off of <1MHz).

docs/source/setting_gain.rst

@@ -0,0 +1,25 @@
+============================
+Setting Gain Controls for RX
+============================
+
+Gain controls
+~~~~~~~~~~~~~
+
+HackRF One provides three different analog gain controls on RX and two on TX.
+
+The three RX gain controls are at these stages:
+
+- RF ("amp", 0 or ~11 dB)
+- IF ("lna", 0 to 40 dB in 8 dB steps)
+- baseband ("vga", 0 to 62 dB in 2 dB steps)
+ 
+The two TX gain controls are at these stages:
+
+- RF (0 or ~11 dB)
+- IF (0 to 47 dB in 1 dB steps)
+
+Note: in some documents, the RF gain was erroneously quoted to be 14 dB. The confusion was based on the fact that the MGA-81563 amplifier is advertised as a "14 dBm" amplifier, but that specifies its output power, not its amplification. See `Martin Ling's comment on issue #1059 <https://github.com/greatscottgadgets/hackrf/issues/1059#issuecomment-1060038293>`__ for some details!
+
+The TX and RX RF amplifiers have two settings: on or off. In the off state, the amps are completely bypassed. They nominally provide around 11 dB of gain when on, but the actual amount of gain varies by frequency. In general, expect less gain at higher frequencies. For fine control of gain, use the IF and/or baseband gain options.
+
+A good default setting to start with is RF=0 (off), IF=16, baseband=16. Increase or decrease the IF and baseband gain controls roughly equally to find the best settings for your situation. Turn on the RF amp if you need help picking up weak signals. If your gain settings are too low, your signal may be buried in the noise. If one or more of your gain settings is too high, you may see distortion (look for unexpected frequencies that pop up when you increase the gain) or the noise floor may be amplified more than your signal is.

docs/source/software_support.rst

@@ -1,82 +1,82 @@
-================================================
-HackRF Compatible Software
-================================================
+===========================================
+Third-Party Software Compatible With HackRF
+===========================================
 
-Software with HackRF Support
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Software That Has Direct Support For HackRF
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This is intended to be a list of software known to work with the HackRF. There are three sections, GNU Radio Based software, those that have direct support, and those that can work with data from the HackRF.
+* GQRX
+
+    * `http://gqrx.dk/ <http://gqrx.dk/>`__
+
+* GNU Radio
+
+    * https://www.gnuradio.org/
+
+* GNU Radio Mode-S/ADS-B
+
+    * `https://github.com/bistromath/gr-air-modes <https://github.com/bistromath/gr-air-modes>`__
+
+* QSpectrumAnalyzer
+
+    * `https://github.com/xmikos/qspectrumanalyzer <https://github.com/xmikos/qspectrumanalyzer>`__
+
+* SDR# 
+
+    * `https://airspy.com/download/ <https://airspy.com/download/>`__
+    * Windows OS only
+    * Only nightly builds currently support HackRF One  
+
+* SDR Console
+
+    * https://www.sdr-radio.com/Console
+
+* Spectrum Analyzer GUI for hackrf_sweep for Windows 
+
+    * `https://github.com/pavsa/hackrf-spectrum-analyzer <https://github.com/pavsa/hackrf-spectrum-analyzer>`__
+
+* Universal Radio Hacker (Windows/Linux) 
+
+    * `https://github.com/jopohl/urh <https://github.com/jopohl/urh>`__
+
+* Web-based APRS tracker 
+
+    * `https://xakcop.com/aprs-sdr <https://xakcop.com/aprs-sdr/>`__
+
+* SigDigger (Windows/Linux/macOS)
+
+    * `https://github.com/BatchDrake/SigDigger <https://github.com/BatchDrake/SigDigger>`__
+    * Supports HackRF through SoapySDR / SoapyHackRF
 
 
 
-GNU Radio Based
-~~~~~~~~~~~~~~~
+Software That Can Use Data From HackRF
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Baudline 
 
-GNU Radio Mode-S/ADS-B - `https://github.com/bistromath/gr-air-modes <https://github.com/bistromath/gr-air-modes>`__
+    * `http://www.baudline.com/ <http://www.baudline.com/>`__ 
+    * Can view/process HackRF data, e.g. hackrf_transfer
 
-GQRX - `http://gqrx.dk/ <http://gqrx.dk/>`__
-
-
-
-Direct Support
-~~~~~~~~~~~~~~
-
-SDR# (Windows only) - `https://airspy.com/download/ <https://airspy.com/download/>`__
-
-    * Only nightly builds currently support HackRF One - `http://sdrsharp.com/downloads/sdr-nightly.zip <http://sdrsharp.com/downloads/sdr-nightly.zip>`__
-
-SDR_Radio.com V2 - `http://v2.sdr-radio.com/Radios/HackRF.aspx <http://v2.sdr-radio.com/Radios/HackRF.aspx>`__
-
-Universal Radio Hacker (Windows/Linux) - `https://github.com/jopohl/urh <https://github.com/jopohl/urh>`__
-
-QSpectrumAnalyzer - `https://github.com/xmikos/qspectrumanalyzer <https://github.com/xmikos/qspectrumanalyzer>`__
-
-Spectrum Analyzer GUI for hackrf_sweep for Windows - `https://github.com/pavsa/hackrf-spectrum-analyzer <https://github.com/pavsa/hackrf-spectrum-analyzer>`__
-
-Web-based APRS tracker `https://xakcop.com/aprs-sdr <https://xakcop.com/aprs-sdr/>`__
-
-
-Can use HackRF data
-~~~~~~~~~~~~~~~~~~~
-
-Inspectrum `https://github.com/miek/inspectrum <https://github.com/miek/inspectrum>`__
+* Inspectrum 
 
+    * `https://github.com/miek/inspectrum <https://github.com/miek/inspectrum>`__
     * Capture analysis tool with advanced features
 
-Baudline `http://www.baudline.com/ <http://www.baudline.com/>`__ (Can view/process HackRF data, e.g. hackrf_transfer)
+* Matlab
+
+    .. code-block :: sh
+
+        fid = open('samples.bin',  'r');
+        len = 1000; % 1000 samples
+        y = fread(fid, 2*len, 'int8');
+        y = y(1:2:end) + 1j*y(2:2:end);
+        fclose(fid)
 
 
 
-HackRF Tools
-~~~~~~~~~~~~
+Troubleshooting Recommendations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In addition to third party tools that support HackRF, we provide some commandline tools for interacting with HackRF. For information on how to use each tool look at the help information provided (e.g. ``hackrf_transfer -h``) or the `manual pages <http://manpages.ubuntu.com/manpages/utopic/man1/hackrf_info.1.html>`__.
+Many of these tools require libhackrf and at times HackRF Tools. It may help you to have updated libhackrf and HackRF Tools when troubleshooting these applications. 
 
-    * **hackrf_info** Read device information from HackRF such as serial number and firmware version.
-
-    * **hackrf_transfer** Send and receive signals using HackRF. Input/output files are 8-bit signed quadrature samples.
-
-    * **hackrf_sweep**, a command-line spectrum analyzer.
-
-    * **hackrf_clock** Read and write clock input and output configuration.
-
-    * **hackrf_operacake** Configure Opera Cake antenna switch connected to HackRF.
-
-    * **hackrf_spiflash** A tool to write new firmware to HackRF. See: :ref:`Updating Firmware <updating_firmware>`.
-
-    * **hackrf_debug** Read and write registers and other low-level configuration for debugging.
-
-
-Handling HackRF data
-~~~~~~~~~~~~~~~~~~~~
-
-Matlab
-^^^^^^
-
-.. code-block :: sh
-
-	fid = open('samples.bin',  'r');
-	len = 1000; % 1000 samples
-	y = fread(fid, 2*len, 'int8');
-	y = y(1:2:end) + 1j*y(2:2:end);
-	fclose(fid)
+It is also strongly suggested, and usually required, that your HackRF Tools and HackRF firmware match. 

docs/source/synchronization_checklist.rst

@@ -0,0 +1,94 @@
+.. _synchronization_checklist:
+
+================================================
+Synchronization Checklist
+================================================
+
+There are many scenarios where you may want to use multiple HackRF One devices
+synchronized with each other. For instance, multiple devices can be used with a
+phased antenna array to implement direction finding or beamforming.
+
+If you're having trouble achieving fully synchronized operation, the following
+checklist may be useful for troubleshooting:
+
+* **Are you running the latest firmware and host software versions?**
+
+    There have been many bug fixes, so please use the latest releases.
+
+* **Are you applying settings to the right target devices?**
+
+    With more than one HackRF device connected, you need to take care to specify
+    which device should be used where. When using our command line tools, use the
+    ``-d`` option with a serial number on the command line to specify which
+    device each command should target.
+
+* **Are all HackRFs sharing a clock?**
+
+    If the HackRFs are not sharing a clock, frequencies and sample rates will
+    not match exactly. See the
+    :ref:`external clock interface <external_clock_interface>`
+    section for how to connect the clock signals.
+
+* **Is the clock input being detected?**
+
+    Use ``hackrf_clock`` with the ``-i`` option to check for clock input.
+    Use the ``-d`` option to specify the serial number.
+
+    This requires ``2022.09.1`` or later host software.
+
+    The older way of checking using ``hackrf_debug`` will not work correctly on
+    some hardware revisions.
+
+* **If the clock source is CLKOUT of another HackRF, has it been enabled?**
+
+    Use ``hackrf_clock`` with the ``-o`` option to enable the clock output.
+    Use the ``-d`` option to specify the serial number.
+
+* **Is the CLKIN waveform correct?**
+
+    * It should be a 10 MHz square wave between 0 V and 3.0 to 3.3 V.
+    * A sine wave is OK, but may give greater phase noise.
+    * An unbuffered TCXO output may not have sufficient voltage.
+    * Some hardware revisions are less tolerant of out-of-spec
+      clock input than others.
+
+* **Is your hardware faulty?**
+
+    Some HackRF clones were sold with a non-functional CLKIN port.
+
+* **Are all HackRFs being started together using hardware triggering?**
+
+    If hardware triggering is not used, start times will not match exactly.
+    See the :ref:`hardware triggering <hardware_triggering>` section for how
+    to connect the necessary trigger signals.
+
+    Use ``hackrf_transfer`` with the ``-H`` option to wait for trigger input.
+
+    If launching multiple ``hackrf_transfer`` instances, make sure that those
+    running with ``-H`` have had time to reach the ``Waiting for trigger...``
+    state before the trigger signal is sent.
+
+    .. note:: There is currently no support for hardware triggering via the
+              Osmocom or Soapy blocks in GNU Radio. The Osmocom block may look
+              like it supports this but the options have no effect. 
+
+* **Are any samples being lost due to USB throughput problems?**
+
+    If RX samples are dropped or TX samples delayed, signals will become out
+    of sync.
+
+    Use ``hackrf_debug -S`` on each HackRF after running your software to check
+    if there were throughput problems. If the shortfall count reported is
+    non-zero, some samples were dropped on RX or late for TX, and signals will
+    be out of sync as a result.
+
+    This requires ``2022.09.1`` or later host software.
+
+    To force shortfalls to stop the device at runtime, use
+    ``hackrf_debug -T 0 -R 0`` to set zero tolerance for shortfalls.
+
+* **Are your HackRFs sharing a USB bus?**
+
+    A single HackRF One at 20 MHz sample rate uses practically all the bandwidth
+    of a single USB 2.0 bus. Unless using very low sample rates, each HackRF
+    should be connected to its own bus.

docs/source/tips_tricks.rst

@@ -1,40 +0,0 @@
-================================================
-Tips and Tricks
-================================================
-
-USB Cables (and why to use a noise reducing one)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The USB cable you choose can make a big difference in what you see when using your HackRF and especially when using it around between 120 and 480 MHz where USB is doing all its work.
-
-    #. Use a shielded USB cable. The best way to guarantee RF interference from USB is to use an unshielded cable. You can test that your cable is shielded by using a continuity tester to verify that the shield on one connector has continuity to the shield on the connector at the other end of the cable.
-
-    #. Use a short USB cable. Trying anything larger than a 6ft cable may yield poor results. The longer the cable, the more loss you can expect and when making this post a 15ft cable was tried and the result was the HackRF would only power up half way.
-
-    #. For best results, select a cable with a ferrite core. These cables are usually advertised to be noise reducing and are recognizable from the plastic block towards one end.
-
-Screenshot before and after changing to a noise reducing cable (`view full size image <http://i.imgur.com/e64LASK.jpg>`__): 
-
-.. image:: ../images/noisereducingcablescreenshot.jpeg
-	:align: center
-
-A shielded cable with ferrite core was used in the right-hand image.
-
-The before and after images were both taken with the preamp on and the LNA and VGA both set to 24db.
-
-
-
-Sampling Rate and Baseband Filters
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Using a sampling rate of less than 8MHz is not recommended. Partly, this is because the MAX5864 (ADC/DAC chip) isn't specified to operate at less than 8MHz, and therefore, no promises are made by Maxim about how it performs. But more importantly, the baseband filter in the MAX2837 has a minimum bandwidth of 1.75MHz. It can't provide enough filtering at 2MHz sampling rate to remove substantial signal energy in adjacent spectrum (more than +/-1MHz from the tuned frequency). The MAX2837 datasheet suggests that at +/-1MHz, the filter provides only 4dB attenuation, and at +/-2MHz (where a signal would alias right into the center of your 2MHz spectrum), it attenuates about 33dB. That's significant. Here's a picture:
-
-.. image:: ../images/max2837-1m75bw-at-2m.png
-	:align: center
-
-At 8MHz sampling rate, and using the minimum 1.75MHz bandwidth filter, this is the response:
-
-.. image:: ../images/max2837-1m75bw-at-8m.png
-	:align: center
-
-You can see that the attenuation is more than 60dB at +/-2.8MHz, which is more than sufficient to remove significant adjacent spectrum interference before the ADC digitizes the baseband. If using this configuration to get a 2MHz sampling rate, use a GNU Radio block after the 8MHz source that performs a 4:1 decimation with a decently sharp low pass filter (complex filter with a cut-off of <1MHz).

docs/source/troubleshooting.rst

@@ -1,69 +1,74 @@
 .. _troubleshooting:
 
-===============
+================================================
 Troubleshooting
-===============
+================================================
 
-Why isn't my HackRF One detectable after I plug it into my computer?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+HackRF not detected / "No HackRF boards found."
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If your HackRF One isn't immediately detectable it is very possible that your Micro USB cable is not meeting HackRF One's requirements. HackRF One requires quite a bit of supply current and solid USB 2.0 high speed communications to operate. It is common for HackRF One to reveal cables with deficiencies such as carrying power but not data, carrying data but not enough power, etc. Please try multiple cables to resolve this issue. More than once people have gotten their HackRF One to work after trying their fifth cable. 
+If the software you're using is unable to detect the HackRF hardware and/or `hackrf_info` returns "No HackRF boards found.", this can be caused by a number of different software or hardware issues.
+
+Solution
+--------
+
+    #. If you are using a PortaPack addon, make sure to select "HackRF" mode from the main menu.
+
+    #. If you are using a virtual machine or Windows Subsystem for Linux (WSL), make sure that it is configured to pass through the USB device.
+
+    #. Check whether the device appears in ``lsusb`` (Linux), Device Manager (Windows), or System Report (macOS). If it doesn't not appear, it could either be a firmware issue, an issue with the cable, or another hardware issue.
+
+    #. Try booting the HackRF in DFU mode by holding the "DFU" button when plugging in the device. It should now appear as `NXP Semiconductors LPC4330FET180 [ARM Cortex M4 + M0] (device firmware upgrade mode)` in the locations listed above. If it does appear, then it was likely a firmware issue and you can follow the instructions to :ref:`recover the SPI flash firmware <recovering_firmware>`.
+
+    #. If the device does not appear in DFU mode then it is likely to be an issue with the USB cable. Charge-only cables (which do not include the data lines) have become very common and will cause this symptom. Ideally, test the cable you're using with another device that does some sort of data transfer to be sure that it works, or just try other cables.
+
+    #. If the device still does not appear, it may be a less common issue or possibly a fault with the hardware. See :doc:`Getting Help <getting_help>` for information on where to ask for more support, and please include as much detail as you can about what you've already tried.
+
+.. _bigspike:
+
+There is a big spike in the center of the received spectrum
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you see a large spike in the center of your FFT display regardless of the frequenecy you are tuned to, you are seeing a DC offset (or component or bias). The term "DC" comes from "Direct Current" in electronics. It is the unchanging aspect of a signal as opposed to the "alternating" part of the signal (AC) that changes over time.
+
+.. figure:: ../images/dc_spike_grc.png
+   :align: center
+
+   DC spike
 
 
-----
+Take, for example, the signal represented by the digital sequence:
+
+.. code-block:: sh
+
+	-2, -1, 1, 6, 8, 9, 8, 6, 1, -1, -2, -1, 1, 6, 8, 9, 8, 6, 1, -1, -2, -1, 1, 6, 8, 9, 8, 6, 1, -1
+
+.. figure:: ../images/dc_spike_example_plot.png
+   :align: center
+
+   Example signal
+
+This periodic signal contains a strong sinusoidal component spanning from -2 to 9. If we plot the spectrum of this signal, you can see one spike at the frequency of this sinusoid and a second spike at 0 Hz (DC).
 
 
-How do I deal with the big spike in the middle of my spectrum?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. figure:: ../images/dc_spike_example_spectrum.png
+   :align: center
 
-Start by reading :ref:`our FAQ Response on the DC Spike <bigspike>`. After that, there are a few options:
+   Spectrum of example signal
+
+If the signal spanned from values -2 to 2 (centered around zero), there would be no DC offset. Since it is centered around 3.5 (the number midway between -2 and 9), there is a DC component.
+
+Samples produced by HackRF are measurements of radio waveforms, but the measurement method is prone to a DC bias introduced by HackRF. It's an artifact of the measurement system, not an indication of a received radio signal. DC offset is not unique to HackRF; it is common to all quadrature sampling systems.
+
+A high DC offset is also one of a few symptoms that can be caused by a software version mismatch. A common problem is that people run an old version of gr-osmosdr with newer firmware.
+
+Solution
+--------
+
+There are a few options:
 
     #. Ignore it. For many applications it isn't a problem. You'll learn to ignore it.
 
     #. Avoid it. The best way to handle DC offset for most applications is to use offset tuning; instead of tuning to your exact frequency of interest, tune to a nearby frequency so that the entire signal you are interested in is shifted away from 0 Hz but still within the received bandwidth. If your algorithm works best with your signal centered at 0 Hz (many do), you can shift the frequency in the digital domain, moving your signal of interest to 0 Hz and your DC offset away from 0 Hz. HackRF's high maximum sampling rate can be a big help as it allows you to use offset tuning even for relatively wideband signals.
 
     #. Correct it. There are various ways of removing the DC offset in software. However, these techniques may degrade parts of the signal that are close to 0 Hz. It may look better, but that doesn't necessarily mean that it is better from the standpoint of a demodulator algorithm, for example. Still, correcting the DC offset is often a good choice.
-
-
-----
-
-
-How should I set the gain controls for RX?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A good default setting to start with is RF=0 (off), IF=16, baseband=16. Increase or decrease the IF and baseband gain controls roughly equally to find the best settings for your situation. Turn on the RF amp if you need help picking up weak signals. If your gain settings are too low, your signal may be buried in the noise. If one or more of your gain settings is too high, you may see distortion (look for unexpected frequencies that pop up when you increase the gain) or the noise floor may be amplified more than your signal is.
-
-
-----
-
-
-What are the minimum system requirements for using HackRF?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The most important requirement is that you supply 500 mA at 5 V DC to your HackRF via the USB port. If your host computer has difficulty meeting this requirement, you may need to use a powered USB hub.
-
-Most users will want to stream data to or from the HackRF at high speeds. This requires that the host computer supports Hi-Speed USB. Some Hi-Speed USB hosts are better than others, and you may have multiple host controllers on your computer. If you have difficulty operating your HackRF at high sample rates (10 Msps to 20 Msps), try using a different USB port on your computer. If possible, arrange things so that the HackRF is the only device on the bus.
-
-There is no specific minimum CPU requirement for the host computer, but SDR is generally a CPU-intensive application. If you have a slower CPU, you may be unable to run certain SDR software or you may only be able to operate at lower sample rates.
-
-
-----
-
-
-Why isn't HackRF working with my virtual machine (VM)?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-HackRF requires the ability to stream data at very high rates over USB. Unfortunately VM software typically has problems with continuous high speed USB transfers.
-
-There are some known bugs with the HackRF firmware's USB implementation. It is possible that fixing these bugs will improve the ability to operate HackRF with a VM, but there is a very good chance that operation at higher sample rates will still be limited.
-
-
-----
-
-
-What LEDs should be illuminated on the HackRF?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-When HackRF One is plugged in to a USB host, four LEDs should turn on: 3V3, 1V8, RF, and USB. The 3V3 LED indicates that the primary internal power supply is working properly. The 1V8 and RF LEDs indicate that firmware is running and has switched on additional internal power supplies. The USB LED indicates that the HackRF One is communicating with the host over USB.
-
-The RX and TX LEDs indicate that a receive or transmit operation is currently in progress.

docs/source/updating_firmware.rst

@@ -4,24 +4,22 @@
 Updating Firmware
 ================================================
 
-HackRF devices ship with firmware on the SPI flash memory. The firmware can be updated with nothing more than a USB cable and host computer.
+HackRF devices ship with firmware on the SPI flash memory. The firmware can be updated with a USB cable and host computer.
 
 These instructions allow you to upgrade the firmware in order to take advantage of new features or bug fixes.
 
-If you have any difficulty making this process work from your native operating system, you can  :ref:`use Pentoo or the GNU Radio Live DVD <try_pentoo>` to perform the updates.
-
 
 
 Updating the SPI Flash Firmware
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To update the firmware on a working HackRF One, use the hackrf_spiflash program:
+To update the firmware on HackRF Pro, use the hackrf_spiflash program:
 
 .. code-block :: sh
 
-	hackrf_spiflash -w hackrf_one_usb.bin
+	hackrf_spiflash -w hackrf_pro_usb.bin
 
-You can find the firmware binary (hackrf_one_usb.bin) in the firmware-bin directory of the latest `release package <https://github.com/mossmann/hackrf/releases/latest>`__ or you can compile your own from the `source <https://github.com/mossmann/hackrf/tree/master/firmware>`__. For Jawbreaker, use hackrf_jawbreaker_usb.bin. If you compile from source, the file will be called hackrf_usb.bin.
+You can find the firmware binary (hackrf_pro_usb.bin) in the firmware-bin directory of the latest `release package <https://github.com/greatscottgadgets/hackrf/releases/latest>`__ or you can compile your own from the `source <https://github.com/greatscottgadgets/hackrf/tree/master/firmware>`__. For HackRF One or other platforms, use the ".bin" file with the appropriate name for your platform such as hackrf_one_usb.bin. If you compile from source, the file will be called hackrf_usb.bin.
 
 The hackrf_spiflash program is part of hackrf-tools.
 
@@ -29,22 +27,18 @@ When writing a firmware image to SPI flash, be sure to select firmware with a fi
 
 After writing the firmware to SPI flash, you may need to reset the HackRF device by pressing the RESET button or by unplugging it and plugging it back in.
 
-If you get an error that mentions HACKRF_ERROR_NOT_FOUND, check out the :ref:`FAQ <faq_hackrf_under_linux>`. It's often a permissions problem that can be quickly solved.
+If you get an error that mentions HACKRF_ERROR_NOT_FOUND, it is often a permissions problem on your OS.
 
+.. _recovering_firmware:
 
+Only if Necessary: Recovering the SPI Flash Firmware
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Updating the CPLD
-~~~~~~~~~~~~~~~~~
+If the firmware installed in SPI flash has been damaged or if you are programming a home-made HackRF for the first time, you will not be able to immediately use the hackrf_spiflash program as listed in the above procedure. Follow these steps instead:
 
-Older versions of HackRF firmware (prior to release 2021.03.1) require an additional step to program a bitstream into the CPLD.
-
-To update the CPLD image, first update the SPI flash firmware, libhackrf, and hackrf-tools to the version you are installing. Then:
-
-.. code-block :: sh
-
-	hackrf_cpldjtag -x firmware/cpld/sgpio_if/default.xsvf
-
-After a few seconds, three LEDs should start blinking. This indicates that the CPLD has been programmed successfully. Reset the HackRF device by pressing the RESET button or by unplugging it and plugging it back in.
+    #. Follow the DFU Boot instructions to start the HackRF in DFU boot mode.
+    #. Type ``dfu-util --device 1fc9:000c --alt 0 --download hackrf_pro_usb.dfu`` to load firmware from a release package into RAM. For HackRF One or other platforms, use the ".dfu" file with the appropriate name for your platform such as hackrf_one_usb.dfu.
+    #. Follow the SPI flash firmware update procedure above to write the ".bin" firmware image to SPI flash.
 
 
 
@@ -53,9 +47,9 @@ Only if Necessary: DFU Boot
 
 DFU boot mode is normally only needed if the firmware is not working properly or has never been installed.
 
-The LPC4330 microcontroller on HackRF is capable of booting from several different code sources. By default, HackRF boots from SPI flash memory (SPIFI). It can also boot HackRF in DFU (USB) boot mode. In DFU boot mode, HackRF will enumerate over USB, wait for code to be delivered using the DFU (Device Firmware Update) standard over USB, and then execute that code from RAM. The SPIFI is normally unused and unaltered in DFU mode.
+The LPC43xx microcontroller on HackRF is capable of booting from several different code sources. By default, HackRF boots from SPI flash memory (SPIFI). It can also boot HackRF in DFU (USB) boot mode. In DFU boot mode, HackRF will enumerate over USB, wait for code to be delivered using the DFU (Device Firmware Update) standard over USB, and then execute that code from RAM. The SPIFI is normally unused and unaltered in DFU mode.
 
-To start up HackRF One in DFU mode, hold down the DFU button while powering it on or while pressing and releasing the RESET button. Release the DFU button after the 3V3 LED illuminates. The 1V8 LED should remain off. At this point HackRF One is ready to receive firmware over USB.
+To start up HackRF Pro or HackRF One in DFU mode, hold down the DFU button while powering it on or while pressing and releasing the RESET button. Then release the DFU button. On HackRF One, the 3V3 LED should illuminate. On HackRF Pro, all LEDs should remain off. At this point the HackRF is ready to receive firmware over USB.
 
 To start up Jawbreaker in DFU mode, short two pins on one of the "BOOT" headers while power is first supplied. The pins that must be shorted are pins 1 and 2 of header P32 on Jawbreaker. Header P32 is labeled "P2_8" on most Jawbreakers but may be labeled "2" on prototype units. Pin 1 is labeled "VCC". Pin 2 is the center pin. After DFU boot, you should see VCCLED illuminate and note that 1V8LED does not illuminate. At this point Jawbreaker is ready to receive firmware over USB.
 
@@ -63,17 +57,6 @@ You should only use a firmware image with a filename ending in ".dfu" over DFU,
 
 
 
-Only if Necessary: Recovering the SPI Flash Firmware
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-If the firmware installed in SPI flash has been damaged or if you are programming a home-made HackRF for the first time, you will not be able to immediately use the hackrf_spiflash program as listed in the above procedure. Follow these steps instead:
-
-    #. Follow the DFU Boot instructions to start the HackRF in DFU boot mode.
-    #. Type ``dfu-util --device 1fc9:000c --alt 0 --download hackrf_one_usb.dfu`` to load firmware from a release package into RAM. If you have a Jawbreaker, use hackrf_jawbreaker_usb.dfu instead. Alternatively, use ``make -e BOARD=HACKRF_ONE RUN_FROM=RAM program`` to load the firmware into RAM and start it.
-    #. Follow the SPI flash firmware update procedure above to write the ".bin" firmware image to SPI flash.
-
-
-
 Obtaining DFU-Util
 ~~~~~~~~~~~~~~~~~~
 
@@ -97,4 +80,19 @@ If you are using a platform without a dfu-util package, build instruction can be
 	make
 	sudo make install
 
-Now you will have the current version of DFU Util installed on your system.
+Now you will have the current version of DFU Util installed on your system.
+
+
+
+Updating the CPLD
+~~~~~~~~~~~~~~~~~
+
+Older versions of HackRF firmware (prior to release 2021.03.1) require an additional step to program a bitstream into the CPLD.
+
+To update the CPLD image, first update the SPI flash firmware, libhackrf, and hackrf-tools to the version you are installing. Then:
+
+.. code-block :: sh
+
+	hackrf_cpldjtag -x firmware/cpld/sgpio_if/default.xsvf
+
+After a few seconds, three LEDs should start blinking. This indicates that the CPLD has been programmed successfully. Reset the HackRF device by pressing the RESET button or by unplugging it and plugging it back in.

docs/source/usb_cables.rst

@@ -0,0 +1,27 @@
+==========
+USB Cables
+==========
+
+The USB cable you choose can make a big difference in what you see when using your HackRF and especially when using it around between 120 and 480 MHz where USB is doing all its work.
+
+    #. Use a shielded USB cable. The best way to guarantee RF interference from USB is to use an unshielded cable. You can test that your cable is shielded by using a continuity tester to verify that the shield on one connector has continuity to the shield on the connector at the other end of the cable.
+
+    #. Use a short USB cable. Trying anything larger than a 6ft cable may yield poor results. The longer the cable, the more loss you can expect and when making this post a 15ft cable was tried and the result was the HackRF would only power up half way.
+
+    #. For best results, select a cable with a ferrite core. These cables are usually advertised to be noise reducing and are recognizable from the plastic block towards one end.
+
+Screenshot before and after changing to a noise reducing cable (`view full size image <http://i.imgur.com/e64LASK.jpg>`__): 
+
+.. image:: ../images/noisereducingcablescreenshot.jpeg
+	:align: center
+
+A shielded cable with ferrite core was used in the right-hand image.
+
+The before and after images were both taken with the preamp on and the LNA and VGA both set to 24db.
+
+
+
+Why isn't my HackRF detectable after I plug it into my computer?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your HackRF isn't immediately detectable it is very possible that your USB cable is not meeting HackRF's requirements. HackRF requires quite a bit of supply current and solid USB 2.0 high speed communications to operate. It is common for HackRF to reveal cables with deficiencies such as carrying power but not data, carrying data but not enough power, etc. Please try multiple cables to resolve this issue. More than once people have gotten their HackRF to work after trying their fifth cable.

docs/source/virtual_machines.rst

@@ -0,0 +1,5 @@
+================
+Virtual Machines
+================
+
+HackRF requires the ability to stream data at very high rates over USB. Unfortunately VM software typically has problems with USB passthrough; especially continuous high speed USB transfers. It is recommended to not use a HackRF with a VM. 

firmware/CMakeLists.txt

@@ -20,10 +20,17 @@
 
 # Top directory CMake project for HackRF firmware
 
-cmake_minimum_required(VERSION 3.1.3)
+option(CHECK_INCLUDES
+	   "Check firmware sources for unused includes and transitive dependencies. (Requires iwyu)" OFF)
+
+cmake_minimum_required(VERSION 3.12.0)
 set(CMAKE_TOOLCHAIN_FILE toolchain-arm-cortex-m.cmake)
 
 project (hackrf_firmware_all C)
 
+if(CHECK_INCLUDES)
+	include(include-what-you-use.cmake)
+endif()
+
 add_subdirectory(blinky)
 add_subdirectory(hackrf_usb)

firmware/README

@@ -28,6 +28,7 @@ $ cmake ..
 $ make
 $ hackrf_spiflash -w hackrf_usb.bin
 
+If you have a HackRF Pro, add -DBOARD=PRALINE to the cmake command.
 If you have a Jawbreaker, add -DBOARD=JAWBREAKER to the cmake command.
 If you have a rad1o, use -DBOARD=RAD1O instead.
 
@@ -48,9 +49,9 @@ For loading firmware into RAM with DFU you will need:
 
 http://dfu-util.sourceforge.net/
 
-To start up HackRF One in DFU mode, hold down the DFU button while powering it
-on or while pressing and releasing the RESET button.  Release the DFU button
-after the 3V3 LED illuminates.
+To start up HackRF One or HackRF Pro in DFU mode, hold down the DFU button
+while powering it on or while pressing and releasing the RESET button.  Release
+the DFU button after the 3V3 LED illuminates.
 
 A .dfu file is built by default when building firmware.  Alternatively you can
 use a known good .dfu file from a release package.  Load the firmware into RAM

firmware/blinky/CMakeLists.txt

@@ -19,7 +19,7 @@
 # Boston, MA 02110-1301, USA.
 #
 
-cmake_minimum_required(VERSION 3.1.3)
+cmake_minimum_required(VERSION 3.10.0)
 set(CMAKE_TOOLCHAIN_FILE ../toolchain-arm-cortex-m.cmake)
 
 project(blinky C)

firmware/blinky/blinky.c

@@ -19,31 +19,39 @@
  * Boston, MA 02110-1301, USA.
  */
 
-#include "hackrf_core.h"
+#include "delay.h"
+#include "leds.h"
+#include "pins.h"
 #include "platform_detect.h"
+#include "power.h"
 
 int main(void)
 {
 	detect_hardware_platform();
-	pin_setup();
+	pins_setup();
 
+#ifndef PRALINE
 	/* enable 1V8 power supply so that the 1V8 LED lights up */
 	enable_1v8_power();
+#else
+	/* enable 1V2 power supply so that the 3V3FPGA LED lights up */
+	enable_1v2_power();
+#endif
 
 	/* Blink LED1/2/3 on the board. */
-	while (1) 
+	while (1)
 	{
 		led_on(LED1);
 		led_on(LED2);
 		led_on(LED3);
 
-		delay(2000000);
-		
+		delay_ms(150);
+
 		led_off(LED1);
 		led_off(LED2);
 		led_off(LED3);
-		
-		delay(2000000);
+
+		delay_ms(150);
 	}
 
 	return 0;

firmware/common/LPC4320_M4_memory.ld

@@ -25,8 +25,9 @@
 MEMORY
 {
 	/* rom is really the shadow region that points to SPI flash or elsewhere */
-	rom (rx)  : ORIGIN = 0x00000000, LENGTH =  96K
-	ram_local1 (rwx) : ORIGIN = 0x10000000, LENGTH =  96K
+	rom (rx)  : ORIGIN = 0x00000000, LENGTH =  1M
+	ram_local1 (rwx) : ORIGIN = 0x10000000, LENGTH =  64K
+	ram_usb (rw) : ORIGIN = 0x10010000, LENGTH = 32K
 	ram_local2 (rwx) : ORIGIN = 0x10080000, LENGTH =  32K
 	ram_sleep (rwx) : ORIGIN = 0x10088000, LENGTH = 8K
 }

firmware/common/LPC4330_M4_memory.ld

@@ -26,7 +26,8 @@ MEMORY
 {
 	/* rom is really the shadow region that points to SPI flash or elsewhere */
 	rom (rx)  : ORIGIN = 0x00000000, LENGTH =  128K
-	ram_local1 (rwx) : ORIGIN = 0x10000000, LENGTH =  128K
+	ram_local1 (rwx) : ORIGIN = 0x10000000, LENGTH =  96K
+	ram_usb(rw) : ORIGIN = 0x10018000, LENGTH = 32K
 	ram_local2 (rwx) : ORIGIN = 0x10080000, LENGTH =  64K
 	ram_sleep (rwx) : ORIGIN = 0x10090000, LENGTH = 8K
 }

firmware/common/LPC43xx_M0_memory.ld

@@ -22,5 +22,5 @@
 
 MEMORY
 {
-	ram (rwx) : ORIGIN = 0x00000000, LENGTH = 28K
+	ram (rwx) : ORIGIN = 0x00000000, LENGTH = 20K
 }

firmware/common/LPC43xx_M4_memory.ld

@@ -23,16 +23,24 @@
 MEMORY
 {
 	/* Physical address in Flash used to copy Code from Flash to RAM */
-	rom_flash (rx)  : ORIGIN = 0x80000000, LENGTH =  1M
-	ram_m0 (rwx) : ORIGIN = 0x20000000, LENGTH = 28K
-	ram_shared (rwx) : ORIGIN = 0x20007000, LENGTH =  4K
-	ram_usb (rwx) : ORIGIN = 0x20008000, LENGTH = 32K
-	/* ram_usb: USB buffer. Straddles two blocks of RAM
+	rom_flash (rx)    : ORIGIN = 0x80000000, LENGTH = 1M
+	/* Buffers for LZ4 decompression */
+	ram_lz4_in (rwx)  : ORIGIN = 0x20000000, LENGTH = 4K
+	ram_lz4_out (rwx) : ORIGIN = 0x20001000, LENGTH = 4K
+	/* RAM for M0 code */
+	ram_m0 (rwx)      : ORIGIN = 0x20002000, LENGTH = 20K
+	/* RAM shared between M0 and M4 */
+	ram_shared (rwx)  : ORIGIN = 0x20007000, LENGTH = 4K
+	/* USB buffer. Straddles two blocks of RAM
 	 * to get performance benefit of having two USB buffers addressable
 	 * simultaneously (on two different buses of the AHB multilayer matrix)
 	 */
+	ram_samp (rwx)     : ORIGIN = 0x20008000, LENGTH = 32K
 }
 
+lz4_in_buf = ORIGIN(ram_lz4_in);
+lz4_out_buf = ORIGIN(ram_lz4_out);
+usb_samp_buffer = ORIGIN(ram_samp);
 usb_bulk_buffer = ORIGIN(ram_usb);
 m0_state = ORIGIN(ram_shared);
 PROVIDE(__ram_m0_start__ = ORIGIN(ram_m0));

firmware/common/LPC43xx_M4_memory_rom_only.ld

@@ -0,0 +1,31 @@
+/*
+ * Copyright 2012-2025 Great Scott Gadgets <info@greatscottgadgets.com>
+ * Copyright 2012 Jared Boone <jared@sharebrained.com>
+ *
+ * This file is part of HackRF
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street,
+ * Boston, MA 02110-1301, USA.
+ */
+
+SECTIONS
+{
+	/* ROM-only section */
+    .rom_only : {
+        . = ALIGN(4);
+        KEEP(*(.rom_only))
+        . = ALIGN(4);
+    } > rom
+}

firmware/common/adc.c

@@ -0,0 +1,48 @@
+/*
+ * Copyright 2025 Great Scott Gadgets <info@greatscottgadgets.com>
+ *
+ * This file is part of HackRF.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#include <stdbool.h>
+
+#include <libopencm3/lpc43xx/adc.h>
+#include <libopencm3/lpc43xx/scu.h>
+
+#include "adc.h"
+
+uint16_t adc_read(uint8_t pin)
+{
+	bool alt_pin = (pin & 0x80);
+	pin &= ~0x80;
+	uint8_t pin_mask = (1 << pin);
+	if (alt_pin) {
+		SCU_ENAIO0 |= pin_mask;
+	} else {
+		SCU_ENAIO0 &= ~pin_mask;
+	}
+	ADC0_CR = ADC_CR_SEL(pin_mask) | ADC_CR_CLKDIV(45) | ADC_CR_PDN | ADC_CR_START(1);
+	while (!(ADC0_GDR & ADC_DR_DONE) || (((ADC0_GDR >> 24) & 0x7) != pin))
+		;
+	return (ADC0_GDR >> 6) & 0x03FF;
+}
+
+void adc_off(void)
+{
+	ADC0_CR = 0;
+}

firmware/common/adc.h

@@ -0,0 +1,27 @@
+/*
+ * Copyright 2025 Great Scott Gadgets <info@greatscottgadgets.com>
+ *
+ * This file is part of HackRF.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#pragma once
+
+#include <stdint.h>
+
+uint16_t adc_read(uint8_t pin);
+void adc_off(void);

firmware/common/bitband.h

@@ -20,8 +20,7 @@
  * Boston, MA 02110-1301, USA.
  */
 
-#ifndef __BITBAND_H__
-#define __BITBAND_H__
+#pragma once
 
 #include <stdint.h>
 
@@ -37,5 +36,3 @@ void peripheral_bitband_clear(
 uint32_t peripheral_bitband_get(
 	volatile void* const peripheral_address,
 	const uint_fast8_t bit_number);
-
-#endif //__BITBAND_H__

firmware/common/clock_gen.c

@@ -0,0 +1,420 @@
+/*
+ * Copyright 2026 Great Scott Gadgets <info@greatscottgadgets.com>
+ *
+ * This file is part of HackRF.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#include "clock_gen.h"
+
+#include <stdint.h>
+
+#include "hackrf_ui.h"
+#include "platform_detect.h"
+#include "sgpio.h"
+#include "si5351c.h"
+#if defined(IS_HACKRF_ONE) || defined(IS_PRALINE)
+	#include "delay.h"
+	#include "portapack.h"
+#endif
+
+void clock_gen_init(void)
+{
+	si5351c_init(&si5351c);
+	si5351c_disable_all_outputs(&si5351c);
+	si5351c_disable_oeb_pin_control(&si5351c);
+	si5351c_power_down_all_clocks(&si5351c);
+	si5351c_set_crystal_configuration(&si5351c);
+	si5351c_enable_xo_and_ms_fanout(&si5351c);
+
+	/*
+	 * Clocks on HackRF One r9:
+	 *   CLK0 -> MAX5864/CPLD/SGPIO (sample clocks)
+	 *   CLK1 -> RFFC5072/MAX2839
+	 *   CLK2 -> External Clock Output/LPC43xx (power down at boot)
+	 *
+	 * Clocks on other platforms:
+	 *   CLK0 -> MAX5864/CPLD
+	 *   CLK1 -> CPLD
+	 *   CLK2 -> SGPIO
+	 *   CLK3 -> External Clock Output (power down at boot)
+	 *   CLK4 -> RFFC5072 (MAX2837 on rad1o)
+	 *   CLK5 -> MAX2837 (MAX2871 on rad1o)
+	 *   CLK6 -> none
+	 *   CLK7 -> LPC43xx (uses a 12MHz crystal by default)
+	 *
+	 * Clocks on Praline:
+	 *   CLK0 -> AFE_CLK (MAX5864/FPGA)
+	 *   CLK1 -> SCT_CLK
+	 *   CLK2 -> MCU_CLK (uses a 12MHz crystal by default)
+	 *   CLK3 -> External Clock Output (power down at boot)
+	 *   CLK4 -> XCVR_CLK (MAX2837)
+	 *   CLK5 -> MIX_CLK (RFFC5072)
+	 *   CLK6 -> AUX_CLK1
+	 *   CLK7 -> AUX_CLK2
+	 */
+
+#ifdef IS_H1_R9
+	if (IS_H1_R9) {
+		/* MS0/CLK0 is the reference for both RFFC5071 and MAX2839. */
+		si5351c_configure_multisynth(
+			&si5351c,
+			0,
+			20 * 128 - 512,
+			0,
+			1,
+			0); /* 800/20 = 40MHz */
+	}
+#endif
+#ifdef IS_NOT_H1_R9
+	if (IS_NOT_H1_R9) {
+		/* MS4/CLK4 is the source for the RFFC5071 mixer (MAX2837 on rad1o). */
+		si5351c_configure_multisynth(
+			&si5351c,
+			4,
+			20 * 128 - 512,
+			0,
+			1,
+			0); /* 800/20 = 40MHz */
+		/* MS5/CLK5 is the source for the MAX2837 clock input (MAX2871 on rad1o). */
+		si5351c_configure_multisynth(
+			&si5351c,
+			5,
+			20 * 128 - 512,
+			0,
+			1,
+			0); /* 800/20 = 40MHz */
+	}
+#endif
+
+	/* MS6/CLK6 is unused. */
+	/* MS7/CLK7 is unused. */
+
+	/* Set to 10 MHz, the common rate between Jawbreaker and HackRF One. */
+	sample_rate_set(SR_FP_MHZ(10), true);
+
+	si5351c_configure_clock_control(&si5351c);
+	si5351c_change_input(&si5351c, SI5351C_INPUT_XTAL);
+	// soft reset
+	si5351c_reset_plls(&si5351c, SI5351C_PLL_MASK_BOTH);
+	si5351c_enable_clock_outputs(&si5351c);
+}
+
+void clock_gen_shutdown(void)
+{
+	si5351c_disable_all_outputs(&si5351c);
+	si5351c_disable_oeb_pin_control(&si5351c);
+	si5351c_power_down_all_clocks(&si5351c);
+}
+
+clock_source_t activate_best_clock_source(void)
+{
+#ifdef IS_EXPANSION_COMPATIBLE
+	if (IS_EXPANSION_COMPATIBLE) {
+		/* Ensure PortaPack reference oscillator is off while checking for external clock input. */
+		if (portapack_present()) {
+			portapack_reference_oscillator(false);
+		}
+	}
+#endif
+
+	clock_source_t source = CLOCK_SOURCE_HACKRF;
+
+	/* Check for external clock input. */
+	if (si5351c_clkin_signal_valid(&si5351c)) {
+		source = CLOCK_SOURCE_EXTERNAL;
+	} else {
+#ifdef IS_EXPANSION_COMPATIBLE
+		if (IS_EXPANSION_COMPATIBLE) {
+			/* Enable PortaPack reference oscillator (if present), and check for valid clock. */
+			if (portapack_present()) {
+				portapack_reference_oscillator(true);
+				delay_ms(18); // for oscillator to enable.
+				if (si5351c_clkin_signal_valid(&si5351c)) {
+					source = CLOCK_SOURCE_PORTAPACK;
+				} else {
+					portapack_reference_oscillator(false);
+				}
+			}
+		}
+#endif
+		/* No external or PortaPack clock was found. Use HackRF Si5351C crystal. */
+	}
+
+	si5351c_input_t input = (source == CLOCK_SOURCE_HACKRF) ? SI5351C_INPUT_XTAL :
+								  SI5351C_INPUT_CLKIN;
+	si5351c_change_input(&si5351c, input);
+
+	hackrf_ui()->set_clock_source(source);
+
+	return source;
+}
+
+/*
+ * Closest fraction to m/d with denominator <= max_den.
+ * Returns result in *r / *s with gcd(*r, *s) == 1 and 0 < *s <= max_den.
+ * Straight port from CPython's fractions, and better documented there.
+ */
+void limit_denominator(
+	uint64_t m,
+	uint64_t d,
+	const uint64_t max_den,
+	uint64_t* r,
+	uint64_t* s)
+{
+	if (d <= max_den) {
+		*r = m;
+		*s = d;
+		return;
+	}
+
+	uint64_t p0 = 0, q0 = 1, p1 = 1, q1 = 0;
+	uint64_t n = m, orig_d = d;
+	uint64_t tmp;
+
+	while (1) {
+		uint64_t a = n / d;
+		uint64_t q2 = q0 + a * q1;
+
+		if (q2 > max_den)
+			break;
+
+		tmp = p0 + a * p1;
+		p0 = p1;
+		q0 = q1;
+		p1 = tmp;
+		q1 = q2;
+
+		tmp = n - a * d;
+		n = d;
+		d = tmp;
+		if (d == 0)
+			break;
+	}
+
+	uint64_t k = (max_den - q0) / q1;
+
+	/* Return closer candidate. */
+	if (2 * d * (q0 + k * q1) <= orig_d) {
+		*r = p1;
+		*s = q1;
+	} else {
+		*r = p0 + k * p1;
+		*s = q0 + k * q1;
+	}
+}
+
+/*
+ * Configure clock generator to produce sample clock in units of 1/(2**36) Hz.
+ * Can be called with program=false for a dry run that returns the resultant
+ * frequency without actually configuring the clock generator.
+ *
+ * The clock generator output frequency is:
+ *
+ * fs = 128 * vco / (512 + p1 + p2/p3))
+ *
+ * where p1, p2, and p3 are register values.
+ *
+ * For more information see:
+ * https://www.pa3fwm.nl/technotes/tn42a-si5351-programming.html
+ */
+fp_28_36_t sample_rate_set(const fp_28_36_t sample_rate, const bool program)
+{
+	const uint64_t vco_hz = 800 * 1000ULL * 1000ULL;
+	uint64_t p1, p2, p3;
+	uint64_t n, d, q1, q2, q3, r1, r2;
+	fp_28_36_t resultant_rate;
+
+	/*
+	 * First double the sample rate so that we can produce a clock at twice
+	 * the intended sample rate. The 2x clock is sometimes used directly,
+	 * and it is divided by two in an output divider to produce the actual
+	 * AFE clock.
+	 */
+	fp_28_36_t rate = sample_rate * 2;
+
+	/*
+	 * Computes p1 = (N << 36) / rate - 512, where N = 128 * vco_hz.
+	 *
+	 * Full numerator (N << 36) is 73 bits, so we split the division:
+	 *
+	 *   (N << 36) / rate = ((N << 27) / rate) << 9
+	 *                    + (((N << 27) % rate) << 9) / rate
+	 *
+	 * IMPORTANT: Assumes sample rate is in [200e3 << 36, 43.6e6 << 36].
+	 */
+	const uint64_t A = (128 * vco_hz) << 27;
+
+	q1 = A / rate;
+	r1 = A % rate;
+
+	// Remaining 9 bits with long division.
+	q2 = 0;
+	r2 = r1;
+	for (int j = 0; j < 9; j++) {
+		uint64_t msb = r2 >> 63;
+		r2 <<= 1;
+		q2 <<= 1;
+		if (msb || r2 >= rate) {
+			r2 -= rate;
+			q2 |= 1;
+		}
+	}
+
+	p1 = (q1 << 9) + q2 - 512;
+
+	if (r2) {
+		/* Use the remainder for the fractional part. */
+		n = r2;
+		d = rate;
+
+		/* Reduce fraction. */
+		const uint64_t p3_max = 0xfffff;
+		limit_denominator(n, d, p3_max, &p2, &p3);
+
+		/* Roll over to next p1 to enable integer mode. */
+		if (p2 >= p3) {
+			p1++;
+			p2 = 0;
+		}
+	} else {
+		p2 = 0;
+	}
+
+	/* Maximum: (128 * 2048) - 512 */
+	if (p1 > 0x3fe00) {
+		p1 = 0x3fe00;
+		p2 = 0;
+	}
+
+	if (p2 == 0) {
+		/* Use unity denominator for integer mode. */
+		p3 = 1;
+		n = (128 * vco_hz) << 18;
+		d = (p1 + 512);
+		q1 = n / d;
+		r1 = n % d;
+		q2 = ((r1 << 18) + (d / 2)) / d;
+		resultant_rate = (q1 << 18) + q2;
+	} else {
+		n = p3 * vco_hz * 128;
+		d = p3 * (p1 + 512) + p2;
+		q1 = n / d;
+		r1 = n % d;
+		q2 = (r1 << 18) / d;
+		r2 = (r1 << 18) % d;
+		q3 = ((r2 << 18) + (d / 2)) / d;
+		resultant_rate = (q1 << 36) + (q2 << 18) + q3;
+	}
+
+	/* Return MCU sample rate, not AFE clock rate. */
+	resultant_rate = (resultant_rate + 1) / 2;
+
+	if (!program) {
+		return resultant_rate;
+	}
+
+	bool streaming = sgpio_cpld_stream_is_enabled(&sgpio_config);
+
+	if (streaming) {
+		sgpio_cpld_stream_disable(&sgpio_config);
+	}
+
+#ifdef IS_NOT_PRALINE
+	if (IS_NOT_PRALINE) {
+		/* Integer mode can be enabled if p1 is even and p2 is zero. */
+		if (p1 & 0x1 || p2) {
+			si5351c_set_int_mode(&si5351c, 0, 0);
+		} else {
+			si5351c_set_int_mode(&si5351c, 0, 1);
+		}
+
+	#ifdef IS_H1_R9
+		if (IS_H1_R9) {
+			/*
+			 * On HackRF One r9 all sample clocks are externally derived
+			 * from MS1/CLK1 operating at twice the sample rate.
+			 */
+			si5351c_configure_multisynth(&si5351c, 1, p1, p2, p3, 0);
+		}
+	#endif
+	#ifdef IS_NOT_H1_R9
+		if (IS_NOT_H1_R9) {
+			/*
+			 * On other platforms the clock generator produces three
+			 * different sample clocks, all derived from multisynth 0.
+			 */
+			/* MS0/CLK0 is the source for the MAX5864/CPLD (CODEC_CLK). */
+			si5351c_configure_multisynth(&si5351c, 0, p1, p2, p3, 1);
+
+			/* MS0/CLK1 is the source for the CPLD (CODEC_X2_CLK). */
+			si5351c_configure_multisynth(
+				&si5351c,
+				1,
+				0,
+				0,
+				0,
+				0); //p1 doesn't matter
+
+			/* MS0/CLK2 is the source for SGPIO (CODEC_X2_CLK) */
+			si5351c_configure_multisynth(
+				&si5351c,
+				2,
+				0,
+				0,
+				0,
+				0); //p1 doesn't matter
+		}
+	#endif
+	}
+#endif
+#ifdef IS_PRALINE
+	if (IS_PRALINE) {
+		/* MS0/CLK0 is the source for the MAX5864 (AFE_CLK). */
+		si5351c_configure_multisynth(&si5351c, 0, p1, p2, p3, 1);
+
+		/* MS1/CLK1 is the source for the FPGA (FPGA_CLK and SCT_CLK). */
+		si5351c_configure_multisynth(&si5351c, 1, p1, p2, p3, 1);
+
+		/* Delay FPGA_CLK relative to AFE_CLK. */
+		uint8_t phase_offset = 0;
+		if (p1 < 2100) {
+			phase_offset = (p1 >> 4) - 6;
+		}
+		si5351c_set_phase(&si5351c, 1, phase_offset);
+
+		if ((detected_revision() & ~BOARD_REV_GSG) < BOARD_REV_PRALINE_R1_1) {
+			/*
+			 * On older boards FPGA_CLK is on CLK2 while SCT_CLK is on
+			 * CLK1. We configure both so that behavior is consistent with
+			 * newer boards that use CLK1 for both FPGA_CLK and SCT_CLK.
+			 */
+			si5351c_configure_multisynth(&si5351c, 2, p1, p2, p3, 1);
+			si5351c_set_phase(&si5351c, 2, phase_offset);
+		}
+
+		/* Reset PLL to synchronize output clock phase. */
+		si5351c_reset_plls(&si5351c, SI5351C_PLL_MASK_A);
+	}
+#endif
+
+	if (streaming) {
+		sgpio_cpld_stream_enable(&sgpio_config);
+	}
+
+	return resultant_rate;
+}

firmware/common/clock_gen.h

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2026 Great Scott Gadgets <info@greatscottgadgets.com>
+ *
+ * This file is part of HackRF.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include <stdbool.h>
+
+#include "fixed_point.h"
+
+typedef enum {
+	CLOCK_SOURCE_HACKRF = 0,
+	CLOCK_SOURCE_EXTERNAL = 1,
+	CLOCK_SOURCE_PORTAPACK = 2,
+} clock_source_t;
+
+void clock_gen_init(void);
+void clock_gen_shutdown(void);
+
+clock_source_t activate_best_clock_source(void);
+
+fp_28_36_t sample_rate_set(const fp_28_36_t sample_rate, const bool program);
+
+#ifdef __cplusplus
+}
+#endif

firmware/common/clock_io.c

@@ -0,0 +1,170 @@
+/*
+ * Copyright 2022-2026 Great Scott Gadgets
+ *
+ * This file is part of HackRF.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2, or (at your option)
+ * any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; see the file COPYING.  If not, write to
+ * the Free Software Foundation, Inc., 51 Franklin Street,
+ * Boston, MA 02110-1301, USA.
+ */
+
+#include "clock_io.h"
+
+#include <stdbool.h>
+#include <stdint.h>
+
+#include <libopencm3/lpc43xx/timer.h>
+#include <libopencm3/lpc43xx/scu.h>
+#include <libopencm3/lpc43xx/gima.h>
+#include <libopencm3/lpc43xx/gpdma.h>
+#include <libopencm3/lpc43xx/creg.h>
+
+#include "gpdma.h"
+#include "gpio.h"
+#include "platform_detect.h"
+#ifdef IS_NOT_PRALINE
+	#include "sgpio.h"
+#endif
+#ifdef IS_PRALINE
+	#include "fpga.h"
+	#include "platform_gpio.h"
+#endif
+
+#define CLOCK_CYCLES_1_MS     (204000)
+#define MEASUREMENT_WINDOW_MS (50)
+#define MEASUREMENT_CYCLES    (CLOCK_CYCLES_1_MS * MEASUREMENT_WINDOW_MS)
+
+/* DMA linked list item */
+typedef struct {
+	uint32_t src;
+	uint32_t dest;
+	uint32_t next_lli;
+	uint32_t control;
+} dma_lli;
+
+/* timer control register configuration sequence */
+typedef struct {
+	uint32_t first_tcr;
+	uint32_t second_tcr;
+} tcr_sequence;
+
+dma_lli timer_dma_lli;
+tcr_sequence reset;
+
+void clkin_detect_init(void)
+{
+	/* Timer1 triggers periodic measurement */
+	timer_set_prescaler(TIMER1, 0);
+	timer_set_mode(TIMER1, TIMER_CTCR_MODE_TIMER);
+	TIMER1_MCR = TIMER_MCR_MR0R;
+	TIMER1_EMR = (TIMER_EMR_EMC_SET << TIMER_EMR_EMC0_SHIFT) |
+		(TIMER_EMR_EMC_TOGGLE << TIMER_EMR_EMC3_SHIFT);
+	TIMER1_MR3 = MEASUREMENT_CYCLES;
+	TIMER1_MR0 = MEASUREMENT_CYCLES;
+
+	/* prevent TIMER1_MR3 from interfering with SCT */
+	CREG_CREG6 |= CREG_CREG6_CTOUTCTRL;
+
+	/* Timer2 counts CLKIN */
+	timer_set_prescaler(TIMER2, 0);
+	TIMER2_CCR = TIMER_CCR_CAP3RE;
+	GIMA_CAP2_3_IN = 0x20; // T1_MAT3
+
+	/* measure CLKIN_DETECT signal on P4_8, pin 15, CTIN_5 */
+	TIMER2_CTCR = TIMER_CTCR_MODE_COUNTER_RISING | TIMER_CTCR_CINSEL_CAPN_2;
+	scu_pinmux(P4_8, SCU_GPIO_PDN | SCU_CONF_FUNCTION1); // CTIN_5
+	GIMA_CAP2_2_IN = 0x00;                               // CTIN_5
+
+	reset.first_tcr = TIMER_TCR_CEN | TIMER_TCR_CRST;
+	reset.second_tcr = TIMER_TCR_CEN;
+	timer_dma_lli.src = (uint32_t) & (reset);
+	timer_dma_lli.dest = (uint32_t) & (TIMER2_TCR);
+	timer_dma_lli.next_lli = (uint32_t) & (timer_dma_lli);
+	timer_dma_lli.control = GPDMA_CCONTROL_TRANSFERSIZE(2) |
+		GPDMA_CCONTROL_SBSIZE(0)   // 1
+		| GPDMA_CCONTROL_DBSIZE(0) // 1
+		| GPDMA_CCONTROL_SWIDTH(2) // 32-bit word
+		| GPDMA_CCONTROL_DWIDTH(2) // 32-bit word
+		| GPDMA_CCONTROL_S(0)      // AHB Master 0
+		| GPDMA_CCONTROL_D(1)      // AHB Master 1
+		| GPDMA_CCONTROL_SI(1)     // increment source
+		| GPDMA_CCONTROL_DI(0)     // do not increment destination
+		| GPDMA_CCONTROL_PROT1(0)  // user mode
+		| GPDMA_CCONTROL_PROT2(0)  // not bufferable
+		| GPDMA_CCONTROL_PROT3(0)  // not cacheable
+		| GPDMA_CCONTROL_I(0);     // interrupt disabled
+	gpdma_controller_enable();
+	GPDMA_C0SRCADDR = timer_dma_lli.src;
+	GPDMA_C0DESTADDR = timer_dma_lli.dest;
+	GPDMA_C0LLI = timer_dma_lli.next_lli;
+	GPDMA_C0CONTROL = timer_dma_lli.control;
+	GPDMA_C0CONFIG = GPDMA_CCONFIG_DESTPERIPHERAL(0x3) // T1_MAT0
+		| GPDMA_CCONFIG_FLOWCNTRL(1)               // memory-to-peripheral
+		| GPDMA_CCONFIG_H(0);                      // do not halt
+	gpdma_channel_enable(0);
+
+	/* start counting */
+	timer_reset(TIMER2);
+	timer_reset(TIMER1);
+	timer_enable_counter(TIMER2);
+	timer_enable_counter(TIMER1);
+}
+
+uint32_t clkin_frequency(void)
+{
+	return TIMER2_CR3 * (1000 / MEASUREMENT_WINDOW_MS);
+}
+
+void trigger_enable(const bool enable)
+{
+#ifdef IS_NOT_PRALINE
+	if (IS_NOT_PRALINE) {
+		gpio_write(sgpio_config.gpio_trigger_enable, enable);
+	}
+#endif
+#ifdef IS_PRALINE
+	if (IS_PRALINE) {
+		fpga_set_trigger_enable(&fpga, enable);
+	}
+#endif
+}
+
+#ifdef IS_PRALINE
+void clkin_ctrl_set(const clkin_signal_t signal)
+{
+	gpio_write(platform_gpio()->clkin_ctrl, signal & 1);
+}
+
+void p1_ctrl_set(const p1_ctrl_signal_t signal)
+{
+	const platform_gpio_t* gpio = platform_gpio();
+
+	gpio_write(gpio->p1_ctrl0, signal & 1);
+	gpio_write(gpio->p1_ctrl1, (signal >> 1) & 1);
+	gpio_write(gpio->p1_ctrl2, (signal >> 2) & 1);
+}
+
+void p2_ctrl_set(const p2_ctrl_signal_t signal)
+{
+	const platform_gpio_t* gpio = platform_gpio();
+
+	gpio_write(gpio->p2_ctrl0, signal & 1);
+	gpio_write(gpio->p2_ctrl1, (signal >> 1) & 1);
+}
+
+void pps_out_set(const uint8_t value)
+{
+	gpio_write(platform_gpio()->pps_out, value & 1);
+}
+#endif