comm.SDRuTransmitter

Send data to USRP device

Description

The SDRuTransmitter System object™ sends data to a Universal Software Radio Peripheral (USRP™) hardware device, enabling simulation and development for various software-defined radio applications. The object enables communication with a USRP board on the same Ethernet subnetwork or a USRP board via a USB connection. You can write a MATLAB^® application that uses the System object, or you can generate code for the System object without connecting to a USRP radio.

This object accepts a column vector or matrix input signal from MATLAB and transmits signal and control data to a USRP board using the Universal Hardware Driver (UHD™) from Ettus Research™. The System object is a sink that sends the data it receives to a USRP board.

To send data from a USRP device:

1. Create the comm.SDRuTransmitter 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

tx = comm.SDRuTransmitter

tx = comm.SDRuTransmitter(address)

tx = comm.SDRuTransmitter(___,Name,Value)

Description

tx = comm.SDRuTransmitter creates a default SDRu transmitter System object.

tx = comm.SDRuTransmitter(address) sets the IPAddress property to address of the connected USRP device.

tx = comm.SDRuTransmitter(___,Name,Value) sets Properties using one or more name-value pairs in addition to any input argument combination from previous syntaxes. Enclose each property name in quotes. For example, 'CenterFrequency',5e6 specifies the center frequency as 5 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.

Platform — Model number of radio

'N200/N210/USRP2' (default) | 'N300' | 'N310' | 'N320/N321' | 'B200' | 'B210' | 'X300' | 'X310'

Model number of the radio, specified as one of these values.

• 'N200/N210/USRP2'

• 'N300'

• 'N310'

• 'N320/N321'

• 'B200'

• 'B210'

• 'X300'

• 'X310'

Data Types: char | string

IPAddress — IP address of USRP device

'192.168.10.2' (default) | dotted-quad character vector | dotted-quad string scalar

IP address of the USRP device, specified as a dotted-quad character vector or dotted-quad string scalar. When you specify more than one IP address, you must separate each address by commas or spaces.

This value must match the physical IP address of the radio hardware assigned during hardware setup. For more information, see Guided USRP Radio Support Package Hardware Setup. If you configure the radio hardware with an IP address other than the default, update this property accordingly.

To find the logical network location of all connected USRP radios, use the findsdru function.

Example: '192.168.10.2, 192.168.10.5' or '192.168.10.2 192.168.10.5' specifies IP addresses for two devices.

Dependencies

To enable this property, set Platform to 'N200/N210/USRP2', 'N300', 'N310', 'N320/N321', 'X300', or 'X310'.

Data Types: char | string

SerialNum — Serial number of radio

'' (default) | character vector | string scalar

Serial number of the radio hardware, specified as a character vector or string scalar.

This property must match the serial number of the radio hardware assigned during hardware setup. For more information, see Guided USRP Radio Support Package Hardware Setup. If you configure the radio hardware with a serial number other than the default, update this property accordingly.

Dependencies

To enable this property, set Platform to 'B200' or 'B210'.

Data Types: char | string

ChannelMapping — Channel mapping for radio or bundled radios

1 (default) | positive scalar | row vector of positive values

Channel mapping for the radio or bundled radios, specified as a positive scalar or a row vector of positive values. This table shows the valid values for various radio platforms.

Platform Property Value	ChannelMapping Property Value
'N200/N210/USRP2'	1-by-N row vector, where N is the number of IP addresses included in the IPAddress property
'N300'	When IPAddress includes one IP address, specify this property as 1, 2, or [1 2]. When IPAddress includes N IP addresses, specify this property as 1-by-2N row vector.
'N310'	When IPAddress includes one IP address, specify this property as 1-, 2-, 3-, or 4-element row vector of channel numbers from the set {1, 2, 3, 4} When IPAddress includes N IP addresses, specify this property as 1-by-4N row vector.
'N320/N321'	When IPAddress includes one IP address, specify this property as 1, 2, or [1 2]. When IPAddress includes N IP addresses, specify this property as 1-by-2N row vector.
'B200'	1
'B210'	1, 2, or [1 2]
'X300' or 'X310'	When the IPAddress property includes one IP address, specify this property as 1, 2, or [1 2]. When IPAddress includes N IP addresses, specify this property as 1-by-2N row vector, where N is the number of IP addresses included in IPAddress.

