composites: add block docstrings

radio/composites/amenvelopedemodulator.lua

@@ -1,3 +1,19 @@
+---
+-- Demodulate a baseband, double-sideband amplitude modulated complex-valued
+-- signal with an envelope detector.
+--
+-- $$ y[n] = \text{AMDemodulate}(x[n], \text{bandwidth}) $$
+--
+-- @category Demodulation
+-- @block AMEnvelopeDemodulator
+-- @tparam[opt=5e3] number bandwidth Bandwidth in Hz
+--
+-- @signature in:ComplexFloat32 > out:Float32
+--
+-- @usage
+-- -- AM demodulator with 5 KHz bandwidth
+-- local demod = radio.AMEnvelopeDemodulator(5e3)
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/amsynchronousdemodulator.lua

@@ -1,3 +1,21 @@
+---
+-- Demodulate a double-sideband amplitude modulated complex-valued signal with
+-- a synchronous detector. The input signal should be centered on the specified
+-- intermediate frequency.
+--
+-- $$ y[n] = \text{AMDemodulate}(x[n], \text{IF}, \text{bandwidth}) $$
+--
+-- @category Demodulation
+-- @block AMSynchronousDemodulator
+-- @tparam number ifreq Intermediate frequency in Hz
+-- @tparam[opt=5e3] number bandwidth Bandwidth in Hz
+--
+-- @signature in:ComplexFloat32 > out:Float32
+--
+-- @usage
+-- -- AM demodulator with 100 KHz IF, 5 KHz bandwidth
+-- local demod = radio.AMSynchronousDemodulator(100e3, 5e3)
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/ax25receiver.lua

@@ -1,3 +1,17 @@
+---
+-- Demodulate and decode AX.25 frames from a baseband, narrowband FM, Bell 202
+-- AFSK modulated complex-valued signal.
+--
+-- @category Receivers
+-- @block AX25Receiver
+--
+-- @signature in:ComplexFloat32 > out:AX25FrameType
+--
+-- @usage
+-- local receiver = radio.AX25Receiver()
+-- local snk = radio.JSONSink()
+-- top:connect(src, receiver, snk)
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/decimator.lua

@@ -1,3 +1,24 @@
+---
+-- Decimate a complex or real valued signal. This block band-limits and
+-- downsamples the input signal. It reduces the sample rate for downstream
+-- blocks in the flow graph by a factor of M.
+--
+-- $$ y[n] = (x * h_{lpf})[nM] $$
+--
+-- @category Sample Rate Manipulation
+-- @block DecimatorBlock
+-- @tparam int decimation Downsampling factor M
+-- @tparam[opt={}] table options Additional options, specifying:
+--                               * `num_taps` (int, default 128)
+--                               * `window_type` (string, default "hamming")
+--
+-- @signature in:ComplexFloat32 > out:ComplexFloat32
+-- @signature in:Float32 > out:Float32
+--
+-- @usage
+-- -- Decimate by 5
+-- local decimator = radio.DecimatorBlock(5)
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/interpolator.lua

