Main Content

comm.SDRRTLReceiver

Receive data from RTL-SDR device

expand all in page

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.

example

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

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

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

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

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

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

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

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

Data Types: double

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

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

Data Types: logical

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.

example

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

example

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

Output Arguments

expand all

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

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

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.

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)

expand all

infoCharacteristic information of RTL-SDR receiver device
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

Open Live Script

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)
Open Live Script

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)
Open Live Script

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

Open Live Script

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

See Also

Blocks

Topics

Introduced in R2014a

Communications Toolbox Support Package for RTL-SDR Radio Documentation

Support

Bridging Wireless Communications Design and Testing with MATLAB

Bridging Wireless Communications Design and Testing with MATLAB

Download white paper