Selector Strings

NI-RFmx TDSCDMA 2.5 Help

Edition Date: June 2018

Part Number: 375760F-01

»View Product Info
Download Help (Windows Only)

RFmx is a powerful API that supports basic and advanced features and provides multiple ways to configure measurements and fetch measurement results. The same configuration and fetch methods can be used in basic and advanced use cases such as named signal configurations without having to rewrite code. The following code shows a basic ACP measurement that does not use named signal configurations.

C#

/* Create a new RFmx Session */
RFmxInstrMX instrSession = new RFmxInstrMX(resourceName, "");
/* Get SpecAn signal */
RFmxSpecAnMX specAn = instrSession.GetSpecAnSignalConfiguration();
/* Configure ACP measurement */
specAn.ConfigureRF("", centerFrequency, referenceLevel, externalAttenuation);
specAn.Acp.Configuration.ConfigureAveraging("", averagingEnabled, averagingCount, averagingType);
specAn.Acp.Configuration.ConfigureCarrierAndOffsets("", integrationBandwidth, numberOfOffsetChannels, channelSpacing);
/* Retrieve results */ 
specAn.Acp.Results.Read("", timeout, out carrierAbsolutePower, out offCh0LowerRelativePower, out offCh0UpperRelativePower,
                        out offCh1LowerRelativePower, out offCh1UpperRelativePower);
instrSession.Close();

VB

' Create a new RFmx Session
Dim instrSession As New RFmxInstrMX(resourceName, "")
' Get SpecAn signal
Dim specAn As RFmxSpecAnMX = instrSession.GetSpecAnSignalConfiguration()
' Configure ACP measurement
specAn.ConfigureRF("", centerFrequency, referenceLevel, externalAttenuation)
specAn.Acp.Configuration.ConfigureAveraging("", averagingEnabled, averagingCount, averagingType)
specAn.Acp.Configuration.ConfigureCarrierAndOffsets("", integrationBandwidth, numberOfOffsetChannels, channelSpacing)
' Retrieve results
specAn.Acp.Results.Read("", timeout, out carrierAbsolutePower, out offCh0LowerRelativePower, out offCh0UpperRelativePower,
                        out offCh1LowerRelativePower, out offCh1UpperRelativePower);
instrSession.Close()

You can enhance the code as shown in the following code to use named signal configurations by passing a signalName to the GetSpecAnSignalConfiguration method. In .NET API, you provide signal name to  Get Signal Configuration methods only.

C#


/* Create a new RFmx Session */
RFmxInstrMX instrSession = new RFmxInstrMX(resourceName, "");
/* Get SpecAn signal */
RFmxSpecAnMX specAn = instrSession.GetSpecAnSignalConfiguration(“MySignalConfig”);
/* Configure measurement */
specAn.ConfigureRF("", centerFrequency, referenceLevel, externalAttenuation);
specAn.Acp.Configuration.ConfigureAveraging("", averagingEnabled, averagingCount, averagingType);
specAn.Acp.Configuration.ConfigureCarrierAndOffsets("", integrationBandwidth, numberOfOffsetChannels,channelSpacing);
/* Retrieve results */
specAn.Acp.Results.Read("", timeout, out carrierAbsolutePower, out offCh0LowerRelativePower, out offCh0UpperRelativePower,
                        out offCh1LowerRelativePower, out offCh1UpperRelativePower);
instrSession.Close();

VB

' Create a new RFmx Session
Dim instrSession As New RFmxInstrMX(resourceName, "")
' Get SpecAn signal
Dim specAn As RFmxSpecAnMX = instrSession.GetSpecAnSignalConfiguration(MySignalConfig)
' Configure measurement
specAn.ConfigureRF("", centerFrequency, referenceLevel, externalAttenuation)
specAn.Acp.Configuration.ConfigureAveraging("", averagingEnabled, averagingCount, averagingType)
specAn.Acp.Configuration.ConfigureCarrierAndOffsets("", integrationBandwidth, numberOfOffsetChannels, channelSpacing)
' Retrieve results
specAn.Acp.Results.Read("", timeout, carrierAbsolutePower, offCh0LowerRelativePower, offCh0UpperRelativePower,
                        offCh1LowerRelativePower, offCh1UpperRelativePower)
instrSession.Close()

The selectorString parameter in RFmx methods allows you to specify the full context of what you are configuring or fetching. In .NET API, you will not need to provide signal name context in selectorString parameter of Configure and Fetch methods. The following code shows an example of the selectorString input on one of the NI-RFmx fetch measurement methods.
public int FetchCarrierMeasurement(string selectorString, double timeout, out double absolutePower, out double totalRelativePower,                                    out double carrierFrequency, out double integrationBandwidth);
For example, an ACP measurement can have multiple offset channels and you can configure the frequency and measurement bandwidth properties for each offset channel. When you configure the measurement bandwidth for a specific offset channel, you must specify the offset channel for which you are configuring the Measurement Bandwidth property. When you configure the first offset channel you must specify the context in the selectorString input as “offset0” as shown in the following code.

C#

/* Fetch ACP offset measurements */
specAn.Acp.Configuration.ConfigureOffsetRrcFilter("offset0", rrcFilterEnabled, rrcFilterAlpha);