@@ -1,3 +1,25 @@
+---
+-- Interpolate a complex or real valued signal. This block scales, band-limits,
+-- and upsamples the input signal. It increases the sample rate for downstream
+-- blocks in the flow graph by a factor of L.
+--
+-- $$ y'[n] = \begin{cases} Lx[n/L] & \text{for integer } n/L \\ 0 & \text{otherwise} \end{cases} $$
+-- $$ y[n] = (y' * h_{lpf})[n] $$
+--
+-- @category Sample Rate Manipulation
+-- @block InterpolatorBlock
+-- @tparam int interpolation Upsampling factor L
+-- @tparam[opt={}] table options Additional options, specifying:
+--                               * `num_taps` (int, default 128)
+--                               * `window_type` (string, default "hamming")
+--
+-- @signature in:ComplexFloat32 > out:ComplexFloat32
+-- @signature in:Float32 > out:Float32
+--
+-- @usage
+-- -- Interpolate by 5
+-- local interpolator = radio.InterpolatorBlock(5)
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/nbfmdemodulator.lua

@@ -1,3 +1,22 @@
+---
+-- Demodulate a baseband, narrowband FM modulated complex-valued signal.
+--
+-- $$ y[n] = \text{NBFMDemodulate}(x[n], \text{deviation}, \text{bandwidth}) $$
+--
+-- The input signal will be band-limited by the specified deviation and
+-- bandwidth with a cutoff frequency calculated by Carson's rule.
+--
+-- @category Demodulation
+-- @block NBFMDemodulator
+-- @tparam[opt=5e3] number deviation Deviation in Hz
+-- @tparam[opt=4e3] number bandwidth Bandwidth in Hz
+--
+-- @signature in:ComplexFloat32 > out:Float32
+--
+-- @usage
+-- -- NBFM demodulator with 5KHz deviation and 4KHz bandwidth
+-- local demod = radio.NBFMDemodulator(5e3, 4e3)
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/pocsagreceiver.lua

@@ -1,3 +1,17 @@
+---
+-- Demodulate and decode POCSAG messages from a baseband, 4.5 KHz shift FSK
+-- modulated complex-valued signal.
+--
+-- @category Receivers
+-- @block POCSAGReceiver
+--
+-- @signature in:ComplexFloat32 > out:POCSAGMessageType
+--
+-- @usage
+-- local receiver = radio.POCSAGReceiver()
+-- local snk = radio.JSONSink()
+-- top:connect(src, receiver, snk)
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/rationalresampler.lua

@@ -1,3 +1,25 @@
+---
+-- Resample a complex or real valued signal by a rational factor. This block
+-- band-limits and resamples the input signal. It changes the sample rate for
+-- downstream blocks in the flow graph by a factor of L/M.
+--
+-- $$ y[n] = \text{Decimate}(\text{Interpolate}(x[n], L), M) $$
+--
+-- @category Sample Rate Manipulation
+-- @block RationalResamplerBlock
+-- @tparam int interpolation Upsampling factor L
+-- @tparam int decimation Downsampling factor M
+-- @tparam[opt={}] table options Additional options, specifying:
+--                               * `num_taps` (int, default 128)
+--                               * `window_type` (string, default "hamming")
+--
+-- @signature in:ComplexFloat32 > out:ComplexFloat32
+-- @signature in:Float32 > out:Float32
+--
+-- @usage
+-- -- Resample by 5/3
+-- local resampler = radio.RationalResamplerBlock(5, 3)
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/rdsreceiver.lua

@@ -1,3 +1,18 @@
+---
+-- Demodulate and decode RDS frames from a baseband, wideband FM broadcast
+-- modulated complex-valued signal.
+--
+-- @category Receivers
+-- @block RDSReceiver
+--
+-- @signature in:ComplexFloat32 > out:RDSFrameType
+--
+-- @usage
+-- local receiver = radio.RDSReceiver()
+-- local decoder = radio.RDSDecoderBlock()
+-- local snk = radio.JSONSink()
+-- top:connect(src, receiver, decoder, snk)
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/ssbdemodulator.lua

@@ -1,3 +1,20 @@
+---
+-- Demodulate a baseband, single-sideband amplitude modulated complex-valued
+-- signal.
+--
+-- $$ y[n] = \text{SSBDemodulate}(x[n], \text{sideband}, \text{bandwidth}) $$
+--
+-- @category Demodulation
+-- @block SSBDemodulator
+-- @tparam string sideband Sideband, choice of "lsb" or "usb".
+-- @tparam[opt=3e3] number bandwidth Bandwidth in Hz
+--
+-- @signature in:ComplexFloat32 > out:Float32
+--
+-- @usage
+-- -- SSB LSB demodulator with 3 KHz bandwidth
+-- local demod = radio.SSBDemodulator("lsb", 3e3)
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/ssbmodulator.lua

@@ -1,3 +1,20 @@
+---
+-- Modulate a real-valued signal into a baseband, single-sideband amplitude
+-- modulated complex-valued signal.
+--
+-- $$ y[n] = \text{SSBModulate}(x[n], \text{sideband}, \text{bandwidth}) $$
+--
+-- @category Modulation
+-- @block SSBModulator
+-- @tparam string sideband Sideband, choice of "lsb" or "usb".
+-- @tparam[opt=3e3] number bandwidth Bandwidth in Hz
+--
+-- @signature in:Float32 > out:ComplexFloat32
+--
+-- @usage
+-- -- SSB LSB modulator with 3 KHz bandwidth
+-- local mod = radio.SSBModulator("lsb", 3e3)
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/tuner.lua

@@ -1,3 +1,28 @@
+---
+-- Frequency translate, low-pass filter, and decimate a complex-valued signal.
+-- This block reduces the sample rate for downstream blocks in the flow graph
+-- by a factor of M.
+--
+-- $$ y[n] = (\text{FrequencyTranslate}(x[n], f_{offset}) * h_{lpf})[nM] $$
+--
+-- This block is convenient for translating signals to baseband and decimating
+-- them.
+--
+-- @category Spectrum Manipulation
+-- @block TunerBlock
+-- @tparam number offset Translation offset in Hz
+-- @tparam number bandwidth Signal bandwidth in Hz
+-- @tparam int decimation Downsampling factor M
+-- @tparam[opt={}] table options Additional options, specifying:
+--                               * `num_taps` (int, default 128)
+--                               * `window_type` (string, default "hamming")
+--
+-- @signature in:ComplexFloat32 > out:ComplexFloat32
+--
+-- @usage
+-- -- Translate -100KHz, filter 12KHz, and decimate by 5
+-- local tuner = radio.TunerBlock(-100e3, 12e3, 5)
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/wbfmmonodemodulator.lua

@@ -1,3 +1,18 @@
+---
+-- Demodulate a baseband, wideband FM modulated complex-valued signal into the
+-- real-valued mono channel (L+R) signal.
+--
+-- $$ y[n] = \text{WBFMMonoDemodulate}(x[n], \tau) $$
+--
+-- @category Demodulation
+-- @block WBFMMonoDemodulator
+-- @tparam[opt=75e-6] number tau FM de-emphasis time constant
+--
+-- @signature in:ComplexFloat32 > out:Float32
+--
+-- @usage
+-- local demod = radio.WBFMMonoDemodulator()
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')

radio/composites/wbfmstereodemodulator.lua

@@ -1,3 +1,18 @@
+---
+-- Demodulate a baseband, wideband FM modulated complex-valued signal into the
+-- real-valued stereo channel (L and R) signals.
+--
+-- $$ y_{left}[n], y_{right}[n] = \text{WBFMStereoDemodulate}(x[n], \tau) $$
+--
+-- @category Demodulation
+-- @block WBFMStereoDemodulator
+-- @tparam[opt=75e-6] number tau FM de-emphasis time constant
+--
+-- @signature in:ComplexFloat32 > left:Float32, right:Float32
+--
+-- @usage
+-- local demod = radio.WBFMStereoDemodulator()
+
 local block = require('radio.core.block')
 local types = require('radio.types')
 local blocks = require('radio.blocks')