blocks/protocol: add block docstrings

radio/blocks/protocol/ax25framer.lua

@@ -1,3 +1,38 @@
+---
+-- Validate and extract AX.25 frames from a bit stream.
+--
+-- @category Protocol
+-- @block AX25FramerBlock
+--
+-- @signature in:Bit > out:AX25FrameType
+--
+-- @usage
+-- local framer = radio.AX25FramerBlock()
+
+---
+-- AX.25 frame type, a Lua object with properties:
+-- ```
+-- {
+--  addresses = {
+--      {callsign = <string>, ssid = <integer>},
+--      ...
+--  },
+--  control = <integer>,
+--  pid = <integer>,
+--  payload = <byte string>,
+-- }
+-- ```
+--
+-- @type AX25FrameType
+-- @category Protocol
+-- @datatype AX25FramerBlock.AX25FrameType
+-- @tparam array addresses Array of addresses, each a table with key `callsign`
+--                         containing a 6-character string callsign and key
+--                         `ssid` containing a 7-bit wide integer SSID
+-- @tparam int control Control field, 8-bits wide
+-- @tparam int pid PID field, 8-bits wide
+-- @tparam string payload Payload byte string (variable length)
+
 local ffi = require('ffi')
 local bit = require('bit')
 

radio/blocks/protocol/pocsagdecoder.lua

@@ -1,3 +1,37 @@
+---
+-- Decode POCSAG frames into POCSAG messages. This block decodes alphanumeric
+-- strings, numeric strings, or both.
+--
+-- @category Protocol
+-- @block POCSAGDecoderBlock
+-- @tparam[opt='alphanumeric'] string mode Decoding mode, choice of
+--                                         "alphanumeric", "numeric", or
+--                                         "both".
+--
+-- @signature in:POCSAGFrameType > out:POCSAGMessageType
+--
+-- @usage
+-- local decoder = radio.POCSAGDecoderBlock()
+
+---
+-- POCSAG message type, a Lua object with properties:
+-- ```
+-- {
+--  address = <21-bit integer>,
+--  func = <2-bit integer>,
+--  alphanumeric = <string>,
+--  numeric = <string>,
+-- }
+-- ```
+--
+-- @type POCSAGMessageType
+-- @category Protocol
+-- @datatype POCSAGDecoderBlock.POCSAGMessageType
+-- @tparam int address Address bits, 21-bits wide
+-- @tparam int func Function bits, 2-bits wide
+-- @tparam string alphanumeric Decoded alphanumeric string
+-- @tparam string numeric Decoded numeric string
+
 local bit = require('bit')
 
 local block = require('radio.core.block')

radio/blocks/protocol/pocsagframer.lua

@@ -1,3 +1,33 @@
+---
+-- Detect, correct, validate, and extract POCSAG frames from a bit stream.
+-- Each frame contains a single message with address, function bits, and data,
+-- so a POCSAG transmission of several batches may yield several frames.
+--
+-- @category Protocol
+-- @block POCSAGFramerBlock
+--
+-- @signature in:Bit > out:POCSAGFrameType
+--
+-- @usage
+-- local framer = radio.POCSAGFramerBlock()
+
+---
+-- POCSAG frame type, a Lua object with properties:
+-- ```
+-- {
+--  address = <21-bit integer>,
+--  func = <2-bit integer>,
+--  data = {<20-bit integer>, ...},
+-- }
+-- ```
+--
+-- @type POCSAGFrameType
+-- @category Protocol
+-- @datatype POCSAGFramerBlock.POCSAGFrameType
+-- @tparam int address Address bits, 21-bits wide
+-- @tparam int func Function bits, 2-bits wide
+-- @tparam array data Array of data words, each 20-bits wide
+
 local ffi = require('ffi')
 local bit = require('bit')
 

radio/blocks/protocol/rdsdecoder.lua

@@ -1,3 +1,79 @@
+---
+-- Decode RDS frames into RDS packets with a header and data payload. The
+-- supported data payloads are basic tuning, radiotext, and datetime.
+--
+-- @category Protocol
+-- @block RDSDecoderBlock
+--
+-- @signature in:RDSFrameType > out:RDSPacketType
+--
+-- @usage
+-- local decoder = radio.RDSDecoderBlock()
+
+---
+-- RDS packet type, a Lua object with properties:
+-- ```
+-- {
+--  header = {
+--      pi_code = <16-bit integer>
+--      group_code = <4-bit integer>
+--      group_version = <1-bit integer>,
+--      tp_code = <1-bit integer>,
+--      pty_code = <5-bit integer>,
+--  },
+--  data = <payload object>,
+-- }
+-- ```
+--
+-- The payload object can be one of the four below.
+--
+-- Basic tuning data payload:
+-- ```
+-- {
+--  type = "basictuning",
+--  ta_code = <1-bit integer>,
+--  ms_code = <1-bit integer>,
+--  di_position = <2-bit integer>,
+--  di_value = <1-bit integer>,
+--  af_code = {<8-bit integer>, <8-bit integer>} or nil,
+--  text_address = <2-bit integer>,
+--  text_data = <string, length 2>,
+-- }
+-- ```
+--
+-- Radio text data payload:
+-- ```
+-- {
+--  type = "radiotext",
+--  ab_flag = <1-bit integer>,
+--  text_address = <4-bit integer>,
+--  text_data = <string, length 4 or 2>,
+-- }
+-- ```
+--
+-- Datetime data payload:
+-- ```
+-- {
+--  type = "datetime",
+--  date = {year = <integer>, month = <integer>, day = <integer>},
+--  time = {hour = <integer>, minute = <integer>, offset = <integer>},
+-- }
+-- ```
+--
+-- Raw data payload (for unsupported group/version codes):
+-- ```
+-- {
+--  type = "raw",
+--  frame = {<16-bit integer>, <16-bit integer>, <16-bit integer>, <16-bit integer>},
+-- }
+-- ```
+--
+-- @type RDSPacketType
+-- @category Protocol
+-- @datatype RDSDecoderBlock.RDSPacketType
+-- @tparam table header Header table, as outlined above
+-- @tparam table data Data payload table, as outlined above
+
 local bit = require('bit')
 
 local block = require('radio.core.block')

radio/blocks/protocol/rdsframer.lua

@@ -1,3 +1,28 @@
+---
+-- Correct, validate, and extract 104-bit RDS data groups from a bit stream
+-- into frames.
+--
+-- @category Protocol
+-- @block RDSFramerBlock
+--
+-- @signature in:Bit > out:RDSFrameType
+--
+-- @usage
+-- local framer = radio.RDSFramerBlock()
+
+---
+-- RDS frame type, a C structure defined as:
+-- ```
+-- typedef struct {
+--     uint16_t blocks[4];
+-- } rds_frame_t;
+-- ```
+--
+-- @type RDSFrameType
+-- @category Protocol
+-- @datatype RDSFramerBlock.RDSFrameType
+-- @tparam table data Array of four data words, e.g. `{{0x3aab, 0x02c9, 0x0608, 0x6469}}`
+
 local ffi = require('ffi')
 local bit = require('bit')