blocks/sinks: add block docstrings

radio/blocks/sinks/benchmark.lua

@@ -1,3 +1,29 @@
+---
+-- Report the average rate of samples delivered to the sink.
+--
+-- ```
+-- [BenchmarkSink] 314.38 MS/s (2.52 GB/s)
+-- [BenchmarkSink] 313.32 MS/s (2.51 GB/s)
+-- [BenchmarkSink] 313.83 MS/s (2.51 GB/s)
+-- ...
+-- ```
+--
+-- @category Sinks
+-- @block BenchmarkSink
+-- @tparam[opt=io.stderr] string|file|int file Filename, file object, or file descriptor
+-- @tparam[opt=false] bool use_json Serialize aggregate results in JSON on termination
+--
+-- @signature in:any >
+--
+-- @usage
+-- -- Benchmark a source, writing periodic results to stderr
+-- local snk = radio.BenchmarkSink()
+-- top:connect(src, snk)
+--
+-- -- Benchmark a source and a block, writing final results in JSON to fd 3
+-- local snk = radio.BenchmarkSink(3, true)
+-- top:connect(src, blk, snk)
+
 local ffi = require('ffi')
 local json = require('radio.thirdparty.json')
 

radio/blocks/sinks/gnuplotplot.lua

@@ -1,3 +1,29 @@
+---
+-- Plot a real-valued signal in a gnuplot time plot. This sink requires the
+-- gnuplot program. This sink should be used with relatively low sample rates,
+-- as it does not skip any samples, or it may otherwise throttle a flow graph.
+--
+-- @category Sinks
+-- @block GnuplotPlotSink
+-- @tparam int num_samples Number of samples to plot
+-- @tparam[opt=""] string title Title of plot
+-- @tparam[opt={}] table options Additional options, specifying:
+--                            * `xlabel` (string, default "Sample Number")
+--                            * `ylabel` (string, default "Value")
+--                            * `yrange` (array of two numbers, default `nil`
+--                            for autoscale)
+--                            * `extra_settings` (array of strings containing
+--                            gnuplot commands)
+--
+-- @signature in:Float32 >
+--
+-- @usage
+-- -- Plot a 1 KHz cosine sampled at 250 KHz
+-- local snk = radio.SignalSource('cosine', 1e3, 250e3)
+-- local throttle = radio.ThrottleBlock()
+-- local snk = radio.GnuplotPlotSink(1000, 'Cosine')
+-- top:connect(src, throttle, snk)
+
 local ffi = require('ffi')
 
 local block = require('radio.core.block')

radio/blocks/sinks/gnuplotspectrum.lua

@@ -1,3 +1,36 @@
+---
+-- Plot the power spectrum of a complex or real-valued signal. This sink
+-- requires the gnuplot program. The power spectral density is estimated with
+-- Bartlett's or Welch's method of averaging periodograms.
+--
+-- @category Sinks
+-- @block GnuplotSpectrumSink
+-- @tparam[opt=1024] int num_samples Number of samples in periodogram
+-- @tparam[opt=""] string title Title of plot
+-- @tparam[opt={}] table options Additional options, specifying:
+--                            * `update_time` (number, default 0.10 seconds)
+--                            * `overlap` fraction (number from 0.0 to 1.0,
+--                            default 0.0)
+--                            * `reference_level` (number, default 0.0 dB)
+--                            * `window` (string, default "hamming")
+--                            * `onesided` (bool, default true)
+--                            * `xrange` (array of two numbers, default `nil`
+--                            for autoscale)
+--                            * `yrange` (array of two numbers, default `nil`
+--                            for autoscale)
+--                            * `extra_settings` (array of strings containing
+--                            gnuplot commands)
+--
+-- @signature in:ComplexFloat32 >
+-- @signature in:Float32 >
+--
+-- @usage
+-- -- Plot the spectrum of a 1 KHz complex exponential sampled at 250 KHz
+-- local snk = radio.SignalSource('exponential', 1e3, 250e3)
+-- local throttle = radio.ThrottleBlock()
+-- local snk = radio.GnuplotSpectrumSink()
+-- top:connect(src, throttle, snk)
+
 local ffi = require('ffi')
 local math = require('math')
 

