Install/Environment

The most widely used tool in the world of software defined radio is GNURadio. While it can be buggy and leaves a lot to be desired, it also is pretty robust and offers a wide variety of different tools that allow for some pretty advanced usecases. This tutorial is in GNURadio because it is very straightforward to pick up and does not require programming experience to be able to use it.

The Anvil VMs which connect to the radios come with GNURadio installed, but the first two lessons can be done on any home computer that has sufficient processing power. More importantly, a common good practice with radio communication is to test your communication scheme in some kind of virtual environment before you try using it over an actual wireless channel. GNURadio makes this easy!

The software was built with Linux in mind and as such, the developers do not seek to officially support other platforms such as Windows and macOS. This makes it difficult to get it working under these platforms and this guide does not seek to be an "end all" to getting it to work on your computer. If you would like to have the most painless experience, we recommend either emulating Linux under something like VirtualBox, or installing it on an external drive or your own internal storage so that you can dual boot. However, if you would like to try to get it working on your current system, here are the things which have been found to work:

Linux

Ubuntu tends to have the best support for Software Defined Radio in general due to its more up to date and larger software repositories (this matters more when interfacing with radio hardware) but the packages exist for all major distributions. The different install commands can be found on their official install page here.

Windows

Windows support is limited given the X11 based software has to be ported to run on windows desktops. While there are many methods that can get you a working interface, they all seem to have issues, especially when working with the new version of GNURadio (3.8+). These issues range from graphical issues to basic modules not working at all due to pathing issues. The most stable option seems to be emulating it under Windows Subsystem for Linux (WSL). Otherwise, you can also install an older version (3.7) which seems to be fairly stable and works decently.

GNURadio Installer Package

GNURadio has releases ready to be installed. The version we recommend is 3.7.13.5.

Windows Linux Subsystem

While WSL works very well for command line applications, it can be used for graphical applications as well, given you have an X window forwarder running. This can be taken care of by Xming. It can be downloaded and installed through chocolaty using:

choco install xming

Or with installer:

https://sourceforge.net/projects/xming/

Once installed, run Xming, which will create a new virtual display that can be used by WSL to render graphical applications.

The next step is to install the X11 window manager as well as GNU Radio under WSL. If using a Debian based distro like Ubuntu, then you can run the following commands:

sudo apt install x11-apps
sudo apt install gnuradio
export DISPLAY=:0 #sets display as 0 as set by Xming
gnuradio-companion #runs GNU Radio

This experience seems to be fairly stable, and works, in some cases, better than the ported Windows version. However, there may need to be some customizations made with Xming to adjust fonts and sizes so that the UI is more readable. More info available here.

Compiling from source

This is not easy and requires getting all of the libraries either installed or compiled. Here's a guide which seeks to make it a little easier however.

MacOS

macOS is the hardest to get working. The homebrew version currently doesn't work at all and the MacPorts version doesn't build correctly either. The best working version seems to be a prebuilt binary made to work painlessly; however, with Catalina's (10.15) new security changes, it does not work correctly and leads to the application not being able to read or write to any files in the user's home directory making it much more difficult to use. The proper fix to this would be to rebuild GNURadio with the proper permissions in mind. Another fix is to allow all console applications the global ability to read and write anywhere, creating a huge security hole as a malicious console application could effectively ruin your computer.

Because of these limitations, we recommend either emulating Linux under something like VirtualBox if you're on macOS Catalina (10.15) or newer until the devlopers resolve the file permissions issue. If you're on an older version, feel free to use the prebuilt App. It should work given you install Python 3.7 and XQuartz.

Prebuilt App (macOS Mojave or older (10.14-)

These fine folks started building GNURadio so that you wouldn't have to. Sadly, it doesn't currently work under macOS Catalina 10.15.

1. Install Python 3.7 by using the installer here.
2. Install XQuartz (X11 windows server) by using the installer here.
3. Download and install GNURadio from here.

Building From Source

If you decide to do this, let us know and you can add your experience to this guide. Here's their guide.

GNURadio Basics

Work in progress

Wave Essentials

Work in progress

Signal Processing

Work in progess

Physical Communication

Work in progress