LuaJITSupport

LuaJIT bindings for SoapySDR

The LuaJIT bindings for SoapySDR give the user access to the full SoapySDR functionality in LuaJIT without having to directly call into the C API. The API is largely identical to the C++ API, but the functions themselves are more 1-to-1 with the C API, with overloads removed and more descriptive function names. Otherwise, there are only small changes, which will be explained below. Full API documentation is available (TODO: link when uploaded) here.

Dependencies

The only requirement for this API is LuaJIT itself, as the calls into the native SoapySDR library are done through LuaJIT's FFI functionality. To install the LuaJIT bindings, LuaJIT must be found on the system at build-time.

Debian/Ubuntu:

sudo apt-get install luajit

Windows+MSVC:

• Install LuaJIT from prebuilt installers.

Basic example

local SoapySDR = require("SoapySDR")

-- Enumerate devices.
local results = SoapySDR.enumerateDevices()

-- Create device instance.
-- Args can be user-defined or from the enumeration result.
local args = {driver = "rtl-sdr"}
local sdr = SoapySDR.Device.new(args)

-- Query device info.
print("Antennas:")
local antennas = sdr:listAntennas(SoapySDR.Direction.RX, 0)
for i = 0, #antennas-1 do
    print(" * " .. antennas[i])
done

print("Gains:")
local gains = sdr:listGains(SoapySDR.Direction.RX, 0)
for i = 0, #gains-1 do
    print(" * " .. gains[i])
done

print("Frequency ranges:")
local freqRanges = sdr:getFrequencyRange(SoapySDR.Direction.RX, 0)
for i = 0, #freqRanges-1 do
    print(" * " .. tostring(freqRanges[i]))
done

-- Apply settings.
sdr:setSampleRate(SoapySDR.Direction.RX, 0, 1e6)
sdr:setFrequency(SoapySDR.Direction.RX, 0, 912.3e6)

-- Setup a stream (complex floats).
local rxStream = sdr:setupStream(SoapySDR.Direction.RX, SoapySDR.Format.CF32, {0})
sdr:activateStream(rxStream) -- Start streaming

-- Create a reusable buffer for RX samples.
local mtu = sdr:getStreamMTU(rxStream)
local cf32Buff = ffi.new("complex float[?]", mtu)
local cf32Buff2D = ffi.new("complex float*[1]", {cf32Buff})

-- Receive some samples.
for i = 0,10 do
    local ret, flags, timeNs = unpack(sdr:readStream(rxStream, cf32Buff2D, mtu))
    print(ret) -- Num samples or error code
    print(flags) -- Flags set by receive operation
    print(timeNs) -- Timestamp for receive buffer
done

-- Shut down the stream.
sdr:deactiveStream(rxStream) -- Stop streaming
sdr:closeStream(rxStream)

More examples

• https://github.com/pothosware/SoapySDR/tree/master/luajit/apps

Differences from C++ API

Native Lua types vs. LuaJIT types

LuaJIT has its own type system, with variables corresponding to C types rather than native Lua types. For the sake of simplicity, the SoapySDR LuaJIT API always returns native Lua types (number, string, boolean) for primitives, with the only exception being complex numbers, in which case the API returns LuaJIT's native complex type. SoapySDR C structs are converted to tables with equivalent fields.

For input parameters, the SoapySDR LuaJIT API accepts both native Lua types and LuaJIT C types, converting them internally. For input variables taking in C structs with buffers or const char* strings, the API accepts Lua tables/arrays with the equivalent fields, converting them internally.

Factory API

Per some Lua conventions, the Device::make() factory function is replaced by Device.new(), and destruction automatically occurs when the object goes out of scope.

Stream API

The readStream() and writeStream() calls do not support C++'s return-by-reference. Therefore, any readback parameters are not passed into the associated calls. These functions return multiple values, which can be parsed as an array or separated into multiple variables with Lua's unpack() function.

These functions take in the same C buffers as the main C++ API, with these allocated through LuaJIT's FFI.