capture

Capture contiguous RF data using USRP embedded series radio hardware

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

Syntax

[data,mdata] = capture(rx,length)

[data,mdata] = capture(rx,length,unit)

[data,mdata,fn] = capture(___,'Filename',filename)

[data,mdata,fn] = capture(___,'Filename',filename,Name,Value)

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.

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

example

[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

Capture RF Data to Baseband File Using E3xx Radio Hardware

This example uses:

Communications Toolbox Support Package for USRP Embedded Series Radio Communications Toolbox Support Package for USRP Embedded Series Radio

Open Live Script

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

`rx` — Receiver
`comm.SDRRxE3xx` System object

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

`length` — Capture duration
numeric scalar

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

`unit` — Capture duration unit
`'Samples'` (default) | `'Seconds'`

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.

`filename` — File name for saving captured data
character vector | string scalar

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.

`Timestamp` — Append capture timestamp to saved file name
`false` (default) | `true`

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

`UserMetadata` — User data
structure

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

`EnableOversizeCapture` — Remove limit on capture duration
`false` (default) | `true`

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

`data` — Output signal
complex matrix

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

`mdata` — Capture-time configuration settings for radio device
structure

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

Field	Description
`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.
`UserMetaData`	Additional structure containing user-defined information included as an input to the `capture` function

Data Types: struct

`fn` — File name for saved captured data and metadata
character vector

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

Data Types: char

Version History

Introduced in R2019b

capture

Syntax

Description

Examples

Capture RF Data to Baseband File Using E3xx Radio Hardware

Input Arguments

`rx` — Receiver
`comm.SDRRxE3xx` System object

`length` — Capture duration
numeric scalar

`unit` — Capture duration unit
`'Samples'` (default) | `'Seconds'`

`filename` — File name for saving captured data
character vector | string scalar

Name-Value Arguments

`Timestamp` — Append capture timestamp to saved file name
`false` (default) | `true`

`UserMetadata` — User data
structure

`EnableOversizeCapture` — Remove limit on capture duration
`false` (default) | `true`

Output Arguments

`data` — Output signal
complex matrix

`mdata` — Capture-time configuration settings for radio device
structure

`fn` — File name for saved captured data and metadata
character vector

Version History

See Also

Objects

Functions

capture

Syntax

Description

Examples

Capture RF Data to Baseband File Using E3xx Radio Hardware

Input Arguments

rx — Receiver comm.SDRRxE3xx System object

length — Capture duration numeric scalar

unit — Capture duration unit 'Samples' (default) | 'Seconds'

filename — File name for saving captured data character vector | string scalar

Name-Value Arguments

Timestamp — Append capture timestamp to saved file name false (default) | true

UserMetadata — User data structure

EnableOversizeCapture — Remove limit on capture duration false (default) | true

Output Arguments

data — Output signal complex matrix

mdata — Capture-time configuration settings for radio device structure

fn — File name for saved captured data and metadata character vector

Version History

See Also

Objects

Functions

`rx` — Receiver
`comm.SDRRxE3xx` System object

`length` — Capture duration
numeric scalar

`unit` — Capture duration unit
`'Samples'` (default) | `'Seconds'`

`filename` — File name for saving captured data
character vector | string scalar

`Timestamp` — Append capture timestamp to saved file name
`false` (default) | `true`

`UserMetadata` — User data
structure

`EnableOversizeCapture` — Remove limit on capture duration
`false` (default) | `true`

`data` — Output signal
complex matrix

`mdata` — Capture-time configuration settings for radio device
structure

`fn` — File name for saved captured data and metadata
character vector