NI SCOPE Calibrate Functions
- niScope_CalSelfCalibrate
- niScope_CalAdjustAccessoryGainAndOffset
- niScope_CalAdjustCompensationAttenuator
- niScope_CalAdjustDCM
- niScope_CalAdjustFrequencyResponse
- niScope_CalAdjustOffsetRange
- niScope_CalAdjustRange
- niScope_CalAdjustVCXO
- niScope_CalChangePassword
- niScope_CalEnd
- niScope_CalFetchCount
- niScope_CalFetchDate
- niScope_CalFetchMiscInfo
- niScope_CalFetchTemperature
- niScope_CalMeasureRISDistribution
- niScope_CalSetAccessorySource
- niScope_CalStart
- niScope_CalStoreMiscInfo
ViStatus niScope_CalSelfCalibrate (ViSession sessionHandle, ViConstString channelList, ViInt32 option);
Self-calibrates most NI digitizers, including all SMC-based devices. To verify that your digitizer supports self-calibration, refer to Features Supported by Device.
For SMC-based digitizers, if the self-calibration is performed successfully in a regular session, the calibration constants are immediately stored in the self-calibration area of the EEPROM. If the self-calibration is performed in an external calibration session, the calibration constants take effect immediately for the duration of the session. However, they are not stored in the EEPROM until niScope_CalEnd is called with action set to NISCOPE_VAL_ACTION_STORE and no errors occur.
| Input | ||
|---|---|---|
| Name | Type | Description |
| vi | ViSession | The instrument handle you obtain from niScope_init that identifies a particular instrument session. |
| channelList | ViConstString | The channel to configure. For more information, refer to Channel String Syntax. |
| option | ViInt32 | The calibration option. Use VI_NULL for a normal self-calibration operation or NISCOPE_VAL_CAL_RESTORE_EXTERNAL_CALIBRATION to restore the previous calibration. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalAdjustAccessoryGainAndOffset ( ViSession sessionHandle, ViConstString channelName, ViReal64 positiveFS, ViReal64 ground, ViReal64 negativeFS );
For the NI 5900, this function externally calibrates the gain and offset.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle returned by niScope_CalStart. |
| channelName | ViConstString | The string name of the channel to calibrate. For more information, refer to Channel String Syntax. |
| positiveFS | ViReal64 | This value is calculated during the external calibration procedure. |
| ground | ViReal64 | This value is calculated during the external calibration procedure. |
| negativeFS | ViReal64 | This value is calculated during the external calibration procedure. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalAdjustCompensationAttenuator (ViSession sessionHandle, ViConstString channelName, ViReal64 range);
For the NI 5132/5133, this function externally calibrates the compensation attenuator. Refer to the NI 5132/5133 Calibration Procedure for more information.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle you obtain from niScope_CalStart. |
| channelName | ViConstString | The string name of the channel to calibrate. For more information, refer to Channel String Syntax. |
| range | ViReal64 | The voltage range to calibrate. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus niScope_CalAdjustDCM (ViSession sessionHandle, ViConstString channelName, ViReal64 stimulusFreq);
For the NI 5104/5105 digitizer, calibrates the external clock digital clock managers (DCMs). DCM calibration ensures that data can be sampled at the correct time in the clock period.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle you obtain from niScope_CalStart. |
| channelName | ViConstString | This parameter is ignored. |
| stimulusFreq | ViReal64 |
The external stimulus applied to the digitizer. Default value: 0 |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalAdjustFrequencyResponse ( ViSession sessionHandle, ViConstString channelName, ViReal64 range, ViReal64 stimulusFreq, ViReal64 stimulusAmp );
For the NI 5622, calibrates the frequency response of the device. The function is called multiple times, one for each frequency point in the sweep. The user must supply the stimulus frequency (in hertz) and stimulus amplitude (in volts) of the input signal.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle returned by niScope_CalStart. |
| channelName | ViConstString | The string name of the channel to calibrate. For more information, refer to Channel String Syntax. |
| range | ViReal64 | The voltage range to calibrate. |
| stimulusFreq | ViReal64 | The frequency of the external stimulus applied to the digitizer. |
| stimulus | ViReal64 | The peak voltage of the signal applied to the digitizer. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalAdjustOffsetRange ( ViSession sessionHandle, ViConstString channelName, ViReal64 range, ViReal64 stimulus );
For the NI 5132/5133, this function externally calibrates the vertical offset. Refer to the NI 5132/5133 Calibration Procedure for the appropriate stimulus voltages.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle you obtain from niScope_CalStart. |
| channelName | ViConstString | The string name of the channel to calibrate. For more information, refer to Channel String Syntax. |
| range | ViReal64 | The voltage range to calibrate. |
| stimulus | ViReal64 | The peak voltage of the applied signal. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalAdjustRange (ViSession sessionHandle, ViConstString channelName, ViReal64 range, ViReal64 stimulus);
 |
