comm.SDRRTLReceiver

Receive data from RTL-SDR device

Add-On Required: This feature requires the Communications Toolbox Support Package for RTL-SDR Radio add-on.

Description

The comm.SDRRTLReceiver System object™ supports communication between MATLAB^® and an RTL-SDR device, enabling 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.

To receive data from an RTL-SDR device:

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(RadioAddress)

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

Description

rx = comm.SDRRTLReceiver creates a default RTL-SDR receiver System object.

rx = comm.SDRRTLReceiver(RadioAddress) sets the RadioAddress property to the USB address of the connected RTL-SDR device.

rx = comm.SDRRTLReceiver(___,Name,Value) sets Properties using one or more name-value arguments in addition to any argument combinations in previous syntaxes. For example,'CenterFrequency',88.9e6 specifies a center frequency of 88.9 MHz.

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 | string scalar

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

USB Port Address Assignment

The assignment of USB port addresses can be counterintuitive. If an RTL-SDR device is plugged into the first USB port, it is at address 0. However, if an RTL-SDR 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 figure shows how the USB port addresses are assigned when devices are added and then removed in first in, first out (FIFO) order.

This figure shows how the USB port addresses are assigned when devices are added and then removed from port 0. The radio address for the second RTL-SDR device changes based on whether the first port has an RTL-SDR 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 — Center frequency

102.5e6 (default) | positive scalar

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 AGC of tuner

false or 0 (default) | true or 1

Enable automatic gain control (AGC) of the tuner, specified as one of these numeric or logical values.

• 0 (false) — Turn off AGC.

• 1 (true) — Turn on AGC.

Tunable: Yes

Data Types: logical | numeric

TunerGain — Tuner gain

0 (default) | scalar

Tuner gain in dB, specified as a scalar. The valid range of this property depends on the tuner chip of the RTL-SDR device. To get valid gain values, use the info function.

Tunable: Yes

Dependencies

To enable this property, set the EnableTunerAGC property to false.

Data Types: double

SampleRate — ADC sample rate

250e3 (default) | positive scalar

Analog-to-digital converter (ADC) sample rate in Hz, specified as a positive scalar. The valid range of sample rates are [225, 300] kHz and [900, 3200] in kHz. If you set the SampleRate property greater than 2560 kHz, you might observe dropped samples. For more information about the maximum reliable sample rate, see [1].

Data Types: double

OutputDataType — Data type of output

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

Data type of output, specified as one of these values.

• 'double' or 'single' — The complex values are scaled to the range of [–1, 1].

• 'int16' — The complex values are the raw 16 bit quadrature (I and Q) samples from the RTL-SDR device.

Data Types: char | string

SamplesPerFrame — Number of samples per frame

1024 (default) | positive integer

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

Data Types: double

FrequencyCorrection — Frequency correction

0 (default) | integer from –1e4 to 1e4

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

Tunable: Yes

Data Types: double

EnableBurstMode — Option for burst mode

false or 0 (default) | true or 1

Option for burst mode, specified as one of these numeric or logical values.

• 0 (false) — Disable burst mode.

• 1 (true) — Enable burst mode. To produce a set of contiguous frames without an overflow to the RTL-SDR device, set this property to true. Enabling burst mode can help you simulate models that cannot run in real time. When you enable burst mode, specify the desired amount of contiguous data by using the NumFramesInBurst property and the SamplesPerFrame property.

Data Types: logical | numeric

NumFramesInBurst — Number of frames in burst

10 (default) | positive integer

Number of frames in a contiguous burst, specified as a positive integer.

Dependencies

To enable this property, set the EnableBurstMode property to true.

Data Types: double

Usage

Syntax

output = rx()

[output,len] = rx()

[output,len,lost] = rx()

[output,len,lost,late] = rx()

Description

output = rx() receives data from an RTL-SDR device associated with the comm.SDRRTLReceiver System object, rx.

[output,len] = rx() returns len, which indicates whether the object receives valid data from the RTL-SDR device.

[output,len,lost] = rx() returns lost, which indicates the number of lost samples.

[output,len,lost,late] = rx() also returns late, which indicates the latency of the received data in frames.

Output Arguments

output — Received data from RTL-SDR device

column vector of complex int16 values | column vector of complex single-precision values | column vector of complex double-precision values

Received data from an RTL-SDR device, returned as one of these values.

• Column vector of complex int16 values — The complex values are the raw 16 bit I and Q samples from the RTL-SDR device.

• Column vector of complex single-precision values — The complex values are scaled to the range of [–1, 1].

• Column vector of complex double-precision values — 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. When the RTL-SDR device returns no valid samples, len is 0.

lost — Number of lost samples

nonnegative integer

Number of lost samples, returned as a nonnegative integer. When the RTL-SDR device reports no lost samples, lost is 0. If your model runs in real time, lost is 0. You can use this output value as a diagnostic tool to determine real-time execution of the object. For more information on real-time operation, see Real-Time Operation.

late — Latency of received data in frames

nonnegative integer

Latency of the received data in frames, returned as a nonnegative integer. When the received frames of data have no latency, late is less than or equal to 1. Even when your model runs in real time, received signals can experience latency. You can use this output value as a diagnostic tool to determine real-time execution of the object. For more information on real-time operation, 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 device
capture	Capture RF signal data using RTL-SDR radio

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

Before the comm.SDRRTLReceiver System object returns processing control to the simulation, the object waits unit it receives the number of samples per frame specified by the SamplesPerFrame property.

MATLAB Compiler Support

For RTL-SDR MATLAB Compiler™ support, see Create MATLAB Function Using RTL-SDR System Object.

References

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

Version History

Introduced in R2014a