Documentation Center

  • Trial Software
  • Product Updates

comm.SDREpiqBitsharkReceiver class

Package: comm

Receive data from Epiq Solution's Bitshark RF board

Description

The SDREpiqBitsharkReceiver System object™ receives data from a Xilinx® FPGA-based radio, allowing simulation and development for various software-defined radio applications. The SDREpiqBitsharkReceiver object enables communication with a FPGA board on the same Ethernet subnetwork.

The SDREpiqBitsharkReceiver System object is a signal sink that receives data from an FPGA board and outputs a column vector signal of fixed length. The first call to this object may contain transient values which result in packets containing undefined data.

The following diagram illustrates how MATLAB®, the SDREpiqBitsharkReceiver System object, and Xilinx FPGA hardware interface.

Data Path

The following diagram illustrates the data path for radio signal reception (when the decimation filter, IF tuner, and DC blocking filter are all specified in the object properties):

Supported Data Types

PortSupported Data Types

Output

The output port supports these complex data types only:

  • Double-precision floating point

  • Single-precision floating point

  • 16-bit signed integers

When you select a 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 board.

Construction

H = comm.SDREpiqBitsharkReceiver creates an SDR receiver System object, H, that receives data from an FPGA development motherboard with an Epiq Solution's Bitshark™ FMC-1Rx daughterboard installed. The System object enables communication with an SDR board on the same gigabit Ethernet subnetwork as the host.

H = comm.SDREpiqBitsharkReceiver(Name,Value) creates an SDR receiver System object, H, 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).

An SDREpiqBitsharkReceiver System object connects to a device when you call the step method, and will stay connected until you call the release method.

Properties

IPAddress

IP address of the SDR device

Specify the logical network location of the SDR device as a string. The default is 192.168.0.2 for Epiq radios.

CenterFrequencySource

Source of the center frequency

Specify the source of the center frequency as one of Property | Input port. The default is Property. Set CenterFrequencySource to Input port to specify the center frequency value using an input to the step method. Set CenterFrequencySource to Property to specify the center frequency value using the CenterFrequency property.

CenterFrequency

Desired center frequency in Hz

Specify the desired center frequency as a double-precision, nonnegative, finite scalar. This property applies when you set the CenterFrequencySource to Property.

The default is 2.4GHz. The valid range of values for this property is 300MHz to 4GHz.

ActualCenterFrequency

Actual center frequency in Hz

Report the actual center frequency of the daughterboard. Desired and actual center frequency can differ slightly due to quantization. This property is read-only.

IntermediateFrequencySource

Source of RF intermediate frequency

Specify the source of the intermediate frequency as Property or Input port. The default is Property. Set IntermediateFrequencySource to Input port to specify the intermediate frequency value using an input to the step method. Set IntermediateFrequencySource to Property to specify the intermediate frequency value using the IntermediateFrequency property.

IntermediateFrequency

Desired intermediate frequency in Hz

The intermediate frequency (IF) tuner allows you to account for the error in tuning between target center frequency and actual center frequency and avoid unwanted interference by shifting it out of the pass band of interest. Specify the desired intermediate frequency as a double-precision, finite scalar. The default value is 0 Hz. The valid range of values for this parameter is to , where is the analog-digital converter (ADC) rate.

ActualIntermediateFrequency

Actual intermediate frequency in Hz

Reports the actual intermediate frequency. Desired and actual intermediate frequency can be slightly different due to quantization. The value is NaN when the actual value is unknown. Use the synchronize method to update the actual value. This property is read-only.

IFBandwidthSource

Source of bandwidth for IF filter

IFBandwidth

Desired IF bandwidth in Hz

ActualIFBandwidth

Actual IF bandwidth in Hz

GainSource

Source of the gain

Specify the source of the gain as one of Property | Input port. The default is Property. Set GainSource to Input port to specify the gain value using an input to the step method. Set GainSource to Property to specify the gain value using the Gain property.

Gain

Desired RF front-end gain in dB

ActualGain

Actual RF front-end gain in dB

Report the actual gain of the daughterboard. Desired and actual gain can differ slightly due to quantization. This property is read-only.

ADCRate

Desired ADC sample rate. The default value is 100MHz. The valid range for this board is 5–105MHz.

ActualADCRate

Actual ADC sample rate in samples per second

DecimationFactor

Desired decimation factor

Specify the desired decimation factor as a double precision nonnegative scalar. The default is 512. The baseband rate is ADCRate/DecimationFactor. See Decimation Factors.

ActualDecimationFactor

Actual decimation factor

Reports the actual decimation factor of the daughterboard. Desired and actual decimation factor can differ slightly due to quantization. The value is NaN when the actual value is unknown. Use the synchronize method to update the actual value. This property is read-only.

LostSamplesOutputPort

Output flag to indicate dropped samples

