LuaRadio

LuaRadio is a lightweight, embeddable flow graph signal processing framework for software-defined radio. It provides a suite of source, sink, and processing blocks, with a simple API for defining flow graphs, running flow graphs, creating blocks, and creating data types. LuaRadio is built on LuaJIT, has a small binary footprint of under 750 KB (including LuaJIT), has no external hard dependencies, and is MIT licensed.

LuaRadio can be used to rapidly prototype software radios, modulation/demodulation utilities, and signal processing experiments. It can also be embedded into existing radio applications to serve as a user scriptable engine for signal processing.

LuaRadio blocks are written in pure Lua, but can use LuaJIT's FFI to wrap external libraries, like VOLK, liquid-dsp, and others, for computational acceleration, sophisticated processing, and interfacing with SDR hardware.

Use GNU Radio? See how LuaRadio compares to GNU Radio.

See the LuaRadio mailing list for general discussion.

Example

Wideband FM Broadcast Radio Receiver

local radio = require('radio')

radio.CompositeBlock():connect(
    radio.RtlSdrSource(88.5e6 - 250e3, 1102500), -- RTL-SDR source, offset-tuned to 88.5MHz-250kHz
    radio.TunerBlock(-250e3, 200e3, 5),          -- Translate -250 kHz, filter 200 kHz, decimate by 5
    radio.FrequencyDiscriminatorBlock(1.25),     -- Frequency demodulate with 1.25 modulation index
    radio.LowpassFilterBlock(128, 15e3),         -- Low-pass filter 15 kHz for L+R audio
    radio.FMDeemphasisFilterBlock(75e-6),        -- FM de-emphasis filter with 75 uS time constant
    radio.DownsamplerBlock(5),                   -- Downsample by 5
    radio.PulseAudioSink(1)                      -- Play to system audio with PulseAudio
):run()

Check out some more examples of what you can build with LuaRadio.

Built-in Applications

LuaRadio comes with a collection of built-in command-line applications. These applications include radio receivers that are compatible with all SDR sources supported by the framework, as well as file and network sources:

$ luaradio
Usage: luaradio [options] <script> [args]

Options:
  -h, --help            Print help and exit
  --version             Print version and exit
  --platform            Dump platform and exit
  -v, --verbose         Enable debug verbosity
  -a, --application     Run built-in application

Application Usage: ./luaradio -a <application> [args]

Built-in Applications:
  rx_raw                Raw Receiver
  rx_wbfm               Wideband FM Receiver
  rx_nbfm               Narrowband FM Receiver
  rx_am                 AM Receiver
  rx_ssb                SSB Receiver
  rx_rds                RDS Receiver
  rx_ax25               AX.25 Receiver
  rx_pocsag             POCSAG Receiver
  rx_ert                ERT Receiver (IDM, SCM, SCM+)
  iq_converter          IQ File Converter
$

See the Applications documentation for more information on running built-in applications.

Quickstart

With LuaJIT installed, LuaRadio can be run directly from the repository:

git clone https://github.com/vsergeev/luaradio.git

$ cd luaradio
$ ./luaradio --platform
luajit          LuaJIT 2.0.5
os              Linux
arch            x64
page size       4096
cpu count       4
cpu model       Intel(R) Core(TM) i5-4570T CPU @ 2.90GHz
features
    fftw3f      true    fftw-3.3.8-sse2-avx
    volk        true    2.0 (avx2_64_mmx_orc)
    liquid      true    1.3.2
$

LuaRadio is accelerated by the optional libraries liquid-dsp, VOLK, and fftw. For best real-time performance, install these libraries and check that the features are marked true in the platform information:

Arch Linux: sudo pacman -S liquid-dsp libvolk fftw
macOS (Homebrew): brew install liquid-dsp fftw
macOS (MacPorts): sudo port install liquid-dsp volk fftw-3
Ubuntu/Debian/Raspbian: sudo apt-get install libliquid-dev libvolk1-dev libfftw3-dev
Fedora/CentOS: sudo yum install liquid-dsp fftw

Try out one of the examples with an RTL-SDR dongle:

$ ./luaradio examples/rtlsdr_wbfm_mono.lua 91.1e6

LuaRadio primarily supports Linux. It also strives to support FreeBSD and macOS, but real-time and audio support on these platforms is currently experimental. LuaRadio and all of its examples run great on the Raspberry Pi 3 with Arch Linux or Raspbian.

See the Getting Started guide for a tutorial on building your own flow graphs.

Installation

Arch Linux users can install LuaRadio with the AUR package luaradio.

macOS users can install LuaRadio with the Homebrew or MacPorts package luaradio.

See the Installation guide for other installation methods and details.

Project Roadmap

Check out the project roadmap for upcoming changes.

Contributions are welcome! See the contributing document for guidelines.

Documentation

LuaRadio documentation is contained in the docs folder.

Project Structure

radio/ - Radio package
- core/ - Core framework
- types/ - Basic types
- utilities/ - Utility classes and functions
- blocks/ - Blocks
  - sources/ - Sources
  - sinks/ - Sinks
  - signal/ - Signal blocks
  - protocol/ - Protocol blocks
- composites/ - Composite blocks
- thirdparty/ - Included third-party libraries
- init.lua - Package init
examples/ - Examples
embed/ - Embeddable C library
- Makefile - C library Makefile
- luaradio.c - C API implementation
- luaradio.h - C API header
- examples/ - C API examples
- tests/ - C API unit tests
benchmarks/ - Benchmark suites
- luaradio_benchmark.lua - LuaRadio benchmark suite
- gnuradio_benchmark.py - GNU Radio benchmark suite
docs/ - Documentation
- refman/ - Reference manual generator
tests/ - Unit tests
CHANGELOG.md - Change log
README.md - This README
LICENSE - MIT License
luaradio - luaradio runner helper script executable

Testing

LuaRadio unit tests are run with busted.

Install busted with LuaRocks:

sudo luarocks --lua-version=5.1 install busted

Run unit tests with:

busted

License

LuaRadio is MIT licensed. See the included LICENSE file.

cdgraff/luaradio