When IPAddress includes multiple IP addresses, the channels defined by ChannelMapping are ordered first by the order in which the IP addresses appear in the list and then by the channel order within the same radio.

Example: If Platform is 'X300' and IPAddress is '192.168.20.2, 192.168.10.3', then ChannelMapping must be [1 2 3 4]. Channels 1, 2, 3, and 4 of the bundled radio refer to channels 1 and 2 of the radio with IP address 192.168.20.2 and channels 1 and 2 of the radio with IP address 192.168.10.3.

Data Types: double

CenterFrequency — Center frequency

2.45e9 | nonnegative scalar | row vector of nonnegative values

Center frequency, specified as a nonnegative scalar or a row vector of nonnegative values. Units are in Hz. The valid range of values for this property depends on the RF daughter card of the USRP device.

To change the center frequency, specify the value according to these conditions.

• For a single channel (SISO), specify the value for the center frequency as a nonnegative scalar.

• For multiple channels (MIMO) that use the same center frequency, specify the center frequency as a nonnegative scalar. The center frequency is set by scalar expansion.

• For multiple channels (MIMO) that use different center frequencies, specify the values in a row vector (for example, [70e6 100e6]). The ith element of the vector is applied to the ith channel specified by the ChannelMapping property.

  Note

  • For MIMO scenario, the center frequency for B210 and N300 radios must be a scalar. You cannot specify the frequencies as a vector.

  • The channels corresponding to the same RF daughterboard of N310 must have the same center frequency value as each other.

Tunable: Yes

Data Types: double

LocalOscillatorOffset — Local oscillator (LO) offset frequency

0 | scalar | row vector

LO offset frequency, specified as a scalar or row vector. Units are in Hz. The valid range of this property depends on the RF daughterboard of the USRP device.

The LO offset does not affect the transmitted center frequency. However, it does affect the intermediate center frequency in the USRP hardware, as shown in this diagram.

In this diagram:

• f_center is the center frequency specified by the System object.

• f_{LO offset} is the local oscillator offset frequency.

To move the center frequency away from interference or harmonics generated by the USRP hardware, use this property.

To change the LO offset, specify the value according to these conditions.

• For a single channel (SISO), specify the LO offset as a scalar.

• For multiple channels (MIMO), the LO offset must be zero. This restriction is due to a UHD limitation. In this case, you can specify the LO offset as scalar (0) or as a vector ([0 0]).

Tunable: Yes

Data Types: double

Gain — Overall gain for USRP hardware transmitter data path

8 | scalar | row vector

Overall gain for the USRP hardware transmitter data path, including analog and digital components, specified as a scalar or row vector. Units are in dB. The valid range of this property depends on the RF daughterboard of the USRP device.

To change the gain, specify the value according to these conditions.

• For a single channel (SISO), specify the value for the gain as a scalar.

• For multiple channels (MIMO) that use the same gain value, specify the gain as a scalar. The gain is set by scalar expansion.

• For multiple channels (MIMO) that use different gains, specify the values in a row vector (for example, [32 30]). The ith element of the vector is applied to the ith channel specified by the ChannelMapping property.

Tunable: Yes

Data Types: double

PPSSource — PPS signal source

'Internal' (default) | 'External' | 'GPSDO'

Pulse per second (PPS) signal source, specified one of these values.

• 'Internal' — Use the internal PPS signal of the USRP radio.

• 'External' — Use the PPS signal from an external signal generator.

• 'GPSDO' — Use the PPS signal from a global positioning system disciplined oscillator (GPSDO).

To synchronize the time for all channels of the bundled radios, you can:

• Provide a common external PPS signal to all of the bundled radios and set this property to 'External'.

• Use the PPS signal from each GPSDO that is available on the USRP radio by setting this property to 'GPSDO'.

To get the lock status of the GPSDO to the GPS constellation, set this property to 'GPSDO' and use the gpsLockedStatus function.

