Main Content

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

Description

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

example

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

example

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

expand all

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.

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.

USB port address assignment for multiple radios is done in FIFO manner.

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.

USB port address assignment for multiple radios. To access a radio with the correct radio address, you must keep track of the plugged-in devices in order.

Data Types: char

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

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

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

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

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

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

Data Types: double

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

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

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

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.

example

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

example

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

Output Arguments

expand all

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

Number of valid samples, returned as a nonnegative integer. When the RTL-SDR device returns no valid samples, len is 0.

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.

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)

expand all

infoCharacteristic information of RTL-SDR device
captureCapture RF signal data using RTL-SDR radio
stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object

Examples

collapse all

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

expand all

References

Version History

Introduced in R2014a