radio/blocks/sinks/gnuplotwaterfall.lua

@@ -1,3 +1,41 @@
+---
+-- Plot the vertical power spectrogram (waterfall) of a complex or real-valued
+-- signal. This sink requires the gnuplot program. The power spectral density
+-- is estimated with Bartlett's or Welch's method of averaging periodograms.
+--
+-- Note: this sink's performance is currently limited and should only be used
+-- with very low sample rates, or it may otherwise throttle a flow graph.
+--
+-- @category Sinks
+-- @block GnuplotWaterfallSink
+-- @tparam[opt=1024] int num_samples Number of samples in periodogram
+-- @tparam[opt=""] string title Title of plot
+-- @tparam[opt={}] table options Additional options, specifying:
+--                            * `update_time` (number, default 0.10 seconds)
+--                            * `overlap` fraction (number from 0.0 to 1.0,
+--                            default 0.0)
+--                            * `height` in rows (number, default 64)
+--                            * `min_magnitude` (number, default -150.0 dB)
+--                            * `max_magnitude` (number, default 0.0 dB)
+--                            * `window` (string, default "hamming")
+--                            * `onesided` (boolean, default true)
+--                            * `xrange` (array of two numbers, default `nil`
+--                            for autoscale)
+--                            * `yrange` (array of two numbers, default `nil`
+--                            for autoscale)
+--                            * `extra_settings` (array of strings containing
+--                            gnuplot commands)
+--
+-- @signature in:ComplexFloat32 >
+-- @signature in:Float32 >
+--
+-- @usage
+-- -- Plot the waterfall of a 1 KHz complex exponential sampled at 250 KHz
+-- local snk = radio.SignalSource('exponential', 1e3, 250e3)
+-- local throttle = radio.ThrottleBlock()
+-- local snk = radio.GnuplotSpectrumSink()
+-- top:connect(src, throttle, snk)
+
 local ffi = require('ffi')
 local math = require('math')
 

radio/blocks/sinks/gnuplotxyplot.lua

@@ -1,3 +1,39 @@
+---
+-- Plot two real-valued signals, or the real and imaginary components of one
+-- complex-valued signal, in a gnuplot XY plot. This sink requires the gnuplot
+-- program. This sink should be used with relatively low sample rates, as it
+-- does not skip any samples, or it may otherwise throttle a flow graph.
+--
+-- @category Sinks
+-- @block GnuplotXYPlotSink
+-- @tparam int num_samples Number of samples to plot
+-- @tparam[opt=""] string title Title of plot
+-- @tparam[opt={}] table options Additional options, specifying:
+--                            * `complex` (bool, default false)
+--                            * `xlabel` (string, default "")
+--                            * `ylabel` (string, default "")
+--                            * `xrange` (array of two numbers, default `nil`
+--                            for autoscale)
+--                            * `yrange` (array of two numbers, default `nil`
+--                            for autoscale)
+--                            * `extra_settings` (array of strings containing
+--                            gnuplot commands)
+--
+-- @signature x:Float32, y:Float32 >
+-- @signature in:ComplexFloat32 >
+--
+-- @usage
+-- -- Plot a 1 KHz complex exponential sampled at 250 KHz
+-- local snk = radio.SignalSource('exponential', 1e3, 250e3)
+-- local throttle = radio.ThrottleBlock()
+-- local snk = radio.GnuplotXYPlotSink(1000, 'Complex Exponential', {complex = true})
+-- top:connect(src, throttle, snk)
+--
+-- -- Plot two real-valued signals
+-- local snk = radio.GnuplotXYPlotSink(1000, 'XY')
+-- top:connect(src1, 'out', snk, 'x')
+-- top:connect(src2, 'out', snk, 'y')
+
 local ffi = require('ffi')
 
 local block = require('radio.core.block')

radio/blocks/sinks/iqfile.lua

