Overview of the RTL TCP ProtocolPaul Tagliamonte 2020-11-03 protocol
The rtl_tcp program will allow a client to remotely receive iq samples from the rtl sdr over a tcp connection. This document describes the mechanism by which the client and server communicate.
All data sent to and from the server are encoded in network byte order (big endian). This doesn’t matter for the actual iq data, since it’s uint8 real/imag interleaved, but it will matter for the header.
TCP Client Stream
On connection to the rtl_tcp socket, the server will begin to stream IQ samples to the client. The first 12 bytes are part of the DongleInfo struct, but since it’s 2 byte aligned, clients can choose to ignore the DongleInfo struct if they so desire.
Following the DongleInfo struct is a stream of infinite length of interleaved IQ data, in the same format that the rtl-sdr library will return data to the caller — a stream of interleaved real and imaginary uint8 values, where 128 is 0, 255 is 1, and 0 is -1.
Dongle Info struct
The first bytes sent to the client contain information about the tuner at the remote end of the rtl_tcp connection. This allows the client to determine ranges for gain values, or if there’s an intermediate frequency gain stage.
These bytes are aligned to 2 byte boundaries (each value is a 4 byte uint32), so consumers need not care about this header if it’s not using any information about the dongle.
The client may, during the course of the connection, send a Request to the server in order to adjust the settings of the remote device. Commonly, this is used to retune the device, change the sample rate, or adjust gain settings.
A full list of Commands, and the semantics of their Argument is detailed on the table below.
|0x01||Tune to a new center frequency||Frequency, in Hz as a uint32|
|0x02||Set the rate at which iq sample pairs are sent||Number of samples (real and imaginary) per second as a uint32|
|0x03||Set the tuner gain mode|
|0x04||Set the tuner gain level||Gain, in tenths of a dB|
|0x05||Set the tuner frequency correction||Frequency correction, in PPM (parts per million)|
|0x06||Set the IF gain level|
Two uint16 values, the least significant int16 (network byte order) is the gain value in tenths of a dB, and the most significant int16 is the gain stage.
|0x07||Put the tuner into test mode|
|0x08||Set the automatic gain correction, a software step to correct the incoming signal, this is not automatic gain control on the hardware chip, that is controlled by tuner gain mode.|
|0x09||Set direct sampling|
|0x0a||Set offset tuning (TODO: EXPLAIN)|
|0x0d||Set tuner gain by the tuner's gain index||Each tuner has a discrete set of supported gain values, which are returned in a sorted order via rtlsdr_get_tuner_gains. The argument here is treated as an index into the tuner gains for the specific tuner on the remote end, and will set the gain by index, rather than in tenths of a dB.|
|0x0e||Set Bias Tee on GPIO pin 0|