Data Types: char | string

EnforceGPSTimeSync — Flag to enforce GPS time synchronization

false or 0 (default) | true or 1

Flag to enforce GPS time synchronization, specified as one of these numeric or logical values.

• 1 (true) — The USRP radio time is synchronized to the valid global positioning system (GPS) time if the GPSDO is locked to the GPS constellation at the beginning of the transmit or receive operation.

• 0 (false) — The USRP radio time is set to the GPSDO time if the GPSDO is not locked to the GPS constellation at the beginning of the transmit or receive operation.

The System object checks the lock status of the GPSDO each time you call the System object object. When the GPSDO is locked to the GPS constellation, the System object sets the USRP radio time to the valid GPS time.

Dependencies

To enable this property, set the PPSSource property to 'GPSDO'.

Data Types: logical

ClockSource — Clock source

'Internal' (default) | 'External' | 'GPSDO'

Clock source, specified as one of these values.

• 'Internal' — Use the internal clock signal of the USRP radio.

• 'External' — Use the 10 MHz clock signal from an external clock generator.

• 'GPSDO' — Use the 10-MHz clock signal from a GPSDO.

For B-series radios, the external clock port is labeled 10 MHz. For N3xx series, N2xx series, USRP2™, and X-series radios, the external clock port is labeled REF IN.

To synchronize the frequency for all channels of the bundled radios, you can:

• Provide a common external 10 MHz clock signal to all of the bundled radios and set this property to 'External'.

• Provide a 10 MHz clock signal from each GPSDO to the corresponding radio and set this property to 'GPSDO'.

To synchronize the frequency for all channels, set this property to 'GPSDO', and then verify that the outputs of the referenceLockedStatus and gpsLockedStatus functions are returned as 1.

Data Types: char | string

MasterClockRate — Master clock rate

positive scalar

Master clock rate, specified as a positive scalar. Units are in Hz. The master clock rate is the A/D and D/A clock rate. The valid range of values for this property depends on the connected radio platform.

Platform Property Value	MasterClockRate Property Value (in Hz)
'N200/N210/USRP2'	100e6 (read-only)
'N300' or 'N310'	122.88e6, 125e6(default), or 153.6e6
'N320/N321'	200e6(default), 245.76e6, or 250e6
'B200' or 'B210'	Value in the range from 5e6 to 61.44e6. When using B210 with multiple channels, the clock rate must be less than or equal to 30.72e6. This restriction is a hardware limitation for the B210 radios when you use two-channel operations. The default value is 32e6.
'X300' or 'X310'	184.32e6 or 200e6(default)

Dependencies

To enable this property, set Platform to 'B200', 'B210', 'N300', 'N310', 'N320/N321', 'X300', or 'X310'.

Data Types: double

InterpolationFactor — Interpolation factor for SDRu transmitter

512 (default) | integer from 1 to 1024

Interpolation factor for the SDRu transmitter, specified as an integer from 1 to 1024 with restrictions, based on the radio you use.

InterpolationFactor Property Value	B-Series	N2xx-Series	N3xx-Series	X-Series
1	Valid	Not valid	Valid	Valid
2	Valid	Acceptable when you use only the int8 transport data type	Valid	Valid
3	Valid	Not valid	Valid	Valid
Odd integer from 4 to 128	Valid	Valid	Not valid	Valid
Even integer from 4 to 128	Valid	Valid	Valid	Valid
Even integer from 128 to 256	Valid	Valid	Valid	Valid
Integer multiple of 4 from 256 to 512	Valid	Valid	Valid	Valid
Integer multiple of 8 from 512 to 1024	Not valid	Not valid	Valid	Not valid

The radio uses the interpolation factor when it upconverts the complex baseband signal to an intermediate frequency (IF) signal.

Data Types: double

TransportDataType — Transport data type

'int16' (default) | 'int8'

Transport data type, specified as one of these values:

• 'int16' — Use 16-bit transport to achieve higher precision.

• 'int8' — Use 8-bit transport to achieve an approximately two times faster transport data rate. The quantization step is 256 times larger than 16-bit transport.

