OpenSourceSDRLab PortaRF · Volume 7

OpenSourceSDRLab PortaRF Volume 7 — Programming Environments

Host-side tools, GNU Radio integration, SDRangel and alternatives, PortaRF-specific host considerations

Contents

SectionTopic
1About this volume
2Host-side tools — hackrf_*
3GNU Radio integration
4SDRangel / GQRX / CubicSDR alternatives
5Python + libhackrf scripting
6PortaRF host-side specifics — USB-C and driver paths
7Resources

1. About this volume

Vol 7 covers programming environments for working with PortaRF from a host PC. Because PortaRF enumerates as a standard HackRF One (same vendor + product ID, same protocol), every host-side tool that works with HackRF works with PortaRF unchanged.

This is the most “inherited” volume of the series — the canonical reference is HackRF One Vol 7. The PortaRF-specific deltas are minimal: USB-C cable handling, no driver differences, no protocol differences.

Cross-reference: ../../../HackRF One/03-outputs/HackRF_One_Complete.html Vol 7 covers host-side tools in full detail. This volume cites that and focuses on PortaRF-specific operational considerations.

Note on Vol 10: Custom Mayhem firmware development moved to Vol 10 in this series. This volume focuses on host-side programming; firmware-side development is Vol 10.

2. Host-side tools — hackrf_*

The standard hackrf_* command suite works identically on PortaRF. Installation:

# macOS (Homebrew)
brew install hackrf

# Debian/Ubuntu
sudo apt install hackrf

# Fedora/CentOS
sudo dnf install hackrf

# Windows: download from greatscottgadgets.com or use Pothos SDR bundle

2.1 The full tool catalog

ToolPurposeTypical use
hackrf_infoIdentify the device, report firmware version, serialFirst command for any session
hackrf_transferCapture raw I/Q to file or replay from fileWorkhorse capture/replay tool
hackrf_spiflashFlash HackRF firmwareRare; Vol 8 covers
hackrf_sweepWideband spectrum sweepDiscovery; can feed a viewer
hackrf_clockConfigure / verify reference clockPPM calibration
hackrf_operacakeConfigure Opera Cake antenna switchRare; only if using daughter card
hackrf_debugRead internal registers / diagnostic outputDebugging silicon-level issues
hackrf_cpldjtagUpdate HackRF CPLDVery rare; only for new revisions

2.2 hackrf_info — the verify-everything-is-OK command

hackrf_info

# Expected output:
# hackrf_info version: 2024.02.1
# libhackrf version: 0.9 (0.9.0)
# Found HackRF
# Index: 0
# Serial number: 0000000000000000XXXXXXXXXXXXXXXX
# Board ID Number: 2 (HackRF One)
# Firmware Version: 2024.02.1 (API:1.07)
# Part ID Number: 0xa000cb3c 0x00641864
# Hardware Revision: r9 (or r10/r10+/H4M per Heath revision)

Use this command:

  • After connecting PortaRF for the first time
  • Before any capture / TX session (confirms device responding)
  • When debugging a problem (“is the unit even there?”)
  • To check firmware version

2.3 hackrf_transfer — capture and replay

Common patterns:

# Capture 10 seconds at 433.92 MHz, 2 MS/s, 40 dB gain
hackrf_transfer -r capture.cfile \
                -f 433920000 \
                -s 2000000 \
                -g 40 \
                -n 20000000  # 20M samples = 10 sec at 2 MS/s

# Replay (TX) the captured file
hackrf_transfer -t capture.cfile \
                -f 433920000 \
                -s 2000000 \
                -x 0  # TX gain; 0 dB conservative

# Wideband capture (more demanding on SD/USB)
hackrf_transfer -r wideband.cfile \
                -f 2400000000 \
                -s 10000000 \
                -g 32 \
                -n 100000000  # 10 seconds at 10 MS/s

Options reference:

  • -r FILE: read from radio (RX); save I/Q to FILE
  • -t FILE: transmit (TX); read I/Q from FILE
  • -f Hz: center frequency
  • -s Hz: sample rate (2 MS/s minimum, 20 MS/s maximum)
  • -g dB: RX gain (0-62 in 8 dB steps; LNA + VGA combined)
  • -x dB: TX gain (0-47 in 1 dB steps)
  • -l N: amp enable (0 or 1; enables external LNA via bias-T)
  • -a N: amp gain for RF amplifier (rarely used)
  • -n N: number of samples to capture

2.4 hackrf_sweep — wideband sweep

# Sweep 100 MHz to 6 GHz, output binary FFT data
hackrf_sweep -f 100:6000 -B

# Sweep narrower band with finer resolution
hackrf_sweep -f 432:435 -B -B 100000

# Pipe to a viewer (requires a viewer)
hackrf_sweep -f 100:6000 -B | python3 viewer.py

hackrf_sweep output is raw FFT bins in binary format. Several community viewers exist (search Mayhem wiki). For PortaRF: Mayhem’s built-in sweep app is easier; hackrf_sweep is for scripted host-side workflows.

