This guide covers the built-in HackRF device path in the current RemoteRF implementation. The HackRF schema and Python binding are included with the base RemoteRF packages, so most setups only need the native HackRF runtime and a correct devices.yml entry.

Overview

There is native support for HackRF devices in RemoteRF via the built-in hackrf schema. Fundamentally, this guide is the same for both servers and hosts; whichever machine the HackRF is physically attached to must have the native HackRF runtime installed, must be able to see the radio locally, and must have the right devices.yml entry.

The only parts that vary are machine-local details such as which Python environment you install into, which devices.yml you edit, and whether you start serverrf or hostrf. The minimum setup of HackRF devices is as follows:

  1. Install the native HackRF runtime and tools on the machine that owns the HackRF. The Python binding is already included with the base RemoteRF package.
  2. Make sure hackrf_info can see the device on that same machine without sudo.
  3. Add each HackRF physically connected to that machine to its devices.yml file.
  4. Restart that machine’s RemoteRF process.

Each of these steps is provided in detail below.

Install and Detect

Step 1

Install HackRF Dependencies

The base remoterf-server and remoterf-host packages already install the HackRF Python binding. Install the native HackRF runtime and tools on the machine that owns the radio so RemoteRF can communicate with the USB hardware.

Run:
sudo apt-get update
sudo apt-get install -y hackrf

The native HackRF runtime is needed only on the machine physically connected to the radio. Clients need no HackRF-specific installation.

Step 2

Verify Detection

Make sure the machine that owns the HackRF can see it before you touch devices.yml.

Run:
hackrf_info
Expected result: hackrf_info should detect the hardware and print its serial number. That serial is the value you will place in devices.yml.
If this fails: Fix the HackRF install or USB/device access first before continuing.

Manifest Example

Save this file on the machine the HackRF is physically attached to. For a HackRF attached to the main RemoteRF server, place it at ~/.config/remoterf/devices.yml. For a HackRF attached to a RemoteRF host, place it at ~/.config/remoterf/host/devices.yml.

Below is an example devices.yml file for a HackRF device:

devices.yml
yaml
devices:
  - device_id: 10
    device_type: hackrf
    name: HackRF One
    init:
      serial: "0000000000000000719031ac235bb14a"

You can also use device_index in the built-in schema, but serial is the better long-term identifier on machines that may have more than one HackRF attached.

For a HackRF attached directly to the main RemoteRF server, add the YAML entry above to the server’s devices.yml file.

If the HackRF is attached to a RemoteRF Host instead, use hostrf for the add command:

hostrf --device --add --hackrf "10:HackRF One:serial=0000000000000000719031ac235bb14a"

For a host-attached HackRF, edit the host’s ~/.config/remoterf/host/devices.yml file directly when you need to change an existing entry.

Important: device_type must be hackrf. init.serial should match the serial reported by hackrf_info. name is just the human-facing label RemoteRF shows to users. You can create many HackRF entries with the same schema because the schema is per device type, while devices.yml is per physical device instance. Keep operating parameters such as frequency, sample rate, gains, amplifier state, and bias tee out of init; clients control those during use.

Verification

Verify the HackRF Comes Online

Now, let's confirm the HackRF is accessible. If you are connecting the HackRF to the server, run serverrf -s. If you are connecting the HackRF to a host, run hostrf -s.

Then check this: In the interactive shell, run devices list to confirm the device was loaded. For a host-attached setup, also run devices list from the server after the host connects so you can confirm the main server sees it too.

Still having issues? Recheck hackrf_info from the same account that starts RemoteRF, then restart the machine that has the HackRF physically attached and repeat the check.

Notes: The built-in driver uses the base package's pyhackrf2 dependency to call the native libhackrf runtime. Only libhackrf must be installed separately, and only on the machine physically connected to the radio. Clients do not download or install a HackRF schema; they automatically fetch the interface exposed by the server and generate their local remote driver.

Next Steps

Recommended
Next Step
Onboarding Users

Once the HackRF appears correctly in the inventory, use this guide to connect clients, reserve devices, and begin running experiments.
Optional
Custom Device

Use this path if you want to change the built-in HackRF driver behavior or build a custom schema around your own Python-controlled hardware.