The default transport data rate data type assigns the first 16 bits to the in-phase component and the latter 16 bits to the quadrature component, resulting in 32 bits for each complex sample of transport data.

Data Types: char | string

EnableBurstMode — Option to enable burst mode

0 or false (default) | 1 or true

Option to enable burst mode, specified as a numeric or logical value of 1 (true) or 0 (false). To produce a set of contiguous frames without an overrun or underrun to the radio, set this property to 1 (true). Enabling burst mode helps you simulate models that cannot run in real time.

When burst mode is enabled, specify the desired amount of contiguous data by using the NumFramesInBurst property. For more information, see Detect Underruns and Overruns.

Data Types: logical

NumFramesInBurst — Number of frames in contiguous burst

1 (default) | nonnegative integer

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

Dependencies

To enable this property, set EnableBurstMode to 1 (true).

Data Types: double

Usage

Syntax

tx(input)

underrun = tx(input)

Description

tx(input) sends data to a USRP device associated with the comm.SDRuTransmitter System object, tx.

underrun = tx(input) returns an integer value that indicates data discontinuity for given input data, input.

Note

Starting in R2016b, instead of using the step method to perform the operation defined by the System object, you can call the object with arguments, as if it were a function. For example, y = step(obj,x) and y = obj(x) perform equivalent operations.

Input Arguments

input — Input signal

complex column vector | complex matrix

Input signal sent to the USRP radio, specified as a complex column vector or complex matrix. The number of columns in the matrix depends on the number of channels in use, as specified by the ChannelMapping property. For a single channel radio, this input must be a column vector. For a multichannel radio, this input must be a matrix. Each column in this matrix corresponds to a channel of complex data sent on one channel.

The complex data type of the transmitted signal must be one of these data types:

• 16-bit signed integers — Complex values in the range of [–32768,32767]

• Single-precision floating point — Complex values in the range of [–1, 1]

• Double-precision floating point — Complex values in the range of [–1, 1]

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

Output Arguments

underrun — Data discontinuity flag

0 | 1

Data discontinuity flag, returned as an integer.

• When flag value is 0 — No underrun detected.

• When flag value is 1 — Underrun detected. The input data does not represent contiguous data from the host to the USRP radio.

Although the reported value does not represent the actual number of packets dropped, as this value increases, the farther your execution of the object is from achieving real-time performance. You can use this value as a diagnostic tool to determine real-time execution of the object. For more information, see Detect Underruns and Overruns.

Data Types: uint32

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

info	USRP radio information
referenceLockedStatus	Lock status of USRP radio to 10 MHz clock signal
gpsLockedStatus	Lock status of GPSDO to GPS constellation

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

Get B210 Radio Information

Use the info object function to get information from the connected B210 radio. The actual values used in the radio are shown by info and can vary slightly from the values specified in the object.

radio = comm.SDRuTransmitter('Platform','B210','SerialNum','31B92DD');
radio.CenterFrequency = 912.3456e6;
radio.LocalOscillatorOffset = 1000;
radio.Gain = 8.3;
radio.MasterClockRate = 10.56789e6;
radio.InterpolationFactor = 510;
info(radio)                   

ans = struct with fields:
                    Mboard: 'B210'
                  RXSubdev: 'FE-RX2'
                  TXSubdev: 'FE-TX2'
    MinimumCenterFrequency: 4.4716e+07
    MaximumCenterFrequency: 6.0053e+09
               MinimumGain: 0
               MaximumGain: 89.7500
                  GainStep: 0.2500
           CenterFrequency: 9.1235e+08
     LocalOscillatorOffset: -999.7189
                      Gain: 8.2500
           MasterClockRate: 1.0568e+07
       InterpolationFactor: 512
        BasebandSampleRate: 2.0640e+04

Transmit Signals with B210 Radio and SDRu Transmitter System Object

Configure a B210 radio with serial number set to '30F59A1'. Set the radio to transmit at 2.5 GHz with an interpolation factor of 256.

Create a SDRu Transmitter System object to use for data transmission.