2.5 Tools rarely needed

  • hackrf_spiflash: see Vol 8 § 4
  • hackrf_operacake: only if using an Opera Cake antenna switch (rare with PortaRF since GPIO header isn’t exposed)
  • hackrf_clock: only for PPM calibration or external clock reference setup
  • hackrf_debug: for vendor / advanced debugging
  • hackrf_cpldjtag: never, unless explicitly directed by vendor

2.6 Cross-reference for full details

The canonical walkthrough of every tool with options, examples, and edge cases lives in HackRF One Vol 7. Use that for depth; this section is the orienting summary.

3. GNU Radio integration

GNU Radio is the foundational framework for software-defined-radio research and development.

3.1 Installation

# macOS
brew install gnuradio

# Debian/Ubuntu
sudo apt install gnuradio gnuradio-osmosdr

# Fedora/CentOS
sudo dnf install gnuradio gr-osmosdr

# Windows: PothosSDR bundle from pothosware.com is the easiest path

The gr-osmosdr package provides the HackRF source/sink blocks used by GNU Radio flowgraphs.

3.2 GNU Radio Companion (GUI)

gnuradio-companion

A graphical flowgraph editor. Drag blocks, connect them, run.

Typical PortaRF flowgraph:

osmocom Source       # PortaRF as I/Q source
   args: hackrf=0
   sample_rate: 2M
   center_freq: 96900000
   gain: 24
   ↓
Low Pass Filter      # Channel selection
   cutoff: 75000
   ↓
WBFM Receive         # FM demodulation
   audio_decimation: 50
   ↓
Audio Sink           # Speaker output

Result: hear local FM broadcasts via PortaRF.

Figure 7.1 — GNU Radio Companion — the graphical flowgraph editor. Tethered over USB-C, the PortaRF is a standard HackRF I/Q source: the osmocom Source block sees it with no special handling, and a…
Figure 7.1 — GNU Radio Companion — the graphical flowgraph editor. Tethered over USB-C, the PortaRF is a standard HackRF I/Q source: the osmocom Source block sees it with no special handling, and any HackRF flowgraph runs against it unchanged. This is the host-side half of the PortaRF's "tethered lab work" mode (Vol 9). Screenshot: Marcusmueller (Ettus), CC BY-SA 4.0, via Wikimedia Commons.

3.3 Python flowgraphs

GNU Radio Companion exports to Python; you can also write directly:

#!/usr/bin/env python3
from gnuradio import gr, blocks, analog, audio
import osmosdr

class fm_receiver(gr.top_block):
    def __init__(self):
        gr.top_block.__init__(self, "FM Receiver")

        # PortaRF source
        self.source = osmosdr.source(args="hackrf=0")
        self.source.set_sample_rate(2e6)
        self.source.set_center_freq(96.9e6, 0)
        self.source.set_gain(24, 0)

        # Filter + demodulator
        self.lpf = filter.fir_filter_ccc(1, [...])
        self.demod = analog.wfm_rcv(quad_rate=2e6, audio_decimation=50)

        # Audio sink
        self.audio = audio.sink(40000)

        # Connect
        self.connect(self.source, self.lpf, self.demod, self.audio)

if __name__ == '__main__':
    tb = fm_receiver()
    tb.start()
    input("Press Enter to exit...")
    tb.stop()

3.4 Common flowgraph patterns

PatternUse case
Source → demod → sinkLive receive (FM, AM, SSB)
Source → file sinkI/Q capture (alternative to hackrf_transfer)
File source → sinkReplay captured signal (TX block at sink)
Source → FFT → displaySpectrum analyzer
Source → decoder → text sinkProtocol decoding
File source → matched filter → bit detectorOffline decoder development

3.5 GR vs Mayhem

For PortaRF specifically:

  • GR is for development / research — flexible, scriptable, but requires a host PC
  • Mayhem is for deployment / operation — fixed apps, no host needed
  • Most users use both — GR for new decoder development, Mayhem for field use

3.6 Performance considerations

GR runs on the host CPU. PortaRF sustains 20 MS/s I/Q output; the host must process this. For high-rate work:

  • Use a modern multi-core CPU
  • Increase the gr-blocks thread count
  • Consider GPU-accelerated blocks (gr-fosphor for waterfall)
  • Drop sample rate if CPU can’t keep up (errors will manifest as dropped samples)

4. SDRangel / GQRX / CubicSDR alternatives

For users who prefer GUI-driven SDR over GR flowgraph composition.

4.1 SDRangel

The most full-featured GUI SDR for HackRF/PortaRF:

# Linux
sudo apt install sdrangel

# Or download from sdrangel.org for Windows / macOS

Features:

  • Multi-channel — multiple receivers / transmitters per device
  • Many built-in decoders — broader than Mayhem in some areas
  • Recording / playback — handles I/Q with various formats
  • Spectrum + waterfall — high-quality real-time displays
  • Custom plugins — community-contributed extensions
  • TX support — generation, replay, beacons

