Skip to content

NI RFmx SpecAn General Functions

Alex Starche edited this page Feb 28, 2022 · 4 revisions

General Functions

RFmxSpecAn_Initialize

int32 __stdcall RFmxSpecAn_Initialize (char resourceName[], char optionString[], niRFmxInstrHandle *handleOut, int32 *isNewSession);

Purpose

Creates an RFmx session to the device you specify through the resourceName parameter, and returns a handleOut that identifies this device in all subsequent RFmx functions.

This function is a wrapper over the RFmx Instruments API, and calls the RFmxInstr_Initialize) function.

Enabling the SFP (Soft Front Panel) debug has a performance impact. For best performance, NI recommends disabling SFP debug.

  • On a 64-bit Windows, SFP debug can be enabled/disabled from either the RFmx Soft Front Panel, the RFSA Soft Front Panel, or the RFmx Debug Configuration Utility.
  • On a 32-bit Windows, SFP debug can be enabled/disabled from the RFSA Soft Front Panel or the RFmx Debug Configuration Utility.

Parameters

Input
Name Type Description
resourceName char[] Specifies the resource name of the device to initialize.

The following table shows examples of how to specify the resource name.
Example # Device Type Syntax
1 myRFmxDevice RFmx device, device name is "myRFmxDevice"
2 myLogicalName IVI logical name or virtual instrument, name is "myLogicalName"


For NI-DAQmx devices, the syntax is the device name specified in MAX, as shown in Example 1. Typical default names for NI-DAQmx devices in MAX are Dev1 or PXI1Slot2. You can rename an NI-DAQmx device by right-clicking the name in MAX, selecting Rename from the pull-down menu, and entering a new name. You can also pass the name of an IVI logical name configured with the IVI Configuration utility. For additional information about IVI, refer to the IVI section of the Measurement & Automation Explorer Help.
optionString char[]

Sets the initial value of certain attributes for the session.

The following attributes are used in this parameter:

- RFmxSetup

- Simulate

- AnalysisOnly



For more information about attributes used in this parameter, refer to the NI RF Vector Signal Analyzers Help.

The format of this string is "AttributeName=Value", where AttributeName is the name of the attribute and Value is the value to which the attribute is set. For example, you can simulate an PXIe-5663E using either of the following strings:

"Simulate=1, RFmxSetup=Model:5663E"

"Simulate=1, RFmxSetup=Model:5601; Digitizer:5622; LO:5652; LOBoardType:PXIe"

To set multiple attributes, separate their assignments with a comma.

To use FPGA extensions, specify the custom LabVIEW FPGA bitfile to use with the bitfile specifier within the RFmxSetup string. For example, "RFmxSetup=bitfile:yourbitfile.lvbitx" specifies that RFmx uses yourbitfile.lvbitx as the LabVIEW FPGA bitfile for the session.

To use AnalysisOnly mode, specify the string as "AnalysisOnly=1". In this mode, user is responsible for waveform acquisition and RFmx driver will perform analysis on user specified IQ waveform or Spectrum. Use personality specific Analyze functions to perform measurements.

Note  To simulate a device using the PXIe-5622 (25 MHz) digitizer, set the Digitizer field to 5622_25MHz_DDC and the Simulate field to 1. You can set the Digitizer field to 5622_25MHz_DDC only when using the PXIe-5665.
To use external NI Source Measure Units (SMU) as the noise source power supply for the noise figure (NF) measurement, use the "NoiseSourcePowerSupply" specifier within the RFmxSetup string. For example, "RFmxSetup= NoiseSourcePowerSupply:myDCPower[0]" configures RFmx to use channel 0 on myDCPower SMU device for powering the noise source. You should allocate a dedicated SMU channel for RFmx.
Note  RFmx supports PXIe-4138, PXIe-4139, and PXIe-4139 (40 W) SMUs.
Output
Name Type Description
handleOut niRFmxInstrHandle* Identifies your instrument session.
isNewSession int32* Returns RFMXSPECAN_VAL_TRUE if the function created a new session, or RFMXSPECAN_VAL_FALSE if the function returned a reference to an existing session.

Return Value

Name Type Description
status int32 Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred.

To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

RFmxSpecAn_SelectMeasurements

int32 __stdcall RFmxSpecAn_SelectMeasurements (niRFmxInstrHandle instrumentHandle, char selectorString[], uInt32 measurements, int32 enableAllTraces);

Purpose

Enables all the measurements that you specify in the measurements parameter and disables all other measurements.

Parameters

Input
Name Type Description
instrumentHandle niRFmxInstrHandle Identifies the RFmx session. You can obtain this parameter from the RFmxSpecAn_Initialize) function.
selectorString char[] Comprises the signal name. If you do not specify the signal name, the default signal instance is used.

Example:

""

"signal::sig1"

