comm.SDRRTLReceiver

Receive data from RTL-SDR device

Description

A comm.SDRRTLReceiver System object™ supports communication between MATLAB^® and an RTL-SDR device, allowing simulation and development of various software-defined radio (SDR) applications. Although comm.SDRRTLReceiver receives data from an RTL-SDR device, the object acts as a signal source that outputs a column vector signal of fixed length.

Connect an RTL-SDR device to a USB port on the host computer, then to receive RTL-SDR device data:

1. Create the comm.SDRRTLReceiver object and set its properties.

2. Call the object as if it were a function.

To learn more about how System objects work, see What Are System Objects?.

Creation

Syntax

rx = comm.SDRRTLReceiver

rx = comm.SDRRTLReceiver(Name,Value)

rx = comm.SDRRTLReceiver(RadioAddress,Name,Value)

Description

rx = comm.SDRRTLReceiver creates an RTL-SDR receiver System object that receives data from the RTL-SDR device.

rx = comm.SDRRTLReceiver(Name,Value) creates an RTL-SDR receiver object with the specified property Name set to the specified Value. You can specify additional name-value pair arguments in any order as (Name1,Value1,...,NameN,ValueN).

Example: comm.SDRRTLReceiver('CenterFrequency',88.9e6) tunes the radio receiver to a center frequency of 88.9 MHz.

rx = comm.SDRRTLReceiver(RadioAddress,Name,Value) creates an RTL-SDR receiver System object, where RadioAddress is a character vector containing a nonnegative integer that refers to the USB ID of the RTL-SDR device, and name-value pair arguments that set additional specified properties.

Properties

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

RadioAddress — USB address of RTL-SDR device

'0' (default) | character vector

USB address of the RTL-SDR device you want to communicate with, specified as a character vector representing a nonnegative integer. Use the sdrinfo function to discover which radios are connected to your computer.

USB Port Address Assignment

The assignment of USB port addresses is not intuitive. If a device is plugged into the first USB port, it is always at address 0. However, if a device is plugged into any port after the first one, the address varies depending on whether a device is plugged into any of the previous ports.

This diagram shows how the USB port addresses are assigned when devices are added and then removed in first in, first out (FIFO) order.

The following diagram shows how the USB port addresses are assigned when devices are added and then removed from port 0. Note that the radio address for the second RTL device changes based on whether the first port has a device in it. To access a radio with the correct radio address, you must keep track of the plugged-in devices in order.

Data Types: char

CenterFrequency — Desired center frequency in Hz

102.5e6 (default) | positive scalar

Desired center frequency in Hz, specified as a positive scalar. The valid range of this property depends on the tuner chip of the RTL-SDR device. For a list of tuner chips and their frequency ranges, see [1].

Tunable: Yes

Data Types: double

EnableTunerAGC — Enable automatic gain control (AGC) of tunner

true (default) | false

Enable automatic gain control (AGC) of the tuner, specified as true to turn on AGC or false to turn off AGC.

Tunable: Yes

Data Types: logical

TunerGain — Desired tuner gain in dB

0 (default) | scalar

Desired tuner gain in dB, specified as a scalar. The valid range of this property depends on the tuner chip of the RTL-SDR device. Use the comm.SDRRTLReceiver.info function to get valid values.

Tunable: Yes

Dependencies

To enable this property, set EnableTunerAGC to false.

Data Types: double

SampleRate — Desired ADC sample rate in Hz

250e3 (default) | positive scalar

Desired ADC sample rate in Hz, specified as a positive scalar. The valid ranges are 225–300 kHz and 900–3200 kHz. A SampleRate setting above 2560 kHz can result in lost samples. For more information about maximum reliable sample rate, see [1].

Data Types: double

OutputDataType — Data type of output

'int16' (default) | 'double' | 'single'

Data type of output, specified as 'int16', 'double', or 'single'. When you select the 'double' or 'single' data type, the complex values are scaled to the range of [–1,1]. When you select 'int16', the complex values are the raw 16-bit I and Q samples from the device.

Data Types: char

SamplesPerFrame — Number of samples per frame

1024 (default) | positive integer