For complex tethered work: SDRangel is often the right tool. It’s more capable than Mayhem on a host PC, less capable on a handheld.

4.2 GQRX

Lightweight Linux/macOS receiver:

brew install gqrx
  • Simple, fast, reliable
  • Receive-only (TX not supported)
  • Good for casual listening / spectrum monitoring
  • Less feature-rich than SDRangel

If you want a “radio that just works” for monitoring: GQRX.

4.3 CubicSDR

Cross-platform GUI:

  • Receive-only
  • Multi-platform (Linux, macOS, Windows)
  • Simple UI
  • Less active development than SDRangel

4.4 SDR#

Windows-only .NET-based:

  • Most popular Windows SDR
  • Receive-only by default; HackRF plugin enables TX
  • Many community plugins
  • Closed source (with open plugins)

4.5 Which to choose

If you…Use
Want maximum flexibilityGNU Radio
Want GUI with broad featuresSDRangel
Want a simple receiverGQRX (Linux/macOS) or SDR# (Windows)
Want cross-platform consistencySDRangel
Are developing custom protocolsGNU Radio
Are debugging HackRFhackrf_* tools first; GR for waveform inspection

For PortaRF: SDRangel is the typical “tethered to a laptop” choice. Mayhem covers standalone use.

5. Python + libhackrf scripting

For automation and scripted workflows.

5.1 PyHackRF wrapper

pip install pyhackrf2

Basic usage:

from pyhackrf2 import HackRF

hackrf = HackRF()
hackrf.sample_rate = 2_000_000
hackrf.center_freq = 433_920_000
hackrf.lna_gain = 16
hackrf.vga_gain = 16

# Capture 1 million samples
samples = hackrf.read_samples(1_000_000)

# samples is a numpy array of complex floats
# Process / save as needed
hackrf.close()

5.2 Custom scripted workflows

# Sweep frequencies, capture at each, save
frequencies = [433_000_000, 868_000_000, 915_000_000, 2_400_000_000]

for f in frequencies:
    hackrf.center_freq = f
    samples = hackrf.read_samples(10_000_000)
    np.save(f"capture_{f}_Hz.npy", samples)

5.3 Integration with analysis frameworks

# Combine with scipy for signal processing
from scipy import signal

# FFT analysis
fft = np.fft.fft(samples)
power = 20 * np.log10(np.abs(fft))

# Filter
b, a = signal.butter(4, 100000, fs=hackrf.sample_rate, btype='low')
filtered = signal.filtfilt(b, a, samples)

# Demodulate (custom)
demod = np.abs(filtered)

5.4 Use cases for Python scripting

  • Scheduled captures (cron jobs running PortaRF nightly)
  • Multi-band sweeps in sequence
  • Custom decoders (when GR doesn’t have what you need)
  • Automated A/B testing of receivers/antennas
  • Batch processing of recorded captures

For deeply-custom workflows, Python scripting is more flexible than GR flowgraphs (though GR is more performant for real-time work).

6. PortaRF host-side specifics — USB-C and driver paths

What’s different between PortaRF and porta on the host side. Spoiler: very little.

6.1 USB enumeration

PortaRF enumerates as a standard HackRF One:

Vendor ID: 0x1d50 (OpenMoko, Inc.)
Product ID: 0x6089 (Great Scott Gadgets HackRF One)

Identical to porta. No driver differences.

6.2 USB-C considerations

  • Cable: USB-C-to-USB-A or USB-C-to-USB-C; data + power capable
  • Avoid charge-only cables — these don’t enumerate as USB devices
  • Cable quality matters at high data rates — cheap cables may drop samples at 20 MS/s

6.3 Linux driver setup

# Add user to plugdev group for non-root access
sudo usermod -a -G plugdev $USER

# Or install hackrf-tools which includes the udev rule
sudo apt install hackrf

# Verify
lsusb | grep -i hackrf
# Expected: Bus 001 Device 042: ID 1d50:6089 OpenMoko, Inc. ...

6.4 macOS driver setup

No driver installation needed beyond brew install hackrf. The libusb-based hackrf tools work directly.

6.5 Windows driver setup

WinUSB-based; install via Zadig if not auto-installed:

  1. Download Zadig from zadig.akeo.ie
  2. Connect PortaRF
  3. Run Zadig
  4. Replace driver with WinUSB
  5. Verify via hackrf_info from PowerShell / cmd

6.6 Cross-platform consistency

Once enumerated, hackrf_* tools behave identically across platforms. Capture files transfer between platforms unchanged. GNU Radio flowgraphs port unchanged. Python scripts portable.

The PortaRF is just a HackRF One to the host PC. No special handling.

7. Resources

HackRF host tools (cross-ref)

GNU Radio

GUI SDR alternatives

Python

Custom firmware development (cross-ref Vol 10)

Sibling references

End of Vol 7. Next: Vol 8 walks the firmware update workflows — Mayhem self-flash via SD card, HackRF firmware update via hackrf_spiflash, recovery procedures.