Install RF Swift

Linux and macOS

The easiest way to install RF Swift on Linux or macOS is to use the installation script:

# Clone the repository
git clone https://github.com/PentHertz/RF-Swift.git
cd RF-Swift

# Run the installation script
./install.sh

The install.sh script will:

• Install all required dependencies (Docker, BuildX, Go)
• Configure necessary services (xhost, PulseAudio)
• Set up proper permissions
• Create a system-wide alias for the rfswift command
• Install the latest RF Swift binary

Windows or Manual Installation

If you prefer manual installation or are using Windows:

1. Download the latest binary from the official repository ↗
2. Rename the binary to rfswift (or rfswift.exe on Windows)
3. Make the binary executable (on Linux/macOS): chmod +x rfswift

When you run the binary for the first time, it will guide you through configuration:

rfswift 
Config file not found. Would you like to create one with default values? (y/n)

Select y to create a default configuration file or n to configure manually.

Pull a Pre-built Image

RF Swift provides several pre-built images to get you started quickly. For example, let’s pull a complete SDR image:

rfswift images pull -i sdr_full

You can also specify a custom tag for the image:

rfswift images pull -i sdr_full -t my_custom_tag

Available Options:

• -i: Remote image label (required)
• -t: Local tag to assign to the pulled image (optional)
• -r: Repository to pull from (defaults to penthertz/rfswift)

Run the Container

Once you have an image, you can create and run a container:

rfswift run -i sdr_full -n my_sdr_container

This will start a container using the sdr_full image with the name my_sdr_container.

Run Command Options:

rfswift run -i sdr_full -n my_sdr_container

The run command has numerous options for configuring your container environment:

Share Files with the Container:

To share files between your host system and the container:

rfswift run -i sdr_full -n my_sdr_container -b ~/sdr_projects:/home/user/projects

You can bind multiple directories by separating them with commas:

rfswift run -i sdr_full -n my_sdr_container -b ~/sdr_projects:/home/user/projects,~/datasets:/home/user/data

Share Specific Devices:

When running in unprivileged mode, you can share specific devices:

rfswift run -i sdr_full -n my_sdr_container -s /dev/ttyUSB0:/dev/ttyUSB0

Multiple devices can be shared by separating them with commas:

rfswift run -i sdr_full -n my_sdr_container -s /dev/ttyUSB0:/dev/ttyUSB0,/dev/ttyACM0:/dev/ttyACM0

Add Linux Capabilities:

For Wi-Fi and Bluetooth tools, you may need additional Linux capabilities:

rfswift run -i wifi_tools -n my_wifi_container -a NET_ADMIN

For multiple capabilities:

rfswift run -i advanced_tools -n my_container -a NET_ADMIN,SYS_ADMIN

Network Configuration:

By default, containers use the host network mode. To use a different network:

rfswift run -i sdr_full -n my_sdr_container -t bridge

Privilege Levels:

Control container privilege level:

# Run in unprivileged mode
rfswift run -i sdr_full -n my_sdr_container -u 0

# Run in privileged mode (use with caution)
rfswift run -i sdr_full -n my_sdr_container -u 1

Custom Commands:

Run a specific command instead of the default shell:

rfswift run -i gnuradio -n signal_processor -e "gnuradio-companion"

Use RF Tools in the Container

Once the container is running, you can use any of the pre-installed RF tools. For example, to run SDR++:

1. Connect your SDR device to your computer
2. Inside the container, run: sdrpp

USB Device Management

USB device handling varies by platform:

Windows USB Forwarding

On Windows, you’ll need to explicitly forward USB devices to your container using the winusb commands in Administrator mode:

# List available USB devices on Windows
rfswift winusb list

# Attach a specific device on Windows
rfswift winusb attach -i <USB ID>

Linux USB Device Access

On Linux, you can access USB devices in two ways:

1. During container creation - use the -s option to bind specific devices:

   rfswift run -i sdr_full -n my_container -s /dev/ttyUSB0:/dev/ttyUSB0

2. After container creation - use the powerful bindings feature to add devices to an existing container:

   # Add a new USB device to an existing container
   rfswift bindings add -c my_container -d -s /dev/ttyUSB0 -t /dev/ttyUSB0*
   
   # Same but shorter: Add a new USB device to an existing container with some destination
   rfswift bindings add -c my_container -t /dev/ttyUSB0
   
   # Add a new volume to an existing container
   rfswift bindings add -c my_container -s /home/user/data -t /root/data
   
   # Remove a binding
   rfswift bindings rm -c my_container -s /dev/ttyUSB0

Note that to rebind a device, you need the -d switch.