Number of samples per frame, specified as a positive integer. See Blocking Behavior.

Data Types: double

FrequencyCorrection — Frequency correction value in ppm

0 (default) | scalar from -1e4 to 1e4

Frequency correction value in ppm, specified as a scalar from -1e4 to 1e4. This property value corrects frequency shift in received data due to local oscillator frequency offset or clock rate inaccuracy.

Tunable: Yes

Data Types: double

EnableBurstMode — Enable burst mode

true (default) | false

Enable burst mode, specified as true to turn on burst mode or false to turn off burst mode.

Data Types: logical

NumFramesInBurst — Number of frames in contiguous burst

10 (default) | positive integer

Number of frames in a contiguous burst, specified as a scalar.

Dependencies

This property is available when EnableBurstMode is set to true.

Data Types: double

Usage

Syntax

rxdata = sdrrx()

[rxdata,len] = sdrrx()

[rxdata,len,lost] = sdrrx()

[rxdata,len,lost,late] = sdrrx()

Description

rxdata = sdrrx() receives signal and control data from an RTL-SDR device, as represented by a comm.SDRRTLReceiver System object. Data from the SDR device is expected to be complex 16-bit signed integer values from –128 to 128. The output data type is specified by OutputDataType.

After the sdrrx object receives SamplesPerFrames samples, it outputs a column vector of complex values. See Blocking Behavior.

[rxdata,len] = sdrrx() returns optional len output, which is the number of valid samples in rxdata

[rxdata,len,lost] = sdrrx() returns optional lost output, which is the number of lost samples.

[rxdata,len,lost,late] = sdrrx() returns optional late output, which is the latency of the received data in frames.

Output Arguments

rxdata — Received data

vector of complex int16 values (default) | vector of complex single-precision values | vector of complex double-precision values

Received data, returned as one of these values.

• 16-bit signed integers — The complex values are the raw 16-bit I and Q samples from the RTL-SDR device.

• Single-precision floating point — The complex values are scaled to the range of [–1, 1].

• Double-precision floating point — The complex values are scaled to the range of [–1, 1].

To specify the base type, use the OutputDataType property.

Data Types: int16 | single | double
Complex Number Support: Yes

len — Number of valid samples

nonnegative integer

Number of valid samples, returned as a nonnegative integer. len is 0 if no valid samples were returned from the radio.

lost — Number of lost samples

nonnegative integer

Number of lost samples, returned as a nonnegative integer. lost is 0 if no samples were lost. If your model runs in real-time, the lost samples output is always zero. This output is a useful diagnostic tool for determining real time operation of the block. See Real Time Operation.

late — Latency of the received data in frames

nonnegative integer

Latency of the received data in frames, returned as a nonnegative integer. late ≤ 1 if the received frames of data have no latency. Even when your model runs in real-time, received signals may experience latency. This output is a useful diagnostic tool for determining real time operation of the block. See Real Time Operation.

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

Specific to comm.SDRRTLReceiver

info	Characteristic information of RTL-SDR receiver device

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
reset	Reset internal states of System object

Examples

Receive Streaming RTL-SDR Data

Receive streaming data from an RTL-SDR device.

Create and initialize an RTL-SDR receiver object. Inspect the object properties.

rxsdr = comm.SDRRTLReceiver('0','CenterFrequency',88.9e6,'SampleRate',250000, ...
    'SamplesPerFrame',2048,'EnableTunerAGC',true,'OutputDataType','double')

rxsdr = 
  comm.SDRRTLReceiver with properties:

           RadioAddress: '0'
        CenterFrequency: 88900000
         EnableTunerAGC: true
             SampleRate: 250000
         OutputDataType: 'double'
        SamplesPerFrame: 2048
    FrequencyCorrection: 0
        EnableBurstMode: false

radioInfo = info(rxsdr)