Set this property to true so that the step method outputs the number of lost samples during host/hardware data transfers. Non-zero values indicate that the host is unable to keep up with the radio data rates. The default is false.

This port is a useful diagnostic tool to determine real time operation of the System object. If your model is not running in real time, you can increase the decimation factor to approach or achieve real-time performance.

OutputDataType

Data type of output

Specify the data type of the output signal as double, single, or int16. The default is int16, with a range of [-32768, 32767]. This block supports the following complex output data types:

  • Double-precision floating point

  • Single-precision floating point

  • 16-bit signed integers

When you set OutputDataType to either Double-precision floating point or Single-precision floating point, the range is [-1, 1].

FrameLength

Frame length

Specify the frame length of the output signal that the object generates as a positive, scalar integer. The default value is 3660. This value optimally utilizes the underlying Ethernet packets, which have a size of 1500 8-bit bytes.

EnableBurstMode

Ensure a set of frames without overrun

When set to true, this property produces a set of contiguous frames without an overrun or underrun to the radio. This setting can help simulate models that cannot run in real time. When enabled, specify the desired amount of contiguous data using the NumFramesInBurst property. The default value is false.

NumFramesInBurst

Number of frames in contiguous burst

This property is valid when EnableBurstMode property is set to true. The default number of frames in a burst is 100.

BypassUserLogic

Bypass user logic from target workflow

When you enable this property, the FPGA data path bypasses the algorithm generated and programmed during the SDR workflow. This bypass can help with debugging system bringup. The default value is false, or not enabled.

BypassDCBlockingFilter

Bypass the DC bias removal filter

When true, the DC blocking filter to automatically reduce a DC bias is bypassed. Enable this when the filter is also blocking some signal and you need to use a different DC bias compensation scheme. The default is false, which means to include the automatic DC blocking filter.

Methods

disconnectAllow other host software to communicate with SDR board
infoObtain SDR board informaion
isLockedLocked status (logical)
releaseAllow property value and input characteristics changes
stepReceive data from SDR board
synchronizeConfigure SDR board

Usage

Object Connectivity

You can verify that your SDREpiqBitsharkReceiver System object is connected to FPGA hardware by using the info method.

  1. Construct an SDREpiqBitsharkReceiver System object.

    h = comm.SDREpiqBitsharkReceiver
  2. Use the info method:

    S = info(h)

    Hardware information is returned in structure S.

Sample Times

The System object determines the radio frequency sample times using the ADC clock rate, decimation factor, and frame size, according to the following formula: Sample time = 1/(ADCRate/DecimationFactor). You can choose to use decimation to reduce your bandwidth. See Decimation Factors.

Decimation Factors

The FPGA image includes a decimation filter chain that is controlled by the Decimation Factor parameter. The filter chain consists of a CIC filter followed by two halfband filters as shown in the diagram below. The first halfband filter has a wider transition band and less filter weights than the second one. For this reason the first halfband is called Halfband Lightweight (HBL) and the second is called Halfband Heavyweight (HBH).

The filter chain supports decimation factors from the following set of values:

[4:128,130:2:256,260:4:512]

That is,

  • Any integer from 4 to 128

  • A multiple of 2 from 130 to 256

  • A multiple of 4 from 260 to 512

    Note:   If the desired decimation factor is not supported then it will be quantized to a supported value from the above set. Furthermore this may result in a suboptimal hardware configuration and is therefore not recommended. See the table below for examples.

The CIC filter has a variable decimation factor (CIC rate) of between 2 and 128 and may be bypassed if necessary. Each halfband filter decimates by a factor of 2 and may be also be bypassed. The filters are enabled or bypassed according to the following rules:

  • If the desired decimation factor is divisible by 4, then both HBL and HBH are enabled.

  • If the desired decimation factor is divisible by 2 and not by 4, then HBL is bypassed and HBH is enabled.

  • If the desired decimation factor is not divisible by 2, then HBL and HBH are both bypassed.

  • The remaining decimation factor is made up by the CIC filter. If the remaining factor is 1 then the CIC is bypassed.

The following table demonstrates some examples of how the filter chain is configured to implement the desired decimation factor:

Desired Decimation FactorCICHBLHBHActual Decimation FactorRecommended
4Bypassed224Yes
55BypassedBypassed5Yes
63Bypassed26Yes
77BypassedBypassed7Yes
.
.
.
1283222128Yes
1293222128No
13065Bypassed2130Yes
1313322132No
.
.
.
2516322252Yes
.
.
.
2566422256Yes
2576422256No
2586422256No
2596522260No
2606522260Yes
2616522260No
2626522260No
2636622264No
.
.
.

The Support Package for Xilinx FPGA-Based Radio software incorporates the logic to determine these settings automatically from the desired decimation factor block mask parameter.

Intermediate Frequency Tuning