@@ -1,3 +1,29 @@
+---
+-- Sink a complex-valued signal to a binary "IQ" file. The file format may be
+-- 8/16/32-bit signed/unsigned integers or 32/64-bit floats, in little or big
+-- endianness, and will be interleaved as real component followed by imaginary
+-- component.
+--
+-- @category Sinks
+-- @block IQFileSink
+-- @tparam string|file|int file Filename, file object, or file descriptor
+-- @tparam string format File format specifying signedness, bit width, and
+--                       endianness of samples. Choice of "s8", "u8", "u16le",
+--                       "u16be", "s16le", "s16be", "u32le", "u32be", "s32le",
+--                       "s32be", "f32le", "f32be", "f64le", "f64be".
+--
+-- @signature in:ComplexFloat32 >
+--
+-- @usage
+-- -- Sink signed 8-bit IQ samples to a file
+-- local snk = radio.IQFileSink('samples.s8.iq', 's8')
+--
+-- -- Sink little-endian 32-bit IQ samples to a file
+-- local snk = radio.IQFileSink('samples.f32le.iq', 'f32le', 1e6, true)
+--
+-- -- Sink little-endian signed 16-bit IQ samples to stdout
+-- local snk = radio.IQFileSink(1, 's16le')
+
 local ffi = require('ffi')
 
 local block = require('radio.core.block')

radio/blocks/sinks/json.lua

@@ -1,3 +1,23 @@
+---
+-- Sink a signal to a file, serialized in JSON. Samples are serialized
+-- individually and newline delimited. This sink accepts any data type that
+-- implements `to_json()`.
+--
+-- @category Sinks
+-- @block JSONSink
+-- @tparam[opt=io.stdout] string|file|int file Filename, file object, or file descriptor
+--
+-- @signature in:implementing >
+--
+-- @usage
+-- -- Sink JSON serialized samples to stdout
+-- local snk = radio.JSONSink()
+-- top:connect(src, snk)
+--
+-- -- Sink JSON serialized samples to a file
+-- local snk = radio.JSONSink('out.json')
+-- top:connect(src, snk)
+
 local ffi = require('ffi')
 
 local block = require('radio.core.block')

radio/blocks/sinks/portaudio.lua

@@ -1,3 +1,24 @@
+---
+-- Sink one or more real-valued signals to the system's audio device with
+-- PortAudio. This source requires the PortAudio library.
+--
+-- @category Sinks
+-- @block PortAudioSink
+-- @tparam int num_channels Number of channels (e.g. 1 for mono, 2 for stereo)
+--
+-- @signature in:Float32 >
+-- @signature in1:Float32, in2:Float32, ... >
+--
+-- @usage
+-- -- Sink to one channel (mono) audio
+-- local snk = radio.PortAudioSink(1)
+-- top:connect(src, snk)
+--
+-- -- Sink to two channel (stereo) audio
+-- local snk = radio.PortAudioSink(2)
+-- top:connect(src_left, 'out', snk, 'in1')
+-- top:connect(src_right, 'out', snk, 'in2')
+
 local ffi = require('ffi')
 
 local block = require('radio.core.block')

radio/blocks/sinks/print.lua

@@ -1,3 +1,19 @@
+---
+-- Sink a signal to a file, formatted as a string. Samples are formatted
+-- individually and newline delimited. This sink accepts any data type that
+-- implements `__tostring()`.
+--
+-- @category Sinks
+-- @block PrintSink
+-- @tparam[opt=io.stdout] string|file|int file Filename, file object, or file descriptor
+--
+-- @signature in:implementing >
+--
+-- @usage
+-- -- Sink string formatted samples to stdout
+-- local snk = radio.PrintSink()
+-- top:connect(src, snk)
+
 local ffi = require('ffi')
 
 local block = require('radio.core.block')

radio/blocks/sinks/pulseaudio.lua