You can use the RFmxSpecAn_BuildSignalString) function to build the selector string).
measurements uInt32 Specifies the measurement to perform. You can specify one or more of the following measurements.
RFMXSPECAN_VAL_ACP (1) Enables adjacent channel power (ACP) measurement.
RFMXSPECAN_VAL_CCDF (2) Enables complementary cumulative distribution function (CCDF) measurement.
RFMXSPECAN_VAL_CHP (4) Enables channel power (CHP) measurement.
RFMXSPECAN_VAL_FCNT (8) Enables frequency count (FCNT) measurement.
RFMXSPECAN_VAL_HARMONICS (16) Enables harmonics measurement.
RFMXSPECAN_VAL_OBW (32) Enables occupied bandwidth (OBW) measurement.
RFMXSPECAN_VAL_SEM (64) Enables spectral emission mask (SEM) measurement.
RFMXSPECAN_VAL_SPECTRUM (128) Enables spectrum measurement.
RFMXSPECAN_VAL_SPUR (256) Enables spurious emissions (Spur) measurement.
RFMXSPECAN_VAL_TXP (512) Enables transmit power (TXP) measurement.
RFMXSPECAN_VAL_AMPM (1024) Enables AMPM measurement.
RFMXSPECAN_VAL_DPD (2048) Enables DPD measurement.
RFMXSPECAN_VAL_IQ (4096) Enables I/Q measurement.
RFMXSPECAN_VAL_IM (8192) Enables IM measurement.
RFMXSPECAN_VAL_NF (16384) Enables noise figure (NF) measurement.
RFMXSPECAN_VAL_PHASENOISE (32768) Enables noise figure (NF) measurement.
enableAllTraces int32 Specifies whether to enable all the traces for the selected measurements.

Return Value

Name Type Description
status int32 Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred.

To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

RFmxSpecAn_Initiate

int32 __stdcall RFmxSpecAn_Initiate (niRFmxInstrHandle instrumentHandle, char selectorString[], char resultName[]);

Purpose

Initiates all enabled measurements. Call this function after configuring the signal and measurement. This function asynchronously launches measurements in the background and immediately returns to the caller program. You can fetch measurement results using the Fetch functions or result attributes. To get the status of measurements, you can use the RFmxSpecAn_CheckMeasurementStatus) function.

Parameters

Input
Name Type Description
instrumentHandle niRFmxInstrHandle Identifies the RFmx session. You can obtain this parameter from the RFmxSpecAn_Initialize) function.
selectorString char[] Specifies a selector string) comprising of the signal name and result name. The result name can either be specified through this input or the resultName input. If you do not specify the signal name, the default signal instance is used. If you do not specify the result name in this input, either the result name specified by the resultName input or the default result instance is used.

Example:

""

"signal::sig1"

"result::r1"

"signal::sig1/result::r1"

You can use the RFmxSpecAn_BuildSignalString) function to build the selector string.
resultName char[] Specifies the name to be associated with measurement results. Provide a unique name, such as "r1" to enable fetching of multiple measurement results and traces. This input accepts the result name with or without the "result::" prefix. The default value is "" (empty string), which refers to the default result instance.
Example:
""
"result::r1"
"r1"

Return Value

Name Type Description
status int32 Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred.

To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

RFmxSpecAn_Close

int32 __stdcall RFmxSpecAn_Close (niRFmxInstrHandle instrumentHandle, int32 forceDestroy);

Purpose

Closes the session to the device.

This function is a wrapper over the RFmx Instruments API, and calls the RFmxInstr_Close) function.

Parameters

Input
Name Type Description
instrumentHandle niRFmxInstrHandle Identifies the RFmx session. You can obtain this parameter from the RFmxSpecAn_Initialize) function.
forceDestroy int32 Specifies whether to destroy the RFmx session.
RFMXSPECAN_VAL_FALSE (0) Destroys the RFmx session. Call the RFmxSpecAn_Close function a number of times equal to the number of times you obtained a reference to the RFmx session.
RFMXSPECAN_VAL_TRUE (1) Destroys the RFmx session. You do not have to call the RFmxSpecAn_Close function multiple times. Destroying the RFmx session invalidates all references to the session.

Return Value

Name Type Description
status int32 Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred.

To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

RFmxSpecAn_GetError

int32 __stdcall RFmxSpecAn_GetError (niRFmxInstrHandle instrumentHandle, int32* errorCode, int32 errorDescriptionBufferSize, char errorDescription[]);

Purpose

Retrieves and then clears the error information for the session or the current execution thread. You must provide a char array to serve as a buffer for the value. Pass the number of bytes in the buffer as the errorDescriptionBufferSize parameter.

If the error description, including the terminating NULL byte, is larger than the size you indicate in the errorDescriptionBufferSize parameter, the function copies buffer size - 1 bytes into the buffer, places an ASCII NULL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the buffer size is 4, the function places "123" into the buffer and returns 7.