radioInfo = 
    The following values show radio settings, not the property 
    values of RTL-SDR receiver System object. For more information, 
    type 'help comm.SDRRTLReceiver'.

                RadioName: 'Generic RTL2832U OEM'
             RadioAddress: '0'
                TunerName: 'R820T'
             Manufacturer: 'Realtek'
                  Product: 'RTL2838UHIDIR'
               GainValues: [0 0.9000 1.4000 2.7000 3.7000 7.7000 8.7000 12.5000 14.4000 15.7000 16.6000 19.7000 20.7000 22.9000 25.4000 28 29.7000 32.8000 33.8000 36.4000 37.2000 38.6000 40.2000 42.1000 43.4000 43.9000 44.5000 48 49.6000]
      RTLCrystalFrequency: 28800000
    TunerCrystalFrequency: 28800000
             SamplingMode: 'Quadrature'
             OffsetTuning: 'Disabled'
          CenterFrequency: 88900000
               SampleRate: 250000
      FrequencyCorrection: 0

Stream data from the device. Release the object when finished using it.

for p=1:1000
    rxdata = rxsdr();
end
release(rxsdr)

Receive Streaming RTL-SDR Data on Two Frequencies

Receive streaming data from an RTL-SDR device at one frequency then change the frequency and stream more data from the device.

Create and initialize an RTL-SDR receiver object. Inspect the object properties.

rxsdr = comm.SDRRTLReceiver('0','CenterFrequency',88.9e6,'SampleRate',250000, ...
    'SamplesPerFrame',2048,'EnableTunerAGC',true,'OutputDataType','double')

rxsdr = 
  comm.SDRRTLReceiver with properties:

           RadioAddress: '0'
        CenterFrequency: 88900000
         EnableTunerAGC: true
             SampleRate: 250000
         OutputDataType: 'double'
        SamplesPerFrame: 2048
    FrequencyCorrection: 0
        EnableBurstMode: false

radioInfo = info(rxsdr)

radioInfo = 
    The following values show radio settings, not the property 
    values of RTL-SDR receiver System object. For more information, 
    type 'help comm.SDRRTLReceiver'.

                RadioName: 'Generic RTL2832U OEM'
             RadioAddress: '0'
                TunerName: 'R820T'
             Manufacturer: 'Realtek'
                  Product: 'RTL2838UHIDIR'
               GainValues: [0 0.9000 1.4000 2.7000 3.7000 7.7000 8.7000 12.5000 14.4000 15.7000 16.6000 19.7000 20.7000 22.9000 25.4000 28 29.7000 32.8000 33.8000 36.4000 37.2000 38.6000 40.2000 42.1000 43.4000 43.9000 44.5000 48 49.6000]
      RTLCrystalFrequency: 28800000
    TunerCrystalFrequency: 28800000
             SamplingMode: 'Quadrature'
             OffsetTuning: 'Disabled'
          CenterFrequency: 88900000
               SampleRate: 250000
      FrequencyCorrection: 0

Stream data from the device.

for p=1:1000
    rxdata = rxsdr();
end

Change the tuner frequency and stream more data. The CenterFrequency property is tunable, so you can change the frequency for the RTL-SDR without releasing the object.

rxsdr.CenterFrequency = 103.1e6;
radioInfo = info(rxsdr)

radioInfo = 
    The following values show radio settings, not the property 
    values of RTL-SDR receiver System object. For more information, 
    type 'help comm.SDRRTLReceiver'.

                RadioName: 'Generic RTL2832U OEM'
             RadioAddress: '0'
                TunerName: 'R820T'
             Manufacturer: 'Realtek'
                  Product: 'RTL2838UHIDIR'
               GainValues: [0 0.9000 1.4000 2.7000 3.7000 7.7000 8.7000 12.5000 14.4000 15.7000 16.6000 19.7000 20.7000 22.9000 25.4000 28 29.7000 32.8000 33.8000 36.4000 37.2000 38.6000 40.2000 42.1000 43.4000 43.9000 44.5000 48 49.6000]
      RTLCrystalFrequency: 28800000
    TunerCrystalFrequency: 28800000
             SamplingMode: 'Quadrature'
             OffsetTuning: 'Disabled'
          CenterFrequency: 103100000
               SampleRate: 250000
      FrequencyCorrection: 0

for p=1:1000
    rxdata = rxsdr();
end

Release the object when you are finished working with it.

release(rxsdr)

Check RTL-SDR Frame Loss and Latency

Check for loss of receiver data samples and the latency of data received from an RTL-SDR device.

