Main Content

capture

Capture contiguous RF data using USRP embedded series radio hardware

Since R2019b

Add-On Required: This feature requires the Communications Toolbox Support Package for USRP Embedded Series Radio add-on.

Description

[data,mdata] = capture(rx,length) captures ceil(length) number of contiguous data samples using the USRP™ embedded series radio hardware associated with the rx receiver System object™. The function returns the captured data samples in the output data. The function also returns capture-time configuration settings for the radio device in the output mdata.

[data,mdata] = capture(rx,length,unit) specifies the unit value for the capture length. The function converts length units into N samples and returns ceil(N) number of samples.

example

[data,mdata,fn] = capture(___,'Filename',filename) specifies a file name for the captured data in addition to the input arguments in any of the previous syntaxes. The function saves the captured data and metadata to a baseband file reader file named fn.

[data,mdata,fn] = capture(___,'Filename',filename,Name,Value) specifies options using one or more name-value pair arguments. For example, 'UserMetadata',moreInfo adds the moreInfo structure defined in the workspace to the mdata output. Specify name-value pair arguments after all other input arguments.

Examples

collapse all

Record RF signals for post-capture processing in MATLAB®. Save an FM broadcast signal to a file as baseband samples. Read the file containing the recorded signal and demodulate the baseband samples.

Configure SDR Hardware

If your radio hardware is already configured for host-radio communication, skip this section. To configure your radio hardware for host-radio communication, follow the steps in the Guided Host-Radio Hardware Setup. Attach an antenna suitable for the 88–108 MHz band to the first RX channel.

Configure Receiver System Object

Create a receiver System object with the specified properties. The specified center frequency corresponds to a local FM station.

stationCenterFrequency = 95e6;
deviceName = 'E3xx';
rx = sdrrx(deviceName,'BasebandSampleRate',528e3,...
    'CenterFrequency',stationCenterFrequency,'OutputDataType','Double');

Initiate Data Capture to File

Call the capture function, specifying the receiver object, a capture duration, and a file name. The function returns the captured data in a file named "FMRecording.bb". After capturing the FM signal, unlock the receiver object by using the release function.

capture(rx,5,'Seconds','Filename','FMRecording.bb');
## Establishing connection to hardware. This process can take several seconds.
release(rx);

Demodulate FM Recording

Create a comm.BasebandFileReader System object to read the captured signal and extract frames of data from the file. Set the baseband file reader to take 4400 samples per frame when reading the saved baseband signal.

bbr = comm.BasebandFileReader('FMRecording.bb');
bbr.SamplesPerFrame = 4400;

Use the BasebandSampleRate field of the baseband file reader object to set the SampleRate property of the demodulator. You can find the BasebandSampleRate field in the MetaData structure. Create a comm.FMBroadcastDemodulator System object. Demodulate and play back each frame of the FM data. Use a while loop to read all frames of the captured data.

fmbDemod = comm.FMBroadcastDemodulator( ...
    'AudioSampleRate', 48e3, ...
    'SampleRate',bbr.Metadata.BasebandSampleRate,'PlaySound',true);

while ~isDone(bbr)
    fmbDemod(bbr());
end

Input Arguments

collapse all

Receiver, specified as a comm.SDRRxE3xx receiver System object. To create this object, use the sdrrx function.

Capture duration, specified as a numeric scalar. The input argument unit specifies the unit of length. The default unit is samples of data. The maximum number of samples to capture is in the range [1, 16,777,216]. You can remove the limit on the maximum number of samples to capture at the cost of guaranteed data contiguity. For more details, see the 'EnableOversizeCapture' name-value pair argument.

Data Types: double

Capture duration unit, specified as one of these values:

  • 'Samples' — The function returns ceil(length) number of samples.

  • 'Seconds' — The function converts length seconds into N samples, based on the BasebandSampleRate property of input receiver rx, and returns ceil(N) number of samples.

File name for saving captured data, specified as a character vector or string scalar. The saved file has the file name extension .bb. To read this file, use the comm.BasebandFileReader System object.

Example: 'rxdata' or 'rxdata.bb' configures the function to save data to a file named rxdata.bb.

Data Types: char | string

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Timestamp',true appends a timestamp to the file name of the captured data.

Append a capture timestamp to the saved file name, specified as the comma separated pair consisting of 'Timestamp' and false or true.

  • When you specify false, no timestamp is appended to the saved file name.

  • When you specify true, the name of the created file takes the form filename_<Year-Month-Day>_<Hour-Minute-Second-Millisecond>.bb, indicating when the data was captured.

Data Types: logical

User data, specified as the comma separated pair consisting of 'UserMetadata' and a single-level structure of data. The function adds this data to the mdata structure output. By default, the function includes no user data in mdata.

Data Types: struct

Remove limit on capture duration, specified as the comma separated pair consisting of 'EnableOversizeCapture' and false or true. When you specify true, the function removes the limit on the number of samples and data contiguity is not guaranteed.

Data Types: logical

Output Arguments

collapse all

Output signal received from the radio hardware, returned as a complex matrix. The number of columns in the matrix depends on the number of channels in use, as specified by the ChannelMapping property of the input receiver rx. Each column corresponds to a channel of complex data received on one channel.

The output signal supports complex values with these data types:

  • 16-bit signed integers — Complex values are the raw 16-bit I and Q samples from the board. The 12-bit value from the ADC of the AD9361 RF chip is sign-extended to 16 bits.

  • Single-precision floating point — Complex values are scaled to the range of [–0.0625, 0.0625]. The object derives this value from the sign-extended 16 bits received from the board.

  • Double-precision floating point — Complex values are scaled to the range of [–0.0625, 0.0625]. The object derives this value from the sign-extended 16 bits received from the board.

To specify the base data type, use the OutputDataType property of the input receiver rx.

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

Capture-time configuration settings for the radio device, returned as a structure that contains these fields:

FieldDescription
Date

Date of the data capture

BasebandSampleRate

Baseband sample rate, in Hz, configured in the SDR device

CenterFrequency

Center frequency, in Hz, configured in the SDR device

DeviceName

Name of the SDR device

ChannelMapping

Channel mapping value configured in the SDR device

Channel mapping is always 1

CaptureLengthSamples

Length of data capture, as specified by inputs length and unit, in samples

CaptureLengthSeconds

Length of data capture, as specified by inputs length and unit, in seconds

SDRReceiverConfiguration

Character vector list of property values and settings that describe the System object state

GainSource

Gain source value configured in the SDR device

DataContiguity

0 indicates discontiguous data.

1 indicates contiguous data.

DiscontiguityIndices

Vector of row indices into the output data

This field only applies when the DataContiguity field is 0. Each index indicates that on or after the corresponding data sample a discontiguity occurs.

UserMetaDataAdditional structure containing user-defined information included as an input to the capture function

Data Types: struct

File name for saved captured data and metadata, returned as a character vector.

Data Types: char

Version History

Introduced in R2019b