Intermediate frequency (IF) tuning supports second stage tuning for both the transmit and receive data paths. The tuner is configurable at run-time (tunable), provides finer resolution when compared to the primary tuner on an RF card, and allows you to remove unwanted interference from the pass band of interest.

IF Tuning on Transmit Data Path

IF Tuning on Receive Data Path

To enable an intermediate frequency tuner, set the IntermediateFrequency property for the receiver System object.

rxIFValue = 1e6;
so = comm.SDREpiqBitsharkReceiver;
so.IntermediateFrequency = rxIFValue

Keep in mind that the actual frequency value is stored in the property ActualIntermediateFrequency.

Desired vs. Actual Device System Object Parameter Values

You can set the desired values in the receiver System object for the following radio properties. However, due to quantization or range issues, the actual values can differ from your desired values. The actual values are stored in the properties that begin with Actual (see table).

Parameter to SetActual Value
CenterFrequencyActualCenterFrequency
IntermediateFrequencyActualIntermediateFrequency
IFBandwidthActualIFBandwidth
GainActualGain
ADCRateActualADCRate
DecimationFactorActualDecimationFactor

Baseband Rate Lost Samples

The SDREpiqBitsharkReceiver System object has an optional lost samples output port. When this port is active, it outputs a logical signal that indicates whether the System object is processing data in real time. If the System object is not keeping up with the hardware, the signal indicates the approximate number of lost samples.

This port is a useful diagnostic tool for determining real time operation of the System objects. If your code is not running in real time, see Xilinx FPGA-Based Radio Processing Errors and Fixes.

DC Blocking

Direct conversion receivers, such as Epic Bitshark, often impose a DC bias on the in-phase and quadrature components of the signal. DC bias, if not dealt with, leads to degraded BER performance for QAM systems, and to a lesser extent, PSK systems. With the DC blocking filter implemented in the FPGA, the DC bias is reduced in the I/Q channels of a received complex signal, to better enable robust receiver processing, and allow you to focus on designing the baseband algorithm without worrying about DC bias that is introduced by the analog front end.

The DC blocking filter is on by default. To bypass this filter, set the BypassDCBlockingFilter property to 1, or true.

so = comm.SDREpiqBitsharkReceiver
so = 

  System: comm.SDREpiqBitsharkReceiver

  Properties:
                      IPAddress: '192.168.0.2'
          CenterFrequencySource: 'Property'   
                CenterFrequency: 2400000000   
          ActualCenterFrequency: NaN          
    IntermediateFrequencySource: 'Property'   
          IntermediateFrequency: 0            
    ActualIntermediateFrequency: NaN          
              IFBandwidthSource: 'Property'   
                    IFBandwidth: 56000000     
              ActualIFBandwidth: NaN          
                     GainSource: 'Property'   
                           Gain: 0            
                     ActualGain: NaN          
                        ADCRate: 100000000    
                  ActualADCRate: NaN          
               DecimationFactor: 512          
         ActualDecimationFactor: NaN          
                EnableBurstMode: false        
                BypassUserLogic: false        
         BypassDCBlockingFilter: false        
          LostSamplesOutputPort: true         
                 OutputDataType: 'int16'      
                    FrameLength: 3660  
so.BypassDCBlockingFilter=1;
so = 

  System: comm.SDREpiqBitsharkReceiver

  Properties:
                      IPAddress: '192.168.0.2'
          CenterFrequencySource: 'Property'   
                CenterFrequency: 2400000000   
          ActualCenterFrequency: NaN          
    IntermediateFrequencySource: 'Property'   
          IntermediateFrequency: 0            
    ActualIntermediateFrequency: NaN          
              IFBandwidthSource: 'Property'   
                    IFBandwidth: 56000000     
              ActualIFBandwidth: NaN          
                     GainSource: 'Property'   
                           Gain: 0            
                     ActualGain: NaN          
                        ADCRate: 100000000    
                  ActualADCRate: NaN          
               DecimationFactor: 512          
         ActualDecimationFactor: NaN          
                EnableBurstMode: false        
                BypassUserLogic: false        
         BypassDCBlockingFilter: true         
          LostSamplesOutputPort: true         
                 OutputDataType: 'int16'      
                    FrameLength: 3660         
                                              

Examples

Configure an SDR board with an IP address of 192.168.0.2 to receive at 2.5 GHz with a codec rate of 100MHz and a baseband rate of 1MHz. Save the data using a signal logger System object.

hSDR = comm.SDREpiqBitsharkReceiver( ...
                'IPAddress',        '192.168.0.2', ...
                'CenterFrequency',  2.5e9, ...
                'ADCRate',          100e6, ...
                'DecimationFactor', 100);
 
    hLogger = dsp.SignalSink;
    for counter = 1:20
      [data, dataLength] = step(hSDR);
      if (dataLength)
        step(hLogger, data);
      end
    end
Was this topic helpful?