Create and initialize an RTL-SDR receiver object. Inspect the object properties.

rxsdr = comm.SDRRTLReceiver('0','CenterFrequency',102.5e6,'SampleRate',250000, ...
    'SamplesPerFrame',2048,'EnableTunerAGC',true)

rxsdr = 
  comm.SDRRTLReceiver with properties:

           RadioAddress: '0'
        CenterFrequency: 102500000
         EnableTunerAGC: true
             SampleRate: 250000
         OutputDataType: 'int16'
        SamplesPerFrame: 2048
    FrequencyCorrection: 0
        EnableBurstMode: false

Inject a dummy processing time into the system using the pause function. Stream signal data from the device. Inspect the third and fourth return values to check for lost frames and for latency of the received data. For efficiency, preallocate uint32 variables for lost and latency. When finished working with the radio, release the object connected to it.

lost = uint32(zeros(100,1));
latency = uint32(zeros(100,1));
frameTime = rxsdr.SamplesPerFrame/rxsdr.SampleRate;
processingTime = frameTime * 4;
for p=1:100
    [x, ~, lost(p), latency(p)] = rxsdr();
    pause(processingTime);
end
release(rxsdr)

Generate plots to show data loss and latency in frames. The RTL-SDR receiver object has a buffer that can hold 128 frames. As the plot indicates, when the cumulative latency reaches 128, data is lost because RTL-SDR device buffer is overflowing.

subplot(211)
numLostFrames = lost/rxsdr.SamplesPerFrame;
ax = plotyy(1:100, latency, 1:100, numLostFrames);
grid on
xlabel('Frame Number')
ylabel(ax(1), 'Latency in Frames')
ylabel(ax(2), 'Lost Frames')
subplot(212)
plot(processingTime*ones(1,100))
hold on
plot(frameTime*ones(1,100))
grid on
xlabel('Frame Number')
ylabel('Time (s)')
legend('Processing time', 'Frame time')
hold off

Check RTL-SDR Data Latency with Varying Processing Time

Check the latency of RTL-SDR receiver data frames when the processing time varies as a sawtooth pattern.

Create and initialize an RTL-SDR receiver object. Inspect the object properties.

rxsdr = comm.SDRRTLReceiver('0','CenterFrequency',102.5e6,'SampleRate',250000, ...
    'SamplesPerFrame',2048,'EnableTunerAGC',true)

rxsdr = 
  comm.SDRRTLReceiver with properties:

           RadioAddress: '0'
        CenterFrequency: 102500000
         EnableTunerAGC: true
             SampleRate: 250000
         OutputDataType: 'int16'
        SamplesPerFrame: 2048
    FrequencyCorrection: 0
        EnableBurstMode: false

Simulate data processing time, using the pause function to inject a dummy processing time into the system that emulates a sawtooth pattern. Stream signal data from the device. Inspect the fourth return value to check for latency of the received data. For efficiency, preallocate a uint32 variable for latency. When finished working with the radio, release the object connected to it.

latency = uint32(zeros(100,1));
frameTime = rxsdr.SamplesPerFrame/rxsdr.SampleRate;
processingTimeStep = 0.1 * frameTime;
for p=1:100
    [x, ~, ~, latency(p)] = rxsdr();
    pause(processingTimeStep * mod(p,15));
end
release(rxsdr)

Generate plots to show received data latency in frames. As the plots indicate, the latency remains at one frame until the processing time exceeds the frame time. The system recovers a few frames after the processing time drops below the frame time.

subplot(211)
plot(latency)
grid on
xlabel('Frame Number')
ylabel('Latency in Frames')
subplot(212)
plot(processingTimeStep * mod(1:100,15))
hold on
plot(frameTime * ones(1,100))
grid on
xlabel('Frame Number')
ylabel('Time (s)')
legend('Processing time', 'Frame time')
hold off

More About

Blocking Behavior

The comm.SDRRTLReceiver System object waits until it receives the number of samples per frame specified by SamplesPerFrame before it returns processing control to the simulation.

References

[1] SDR (Software Defined Radio), https://osmocom.org/projects/sdr/wiki/rtl-sdr#Specifications