VB

' Fetch ACP offset measurements
specAn.Acp.Configuration.ConfigureOffsetRrcFilter("offset0", rrcFilterEnabled, rrcFilterAlpha)

The contexts you can specify depend on what you are configuring or fetching. For example, if  you are configuring a carrier channel you specify which carrier channel, such as “carrier3”, that you are configuring. If you are configuring an offset channel, you specify which offset channel, such as “offset2”, that you are configuring.
Named Results can be specified in only the Initiate and fetch methods.

Multiple Contexts

When using multiple features in the API, you can specify multiple contexts in the same selectorString input separated with a ‘/’. For example, to fetch a result for carrier 0 in the named result context called “MyResult”, you must specify “result::MyResult/carrier0” to the selectorString parameter in the Fetch method.
Another example of multiple contexts is when performing LTE non-contiguous carrier aggregation measurements. In this case the signal is composed of multiple subblocks and each subblock can contain multiple carriers. When you configure a property of a carrier in LTE non-contiguous carrier aggregation, you must specify the index of the carrier within the subblock and the index of the subblock. For example, you would specify that you are configuring the first carrier in the second subblock by using “subblock1/carrier0” as the selector string.

String Prefixes in Selector Strings

NI-RFmx requires a prefix, such as “carrier” or “result::”, before the number or name in the selector string so that it is clear what is being configured. The “::” is required for “signal::” and “result::” because those items use arbitrary user defined names and the API needs to be able to know where the user specified name starts in the selector string. You can specify the selector strings as constants, such as “carrier0” and “result::myResult” or use the build string utility methods provided by RFmx to create correctly formed strings.

Build String Utility Methods

NI-RFmx provides a set of utility methods as shown below to build context string for various measurement configurations.

  • BuildResultString
  • BuildCarrierString2
  • BuildHarmonicString2
  • BuildMarkerString2
  • BuildOffsetString2
  • BuildSpurString2
  • BuildRangeString2

For example, the BuildResultString method takes in a result name and outputs a string containing the contexts you specified. If you call the BuildResultString method with “MyResult” passed to the resultName input, the output string will be “result::MyResult”. Each RFmx driver provides build string utility methods for specific cases such as BuildSpurString2 which takes in a spur number, in additional to optionally taking in a previously constructed selector string.

C#


static public string BuildSpurString2(string selectorString, int spurNumber);

VB

Public Shared Function BuildSpurString2(selectorString As String, spurNumber As Integer) As String

Selector String in Set or Get Methods

When setting properties from an RFmx set or get method in .NET, you specify the context using the selectorString parameter.

Selector Strings when using Array Methods

Note that RFmx provides array versions of configure and fetch methods for many cases that allow you to configure multiple instances of a property or fetch multiple instances of a result. For example, to configure the frequencies of all the ACP measurement offset channels, you can use Acp.Configuration.ConfigureOffsetArray passing in an array that has the frequency for each of the offset channels. When using these array methods, you do not need to specify, in the selectorString input, the context that the elements in the array correspond to. For example, you pass “” as the selector string in Acp.Configuration.ConfigureOffsetArray.  However, in case of Fetch array methods, if you are using named results, you pass the result context in the selector string.

Selector String Syntax

The following table lists the various active channel string formats that you can use. For integral channel specifiers, valid values for i are 0 to (number of channels - 1). For example, if you set the value of NumberOfOffsets to 5, you can configure ACP offset properties for offset0, offset1, offset2, offset3, and offset4.

In the following table, the term channel or ch is used to refer to numeric contexts such as carrier, offset, or range.

Selector String

String Method

Example

ch<i>

Configures one channel

carrier0

ch<i>-<j>

Configures a range of channels between i and j

carrier0-5

ch<i>:<j>

Configures a range of channels between i and j

carrier0:5

ch<i>, ch<j>, ch<k>

Configures channels i, j, and k

carrier0, carrier2, carrier4

ch<i>, ch<j>-<k>

Configures channel i and a range of channels between j and k

carrier0, carrier1-5

ch<i>, ch<j>:<k>

Configures channel i and a range of channels between j and k

carrier0, carrier1:5

ch::all

Configures all channels from 0 to (Number of X - 1). Number of X is the current value of the Number of .. property that corresponds to the context being used. For example, in an ACP measurement, you set the Number of Offsets property before setting any offset properties and when you use “all”, RFmx uses the current value of Number of Offsets to determine which offset channels to configure.

offset::all

The following table lists the various selector string formats that you can use to specify the named results (using the “result::” prefix).  Note that the “result::” prefix is valid only when fetching results and currently cannot be used to configure measurements.

Syntax

String Function

Example

result::<resultname>/ch<i>

Specifies channel i for result <resultname> on signal corresponding to the signal  configuration object being used

result::r1/carrier0

result::<resultname>

Specifies named result <resultname> on signal corresponding to the signal  configuration object being used

result::r1

The following characters are not allowed in signal names and result names: ()*+,-./{} !"#$%&':;<=>?@[]\^`|~ and any non-printable character.

 

WAS THIS ARTICLE HELPFUL?

Not Helpful