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

libhackrf: Set a 500ms timeout for changing fpga bitstream

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -0,0 +1,37 @@
+name: Bug Report 
+description: Submit a bug report
+labels: ["bug report"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to fill out this bug report!
+  - type: dropdown
+    id: issue-type
+    attributes: 
+      label: What type of issue is this? 
+      options:
+        - transient - occurring only once
+        - intermittent - occurring irregularly
+        - permanent - occurring repeatedly
+    validations:
+      required: true
+  - type: textarea
+    id: issue
+    attributes:
+      label: What issue are you facing? 
+      placeholder: Please describe what you have encountered
+    validations:
+      required: true
+  - type: textarea
+    id: reproduce-issue
+    attributes:
+      label: What are the steps to reproduce this? 
+      placeholder: Please provide the steps to reproduce this issue
+    validations:
+      required: true      
+  - type: textarea
+    id: logs
+    attributes:
+      label: Can you provide any logs? (output, errors, etc.)
+      placeholder: Please provide any logs you might have that illustrate the issue

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/documentation-request.yml

@@ -0,0 +1,14 @@
+name: Documentation 
+description: Make a request regarding HackRF documentation 
+labels: ["documentation"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to help Great Scott Gadgets improve the HackRF One documentation! 
+  - type: textarea
+    id: documentation-request
+    attributes:
+      label: What would you like us to add to or change about the HackRF One documentation?
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -0,0 +1,16 @@
+name: Feature Request 
+description: File a feature request
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to fill out this feature request form! 
+  - type: textarea
+    id: feature-request
+    attributes:
+      label: What feature would you like to see and why?
+      description: Please be as detailed as possible with your feature request.
+    validations:
+      required: true
+  

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,14 @@
+name: Question  
+description: Ask a question not covered by current hackrf.rtfd.io documentation 
+labels: ["question"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to ask your question! If you need technical support, want to open a feature request, or need to file a bug report, please abandon this issue, open a new issue, and choose the correct template. If you do not choose the correct template, you will be asked to re-open your issue with the correct template. 
+  - type: textarea
+    id: question
+    attributes:
+      label: What would you like to know?
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/technical-support.yml

@@ -0,0 +1,51 @@
+name: Technical Support Request
+description: File a technical support request
+labels: ["technical support"]
+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: textarea
+    id: expected-outcome
+    attributes:
+      label: What outcome were you hoping for?
+      placeholder: Please be detailed in what you expected to happen
+    validations:
+      required: true
+  - type: textarea
+    id: actual-outcome
+    attributes:
+      label: What outcome actually happened? 
+      placeholder: Please be detailed in what did happen
+    validations:
+      required: true
+  - type: textarea
+    id: operating-systems
+    attributes:
+      label: What operating systems are you seeing the problem on?
+    validations:
+      required: true
+  - type: textarea
+    id: hackrf_info-output
+    attributes:
+      label: What is the output of ```hackrf_info```?
+      description: Please put the output of the command in the box below or indicate N/A. 
+    validations:
+      required: true
+  - type: textarea
+    id: third-party-software
+    attributes:
+      label: Are you using any third-party software?
+      description: Please list the software you are using with your HackRF or indicate N/A. Please list version numbers where possible. 
+      placeholder: GNU Radio, GQRX, etc. 
+    validations:
+      required: true
+  - type: textarea
+    id: third-party-hardware
+    attributes:
+      label: Are you using any third-party hardware? 
+      description: Please list any hardware you are using with your HackRF or indicate N/A. 
+      placeholder: portapack, specialized antenna, etc. 
+    validations:
+      required: true

.github/workflows/build.yml

@@ -9,118 +9,286 @@ on:
     - cron: 1 12 * * 1
 
 env:
-  BUILD_TYPE: Release
+
+  # Override OSX architecture detection. Required for CMake versions < 3.19.2.
+  CMAKE_OSX_ARCHITECTURES: arm64
 
 jobs:
   host:
     strategy:
       matrix:
-        os: ['macos-latest', 'ubuntu-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: Create Build Environment
-      run: cmake -E make_directory ${{runner.workspace}}/host/build
+    - name: Install dependencies (Windows)
+      run: vcpkg install --triplet=x64-windows libusb fftw3 pthreads pkgconf
+      if: matrix.os == 'windows' && matrix.shell != 'msys2'
 
-    - name: Configure CMake
-      shell: bash
-      working-directory: ${{runner.workspace}}/host/build
-      run: cmake $GITHUB_WORKSPACE/host/ -DCMAKE_BUILD_TYPE=$BUILD_TYPE
+    - 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: Build
-      working-directory: ${{runner.workspace}}/host/build
-      shell: bash
-      run: cmake --build . --config $BUILD_TYPE
+    # Build libhackrf and hackrf-tools together
 
-    - name: Create Build Environment (libhackrf)
-      run: cmake -E make_directory ${{runner.workspace}}/host/libhackrf/build
+    - 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: Configure CMake (libhackrf)
-      shell: bash
-      working-directory: ${{runner.workspace}}/host/libhackrf/build
-      run: cmake $GITHUB_WORKSPACE/host/libhackrf/ -DCMAKE_BUILD_TYPE=$BUILD_TYPE
+    # Build libhackrf ONLY
 
-    - name: Build (libhackrf)
-      working-directory: ${{runner.workspace}}/host/libhackrf/build
-      shell: bash
-      run: cmake --build . --config $BUILD_TYPE
+    - 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
-      shell: bash
       run: |
-        sudo cmake --install . --config $BUILD_TYPE
+        ${{ matrix.sudo }} cmake ${{ matrix.install_cmd }} host/libhackrf/build ${{ matrix.install_args }} --config Release
 
-    - name: Create Build Environment (hackrf-tools)
-      run: cmake -E make_directory ${{runner.workspace}}/host/hackrf-tools/build
+    # Build hackrf-tools ONLY
 
-    - name: Configure CMake (hackrf-tools)
-      shell: bash
-      working-directory: ${{runner.workspace}}/host/hackrf-tools/build
-      run: cmake $GITHUB_WORKSPACE/host/hackrf-tools/ -DCMAKE_BUILD_TYPE=$BUILD_TYPE
+    - name: Configure & Build (hackrf-tools)
+      run: |
+        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: Build (hackrf-tools)
-      working-directory: ${{runner.workspace}}/host/hackrf-tools/build
-      shell: bash
-      run: cmake --build . --config $BUILD_TYPE
+    - name: Install (hackrf-tools)
+      run: |
+        ${{ matrix.sudo }} cmake ${{ matrix.install_cmd }} host/hackrf-tools/build ${{ matrix.install_args }}
+
+    # 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
-        pip 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
-      run: cmake $GITHUB_WORKSPACE/firmware/ -DCMAKE_BUILD_TYPE=$BUILD_TYPE -DBOARD=${{ matrix.board }}
+      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 $BUILD_TYPE
+      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
-ENV DEBIAN_FRONTEND=noninteractive 
+# 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,9 +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
+
+# 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,37 +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'
             }
         }
     }
     post {
         always {
-            sh './ci-scripts/configure-hubs.sh --reset'
-            sh 'rm -rf testing-venv/'
             cleanWs(cleanWhenNotBuilt: false,
                     deleteDirs: true,
                     disableDeferredWipeout: true,
@@ -39,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,14 +15,19 @@ 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`
+* navigate to hackrf/docs on command line
+* run the command `make latex`
+* run the command `make latexpdf`
 
 --------------------
 
 # 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-debug.py

@@ -0,0 +1,37 @@
+#!/usr/bin/python3
+import sys
+import subprocess
+
+PASS, FAIL  = range(2)
+EUT         = "RunningFromRAM"
+
+
+def check_debug(target, register, reg_val):
+    hackrf_debug = subprocess.run(["host/build/hackrf-tools/src/hackrf_debug",
+                                   f"--{target}", "--register", register,
+                                   "--read", "--device", EUT],
+                                  capture_output=True, encoding="UTF-8")
+
+    if reg_val in hackrf_debug.stdout:
+        print(f"hackrf_debug --{target} passed.")
+        return PASS
+    else:
+        print(f"hackrf_debug --{target} failed.")
+        return FAIL
+
+
+def main():
+    results = [
+        check_debug("si5351c", "2", "0x03"),
+        check_debug("max2837", "3", "0x1b9"),
+        check_debug("rffc5072", "2", "0x9055"),
+    ]
+
+    if FAIL not in results:
+        sys.exit(PASS)
+    else:
+        sys.exit(FAIL)
+
+
+if __name__ == "__main__":
+    main()

ci-scripts/test-firmware-flash.sh

@@ -3,7 +3,7 @@ host/build/hackrf-tools/src/hackrf_spiflash -w firmware/hackrf_usb/build/hackrf_
 EXIT_CODE="$?"
 if [ "$EXIT_CODE" == "1" ]
 then
-    echo "No GreatFET found! Disconnected? Exiting.."
+    echo "No HackRF found! Disconnected? Exiting.."
     exit $EXIT_CODE
 elif [ "$EXIT_CODE" == "0" ]
 then
@@ -13,6 +13,6 @@ then
     echo "Host tool installation failed! Exiting.."
     exit $EXIT_CODE
 else
-    echo "god have mercy on your soul"
+    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
+dfu-util --device 1fc9:000c --alt 0 --download firmware/hackrf_usb/build/hackrf_usb.dfu
 sleep 1s
-dfu-util --path 1-1.2 --alt 0 --download firmware/hackrf_usb/build/hackrf_usb.dfu
 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

@@ -0,0 +1,127 @@
+#!/usr/bin/python3
+import subprocess
+import time
+import sys
+from os import environ
+
+EUT     = environ.get('EUT')
+TESTER  = environ.get('TESTER')
+PASS, FAIL = range(2)
+
+
+def write_bytes():
+    tx_bytes = b'\x7f\x00\x59\x59\x00\x7f\xa7\x59\x81\x00\xa7\xa7\x00\x81\x59\xa7'
+    with open("/tmp/binary100", "wb") as bin_file:
+        for i in range(62500):  # 1MB file size
+            bin_file.write(tx_bytes)
+
+
+def capture_signal(sweep_range, tx_gain, rx_lna_gain, rx_vga_gain, freq=None,
+                   if_freq=None, lo_freq=None, image_reject=0):
+
+    test_type = sys.argv[1]
+    if test_type == "tx":
+        transmitter = EUT
+        receiver = TESTER
+    elif test_type == "rx":
+        transmitter = TESTER
+        receiver = EUT
+    else:
+        print(f"Invalid command-line argument: {test_type}. Use tx or rx")
+        sys.exit(1)
+
+    if if_freq == None:
+        transmit = subprocess.Popen(["host/build/hackrf-tools/src/hackrf_transfer",
+                                     "-d", transmitter, "-R", "-t", "/tmp/binary100",
+                                     "-a", "0", "-x", tx_gain, "-f", freq],
+                                    stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    else:
+        transmit = subprocess.Popen(["host/build/hackrf-tools/src/hackrf_transfer",
+                                     "-d", transmitter, "-R", "-t", "/tmp/binary100",
+                                     "-a", "0", "-x", tx_gain, "-i", if_freq,
+                                     "-o", lo_freq, "-m", image_reject],
+                                     stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+
+    time.sleep(1)
+    sweep = subprocess.Popen(["host/build/hackrf-tools/src/hackrf_sweep",
+                              "-d", receiver, "-N", "2", "-w", "333333",
+                              "-f", sweep_range, "-a", "0", "-l", rx_lna_gain,
+                              "-g", rx_vga_gain],
+                             stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    sweep.wait()
+    transmit.terminate()
+    transmit.wait()
+
+    # parse the hackrf_sweep output
+    data, stderr = sweep.communicate()
+    data = data.decode("utf-8")
+    data = data.split("\n")
+    print(data[4])
+    data = data[4]  # Note: using data from the 2nd sweep until issue #1230 is resolved.
+    data = data.split(", ")
+    data = data[6:21]
+    bins = [float(bin) for bin in data]
+    return bins
+
+
+def check_signal(freq, bins):
+    signal = bins.pop(1)
+    signal_threshold = -25
+    max_power = -10
+    result = PASS
+
+    if signal < signal_threshold:
+        print(f"Signal not strong enough at {freq} MHz")
+        result = FAIL
+    elif signal > max_power:
+        print(f"Received signal exceeded maximum power at {freq} MHz")
+        result = 1
+
+    for bin in bins:
+        if bin > max_power or bin > signal:
+            print(f"Non-target bin power exceeded max power threshold at {freq} MHz")
+            result = FAIL
+            break
+
+    return result
+
+
+def main():
+    write_bytes()
+    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",
+                                            "-o", "1", "-d", EUT])
+    tester_clkout_off   = subprocess.Popen(["host/build/hackrf-tools/src/hackrf_clock",
+                                            "-o", "0", "-d", TESTER])
+    eut_clkout_on.wait()
+    tester_clkout_off.wait()
+
+    _9_5Mhz_data    = capture_signal(sweep_range="9:29", tx_gain="38", rx_lna_gain="16",
+                                     rx_vga_gain="16", if_freq="2628250000",
+                                     lo_freq="2620000000", image_reject="1")
+    _915_5Mhz_data  = capture_signal(sweep_range="915:935", tx_gain="38", rx_lna_gain="16",
+                                     rx_vga_gain="16", if_freq="2540750000",
+                                     lo_freq="3455000000", image_reject="1")
+    _2665_5Mhz_data = capture_signal(sweep_range="2665:2685", tx_gain="26", rx_lna_gain="16",
+                                     rx_vga_gain="16", freq="2664250000")
+    _5999_5Mhz_data = capture_signal(sweep_range="5999:6019", tx_gain="37", rx_lna_gain="32",
+                                     rx_vga_gain="40", if_freq="2540750000",
+                                     lo_freq="3460000000", image_reject="2")
+
+    lp1_result  = check_signal(9.5, _9_5Mhz_data)
+    lp2_result  = check_signal(915.5, _915_5Mhz_data)
+    bp_result   = check_signal(2665.5, _2665_5Mhz_data)
+    hp_result   = check_signal(5999.5, _5999_5Mhz_data)
+    results     = [lp1_result, lp2_result, bp_result, hp_result]
+
+    if FAIL in results:
+        sys.exit(FAIL)
+    else:
+        sys.exit(PASS)
+
+
+if __name__ == "__main__":
+    main()
+

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/images/block-diagram.svg

@@ -1,22 +1,22 @@
 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
 <svg
-   xmlns:dc="http://purl.org/dc/elements/1.1/"
-   xmlns:cc="http://creativecommons.org/ns#"
-   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
-   xmlns:svg="http://www.w3.org/2000/svg"
-   xmlns="http://www.w3.org/2000/svg"
-   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
-   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
    width="1280"
    height="720"
    viewBox="0 0 338.66666 190.50001"
    version="1.1"
    id="svg8"
-   inkscape:version="1.0.1 (3bc2e813f5, 2020-09-07)"
+   inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)"
    sodipodi:docname="block-diagram.svg"
-   inkscape:export-filename="C:\Users\Martin\Documents\hackrf\docs\images\block-diagram.png"
+   inkscape:export-filename="block-diagram.png"
    inkscape:export-xdpi="96"
-   inkscape:export-ydpi="96">
+   inkscape:export-ydpi="96"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:dc="http://purl.org/dc/elements/1.1/">
   <defs
      id="defs2">
     <marker
@@ -163,9 +163,9 @@
      borderopacity="1.0"
      inkscape:pageopacity="0.0"
      inkscape:pageshadow="2"
-     inkscape:zoom="1"
-     inkscape:cx="633.92814"
-     inkscape:cy="396.56459"
+     inkscape:zoom="0.70710678"
+     inkscape:cx="603.16209"
+     inkscape:cy="390.32295"
      inkscape:document-units="px"
      inkscape:current-layer="layer1"
      inkscape:document-rotation="0"
@@ -173,17 +173,18 @@
      units="px"
      inkscape:snap-text-baseline="true"
      showguides="true"
-     inkscape:window-width="1920"
-     inkscape:window-height="1137"
-     inkscape:window-x="-8"
-     inkscape:window-y="-8"
+     inkscape:window-width="1916"
+     inkscape:window-height="1005"
+     inkscape:window-x="1600"
+     inkscape:window-y="54"
      inkscape:window-maximized="1"
      inkscape:snap-object-midpoints="false"
      inkscape:snap-bbox="false"
      inkscape:snap-page="true"
      inkscape:bbox-nodes="true"
      inkscape:snap-nodes="true"
-     inkscape:snap-others="true">
+     inkscape:snap-others="true"
+     inkscape:pagecheckerboard="0">
     <inkscape:grid
        type="xygrid"
        id="grid833"
@@ -235,11 +236,6 @@
        height="80.433342"
        x="203.20001"
        y="21.166662" />
-    <path
-       style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.529167, 0.529167;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
-       d="m 213.78333,40.216668 1e-5,15.875 h 12.7 l -1e-5,39.158334 23.28334,0"
-       id="path2723"
-       sodipodi:nodetypes="ccccc" />
     <g
        id="g4744"
        transform="matrix(0,1,1,0,182.03336,-118.53334)">
@@ -1456,29 +1452,6 @@
          x="206.37503"
          y="28.575012"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:5.82083px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583">MAX2837 </tspan></text>
-    <g
-       id="g2581"
-       transform="translate(12.699999,16.933341)">
-      <rect
-         style="fill:#4095bf;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
-         id="rect2575"
-         width="12.699997"
-         height="8.4666672"
-         x="194.73335"
-         y="27.516672" />
-      <text
-         xml:space="preserve"
-         style="font-size:2.64583px;line-height:1.25;font-family:sans-serif;stroke-width:0.264583"
-         x="201.08334"
-         y="33.866669"
-         id="text2579"><tspan
-           sodipodi:role="line"
-           id="tspan2577"
-           x="201.08334"
-           y="33.866669"
-           style="font-size:6.35px;text-align:center;text-anchor:middle;stroke-width:0.264583"
-           rotate="0 0 0 0">LPF</tspan></text>
-    </g>
     <g
        id="g2689"
        transform="translate(12.700006,4.2333395)">
@@ -1569,54 +1542,6 @@
        style="fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="M 259.29169,42.333333 257.17502,41.275 v 2.116667 z"
        id="path2697" />
-    <g
-       id="g2805"
-       transform="matrix(-1,0,0,1,427.56669,33.866685)">
-      <rect
-         style="fill:#4095bf;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
-         id="rect2799"
-         width="12.700001"
-         height="8.4666672"
-         x="194.73335"
-         y="27.516666" />
-      <text
-         xml:space="preserve"
-         style="font-size:2.64583px;line-height:1.25;font-family:sans-serif;stroke-width:0.529167;stroke-miterlimit:4;stroke-dasharray:none"
-         x="-201.33759"
-         y="33.866669"
-         id="text2803"
-         transform="scale(-1,1)"><tspan
-           sodipodi:role="line"
-           id="tspan2801"
-           x="-201.33759"
-           y="33.866669"
-           style="font-size:6.35px;text-align:center;text-anchor:middle;stroke-width:0.529167;stroke-miterlimit:4;stroke-dasharray:none"
-           rotate="0 0 0 0">LPF</tspan></text>
-    </g>
-    <g
-       id="g2813"
-       transform="matrix(-1,0,0,1,427.56669,46.566685)">
-      <rect
-         style="fill:#4095bf;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
-         id="rect2807"
-         width="12.700001"
-         height="8.4666672"
-         x="194.73335"
-         y="27.516666" />
-      <text
-         xml:space="preserve"
-         style="font-size:2.64583px;line-height:1.25;font-family:sans-serif;stroke-width:0.264583"
-         x="-201.33759"
-         y="33.866669"
-         id="text2811"
-         transform="scale(-1,1)"><tspan
-           sodipodi:role="line"
-           id="tspan2809"
-           x="-201.33759"
-           y="33.866669"
-           style="font-size:6.35px;text-align:center;text-anchor:middle;stroke-width:0.264583"
-           rotate="0 0 0 0">LPF</tspan></text>
-    </g>
     <g
        id="g2819"
        transform="matrix(-1,0,0,1,427.56669,33.866685)">
@@ -1837,7 +1762,7 @@
          id="tspan3054"
          x="207.43335"
          y="99.483337"
-         style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.175px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.264583">2150–2750 MHz</tspan></text>
+         style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.175px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.264583">2170–2740 MHz</tspan></text>
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.175px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.264583"
@@ -2586,22 +2511,22 @@
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.264583"
-       x="281.51669"
+       x="281.23917"
        y="41.274998"
        id="text3678"><tspan
          sodipodi:role="line"
-         x="281.51669"
+         x="281.23917"
          y="41.274998"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          id="tspan3676">TX_IF</tspan></text>
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.264583"
-       x="280.45834"
+       x="281.00922"
        y="70.90834"
        id="text3682"><tspan
          sodipodi:role="line"
-         x="280.45834"
+         x="281.00922"
          y="70.90834"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          id="tspan3680">RX_IF</tspan></text>
@@ -2845,17 +2770,17 @@
          x="16.933332"
          y="177.39795"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.1;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.264583"
-         id="tspan810">1–2150 MHz: 5–15 dBm</tspan><tspan
+         id="tspan810">1–2170 MHz: 5–15 dBm</tspan><tspan
          sodipodi:role="line"
          x="16.933332"
          y="180.30836"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.1;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.264583"
-         id="tspan812">2150–2750 MHz: 13–15 dBm</tspan><tspan
+         id="tspan812">2170–2740 MHz: 13–15 dBm</tspan><tspan
          sodipodi:role="line"
          x="16.933332"
          y="183.21878"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.1;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.264583"
-         id="tspan816">2750–4000 MHz: 0–5 dBm</tspan><tspan
+         id="tspan816">2740–4000 MHz: 0–5 dBm</tspan><tspan
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.1;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.264583"
          sodipodi:role="line"
          id="tspan822"
@@ -3275,7 +3200,7 @@
        id="path4820" />
     <path
        style="fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 31.750002,143.93334 2.11667,1.05834 v -2.11667 z"
+       d="m 31.913522,143.93334 2.11667,1.05834 v -2.11667 z"
        id="path4822" />
     <text
        xml:space="preserve"
@@ -3603,7 +3528,7 @@
          id="tspan1878"
          x="226.48334"
          y="147.10834"
-         style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.175px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.264583">&gt; 2750 MHz</tspan></text>
+         style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.175px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.264583">&gt; 2740 MHz</tspan></text>
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.175px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:center;text-anchor:middle;stroke-width:0.264583"
@@ -3614,7 +3539,7 @@
          id="tspan1882"
          x="226.48334"
          y="164.04167"
-         style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.175px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.264583">&lt; 2150 MHz</tspan></text>
+         style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.175px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';stroke-width:0.264583">&lt; 2170 MHz</tspan></text>
     <path
        style="opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
        d="m 247.65003,118.53335 27.51665,-1e-5"
@@ -3808,74 +3733,74 @@
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
-       x="281.51669"
+       x="281.00922"
        y="87.841675"
        id="text1778"><tspan
          sodipodi:role="line"
-         x="281.51669"
+         x="281.00922"
          y="87.841675"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          id="tspan1776">MIX_BYPASS</tspan></text>
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
-       x="270.93335"
+       x="270.42587"
        y="176.74168"
        id="text1782"><tspan
          sodipodi:role="line"
-         x="270.93335"
+         x="270.42587"
          y="176.74168"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          id="tspan1780">RX</tspan></text>
     <path
-       style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.529167, 0.529167;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
-       d="m 270.93337,177.80001 h 8.46666 v -61.38334"
+       style="font-variation-settings:normal;opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.52916668;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.52916668,0.52916668;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
+       d="m 270.66875,177.79994 h 8.73118 v -61.38327"
        id="path1786"
        sodipodi:nodetypes="ccc" />
     <path
-       style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.529167, 0.529167;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
-       d="m 190.50002,177.80001 h 63.5 v -14.81666"
+       style="font-variation-settings:normal;opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.52916668;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.52916668,0.52916668;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
+       d="M 190.23542,177.80001 H 254 v -14.81666"
        id="path1788"
        sodipodi:nodetypes="ccc" />
     <path
-       style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.529167, 0.529167;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
+       style="font-variation-settings:normal;opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.52916699;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.52916699,0.52916699;stroke-dashoffset:0.2645835;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
        d="M 198.96668,177.80001 V 162.98335"
        id="path1790" />
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
-       x="190.50002"
+       x="189.99254"
        y="176.74168"
        id="text1794"><tspan
          sodipodi:role="line"
-         x="190.50002"
+         x="189.99254"
          y="176.74168"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          id="tspan1792">LP</tspan></text>
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
-       x="63.500004"
+       x="63.2225"
        y="185.20834"
        id="text1798"><tspan
          sodipodi:role="line"
-         x="63.500004"
+         x="63.2225"
          y="185.20834"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          id="tspan1796">TX_AMP</tspan></text>
     <path
-       style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.529167, 0.529167;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
-       d="m 63.500004,186.26668 67.733346,0 v -23.28333"
+       style="font-variation-settings:normal;opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529174;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.529174, 0.529174;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
+       d="M 63.235418,186.26668 H 131.23333 V 162.98335"
        id="path1800"
        sodipodi:nodetypes="ccc" />
     <path
-       style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.529167, 0.529167;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
+       style="font-variation-settings:normal;opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.52916699;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.52916699,0.52916699;stroke-dashoffset:0.2645835;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
        d="M 84.666674,186.26668 V 162.98335"
        id="path1802"
        sodipodi:nodetypes="cc" />
     <path
-       style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.529167, 0.529167;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
-       d="M 281.51667,88.900008 H 300.5667 V 44.450004"
+       style="font-variation-settings:normal;opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.52916668;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.52916668,0.52916668;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
+       d="m 281.25209,88.899987 h 19.31457 V 44.450004"
        id="path1804" />
     <path
        style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
@@ -3942,18 +3867,18 @@
        sodipodi:nodetypes="ccc" />
     <path
        style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
-       d="M 57.150004,150.28335 H 40.216668"
+       d="M 57.150004,150.28335 H 39.952084"
        id="path2613"
        sodipodi:nodetypes="cc" />
     <text
        xml:space="preserve"
        style="font-size:2.64583px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:0.264583"
-       x="40.216667"
+       x="39.775093"
        y="149.22501"
        id="text2617"><tspan
          sodipodi:role="line"
          id="tspan2615"
-         x="40.216667"
+         x="39.775093"
          y="149.22501"
          style="font-weight:bold;text-align:start;text-anchor:start;stroke-width:0.264583">3.3V 50mA</tspan></text>
     <ellipse
@@ -3993,87 +3918,88 @@
     </g>
     <path
        style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.529167, 0.529167;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
-       d="m 40.21667,158.75002 h 21.166667 v -2.11667"
-       id="path2634" />
+       d="m 39.952084,158.75002 h 21.431253 v -2.11667"
+       id="path2634"
+       sodipodi:nodetypes="ccc" />
     <text
        xml:space="preserve"
        style="font-size:2.64583px;line-height:1.25;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:0.264583"
-       x="40.216667"
+       x="39.581306"
        y="157.69168"
        id="text2638"><tspan
          sodipodi:role="line"
          id="tspan2636"
-         x="40.216667"
+         x="39.581306"
          y="157.69168"
          style="font-weight:bold;text-align:start;text-anchor:start;stroke-width:0.264583">!ANT_BIAS</tspan></text>
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
-       x="63.5"
+       x="62.992538"
        y="178.85834"
        id="text1611"><tspan
          sodipodi:role="line"
-         x="63.5"
+         x="62.992538"
          y="178.85834"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          id="tspan1609">RX_AMP</tspan></text>
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
-       x="63.5"
+       x="63.2225"
        y="182.03334"
        id="text1615"><tspan
          sodipodi:role="line"
-         x="63.5"
+         x="63.2225"
          y="182.03334"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          id="tspan1613">AMP_BYPASS</tspan></text>
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
-       x="190.50002"
+       x="189.99254"
        y="173.56668"
        id="text1619"><tspan
          sodipodi:role="line"
-         x="190.50002"
+         x="189.99254"
          y="173.56668"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          id="tspan1617">HP</tspan></text>
     <path
-       style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.529, 0.529;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
-       d="m 143.93334,186.26668 h 21.16667 v -23.28333"
+       style="font-variation-settings:normal;opacity:1;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529204;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.529204, 0.529204;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
+       d="m 143.66875,186.26666 h 21.43123 v -23.28331"
        id="path1621"
        sodipodi:nodetypes="ccc" />
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
-       x="143.93335"
+       x="143.65584"
        y="185.20834"
        id="text1625"><tspan
          sodipodi:role="line"
-         x="143.93335"
+         x="143.65584"
          y="185.20834"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          id="tspan1623">TX_MIX_BP</tspan></text>
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
-       x="143.93335"
+       x="143.29797"
        y="178.85834"
        id="text1629"><tspan
          sodipodi:role="line"
-         x="143.93335"
+         x="143.29797"
          y="178.85834"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          id="tspan1627">!MIX_BYPASS</tspan></text>
     <text
        xml:space="preserve"
        style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
-       x="143.93335"
+       x="143.42587"
        y="182.03334"
        id="text1633"><tspan
          sodipodi:role="line"
-         x="143.93335"
+         x="143.42587"
          y="182.03334"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          id="tspan1631">RX_MIX_BP</tspan></text>
@@ -4175,6 +4101,11 @@
        style="fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m 225.42502,88.900005 -2.11667,-1.05834 v 2.11667 z"
        id="path2876" />
+    <path
+       style="font-variation-settings:normal;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:0.529167, 0.529167;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000"
+       d="m 213.78334,39.952084 1e-5,16.139584 h 12.7 l -1e-5,39.158335 h 23.28334"
+       id="path2723"
+       sodipodi:nodetypes="ccccc" />
     <path
        style="fill:#000000;fill-opacity:1;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
        d="m 225.42502,93.133338 -2.11667,-1.05834 v 2.11667 z"
@@ -4243,65 +4174,91 @@
            style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:6.90875px;line-height:0.85;font-family:'League Gothic';-inkscape-font-specification:'League Gothic Bold';text-align:end;text-anchor:end;stroke-width:0.172719"
            id="tspan3429">GADGETS</tspan></text>
     </g>
+    <path
+       style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
+       d="m 16.933335,136.52501 h 1.058333 v -2.11667 h 2.116667 v 2.11667 h 2.116667 v -2.11667 h 2.116666 v 2.11667 h 2.116666 v -2.11667 h 2.116669 v 2.11667 h 1.058334"
+       id="path1717" />
+    <path
+       style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
+       d="m 16.933336,153.45836 h 1.058333 v -2.11667 h 2.116667 v 2.11667 h 2.116667 v -2.11667 h 2.116666 v 2.11667 h 2.116666 v -2.11667 h 2.116669 v 2.11667 h 1.058334"
+       id="path1719" />
     <g
-       id="g3853">
+       id="g3853"
+       transform="translate(-0.23745481,-0.10144164)">
       <text
          xml:space="preserve"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          x="129.11667"
-         y="134.40834"
+         y="135.99582"
          id="text1551"><tspan
            sodipodi:role="line"
            x="129.11667"
-           y="134.40834"
+           y="135.99582"
            style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.23333px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
-           id="tspan1553">Diagram Revision: A</tspan><tspan
+           id="tspan1553">Diagram Revision: C</tspan><tspan
            sodipodi:role="line"
            x="129.11667"
-           y="138.29544"
+           y="139.88292"
            style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:5.29167px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
            id="tspan1559" /></text>
+      <text
+         xml:space="preserve"
+         style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
+         x="129.11667"
+         y="131.23338"
+         id="text1551-3"><tspan
+           sodipodi:role="line"
+           x="129.11667"
+           y="131.23338"
+           style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:4.23333px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
+           id="tspan1553-6">Hardware Revision: r1-r8</tspan><tspan
+           sodipodi:role="line"
+           x="129.11667"
+           y="135.12048"
+           style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:5.29167px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
+           id="tspan1559-7" /></text>
       <text
          xml:space="preserve"
          style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.175px;line-height:1.25;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
          x="129.11667"
-         y="138.64168"
+         y="140.75832"
          id="text1563"><tspan
            sodipodi:role="line"
            id="tspan1561"
            x="129.11667"
-           y="138.64168"
-           style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:3.175px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583">© Great Scott Gadgets 2022</tspan><tspan
+           y="140.75832"
+           style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583">© Great Scott Gadgets 2022-2023</tspan><tspan
            sodipodi:role="line"
            x="129.11667"
-           y="142.61043"
+           y="144.72707"
            style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:2.64583px;font-family:sans-serif;-inkscape-font-specification:'sans-serif Bold';text-align:start;text-anchor:start;stroke-width:0.264583"
            id="tspan3512" /></text>
       <rect
-         style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.264583;stroke-linecap:square;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
+         style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.299903;stroke-linecap:square;stroke-miterlimit:4;stroke-dasharray:none;stroke-opacity:1"
          id="rect3475"
-         width="71.966675"
-         height="19.050007"
-         x="127.00001"
-         y="129.11667" />
+         width="71.947708"
+         height="24.481998"
+         x="127.00948"
+         y="125.59979" />
       <text
          xml:space="preserve"
          style="font-size:2.64583px;line-height:0;font-family:sans-serif;text-align:center;text-anchor:middle;stroke-width:0.264583"
          x="129.10376"
-         y="142.76855"
+         y="144.88519"
          id="text3532"><tspan
            sodipodi:role="line"
            id="tspan3530"
            x="129.10376"
-           y="142.76855"
+           y="144.88519"
            style="font-weight:bold;line-height:1.1;text-align:start;text-anchor:start;stroke-width:0.264583">This design may be copied &amp; used</tspan><tspan
            sodipodi:role="line"
            x="129.10376"
-           y="145.67897"
+           y="147.79561"
            style="font-weight:bold;line-height:1.1;text-align:start;text-anchor:start;stroke-width:0.264583"
            id="tspan3534">under the terms of CERN-OHL-P v2</tspan></text>
       <g
-         id="g3819">
+         id="g3819"
+         transform="translate(0,2.1166668)">
         <g
            transform="matrix(0.0574526,0,0,-0.0574526,161.22832,155.90395)"
            id="g3012"
@@ -4392,13 +4349,76 @@
         </g>
       </g>
     </g>
-    <path
-       style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
-       d="m 16.933335,136.52501 h 1.058333 v -2.11667 h 2.116667 v 2.11667 h 2.116667 v -2.11667 h 2.116666 v 2.11667 h 2.116666 v -2.11667 h 2.116669 v 2.11667 h 1.058334"
-       id="path1717" />
-    <path
-       style="font-variation-settings:normal;opacity:1;vector-effect:none;fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1;stop-color:#000000;stop-opacity:1"
-       d="m 16.933336,153.45836 h 1.058333 v -2.11667 h 2.116667 v 2.11667 h 2.116667 v -2.11667 h 2.116666 v 2.11667 h 2.116666 v -2.11667 h 2.116669 v 2.11667 h 1.058334"
-       id="path1719" />
+    <g
+       id="g2581"
+       transform="translate(12.699999,16.933341)">
+      <rect
+         style="fill:#4095bf;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="rect2575"
+         width="12.699997"
+         height="8.4666672"
+         x="194.73335"
+         y="27.516672" />
+      <text
+         xml:space="preserve"
+         style="font-size:2.64583px;line-height:1.25;font-family:sans-serif;stroke-width:0.264583"
+         x="201.08334"
+         y="33.866669"
+         id="text2579"><tspan
+           sodipodi:role="line"
+           id="tspan2577"
+           x="201.08334"
+           y="33.866669"
+           style="font-size:6.35px;text-align:center;text-anchor:middle;stroke-width:0.264583"
+           rotate="0 0 0 0">LPF</tspan></text>
+    </g>
+    <g
+       id="g2805"
+       transform="matrix(-1,0,0,1,427.56669,33.866685)">
+      <rect
+         style="fill:#4095bf;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="rect2799"
+         width="12.700001"
+         height="8.4666672"
+         x="194.73335"
+         y="27.516666" />
+      <text
+         xml:space="preserve"
+         style="font-size:2.64583px;line-height:1.25;font-family:sans-serif;stroke-width:0.529167;stroke-miterlimit:4;stroke-dasharray:none"
+         x="-201.33759"
+         y="33.866669"
+         id="text2803"
+         transform="scale(-1,1)"><tspan
+           sodipodi:role="line"
+           id="tspan2801"
+           x="-201.33759"
+           y="33.866669"
+           style="font-size:6.35px;text-align:center;text-anchor:middle;stroke-width:0.529167;stroke-miterlimit:4;stroke-dasharray:none"
+           rotate="0 0 0 0">LPF</tspan></text>
+    </g>
+    <g
+       id="g2813"
+       transform="matrix(-1,0,0,1,427.56669,46.566685)">
+      <rect
+         style="fill:#4095bf;fill-opacity:1;stroke:#000000;stroke-width:0.529167;stroke-linecap:round;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="rect2807"
+         width="12.700001"
+         height="8.4666672"
+         x="194.73335"
+         y="27.516666" />
+      <text
+         xml:space="preserve"
+         style="font-size:2.64583px;line-height:1.25;font-family:sans-serif;stroke-width:0.264583"
+         x="-201.33759"
+         y="33.866669"
+         id="text2811"
+         transform="scale(-1,1)"><tspan
+           sodipodi:role="line"
+           id="tspan2809"
+           x="-201.33759"
+           y="33.866669"
+           style="font-size:6.35px;text-align:center;text-anchor:middle;stroke-width:0.264583"
+           rotate="0 0 0 0">LPF</tspan></text>
+    </g>
   </g>
 </svg>

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/LPC4350.rst

@@ -1,168 +0,0 @@
-================================================
-LPC4350 SGPIO Experimentation
-================================================
-
-The NXP LPC43xx microcontrollers have an interesting, programmable serial peripheral called the SGPIO (Serial GPIO). It consists of a slew of counters and shift registers that can be configured to serialize and deserialize many channels of data. Channels can be grouped to create multi-bit parallel data streams.
-
-The current HackRF design entails using the SGPIO peripheral to move quadrature baseband receive and transmit data between the USB interface and the baseband ADC/DAC IC. Because the baseband ADC/DAC IC (MAX5864) uses DDR signaling, we expect to use a CPLD to convert bus signaling. The CPLD may also help manage bus turnaround (between transmit and receive modes) or interfacing two narrower but faster interfaces to the LPC43xx to facilitate full-duplex.
-
-Because the Jellybean board wasn't completed at the time of these experiments, I used the Diolan LPC-4350-DB1-A development board. Despite using an LPC4350 in an BGA256 package, the SGPIO peripheral's signals can be mapped to many different pins. So reworking code to a new set of SGPIO pins should be a trivial matter of switching the SGU configuration for the affected pins.
-
-
-
-SGPIO Examples
-~~~~~~~~~~~~~~
-
-Some SGPIO peripheral examples can be found in `the LPCWare repository <http://sw.lpcware.com/?p=lpc43xx.git&a=summary>`__. All source I've found so far is focused on generating many I2S interfaces, which is not very similar to HackRF's needs. But reviewing the code is still valuable in grasping how the SGPIO peripheral operates.
-
-There are a few common details to setting up the SGPIO peripheral:
-
-.. code-block :: C
-
-	// Configure the PLL to generate a reasonable clock. The SGPIO
-	// will operate with a clock of up to 204MHz (the same as the
-	// M4 clock.
-	CGU_SetPLL1(12);
-
-	// Set the BASE_PERIPH clock to come from PLL1.
-	CGU_EnableEntity(CGU_BASE_PERIPH, ENABLE);
-	CGU_EntityConnect(CGU_CLKSRC_PLL1, CGU_BASE_PERIPH);
-
-	// Compute and commit clock configuration changes.
-	CGU_UpdateClock();
-
-
-
-Jiggle SGPIO Pins From GPIO Mode
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-My first test was to ensure I had the right pin(s) hooked up to my scope:
-
-.. code-block :: C
-
-	// Jiggle one of the SGPIO pins in GPIO mode, to make sure
-	// I'm looking at the right pin on the scope.
-	scu_pinmux(9,  0, MD_PLN_FAST, 0);	
-
-	GPIO_SetDir(4, 1L << 12, 1);
-
-	while(1) {
-	    volatile int i;
-	    GPIO_SetValue(4, 1L << 12);
-	    for(i=0; i<1000; i++);
-	    GPIO_ClearValue(4, 1L << 12);
-	    for(i=0; i<1000; i++);
-	}
-
-
-
-Jiggle Pins from SGPIO Mode
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-You can also control SGPIO pins, GPIO-style, from within the SGPIO peripheral. This helped me understand the basics of operating the SGPIO output mux.
-
-.. code-block :: C
-
-	// Set pin to SGPIO mode, toggle output using SGPIO
-	// peripheral registers.
-	scu_pinmux(9,  0, MD_PLN_FAST, 6);  // SGPIO0
-
-	// P_OUT_CFG = 4, gpio_out
-	// P_OE_CFG = X
-	LPC_SGPIO->OUT_MUX_CFG[0] = (0L << 4) | (4L << 0);
-	LPC_SGPIO->GPIO_OENREG |= (1L << 0);
-
-	while(1) {
-	    volatile int i;
-	    LPC_SGPIO->GPIO_OUTREG |= (1L << 0);
-	    for(i=0; i<1000; i++);
-	    LPC_SGPIO->GPIO_OUTREG &= ~(1L << 0);
-	    for(i=0; i<1000; i++);
-	}
-
-
-Serializing Data With Slice Clock Source
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-My first full-on SGPIO experiment involved serializing a data pattern from slice A, using slice D to generate a SGPIO_CLK/2 data rate. I derived the code from examples that configured the SGPIO as I2S interfaces:
-
-.. code-block :: C
-
-	// Disable all counters during configuration
-	LPC_SGPIO->CTRL_ENABLED = 0;
-
-	// Configure pin functions.
-	scu_pinmux(9,  0, MD_PLN_FAST, 6);  // SGPIO0
-	scu_pinmux(2,  3, MD_PLN_FAST, 0);  // SGPIO12
-
-	// Enable SGPIO pin outputs.
-	LPC_SGPIO->GPIO_OENREG =
-	    (1L << 12) |    // SGPIO12
-	    (1L <<  0);     // SGPIO0
-
-	// SGPIO pin 0 outputs slice A bit 0.
-	LPC_SGPIO->OUT_MUX_CFG[0] =
-	    (0L <<  4) |    // P_OE_CFG = X
-	    (0L <<  0);     // P_OUT_CFG = 0, dout_doutm1 (1-bit mode)
-
-	// SGPIO pin 12 outputs slice D bit 0.
-	LPC_SGPIO->OUT_MUX_CFG[12] =
-	    (0L <<  4) |    // P_OE_CFG = X
-	    (0L <<  0);     // P_OUT_CFG = 0, dout_doutm1 (1-bit mode)
-
-	// Slice A
-	LPC_SGPIO->SGPIO_MUX_CFG[0] = 
-	    (0L << 12) |    // CONCAT_ORDER = 0 (self-loop)
-	    (1L << 11) |    // CONCAT_ENABLE = 1 (concatenate data)
-	    (0L <<  9) |    // QUALIFIER_SLICE_MODE = X
-	    (0L <<  7) |    // QUALIFIER_PIN_MODE = X
-	    (0L <<  5) |    // QUALIFIER_MODE = 0 (enable)
-	    (0L <<  3) |    // CLK_SOURCE_SLICE_MODE = 0, slice D
-	    (0L <<  1) |    // CLK_SOURCE_PIN_MODE = X
-	    (0L <<  0);     // EXT_CLK_ENABLE = 0, internal clock signal (slice)
-	    
-	LPC_SGPIO->SLICE_MUX_CFG[0] =
-	    (0L <<  8) |    // INV_QUALIFIER = 0 (use normal qualifier)
-	    (0L <<  6) |    // PARALLEL_MODE = 0 (shift 1 bit per clock)
-	    (0L <<  4) |    // DATA_CAPTURE_MODE = 0 (detect rising edge)
-	    (0L <<  3) |    // INV_OUT_CLK = 0 (normal clock)
-	    (0L <<  2) |    // CLKGEN_MODE = 0 (use clock from COUNTER)
-	    (0L <<  1) |    // CLK_CAPTURE_MODE = 0 (use rising clock edge)
-	    (0L <<  0);     // MATCH_MODE = 0 (do not match data)
-	    
-	LPC_SGPIO->PRESET[0] = 1;
-	LPC_SGPIO->COUNT[0] = 0;
-	LPC_SGPIO->POS[0] = (0x1FL << 8) | (0x1FL << 0);
-	LPC_SGPIO->REG[0] = 0xAAAAAAAA;     // Primary output data register
-	LPC_SGPIO->REG_SS[0] = 0xAAAAAAAA;  // Shadow output data register
-
-	// Slice D (clock for Slice A)
-	LPC_SGPIO->SGPIO_MUX_CFG[3] = 
-	    (0L << 12) |    // CONCAT_ORDER = 0 (self-loop)
-	    (1L << 11) |    // CONCAT_ENABLE = 1 (concatenate data)
-	    (0L <<  9) |    // QUALIFIER_SLICE_MODE = X
-	    (0L <<  7) |    // QUALIFIER_PIN_MODE = X
-	    (0L <<  5) |    // QUALIFIER_MODE = 0 (enable)
-	    (0L <<  3) |    // CLK_SOURCE_SLICE_MODE = 0, slice D
-	    (0L <<  1) |    // CLK_SOURCE_PIN_MODE = X
-	    (0L <<  0);     // EXT_CLK_ENABLE = 0, internal clock signal (slice)
-	    
-	LPC_SGPIO->SLICE_MUX_CFG[3] =
-	    (0L <<  8) |    // INV_QUALIFIER = 0 (use normal qualifier)
-	    (0L <<  6) |    // PARALLEL_MODE = 0 (shift 1 bit per clock)
-	    (0L <<  4) |    // DATA_CAPTURE_MODE = 0 (detect rising edge)
-	    (0L <<  3) |    // INV_OUT_CLK = 0 (normal clock)
-	    (0L <<  2) |    // CLKGEN_MODE = 0 (use clock from COUNTER)
-	    (0L <<  1) |    // CLK_CAPTURE_MODE = 0 (use rising clock edge)
-	    (0L <<  0);     // MATCH_MODE = 0 (do not match data)
-	    
-	LPC_SGPIO->PRESET[3] = 0;
-	LPC_SGPIO->COUNT[3] = 0;
-	LPC_SGPIO->POS[3] = (0x1FL << 8) | (0x1FL << 0);
-	LPC_SGPIO->REG[0] = 0xAAAAAAAA;     // Primary output data register
-	LPC_SGPIO->REG_SS[0] = 0xAAAAAAAA;  // Shadow output data register
-
-	// Start SGPIO operation by enabling slice clocks.
-	LPC_SGPIO->CTRL_ENABLED =
-	    (1L <<  3) |    // Slice D
-	    (1L <<  0);     // Slice A

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/clocking.rst

@@ -1,38 +0,0 @@
-================================================
-Clocking Signals
-================================================
-
-
-
-HackRF clock signals are generated by the Si5351. The plan so far:
-
-    * crystal frequency: 25 MHz (supports 25 or 27 MHz)
-    * optional clock input frequency: 10 MHz recommended (supports 10 to 40 MHz, or higher with division)
-    * VCO frequency: 800 MHz (supports 600 to 900 MHz)
-    * MAX2837 clock: 40 MHz
-    * preferred MAX5864 clocks: 8, 10, 12.5, 16, 20 MHz
-    * A clock at double the MAX5864 rate will be delivered to the CPLD and SGPIO.
-    * LPC43xx clock: 12 MHz (from separate crystal so the ROM-based USB DFU will work)
-
-Lemondrop+Jellybean Si5351 output mapping:
-
-    * CLK0 -> MAX2837
-    * CLK1 -> MAX5864/CPLD
-    * CLK2 -> CPLD
-    * CLK3 -> CPLD
-    * CLK4 -> LPC4330
-    * CLK5 -> RFFC5072
-    * CLK6 -> extra
-    * CLK7 -> extra
-
-Jawbreaker output mapping:
-
-    * CLK0 -> MAX5864/CPLD
-    * CLK1 -> CPLD
-    * CLK2 -> SGPIO
-    * CLK3 -> external clock output
-    * CLK4 -> RFFC5072
-    * CLK5 -> MAX2837
-    * CLK6 -> none
-    * CLK7 -> LPC4330 (but LPC4330 will start up on its own crystal)
-

docs/source/conf.py

@@ -1,12 +1,16 @@
+import sphinx_rtd_theme
+
+extensions = [
+    'sphinx_rtd_theme'
+]
+
 # -- Project information -----------------------------------------------------
 
 project = 'HackRF'
 copyright = '2021, Great Scott Gadgets'
 author = 'Great Scott Gadgets'
 
-# The short X.Y version
 version = ''
-# The full version, including alpha/beta/rc tags
 release = ''
 
 
@@ -26,7 +30,7 @@ pygments_style = None
 
 
 # -- Options for HTML output -------------------------------------------------
-
-html_theme = 'sphinx_rtd_theme'
+# run pip install sphinx_rtd_theme if you get sphinx_rtd_theme errors
+html_theme = "sphinx_rtd_theme"
 html_css_files = ['status.css']
 

docs/source/design_goals.rst

@@ -1,29 +0,0 @@
-================================================
-Design Goals
-================================================
-
-Eventually, the HackRF project may result in multiple hardware designs, but the initial goal is to build a single wideband transceiver peripheral that can be attached to a general purpose computer for software radio functions.
-
-Primary goals:
-
-    * half-duplex transceiver
-    * operating freq: 100 MHz to 6 GHz
-    * maximum sample rate: 20 Msps
-    * resolution: 8 bits
-    * interface: High Speed USB
-    * power supply: USB bus power
-    * portable
-    * open source
-
-Wish list:
-
-    * full-duplex (at reduced max sample rate)
-    * external clock reference
-    * dithering
-    * parallel interface for external FPGA, etc.
-
-If there is a primary goal we miss, it will probably be the operating frequency range. The wideband front end is the part of the design furthest from completion. At an absolute minimum, the board should do 900 MHz and 2.4 GHz.
-
-The design is FPGA-less. There will be a tiny bit of DSP capability (ARM Cortex-M4), but mostly we're just trying to get samples to and from a host computer.
-
-We are trading resolution and DSP capability for cost, portability, and frequency range. Considering that we'll be able to support oversampling for many applications and that we should be able to implement AGC, it should be a pretty good trade.

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,26 +163,70 @@ SDIO, GPIO, clocks, and CPLD.
   * - 12  
     - GND
   * - 13  
-    - GCK2
+    - GCK2 (One) / P5_6 (Pro)
   * - 14  
-    - GCK1
+    - GCK1 (One) / P5_7 (Pro)
   * - 15  
-    - B1AUX14
+    - Trigger out: B1AUX14 (One) / TRIGGER.OUT (Pro)
   * - 16  
-    - B1AUX13
+    - 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.
 
-Refer to the schematics and component documentation for more information.
+Refer to the schematics and component documentation for more information.

docs/source/external_clock_interface.rst

@@ -1,11 +1,29 @@
-===========================================
-External Clock Interface (CLKIN and CLKOUT)
-===========================================
+========================
+External Clock Interface
+========================
 
-HackRF One produces a 10 MHz clock signal on CLKOUT. The signal is a 10 MHz square wave from 0 V to 3 V intended for a high impedance load.
+.. _external_clock_interface:
 
-The CLKIN port on HackRF One is a high impedance input that expects a 0 V to 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
+~~~~~~~~~~
+
+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.
 
 To verify that a signal has been detected on CLKIN, use ``hackrf_clock -i``. The expected output with a clock detected is `CLKIN status: clock signal detected`. The expected output with no clock detected is `CLKIN status: no clock signal detected`.
+
+To activate CLKOUT, use ``hackrf_clock -o 1``. To switch it off, use ``hackrf_clock -o 0``.

docs/source/faq.rst

@@ -1,155 +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 2150 MHz: 5 dBm to 15 dBm, generally decreasing as frequency increases
-    * 2150 MHz to 2750 MHz: 13 dBm to 15 dBm
-    * 2750 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 2150 MHz to 2750 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 14 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 14 dB)
-- IF (0 to 47 dB in 1 dB steps)
-
-
-----
-
-
-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 14 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/future_hardware_modifications.rst

@@ -1,98 +0,0 @@
-================================================
-Future Hardware Modifications
-================================================
-
-Things to consider for post-Jawbreaker hardware designs:
-
-----
-
-Antenna
-^^^^^^^
-
-The PCB antenna on Jawbreaker was included to facilitate beta testing. Future designs likely will not include a PCB antenna.
-
-SMA connectors will be PCB edge-mounted.
-
-----
-
-Baseband
-^^^^^^^^
-
-The interfaces between the MAX2837 and MAX5864 have some signals inverted. Theoretically, that's fine if compensated for in software. However, I'm theorizing that RX/ADC DC offset compensation assumes that both channels have the same DC polarity. I've fixed the inversion in the CPLD. However, a PCB experiment should be conducted to see if the DC offset is reduced by un-inverting the RX Q channel connections to the MAX5864.
-
-----
-
-CPLD
-^^^^
-
-The CPLD could be removed, but some sort of multiplexer would be needed to meet the MAX5864 i/o requirements. Depending on the particular LPC43xx part used, it might be possible to use the System Control Unit (SCU) for this.
-
-----
-
-Clocking
-^^^^^^^^
-
-The clock signal from the Si5351C to the LPC43xx's GP_CLKIN pin may need different passives, but the documentation on that clock input is thin (acceptable peak-to-peak voltage anyone?).
-
-An unpopulated footprint for a 32.768 kHz RTC crystal would be nice. Also break out RTC battery pins to an expansion header.
-
-----
-
-USB
-^^^
-
-Would support for host mode on the second USB PHY be useful somehow? This is only possible with a larger LPC43xx package that exposes the second PHY's ULPI signals. Unless, of course, a mere full-speed PHY is acceptable.
-
-----
-
-Power Management
-^^^^^^^^^^^^^^^^
-
-The MAX5864 appears to come up in "Tx" or "Rcvr" mode -- I have observed that the part will pass DA bus data to ID/QD without any SPI configuration. If we're worried about USB power and minimizing current consumption, it might be good to have this device on a power regulator with an ENABLE pin, or have a FET power switch. Yes, let's add a high side switch for the whole RF section.
-
-----
-
-Regulators
-^^^^^^^^^^
-
-U21 (the TPS62410) FB1 pin is connected on the far side of jumper P8 (VCC), which puts the jumper inside the feedback path. If the jumper trace is cut, the regulator may go nuts because the FB pin is floating.
-
-----
-
-Buttons
-^^^^^^^
-
-Add a reset button (for the LPC43xx). Maybe add a DFU button too.
-
-----
-
-Shielding
-^^^^^^^^^
-
-Maybe add a can around the RF section.
-
-----
-
-Footprints
-^^^^^^^^^^
-
-Tighten up holes for USB connector support legs to improve placement consistency. Make some of the QFN pads bigger (especially on the RF switches) for better soldering.
-
-----
-
-Shield Support
-^^^^^^^^^^^^^^
-
-If support for add-on shields is considered valuable, here are some tweaks I'd suggest:
-
-Any reason P28 (SD) pin 12 isn't grounded or doing something useful? Same goes for P25 (LPC_ISP) pin 3 -- maybe make it VCC, the signaling voltage for the ISP interface? The SPIFI connector could also use a reference voltage (GND?).
-
-I'd like to see an I2C bus exposed somewhere, and perhaps an I2S0_RX_SDA signal, so I don't have to steal it from the CPLD interface. The I2S0 will function in "four-wire mode" with only one more pin (RX_SDA), so why not?
-
-Provide a way to inject a supply voltage into the board? Having diodes managing multiple voltage sources would be lossy, so a more expensive solution would be necessary on the Jawbreaker board, adding cost.
-
-If an LPC43xx package with a higher pin-count is used, it would be stellar to expose the LCD interface and quadrature encoder peripheral pins.
-
-The RTC would be handy for stand-alone use. This would require a crystal (32.768kHz) between RTCX1 and RTCX2, and exposing VBAT to a shield for battery backup (disconnecting it from VCC) or providing a coin cell footprint on the HackRF PCB.
-
-Coalesce separate headers into fewer, larger banks of headers, to reduce the number of unique, small header receptacles required for mating? Reducing the header count will also increase the amount of board space around the perimeter of a shield for components and connectors.

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,9 +2,15 @@
 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:
 
+.. image:: ../images/HackRF-One-fd0-0009.jpeg
+  :alt: HackRF One
 
+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
 ~~~~~~~~
@@ -15,11 +21,44 @@ Features
     * resolution: 8 bits
     * interface: High Speed USB (with USB Micro-B connector)
     * power supply: USB bus power
-    * software-controlled antenna port power (max 50 mA at 3.3 V)
+    * software-controlled antenna port power (max 50 mA at 3.0 to 3.3 V)
     * SMA female antenna connector (50 ohms)
     * SMA female clock input and output for synchronization
     * convenient buttons for programming
     * 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
-    [-n num_samples] # Number of samples per frequency, 8192-4294967296
-    [-w bin_width] # FFT bin width (frequency resolution) in Hz
-    [-1] # one shot mode
-    [-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
-
-Two ranges of 5 MHz are analyzed at once from the same set of samples, so a single timestamp applies to the whole range.
-
-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,18 +2,56 @@
 Hardware Components
 ================================================
 
-Major parts used in HackRF One:
+Block Diagrams
+~~~~~~~~~~~~~~
 
-* `MAX2837 2.3 to 2.7 GHz transceiver <https://www.maximintegrated.com/en/products/comms/wireless-rf/MAX2837.html>`__
-    * `Datasheet <https://datasheets.maximintegrated.com/en/ds/MAX2837.pdf>`__
-    * There's also a register map document that Mike received directly from Maxim. Send an email to Mike or submit a support request to Maxim if you want a copy.
-* `MAX5864 ADC/DAC <http://www.maxim-ic.com/datasheet/index.mvp/id/3946/t/do>`__
-    * `Datasheet <http://datasheets.maxim-ic.com/en/ds/MAX5864.pdf>`__
+HackRF Pro Block Diagram
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ../images/block-diagram-pro.png
+        :align: center
+
+|
+
+HackRF One r1-r8 Block Diagram
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. image:: ../images/block-diagram.png
+        :align: center
+
+|
+
+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>`__ - this document is a mess of typos, and best used in conjunction with AN619, which has its own typos. Usually, you can reconcile what's true by comparison and a bit of thought.
+    * `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
+* `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>`__
@@ -23,13 +61,5 @@ Major parts used in HackRF One:
 * `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 Diagram
-~~~~~~~~~~~~~
-
-.. image:: ../images/block-diagram.png
-	:align: center
+* `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

@@ -0,0 +1,81 @@
+.. _hardware_triggering:
+
+===================
+Hardware Triggering
+===================
+
+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 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 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.
+
+
+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
+~~~~~~~~~~~~~~~~~~~~
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+HackRF One has four normally-populated pin headers, three of which are arranged in a 'C' shape. On the circuit board these are marked P28, P22, and P20. P28 is the header nearest to the center of the board. Locate pins 15 (trigger output) and 16 (trigger input) on header P28.
+
+.. image:: ../images/trigger-pins.png
+	:align: center
+
+
+Connect the Trigger Output to the Trigger Input
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First ensure that the two devices share a common ground. This may be accomplished by connecting one's CLKIN to the other's CLKOUT as recommended above. Alternatively, connect a jumper wire from P28 pin 2 on one HackRF One to P28 pin 2 on the other HackRF One.
+
+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.
+
+
+References
+~~~~~~~~~~
+
+HackRF's trigger mechanism was contributed by the authors of `Synchronisation of Low-Cost Open Source SDRs for Navigation Applications <http://spcomnav.uab.es/docs/conferences/Bartolucci_NAVITEC_2016.pdf>`__ which provides details about the implementation and background.

docs/source/index.rst

@@ -6,23 +6,36 @@ Welcome to HackRF's documentation!
    :maxdepth: 2
    :caption: User Documentation
 
-   hackrf_one
-   opera_cake
-   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,25 +48,31 @@ Welcome to HackRF's documentation!
 
 .. toctree::
    :maxdepth: 2
-   :caption: Hardware
+   :caption: Software
+
+   installing_hackrf_software
+   hackrf_tools
+   software_support
+   sampling_rate
+   setting_gain
+   virtual_machines
 
-   list_of_hardware_revisions
-   hardware_components
-   enclosure_options   
-   hackrfs_buttons
-   external_clock_interface
-   clocking
-   expansion_interface
-   multiple_device_hardware_synch
-   rf_shield_installation
 
 .. toctree::
    :maxdepth: 2
-   :caption: Retired Content
+   :caption: Gateware
 
-   jawbreaker
-   design_goals
-   future_hardware_modifications
-   lemondrop_bringup
-   LPC4350
+   gateware
 
+.. toctree::
+   :maxdepth: 2
+   :caption: Opera Cake Documentation
+
+   opera_cake
+   opera_cake_faq
+   opera_cake_hardware
+   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.
@@ -556,5 +557,5 @@ Jawbreaker was the beta platform that preceded HackRF One. HackRF One incorporat
     * Real-Time Clock: An RTC is installed on HackRF One.
     * LPC4320 microcontroller: Jawbreaker had an LPC4330.
     * RF shield footprint: An optional shield may be installed over HackRF One's RF section.
-    * Antenna port power: HackRF One can supply up to 50 mA at 3.3 V DC on the antenna port for compatibility with powered antennas and other low power amplifiers.
+    * Antenna port power: HackRF One can supply up to 50 mA at 3.0 to 3.3 V DC on the antenna port for compatibility with powered antennas and other low power amplifiers.
     * Enhanced frequency range: The RF performance of HackRF One is better than Jawbreaker, particularly at the high and low ends of the operating frequency range. HackRF One can operate at 1 MHz or even lower.

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/lemondrop_bringup.rst

@@ -1,239 +0,0 @@
-================================================
-Lemondrop Bring Up
-================================================
-
-Board draws approximately 24mA from +3V3 when power is applied. This seems a bit high, but may be expected if not all parts are capable of low-power mode, or aren't configured for low power at power-on. I need to review the schematic and datasheets and see what can be done.
-
-When I put my finger on the MAX2837, current consumption goes up. This suggests there may be floating nodes in that region of the circuit.
-
-
-Si5351 I2C
-~~~~~~~~~~
-
-Attached crystal is 25MHz. For now, I'm assuming 10pF "internal load capacitance" is good enough to get the crystal oscillating. The crystal datasheet should be reviewed and measurements made...
-
-Be sure to reference Silicon Labs application note 619 (AN619). The datasheet is a terrible mess (typos and lack of some details). AN619 appears to be less of a mess, on the whole. And as a bonus, AN619 has PDF bookmarks for each register.
-
-
-
-Connections
-^^^^^^^^^^^
-
-    * Bus Pirate GND to P7 pin 1
-    * Bus Pirate +3V3 to P7 pin 2 (through multimeter set to 200mA range)
-    * Bus Pirate CLK to P7 pin 3
-    * Bus Pirate MOSI to P7 pin 5
-
-
-
-Bus Pirate I2C Initialization
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. code-block:: sh
-
-	# set mode
-	m
-	# I2C mode
-	4
-	# ~100kHz speed
-	3
-	# power supplies ON
-	W
-	# macro 1: 7-bit address search
-	(1)
-	Searching I2C address space. Found devices at:
-	0xC0(0x60 W) 0xC1(0x60 R) 
-
-I2C A0 address configuration pin (not available on QFN20 package) is apparently forced to "0".
-
-
-
-Reading registers
-^^^^^^^^^^^^^^^^^
-
-.. code-block:: sh
-
-	# Read register 0
-	I2C>[0xc0 0[0xc1 r]]
-	...
-	# Register 0: SYS_INIT=0, LOL_B=0, LOL_A=0, LOS=1, REVID=0
-	READ: 0x10
-	...
-	# Read 16 registers, starting with register 0
-	I2C>[0xc0 0[0xc1 r:16]]
-	...
-	READ: 0x10  ACK 0xF8  ACK 0x03  ACK 0x00  ACK 0x00  ACK 0x00  ACK 0x8F  ACK 0x01  ACK
-	      0x00  ACK 0x00  ACK 0x00  ACK 0x00  ACK 0x00  ACK 0x00  ACK 0x90  ACK 0x00
-	...
-	# Read 16 registers, starting with register 16
-	I2C>[0xc0 16[0xc1 r:16]]
-	...
-	READ: 0x00  ACK 0x00  ACK 0x00  ACK 0x00  ACK 0x00  ACK 0x00  ACK 0x00  ACK 0x00  ACK
-	      0x00  ACK 0x00  ACK 0x00  ACK 0x00  ACK 0x00  ACK 0x00  ACK 0x00  ACK 0x00 
-	...
-
-
-
-Writing registers
-^^^^^^^^^^^^^^^^^
-
-
-Simple XTAL passthrough to CLK0
-+++++++++++++++++++++++++++++++
-
-.. code-block:: sh
-
-	# Disable all CLKx outputs.
-	[0xC0 3 0xFF]
-
-	# Turn off OEB pin control for all CLKx
-	[0xC0 9 0xFF]
-
-	# Power down all CLKx
-	[0xC0 16 0x80 0x80 0x80 0x80 0x80 0x80 0x80 0x80]
-
-	# Register 183: Crystal Internal Load Capacitance
-	# Reads as 0xE4 on power-up
-	# Set to 10pF (until I find out what loading the crystal/PCB likes best)
-	[0xC0 183 0xE4]
-
-	# Register 187: Fanout Enable
-	# Turn on XO fanout only.
-	[0xC0 187 0x40]
-
-	# Register 15: PLL Input Source
-	# CLKIN_DIV=0 (Divide by 1)
-	# PLLB_SRC=0 (XTAL input)
-	# PLLA_SRC=0 (XTAL input)
-	[0xC0 15 0x00]
-
-	# Registers 16 through 23: CLKx Control
-	# CLK0:
-	#   CLK0_PDN=0 (powered up)
-	#   MS0_INT=1 (integer mode)
-	#   MS0_SRC=0 (PLLA as source for MultiSynth 0)
-	#   CLK0_INV=0 (not inverted)
-	#   CLK0_SRC=0 (XTAL as clock source for CLK0)
-	#   CLK0_IDRV=3 (8mA)
-	[0xC0 16 0x43 0x80 0x80 0x80 0x80 0x80 0x80 0x80]
-
-	# Enable CLK0 output only.
-	[0xC0 3 0xFE]
-
-
-
-Clocking Scheme (Work In Progress)
-++++++++++++++++++++++++++++++++++
-
-From AN619: If Fxtal=25MHz, Fvco = Fxtal * (a + (b / c)). If we want Fvco = 800MHz, a = 32, b = 0, c = don't care.
-
-.. code-block:: sh
-
-	MSNA_P1[17:0] = 128 * a + floor(128 * b / c) - 512
-	              = 128 * a + floor(0) - 512
-	              = 128 * 32 + 0 - 512
-	              = 3584 = 0xE00
-	MSNA_P1[17:16] (register 28) = 0x00
-	MSNA_P1[15: 8] (register 29) = 0x0E
-	MSNA_P1[ 7: 0] (register 30) = 0x00
-	MSNA_P2[19:0] = 128 * b - c * floor(128 * b / c)
-	              = 128 * 0 - 0 * floor(128 * 0 / X)
-	              = 0
-	MSNA_P3[19:0] = 0
-
-MultiSynth0 should output 40MHz (800MHz VCO divided by 20):
-
-.. code-block:: sh
-
-	a = 20, b = 0, c = X
-	MS0_P1[17: 0] = 128 * a + floor(128 * b / c) - 512
-	              = 2048 = 0x800
-	MS0_P1[17:16] (register 44) = 0x00
-	MS0_P1[15: 8] (register 45) = 0x08
-	MS0_P1[ 7: 0] (register 46) = 0x00
-	MS0_P2[19:0]  = 0
-	MS0_P3[19:0]  = 0
-
-MultiSynth1 should output 20MHz (800MHz VCO divided by 40) or some smaller integer fraction of the VCO:
-
-.. code-block:: sh
-
-	a = 40, b = 0, c = X
-	MS1_P1[17: 0] = 128 * a + floor(128 * b / c) - 512
-	              = 4608 = 0x1200
-	MS1_P1[17:16] (register 52) = 0x00
-	MS1_P1[15: 8] (register 53) = 0x12
-	MS1_P1[ 7: 0] (register 54) = 0x00
-	MS1_P2[19:0]  = 0
-	MS1_P3[19:0]  = 0
-
-Initialization:
-
-.. code-block:: sh
-
-	# Disable all CLKx outputs.
-	[0xC0 3 0xFF]
-
-	# Turn off OEB pin control for all CLKx
-	[0xC0 9 0xFF]
-
-	# Power down all CLKx
-	[0xC0 16 0x80 0x80 0x80 0x80 0x80 0x80 0x80 0x80]
-
-	# Register 183: Crystal Internal Load Capacitance
-	# Reads as 0xE4 on power-up
-	# Set to 10pF (until I find out what loading the crystal/PCB likes best)
-	[0xC0 183 0xE4]
-
-	# Register 187: Fanout Enable
-	# Turn on XO and MultiSynth fanout only.
-	[0xC0 187 0x50]
-
-	# Register 15: PLL Input Source
-	# CLKIN_DIV=0 (Divide by 1)
-	# PLLB_SRC=0 (XTAL input)
-	# PLLA_SRC=0 (XTAL input)
-	[0xC0 15 0x00]
-
-	# MultiSynth NA (PLL1)
-	[0xC0 26 0x00 0x00 0x00 0x0E 0x00 0x00 0x00 0x00]
-
-	# MultiSynth NB (PLL2)
-	...
-
-	# MultiSynth 0
-	[0xC0 42 0x00 0x00 0x00 0x08 0x00 0x00 0x00 0x00]
-
-	# MultiSynth 1
-	[0xC0 50 0x00 0x00 0x00 0x12 0x00 0x00 0x00 0x00]
-
-	# Registers 16 through 23: CLKx Control
-	# CLK0:
-	#   CLK0_PDN=0 (powered up)
-	#   MS0_INT=1 (integer mode)
-	#   MS0_SRC=0 (PLLA as source for MultiSynth 0)
-	#   CLK0_INV=0 (not inverted)
-	#   CLK0_SRC=3 (MS0 as input source)
-	#   CLK0_IDRV=3 (8mA)
-	# CLK1:
-	#   CLK1_PDN=0 (powered up)
-	#   MS1_INT=1 (integer mode)
-	#   MS1_SRC=0 (PLLA as source for MultiSynth 1)
-	#   CLK1_INV=0 (not inverted)
-	#   CLK1_SRC=3 (MS1 as input source)
-	#   CLK1_IDRV=3 (8mA)
-	[0xC0 16 0x4F 0x4F 0x80 0x80 0x80 0x80 0x80 0x80]
-
-	# Enable CLK0 output only.
-	[0xC0 3 0xFC]
-
-
-
-Si5351 output phase relationships
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Tested CLK4 and CLK5 (integer division only):
-
-With CLK4 set to MS4 and CLK5 set to MS5, even with both multisynths configured identically, there was no consistent phase between the two. Once started, the clocks maintained relative phase with each other, but when stopped and restarted the initial phase offset was unpredictable.
-
-With CLK4 and CLK5 both set to MS4, the phase of both outputs was identical when no output (R) divider was selected. When an output divider was selected on both MS4 and MS5, the relative phase became predictable only within the constraints of the divider (e.g. with R=2 the relative phase was always either 0 or half a cycle, with R=4 the relative phase was always either 0, a quarter, a half, or three quarters of a cycle). With R=1 on MS4 and R=2 on MS5, the two outputs were consistently in phase with each other. The output (R) dividers supposedly tied to the multisynths are actually tied to the outputs.

docs/source/libhackrf_api.rst

@@ -1,568 +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
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-
-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
-^^^^^^^^^^^^^^^^^
-
-Device will need to be reset 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 	
-    - Bandwidth 	
-    - Antenna port power
-  * - HackRF One 	
-    - 1MHz - 6Ghz 	
-    - 20MHz 	
-    - Yes
-  * - Jawbreaker 	
-    - 10MHz - 6GHz 	
-    - 20MHz 	
-    - No
-  * - Rad1o 	
-    - 50MHz - 4GHz 	
-    - 20MHz 	
-    - Unknown
-  * - Jellybean 	
-    - N/A 	
-    - 20MHz 	
-    - No
-
-Most boards will identify as HackRF One, Jawbreaker or Rad1o. Jellybean was a pre-production revision of HackRF. No hardware device should intentionally report itself with an invalid board ID.
-
-.. code-block :: sh
-
-	enum hackrf_board_id {
-		BOARD_ID_JELLYBEAN  = 0,
-		BOARD_ID_JAWBREAKER = 1,
-		BOARD_ID_HACKRF_ONE = 2,
-		BOARD_ID_RAD1O = 3,
-		BOARD_ID_INVALID = 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 three main transceiver modes, Receive, Transmit and Signal Source. There is also a CPLD update mode which is used to write firmware images to the CPLD.
-
-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 {
-		TRANSCEIVER_MODE_OFF = 0,
-		TRANSCEIVER_MODE_RX = 1,
-		TRANSCEIVER_MODE_TX = 2,
-		TRANSCEIVER_MODE_SS = 3,
-		TRANSCEIVER_MODE_CPLD_UPDATE = 4
-	};
-
-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_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,33 +1,55 @@
 ================================================
-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 due to component availability. Although the SKY13453 uses simplified control logic, it did not require a firmware modification. Manufacturing year: 2020
+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 due to component availability. USB VBUS detection resistor values were changed to better protect the LPC4320. Manufacturing year: 2021
+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 due to component availability. Manufacturing years: 2021–2022
+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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 HackRF Ones manufactured by Great Scott Gadgets have the revision number printed on the PCB top silkscreen layer near the MAX5864 (U18).
+
+Starting with HackRF One r6, hardware revisions are detected by firmware and reported by ``hackrf_info``.