If you want to call this function just to get the required buffer size, you must pass 0 for errorDescriptionBufferSize and NULL for the errorDescription buffer.

Note  Use the RFmxSpecAn_GetErrorString function if the RFmxSpecAn_GetError function does not return an error message.

Parameters

Input
Name Type Description
instrumentHandle niRFmxInstrHandle Specifies the RFmx session. If a valid session handle is passed, the last error stored in that session is retrieved. You can pass NULL to retrieve the last error stored in the current execution thread.
errorDescriptionBufferSize int32 Passes the number of bytes in the char array you specify in errorDescription.

If the error description, including the terminating NULL byte, contains more bytes than you indicate in this parameter, the function copies errorDescriptionBufferSize – 1 bytes into the buffer, places an ASCII NULL byte at the end of the buffer, and returns the size of the buffer that you must pass to get the entire value. For example, if the value is "123456" and the buffer size is 4, the function places "123" into the buffer and returns 7.
Output
Name Type Description
errorCode int32* Returns the error code for the session or execution thread. If you pass 0 for the errorDescriptionBufferSize parameter, you can pass NULL for the errorCode parameter.
errorDescription char[] Returns the error description for the session or execution thread. If there is no description, this function returns an empty string.

The buffer must contain at least as many elements as the value you specify with the errorDescriptionBufferSize parameter.

Return Value

Name Type Description
statusOrRequiredSize int32 Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred.

When the statusOrRequiredSize return value returns the buffer size, the status code is not returned.

To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

RFmxSpecAn_GetErrorString

int32 __stdcall RFmxSpecAn_GetErrorString (niRFmxInstrHandle instrumentHandle, int32 errorCode, int32 errorDescriptionBufferSize, char errorDescription[]);

Purpose

Converts a status code returned by an RFmxSpecAn function into a user-readable string. You must provide a char array to serve as a buffer for the value. Pass the number of bytes in the buffer as the errorDescriptionBufferSize parameter.

If the error description, including the terminating NULL byte, is larger than the size you indicate in the errorDescriptionBufferSize parameter, the function copies buffer size - 1 bytes into the buffer, places an ASCII NULL byte at the end of the buffer, and returns the buffer size you must pass to get the entire value. For example, if the value is "123456" and the buffer size is 4, the function places "123" into the buffer and returns 7.

If you want to call this function just to get the required buffer size, you must pass 0 for errorDescriptionBufferSize and NULL for the errorDescription buffer.

Parameters

Input
Name Type Description
instrumentHandle niRFmxInstrHandle Identifies the RFmx session. You can obtain this parameter from the RFmxSpecAn_Initialize) function.
errorCode int32 Passes the statusOrRequiredSize parameter that is returned from any RFmxSpecAn function.
errorDescriptionBufferSize int32 Passes the number of bytes in the char array you specify in errorDescription.

If the error description, including the terminating NULL byte, contains more bytes than you indicate in this parameter, the function copies errorDescriptionBufferSize – 1 bytes into the buffer, places an ASCII NULL byte at the end of the buffer, and returns the size of the buffer that you must pass to get the entire value. For example, if the value is "123456" and the buffer size is 4, the function places "123" into the buffer and returns 7.
Output
Name Type Description
errorDescription char[] Returns the user-readable message string that corresponds to the status code you specify.

If you pass 0 for errorDescriptionBufferSize, you can pass NULL for the errorDescription buffer parameter to get the size of error description message.

Return Value

Name Type Description
statusOrRequiredSize int32 Returns the status code of this operation. The status code either indicates success or describes an error or warning condition. Examine the status code from each call to an RFmx function to determine if an error has occurred.

When the statusOrRequiredSize return value returns the buffer size, the status code is not returned.

To obtain a text description of the status code and additional information about the error condition, call the RFmxSpecAn_GetError) function.

The general meaning of the status code is as follows:
Value Meaning
0 Success
Positive Values Warnings
Negative Values Errors

Table of Contents

Internal Development

Creating and Setting Up a gRPC Server

Server Security Support

Creating a gRPC Client

gRPC Client Examples

Session Utilities API Reference

Driver Documentation

gRPC API Differences From C API

Sharing Driver Sessions Between Clients

C API Docs
NI-DAQmx
NI-DCPOWER
NI-DIGITAL PATTERN DRIVER
NI-DMM
NI-FGEN
NI-FPGA
NI-RFmx Bluetooth
NI-RFmx NR
NI-RFmx WCDMA
NI-RFmx GSM
NI-RFmx CDMA2k
NI-RFmx Instr
NI-RFmx LTE
NI-RFmx SpecAn
NI-RFmx TD-SCDMA
NI-RFmx WLAN
NI-RFSA
NI-RFSG
NI-SCOPE
NI-SWITCH
NI-TCLK
NI-XNET
Clone this wiki locally