@@ -1,3 +1,24 @@
+---
+-- Sink one or more real-valued signals to the system's audio device with
+-- PulseAudio. This source requires PulseAudio.
+--
+-- @category Sinks
+-- @block PulseAudioSink
+-- @tparam int num_channels Number of channels (e.g. 1 for mono, 2 for stereo)
+--
+-- @signature in:Float32 >
+-- @signature in1:Float32, in2:Float32, ... >
+--
+-- @usage
+-- -- Sink to one channel (mono) audio
+-- local snk = radio.PulseAudioSink(1)
+-- top:connect(src, snk)
+--
+-- -- Sink to two channel (stereo) audio
+-- local snk = radio.PulseAudioSink(2)
+-- top:connect(src_left, 'out', snk, 'in1')
+-- top:connect(src_right, 'out', snk, 'in2')
+
 local ffi = require('ffi')
 
 local block = require('radio.core.block')

radio/blocks/sinks/rawfile.lua

@@ -1,3 +1,24 @@
+---
+-- Sink a signal to a binary file. The samples are serialized raw, in their
+-- native binary representation, with no signedness conversion, endian
+-- conversion, or interpretation. This is useful for serializing data types
+-- across a pipe or other file descriptor based IPC.
+--
+-- @category Sinks
+-- @block RawFileSink
+-- @tparam string|file|int file Filename, file object, or file descriptor
+--
+-- @signature in:any >
+--
+-- @usage
+-- -- Sink raw samples to a file
+-- local snk = radio.RawFileSink('samples.raw')
+-- top:connect(src, snk)
+--
+-- -- Sink raw samples to file descriptor 3
+-- local snk = radio.RawFileSink(3)
+-- top:connect(src, snk)
+
 local ffi = require('ffi')
 
 local block = require('radio.core.block')

radio/blocks/sinks/realfile.lua

@@ -1,3 +1,29 @@
+---
+-- Sink a real-valued signal to a binary file. The file format may be
+-- 8/16/32-bit signed/unsigned integers or 32/64-bit floats, in little or big
+-- endianness. This is the real-valued counterpart of
+-- [`IQFileSink`](#iqfilesink).
+--
+-- @category Sinks
+-- @block RealFileSink
+-- @tparam string|file|int file Filename, file object, or file descriptor
+-- @tparam string format File format specifying signedness, bit width, and
+--                       endianness of samples. Choice of "s8", "u8", "u16le",
+--                       "u16be", "s16le", "s16be", "u32le", "u32be", "s32le",
+--                       "s32be", "f32le", "f32be", "f64le", "f64be".
+--
+-- @signature in:Float32 >
+--
+-- @usage
+-- -- Sink signed 8-bit real samples to a file
+-- local snk = radio.RealFileSink('samples.s8.real', 's8')
+--
+-- -- Sink little-endian 32-bit real samples to a file
+-- local snk = radio.RealFileSink('samples.f32le.real', 'f32le', 1e6, true)
+--
+-- -- Sink little-endian signed 16-bit real samples to stdout
+-- local snk = radio.RealFileSink(1, 's16le')
+
 local ffi = require('ffi')
 
 local block = require('radio.core.block')

radio/blocks/sinks/wavfile.lua

@@ -1,3 +1,27 @@
+---
+-- Sink one or more real-valued signals to a WAV file. The supported sample
+-- formats are 8-bit unsigned integer, 16-bit signed integer, and 32-bit signed
+-- integer.
+--
+-- @category Sinks
+-- @block WAVFileSink
+-- @tparam string|file|int file Filename, file object, or file descriptor
+-- @tparam int num_channels Number of channels (e.g. 1 for mono, 2 for stereo, etc.)
+-- @tparam[opt=16] int bits_per_sample Bits per sample, choice of 8, 16, or 32
+--
+-- @signature in:Float32 >
+-- @signature in1:Float32, in2:Float32, ... >
+--
+-- @usage
+-- -- Sink to a one channel WAV file
+-- local snk = radio.WAVFileSink('test.wav', 1)
+-- top:connect(src, snk)
+--
+-- -- Sink to a two channel WAV file
+-- local snk = radio.WAVFileSink('test.wav', 2)
+-- top:connect(src1, 'out', snk, 'in1')
+-- top:connect(src2, 'out', snk, 'in2')
+
 local ffi = require('ffi')
 
 local block = require('radio.core.block')