tx = comm.SDRuTransmitter(...
              'Platform','B210', ...
              'SerialNum','30F59A1', ...
              'CenterFrequency',2.5e9, ...
              'InterpolationFactor',256);

Create a DPSK modulator as the data source using comm.DPSKModulator System object. Inside a for loop, transmit the data using the tx System object.

mod = comm.DPSKModulator('BitInput',true);
    for counter = 1:20
      data = randi([0 1],30,1);
      modSignal = mod(data);
      tx(modSignal);
    end

Detect Lost Samples using SDRuTransmitter System Object

Configure an B210 radio with serial number set to '30F59A1'. Set the radio to transmit at 2.5 GHz with an interpolation factor of 125 and master clock rate of 56 MHz.

Create a SDRu Transmitter System object to use for data transmission.

tx = comm.SDRuTransmitter(...
               'Platform','B210', ...
              'SerialNum','30F59A1', ...
              'CenterFrequency',2.5e9, ...
              'InterpolationFactor',125, ...
              'MasterClockRate', 56e6);

Create a DPSK modulator as the data source using comm.DPSKModulator System object.

modulator = comm.DPSKModulator('BitInput',true);

Inside a for loop, transmit the data using the tx System object and return underrun as an output argument. Display the messages when transmitter indicates underrun with data loss.

for frame = 1:20000
      data = randi([0 1], 30, 1);
      modSignal = modulator(data);
      underrun = tx(modSignal);
      if underrun~=0
          msg = ['Underrun detected in frame # ', int2str(frame)];
      end
end
    release(tx)

With SRDu transmitter System objects, the underrun output indicates data loss. This output is a useful diagnostic tool for determining real-time operation of the System object.

Burst-Mode Buffering to Overcome Underruns at Transmitter

Configure a B200 radio with serial number set to '30FD838'. Set the radio to transmit at 2.5 GHz with an interpolation factor of 125 and master clock rate of 56 MHz. Enable burst-mode buffering to overcome underruns. Set number of frames in a burst to 20.

Create a SDRu Transmitter System object to use for data transmission.

tx = comm.SDRuTransmitter(...
               'Platform','B200', ...
              'SerialNum','30FD838', ...
              'CenterFrequency',2.5e9, ...
              'InterpolationFactor',125, ...
              'MasterClockRate',56e6);
tx.EnableBurstMode = true;
tx.NumFramesInBurst = 20;

Create a DPSK modulator as the data source using comm.DPSKModulator System object.

modulator = comm.DPSKModulator('BitInput',true);
data = randi([0 1],37500,1);
modSignal = modulator(data);

Inside a for loop, transmit the data using the tx System object.

numFrames = 100;
for frame = 1:numFrames
    underrun = tx(modSignal);
end

no tx ack

release(tx)

Generate MEX Function from a MATLAB Function That Uses SDRu Transmitter System Object

This example generates a MEX file called sdruTransmitMex from the function sdruTransmitData. You can observe a speedup (in megasamples per second (MS/s)) with no underruns at 10000 samples per frame when you run the MEX file of this code.

Create a sdruTransmitData function that configures comm.SDRuTransmitter System object. Generate a sine wave of 100 kHz for transmission. The sample rate is calculated from the master clock rate and interpolation factor. Set the frame duration for the sine wave to transmit based on the samples per frame and sample rate. Display the message when transmission starts. Inside a for loop, transmit the data using the tx System object and return underrun as an output argument.

function[transmitTime,underrunCount] = sdruTransmitData()
       Duration = 10;
       SamplesPerFrame = 1e4;
       MasterClockRate = 20e6;
       InterpolationFactor = 1;
 
       SampleRate = masterClockRate/interp;
       FrameDuration = SamplesPerFrame/SampleRate;
       Iterations = Duration/FrameDuration;

       sinGen = dsp.SineWave('Frequency',100e3,'SampleRate',SampleRate, ...
                       'SamplesPerFrame',SamplesPerFrame, ...
                       'ComplexOutput',true);
       data = sinGen();
       tx = comm.SDRuTransmitter('Platform','B210','SerialNum','30F59A1', ...
                          'CenterFrequency',2.45e9, ...
                          'MasterClockRate',MasterClockRate, ...
                          'InterpolationFactor',InterpolationFactor);
       tx(data);
       disp('Started Transmission...');
       underrunCount = 0;
       tic
       for i = 1:Iterations
           underrun = tx(data);
           if underrun
              underrunCount = underrunCount+1;
           end
       end
       transmitTime = toc;
       release(tx);
