Data, Transport and Source Blocks

After a deframer has produced frames, transports and data sinks decide what happens to them, and data sources can replay previously saved frames. This page documents the blocks under Satellites > Transports, Satellites > Data sinks and Satellites > Data sources in GNU Radio Companion: their parameters, their exact input and output, and their quirks.

All of these blocks work on PDUs (message ports in and out) whose payload is a u8vector. A PDU with a different payload type is rejected with [ERROR] Received invalid message type. Expected u8vector.

Data Sources

KISS File Source

Reads a KISS file and outputs each data frame as a PDU on out.

Parameter Meaning
File Path of the KISS file.

Only frames whose KISS command byte has a low nibble of 0 (data frames) are output, with the command byte removed. The timestamp frames (0x09) written by gr-satellites are skipped. This is the block behind gr_satellites --kiss_in.

Reading or capturing RF samples needs no special source: the standard GNU Radio blocks (File Source, WAV File Source, Audio Source, UDP Source, SDR blocks) do that.

Transports

KISS Transport

Joins the payloads of consecutive frames into one KISS byte stream and extracts the packets in it, so packets can be longer than a frame or span frame boundaries. KISS idle bytes (c0 padding) are discarded.

Parameter Default Meaning
Expect control byte True: each packet starts with a KISS command byte, which must be a data command (low nibble 0) and is removed; other packets are dropped. False: no command byte.

When KISS is only used for fragmentation, as in BY70-1 and LilacSat-1, there is no control byte. In examples/components/kiss_transport.grc (BY70-1), a 114-byte RS frame such as

pdu_length = 114
contents = 
0000: c0 b8 64 3d 00 12 00 00 00 00 c8 3a 00 80 00 00 
...
0050: 18 21 00 00 db dc 4b f7 07 c0 c0 c0 c0 c0 c0 c0 
...

becomes an 87-byte packet: the leading and trailing c0 bytes are removed and the escape db dc is turned back into c0.

In Python the class also accepts header_remove_bytes, which strips a fixed number of bytes from the start of each frame first (used by the KISS KS-1Q protocol).

TM KISS Transport

For CCSDS TM frames whose data field carries a KISS stream. Frames are parsed with a TM primary header, frames on virtual channels not in the list are dropped, and a separate KISS stream is followed for each listed virtual channel.

Parameter Meaning
Virtual channels List of virtual channel IDs to extract, e.g. [1].
Short TM Use the short (5-byte) TM primary header of BY02 and similar missions instead of the standard header.

Warning: The GRC block definition of TM KISS Transport generates a call to kiss_transport(virtual_channels=..., short_tm=...) instead of tm_kiss_transport(...), so a flowgraph using this block fails with a TypeError when it starts. In Python, use satellites.components.transports.tm_kiss_transport directly. The command line tool is not affected; it uses the correct class for the TM KISS protocols.

Defragments NANOLINK byte streams (syncword faf320) into NANOLINK frames. It has no parameters besides Command line options and is not available as a SatYAML protocol.

Data Sinks

Telemetry Parser

Parses each frame with a telemetry definition from satellites.telemetry (a construct structure or an object with a parse() method) and prints the result.

Parameter Meaning
Telemetry Definition Name of the definition, e.g. funcube, au03, csp, ax25.
Output Standard output, or a file.
File Output file (when Output is a file). It is opened in append mode.

For each frame it prints -> Packet from <transmitter> if the PDU metadata has a transmitter key (frames from the Satellite decoder block do), then the parsed structure. Parse errors print Could not parse telemetry beacon <error>. If the definition returns nothing (some stateful parsers do for frames they ignore), nothing is printed.

The Telemetry Parser does not parse its Command line options string: it only reads telemetry_output from an argparse namespace, which is what the command line tool passes. In GRC, choose the output with the Output and File parameters.

The list of definitions is in python/telemetry/__init__.py; in Python, help(satellites.telemetry) lists them. Example: examples/components/telemetry_parser.grc parses GOMX-1 beacons. Output starts like:

Container: 
    csp_header = Container: 
        priority = 2
        source = 1
        destination = 10
        destination_port = 30
        ...
    beacon_time = 2015-03-31 20:57:01

Telemetry Submit

Submits frames to a telemetry server, reading credentials from ~/.gr_satellites/config.ini (see Telemetry Submission).

Parameter Default Used by
Server SatNOGS SatNOGS, FUNcube, PWSat, BME, BMEWS, HIT, SIDS
URL SIDS
NORAD ID 0 SatNOGS, SIDS (sent to the server) and BME (must be 44830, 44832 or 47964, otherwise a KeyError)
TCP server port 0 HIT (proxy port on 127.0.0.1)

This block submits whenever the flowgraph runs: it ignores submit_tlm and GR_SATELLITES_SUBMIT_TLM. SatNOGS/SIDS submission still does nothing if the callsign is empty or the location is (0, 0). Its --start_time option sets the timestamp base for SatNOGS/SIDS.

Hexdump Sink

Prints PDUs in hex using GNU Radio's Message Debug block (print port). It is the block used by gr_satellites --hexdump, and a drop-in alternative to Message Debug in custom flowgraphs.

KISS File Sink

Writes PDUs to a KISS file, each preceded by a timestamp frame (control byte 0x09, big-endian 64-bit milliseconds since the UNIX epoch).

Parameter Meaning
File Output path.
Append file Append instead of overwriting.

--start_time in the options sets the time base for the timestamps. Read the file back with the KISS File Source block or gr_satellites --kiss_in.

KISS Server Sink

Runs a TCP server that sends PDUs in KISS format, with timestamp frames, to all connected clients.

Parameter Meaning
Address Bind address; '' for all interfaces.
Port TCP port.

File and Image Receivers

Reassemble files sent in chunks using a definition from satellites.filereceiver (see Files and Images and Writing a File Receiver).

Parameter File Receiver Image Receiver Meaning
FileReceiver / ImageReceiver class ✓ ✓ Definition name, e.g. smogp or by70_1. Image receivers must derive from ImageReceiver.
Path ✓ ✓ Output directory.
Verbose ✓ ✓ Print reception progress.
Display ✓ (default True) Open feh when enough data has arrived.
Fullscreen ✓ (default True) Run feh fullscreen.

examples/components/image_receiver.grc replays a LilacSat-1 image transfer with a Throttle block, decodes it with the Satellite decoder, extracts the packets with a KISS Transport and feeds the Image Receiver, which opens feh as soon as the image starts.

Codec2 UDP Sink

Sends each 7-byte Codec2 frame in its own UDP datagram, for minimum latency. Used by the LilacSat-1 decoder.

Parameter Default Meaning
IP 127.0.0.1 Destination address (--codec2_ip on the command line).
Port 7000 Destination UDP port (--codec2_port).

Play the voice with: nc -lu 7000 | c2dec 1300 - - | play -t raw -r 8000 -e signed-integer -b 16 -c 1 - (c2dec comes from the codec2 library).

See Also