Note Use this function only when following the device calibration procedure. |
|---|---|
| Before calling this function, connect an accurate DC reference voltage to one of the digitizer's channels. Use the function parameters to indicate the voltage and channel. |
- SMC-Based Digitizers
For SMC-based digitizers, this function calibrates the range (that is, gain) accuracy of the entire device using the specified channel. The function must be called twice in the same session with two different stimulus values. The stimulus values should be several volts apart, but within ±4 V; the recommended values are +4.0 V and 0.0 V. The two calls should use the same channel—it is not necessary to repeat the procedure on the remaining channel. This function adjusts the gain and range calibration constants so that the digitizer reads exactly the correct difference between the two stimulus voltages. This calibrates the onboard voltage reference against the external voltage reference. Calibrating with a voltage difference instead of a single reading eliminates any error due to offset.
The new calibration constants for the digitizer take effect immediately for the duration of the external calibration session. The constants are written to the EEPROM if you call niScope_CalEnd with no errors and with action set to NISCOPE_VAL_ACTION_STORE.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle you obtain from niScope_CalStart. |
| channelName | ViConstString | The string name of the channel to calibrate. For more information, refer to Channel String Syntax |
| range | ViReal64 | The voltage range to calibrate. |
| stimulus | ViReal64 | The peak voltage of the applied signal. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalAdjustVCXO (ViSession sessionHandle, ViReal64 stimulusFreq);
|
Note Use this function only when following the device calibration procedure. |
|---|---|
| For SMC-based digitizers, this function calibrates the sample rate of the digitizer. The function adjusts the frequency of the oscillator (VCXO) that serves as the digitizer's onboard sample rate timebase. Check the calibration procedure specific to your device and set the value of the stimulusFreq parameter. Before calling this function, connect an accurate, stable reference signal to channel 0. (The channel used is not configurable.) The function adjusts frequency calibration constants until the digitizer exactly measures the frequency of the reference signal. The new calibration constants take effect immediately for the duration of the external calibration session. The constants are written to the EEPROM if you call niScope CalEnd with no errors and with action set to NISCOPE_VAL_CAL_ACTION_STORE. |
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle you obtain from niScope_CalStart. |
| stimulusFreq | ViReal64 | The frequency of the reference clock present on channel 0. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalChangePassword (ViSession sessionHandle, ViConstString oldPassword, ViConstString newPassword);
Verifies the old password against the one stored in the EEPROM. If the two match, the function stores the new password in the EEPROM. The password is stored as four characters, but shorter strings are acceptable. For most digitizers, the default password is the empty string (" "). For SMC-based digitizers, the default password is "NI". If you forget your password, call National Instruments for assistance.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle you obtain from niScope_CalStart. |
| oldPassword | ViConstString | The previous password is verified against what is stored in the EEPROM. |
| newPassword | ViConstString | The new password that is written to the EEPROM. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalEnd ( ViSession sessionHandle, ViInt32 action );
Closes an external calibration session. If action is set to NISCOPE_VAL_ACTION_ABORT, the session is closed and the new calibration constants are lost. Some devices may write to the EEPROM during calibration, in which case the Abort Calibration action restores the EEPROM to its original state. It is, therefore, very important to call niScope_CalEnd each time niScope_CalStart is called, even if an error occurs during calibration.
If action is set to NISCOPE_VAL_ACTION_STORE, the new calibration constants are stored in the EEPROM. For most digitizers, the current system date and the incremented calibration count are also stored; for SMC-based digitizers, the current system date and onboard temperature are stored.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle returned by niScope_CalStart. |
| action | ViInt32 | NISCOPE_VAL_CAL_ACTION_STORE or NISCOPE_VAL_CAL_ACTION_ABORT |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalFetchCount ( ViSession sessionHandle, ViInt32 whichOne, ViInt32* calibrationCount );
Returns the calibration count, which is the number of times the device has been calibrated.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle you obtain from niScope_CalStart or niScope_init. |
| whichOne | ViInt32 | Which type of calibration count to store: self-calibration or external calibration count. |
| Output | ||
| Name | Type | Description |
| calibrationCount | ViInt32* | The number of calibrations performed on this device. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalFetchDate (ViSession sessionHandle, ViInt32 whichOne, ViInt32* year, ViInt32* month, ViInt32* day);
Returns the last self-calibration, external calibration, or manufacture date.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle you obtain from niScope_CalStart or niScope_init. |
| whichOne | ViInt32 | The type of calibration for which the information is stored: self-calibration, external calibration, or manufacture date. |
| Output | ||
| Name | Type | Description |
| year | ViInt32* | The year of the last calibration, such as 2003. |
| month | ViInt32* | The month of the last calibration (1–12). |
| day | ViInt32* | The day of the last calibration (1–31). |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalFetchMiscInfo ( ViSession sessionHandle, ViChar* miscInfo );
Returns the miscellaneous information stored in the EEPROM using niScope_CalStoreMiscInfo.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle you obtain from niScope_CalStart or niScope_init. |
| Output | ||
| Name | Type | Description |
| miscInfo | ViChar* | 4 characters stored in the EEPROM. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalFetchTemperature (ViSession sessionHandle, ViInt32 whichOne, ViReal64* temperature);
For SMC-based digitizers, returns the onboard temperature of the digitizer at the time of the last self-calibration or external calibration, in degrees Celsius. The temperature returned by this function is an onboard temperature read from a sensor on the surface of the digitizer. This temperature should not be confused with the environmental temperature of the digitizer's surroundings. During operation, the onboard temperature is normally higher than the environmental temperature.
Temperature-sensitive parameters are calibrated during self-calibration. Therefore, the self-calibration temperature is usually the more important one to read.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle you obtain from niScope_CalStart. |
| whichOne | ViInt32 |
Defined Values NISCOPE_VAL_CAL_SELF NISCOPE_VAL_CAL_EXTERNAL |
| Output | ||
| Name | Type | Description |
| temperature | ViReal64* | The returned temperature of last calibration, in °C. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalMeasureRISDistribution (ViSession sessionHandle, ViConstString channelName, ViInt32 maxTime, ViReal64* minBinPercent, ViInt32 distributionSize, ViInt32* distribution);
Calls niScope_Read 2,000 times to take an acquisition from the specified channel and retrieve the initial X value, which includes the time-to-digital (TDC) conversion. The TDC should be a uniform distribution between two sample points because triggers should occur randomly. To test this distribution, the distribution of initial X values is created. The percentage of triggers in the smallest bin of this distribution is returned for comparison to a specification to determine if RIS is operating correctly. The distribution parameter must be declared as an array of distributionSize to return the distribution. Optionally, setting distribution to VI_NULL specifies that the distribution is not returned.
- Equivalent-Time Sampling and Random Interleaved Sampling
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle you obtain from niScope_CalStart or niScope_init. |
| channelName | ViConstString | The name of the channel to calibrate. For more information, refer to Channel String Syntax. |
| maxTime | ViInt32 | The maximum time in ms for each acquisition. |
| minBinPercent | ViReal64* | The percentage (0–1) of triggers in the least full bin. |
| Output | ||
| Name | Type | Description |
| distributionSize | ViInt32 | The number of bins for distribution. |
| distribution | ViInt32* | The array for distribution; use VI_NULL for do not return. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalSetAccessorySource ( ViSession sessionHandle, ViConstString channelName, ViInt32 calSource );
For the NI 5900, this function sets the calibration source for the device.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle returned by niScope_CalStart. |
| channelName | ViConstString | The string name of the channel to calibrate. For more information, refer to Channel String Syntax. |
| calSource | ViInt32 | The calibration signal souce. |
| Defined Values |
|---|
| NISCOPE_VAL_CAL_SOURCE_GROUND |
| NISCOPE_VAL_CAL_SOURCE_POSITIVEFS |
| NISCOPE_VAL_CAL_SOURCE_NEGATIVEFS |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalStart(ViRsrc resourceName, ViConstString password, ViSession* sessionHandle);
Opens an external calibration session and produces a calibration session handle that is required by the external calibration functions. All other calibration functions, such as verification and fetch VIs, work with both a calibration session and a session handle obtained from niScope_init. Acceptable session handles are documented for each function in the calibration procedure documents.
By default, the calibration password for the SMC-based digitizers is "NI". The password is stored in the EEPROM as an array of four characters. Nonprintable characters are allowed, but the array is padded with NULLs after the first NULL is found. This padding allows strings of less than four characters to be valid passwords. The password is verified against the password stored in the EEPROM. You can change the password from the default by calling niScope_CalChangePassword.
Only one session handle can be obtained at a time, and every session started with niScope_CalStart must be closed by calling niScope_CalEnd. If you fail to close the session, you must unload the niScope_32.dll by closing your application or application development environment (ADE) before you can open another session.
If an error occurs during calibration, call niScope_errorHandler to get the error message text. You can call niScope_CalEnd with action set to NISCOPE_VAL_CAL_ACTION_ABORT to end the session without updating the EEPROM. For SMC-based digitizers, the EEPROM is also not updated if an error occurs.
| Input | ||
|---|---|---|
| Name | Type | Description |
| resourceName | ViRsrc | The device number assigned by Measurement & Automation Explorer (MAX). |
| password | ViConstString | The password you use, which is verified against the password stored in the EEPROM. |
| Output | ||
| Name | Type | Description |
| sessionHandle | ViSession* | The returned session handle. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |
ViStatus _VI_FUNC niScope_CalStoreMiscInfo (ViSession sessionHandle, ViConstString miscInfo);
Stores miscellaneous information in the EEPROM. For example, you can store an operator ID for the person or company performing a calibration.
Four characters are stored in the EEPROM, and nonprintable characters are valid. However, NULL is treated as an end-of-string marker, and all characters following the first NULL are also set to NULL.
| Input | ||
|---|---|---|
| Name | Type | Description |
| sessionHandle | ViSession | The session handle you obtain from niScope_CalStart or niScope_init. |
| miscInfo | ViConstString | Pointer to 4 characters stored in the EEPROM; can be less than four if NULL terminated. |
| Name | Type | Description |
|---|---|---|
| Status | ViStatus | Reports the status of this operation. To obtain a text description of the status code, call niScope_GetErrorMessage. To obtain additional information concerning the error condition, use niScope_GetError and niScope_ClearError. The general meaning of the status code is as follows: |
| Value | Meaning |
|---|---|
| 0 | Success |
| Positive Values | Warnings |
| Negative Values | Errors |