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:

Create the comm.SDRRTLReceiver object and set its properties.
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.

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.

example

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.

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

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

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

example

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

example

Output Arguments

expand all

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

expand all

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

collapse all

Receive Streaming RTL-SDR Data

This example uses:

Communications Toolbox Support Package for RTL-SDR Radio Communications Toolbox Support Package for RTL-SDR Radio

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)

Receive Streaming RTL-SDR Data on Two Frequencies

This example uses:

Communications Toolbox Support Package for RTL-SDR Radio Communications Toolbox Support Package for RTL-SDR Radio

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)

Check RTL-SDR Frame Loss and Latency

This example uses:

Communications Toolbox Support Package for RTL-SDR Radio Communications Toolbox Support Package for RTL-SDR Radio

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

Check RTL-SDR Data Latency with Varying Processing Time

This example uses:

Communications Toolbox Support Package for RTL-SDR Radio Communications Toolbox Support Package for RTL-SDR Radio

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

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.

References

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

Version History

Introduced in R2014a

comm.SDRRTLReceiver

Description

Creation

Syntax

Description

Properties

RadioAddress — USB address of RTL-SDR device '0' (default) | character vector | string scalar

CenterFrequency — Center frequency 102.5e6 (default) | positive scalar

EnableTunerAGC — Enable AGC of tuner false or 0 (default) | true or 1

TunerGain — Tuner gain 0 (default) | scalar

Dependencies

SampleRate — ADC sample rate 250e3 (default) | positive scalar

OutputDataType — Data type of output 'int16' (default) | 'double' | 'single'

SamplesPerFrame — Number of samples per frame 1024 (default) | positive integer

FrequencyCorrection — Frequency correction 0 (default) | integer from –1e4 to 1e4

EnableBurstMode — Option for burst mode false or 0 (default) | true or 1

NumFramesInBurst — Number of frames in burst 10 (default) | positive integer

Dependencies

Usage

Syntax

Description

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

len — Number of valid samples nonnegative integer

lost — Number of lost samples nonnegative integer

late — Latency of received data in frames nonnegative integer

Object Functions

Specific to comm.SDRRTLReceiver

Common to All System Objects

Examples

Receive Streaming RTL-SDR Data

Receive Streaming RTL-SDR Data on Two Frequencies

Check RTL-SDR Frame Loss and Latency

Check RTL-SDR Data Latency with Varying Processing Time

More About

Blocking Behavior

References

Version History

See Also

Blocks

Topics

`RadioAddress` — USB address of RTL-SDR device
`'0'` (default) | character vector | string scalar

`CenterFrequency` — Center frequency
`102.5e6` (default) | positive scalar

`EnableTunerAGC` — Enable AGC of tuner
`false` or `0` (default) | `true` or `1`

`TunerGain` — Tuner gain
`0` (default) | scalar

`SampleRate` — ADC sample rate
`250e3` (default) | positive scalar

`OutputDataType` — Data type of output
`'int16'` (default) | `'double'` | `'single'`

`SamplesPerFrame` — Number of samples per frame
`1024` (default) | positive integer

`FrequencyCorrection` — Frequency correction
`0` (default) | integer from –1e4 to 1e4

`EnableBurstMode` — Option for burst mode
`false` or `0` (default) | `true` or `1`

`NumFramesInBurst` — Number of frames in burst
`10` (default) | positive integer

`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

`len` — Number of valid samples
nonnegative integer

`lost` — Number of lost samples
nonnegative integer

`late` — Latency of received data in frames
nonnegative integer

Specific to `comm.SDRRTLReceiver`