end

Run this command to generate a MEX file called sdruTransmitMex from the function sdruTransmitData.

codegen sdruTransmitData -o sdruTransmitMex;

Run this MEX file to transmit data using the generated MEX, and observe the transmission time and number of underruns.

[transmitTime,underrunCount] = sdruTransmitMex()

More About

Single and Multiple Channel Output

• N200, N210, USRP2, and B200 radios support a single channel that you can use to:

  • Send data with the comm.SDRuTransmitter System object . The comm.SDRuTransmitter System object receives a column vector signal of fixed length.

  • Receive data with the comm.SDRuReceiver System object. The comm.SDRuReceiver System object outputs a column vector signal of fixed length.

• B210, X300, X310, N300, N320 and N321 radios support two channels that you can use to transmit and receive data with System objects. You can use both channels or only a single channel (either channel 1 or 2).

  • The comm.SDRuTransmitter System object receives a matrix signal, where each column is a channel of data of fixed length.

  • The comm.SDRuReceiver System object outputs a matrix signal, where each column is a channel of data of fixed length.

    Note

    When two TwinRX daughterboards are connected to X300 or X310 radio, the radio supports up to four channel reception.

• N310 radio support four channels that you can use to transmit and receive data with System objects. You can use up to four channels.

  • The comm.SDRuTransmitter System object receives a matrix signal, where each column is a channel of data of fixed length.

  • The comm.SDRuReceiver System object outputs a matrix signal, where each column is a channel of data of fixed length.

You can set the CenterFrequency, LocalOsillatorOffset, and Gain properties independently for each channel. Alternatively, you can apply the same setting to all channels. All other System object property values apply to all channels.

For more information, see Single Channel Input and Output Operations and Multiple Channel Input and Output Operations.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

For more information on codegen support to the System objects, see System Objects in MATLAB Code Generation (MATLAB Coder).

For more information on MATLAB Compiler™ support to the System objects, see Code Generation and Deployment

Version History

Introduced in R2011b

R2022b: Reduced setup time for comm.SDRuTransmitter

The time required to initialize the comm.SDRuTransmitter System Object™ is now about 17 seconds faster for B2xx and N3xx radios and about 30 seconds faster for N210 and X3xx radios compared to the R2022a release.

Simulation performance results for comm.SDRuTransmitter System Object:

Case 1:

• Platform: B210

• Frame time: 0.001 s

Release	Time Required to Set Center Frequency (s)	Time Required to Set Gain (s)	Time Required to Run System Object (s)	Total Time Required to Set Properties and Call System Object (s)
R2022a	9.108438	9.084412	8.614395	~26.8
R2022b	0.002963	0.003463	8.705884	~8.71

Case 2:

• Platform: X310

• Frame time: 0.001 s

Release	Time Required to Set Center Frequency (s)	Time Required to Set Gain (s)	Time Required to Run System Object (s)	Total Time Required to Set Properties and Call System Object (s)
R2022a	13.958173	13.793633	15.975323	~43.73
R2022b	0.004808	0.001146	15.446236	~15.45

The code execution was timed on a Windows^® 10, Intel^® Xeon^® W-2133 CPU @ 3.60 GHz installed RAM 64.0 GB test system.

R2020a: X3xx series radios no longer support 120 MHz master clock rate

Beginning with Ettus Research UHD version 003.014.000.000, X3xx series radios do not support a master clock rate value of 120 MHz. Consequently, starting in R2020a, which supports UHD version 003.015.000.000, Communications Toolbox™ Support Package for USRP Radio does not support a master clock rate value of 120 MHz for X3xx series radios.

For the comm.SDRuTransmitter and comm.SDRuReceiver System objects, when you specify an X3xx series radio for the Platform property, you can no longer set the MasterClockRate property to 120e6.