ividev

Instrument connection using MATLAB driver

Since R2022a

Description

Use ividev to create a connection to an instrument using a MATLAB^® driver. After you create an ividev object, you can explore the instrument's attributes and capabilities by calling help on the object. Configure and communicate with the instrument by using its functions. To use the ividev interface, you must have the Instrument Control Toolbox™ Support Package for IVI^® and VXIplug&play Drivers. For more information, see Install Instrument Control Toolbox Support Package for IVI and VXIplug&play Drivers.

Creation

Syntax

dev = ividev(matlabDriver,resourceName)

dev = ividev(matlabDriverClassCompliant,logicalName)

dev = ividev(___,Name=Value)

Description

dev = ividev(matlabDriver,resourceName) connects to a physical instrument specified by the resource string resourceName and using the driver specified by the string matlabDriver. View a list of drivers and resource names using ividevlist.

All ividev objects have a common set of Properties. The rest of the properties are from the instrument. All the ividev object functions are also from the instrument. You can explore the ividev properties and object functions for your instrument by clicking the links in the object output display. You can also use the help function on the object.

dev = ividev(matlabDriverClassCompliant,logicalName) connects to a physical instrument specified by the logical name logicalName and using the IVI-C class-compliant driver specified by the string matlabDriverClassCompliant. View a list of class-compliant drivers using ividriverlist and define a logical name for your instrument using iviconfigurationstore.

This syntax is valid only for IVI-C class-compliant devices. You can use this syntax for your instrument if its driver is not supported by the Instrument Control Toolbox Support Package for IVI and VXIplug&play Drivers. For more information and an example, see Use IVI-C Class-Compliant Drivers.

dev = ividev(___,Name=Value) connects to the instrument and sets additional properties using optional name-value arguments using in addition to the input arguments in previous syntaxes.

Input Arguments

matlabDriver — MATLAB driver name

character vector | string scalar

MATLAB driver name, specified as a character vector or string scalar. You can identify the driver name using the information returned by ividriverlist or ividevlist.

resourceName — IVI-C or VXIplug&play resource name

character vector | string scalar

IVI-C or VXIplug&play resource name, specified as a character vector or string scalar. You can identify your instrument's resource name using the information returned by ividevlist. This input sets the Resource property.

If you are using either the NI-RFSA or NI-RFSG driver and do not see your instrument in the ividevlist output, you can identify its resource name from the NI™ Measurement and Automation Explorer (NI MAX) software.

matlabDriverClassCompliant — IVI-C class-compliant MATLAB driver name

character vector | string scalar

IVI-C class-compliant MATLAB driver name, specified as a character vector or string scalar. You can identify the IVI class for your instrument using the information returned by ividriverlist.

Possible values for this input are:

• IviScope

• IviFgen

• IviRFSigGen

• IviSpecAn

• IviDmm

• IviACPwr

• IviDCPwr

• IviCounter

• IviDigitizer

• IviPwrMeter

• IviSwtch

• IviDownconverter

• IviUpconverter

logicalName — Instrument logical name

character vector | string scalar

Instrument logical name, specified as a character vector or string scalar. Set up a logical name for your instrument using the IVI Configuration Store. You can configure the IVI Configuration Store using the iviconfigurationstore function or from the VISA vendor's configuration utility, such as Keysight Connection Expert of NI Measurement and Automation Explorer.

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.

Example: dev = ividev("tktds1k2k","",Simulate=true,ResetDevice=true) connects to a simulated tktds1k2k driver and uses DriverSetup to specify the simulated instrument model as TDS2024.

IDQuery — Instrument ID query

true (default) | false

Instrument ID query, specified as logical true or false. If this argument is true, the ividev function queries the instrument ID and checks that it is valid for the driver matlabDriver.

Example: dev = ividev("matlabDriver","resourceName",IDQuery=false) disables instrument ID query.

ResetDevice — Instrument reset

false (default) | true

Instrument reset, specified as logical false or true. If this argument is true, the ividev function resets the instrument to a known state.

If you adjusted the knobs on your instrument before connecting to it, you can read those values by connecting to the instrument with this argument set to false. However, if you want a known starting state, you can connect to the instrument with this argument set to true.

Example: dev = ividev("matlabDriver","resourceName",ResetDevice=true) resets the instrument to a known state.

Simulate — Simulation mode

false (default) | true

Simulation mode, specified as logical true or false. If this argument is true, the instrument runs in simulation mode.

In simulation mode, you do not need to have an instrument physically connected to your computer and you can specify resourceName as anything. You can specify additional parameters, such as a simulated instrument model, using the DriverSetup argument. Any data that you read from a simulated instrument are simulated values.

Example: dev = ividev("matlabDriver","",Simulate=true,DriverSetup="Model:2024") connects to a simulated instrument.

RangeCheck — Parameter value validation

true (default) | false

Parameter value validation, specified as true or false. If this argument is true, the instrument driver validates parameter values that you pass into driver functions. You can set this to false for improved performance.

Example: dev = ividev("matlabDriver","resourceName",RangeCheck=false) does not validate parameter values.

Cache — State caching

true (default) | false

State caching, specified as true or false. If this argument is true, the instrument driver caches attribute values to offer better performance by reducing I/O traffic.

Example: dev = ividev("matlabDriver","resourceName",Cache=false) turns off state caching.

QueryInstrStatus — Instrument error status check

true (default) | false

Instrument error status check, specified as true or false. If this argument is true, the instrument driver checks the instrument's error status after each operation. You can set this to false for improved performance.

Example: dev = ividev("matlabDriver","resourceName",QueryInstrStatus=false) does not check the instrument's error status.

InterchangeCheck — Interchangeability check

false (default) | true

Interchangeability check, specified as false or true. If this argument is true, the instrument driver keeps track of each interchangeability warning it encounters.

Example: dev = ividev("matlabDriver","resourceName",InterchangeCheck=true) keeps track of interchangeability warnings.

RecordCoercions — Value coercion record

false (default) | true

Value coercion record, specified as false or true. If this argument is true, the driver matlabDriver keeps a record of each value coercion. A value coercion is when you specify a value for a function that accepts a list of discrete inputs and the value is coerced to the closest discrete value.

Example: dev = ividev("matlabDriver","resourceName",RecordCoercions=true) keeps a record of each value coercion.

OptionString — Options string

string scalar

Options string, specified as a string scalar. Use this argument to specify instrument attribute values in the same format that you pass into InitWithOptions. Specify multiple attribute values by separating them with commas. You can copy the option string from your C code to use as the value for this argument.

For name-value arguments, you must specify them only as name-value arguments or using this argument. For example, you cannot enable simulation mode by using Simulate=true and OptionString="Simulate=true".

Example: dev = ividev("matlabDriver","resourceName",OptionString="Simulate=true,ResetDevice=true") turns simulation mode on with device reset.

DriverSetup — Driver settings

string scalar

Driver settings, specified as a string scalar. Use this argument to specify additional settings defined by the vendor driver. Refer to the vendor driver documentation for more information.

Example: dev = ividev("tktds1k2k","",Simulate=true,DriverSetup="Model:2024") connects to a simulated tktds1k2k driver and uses DriverSetup to specify the simulated instrument model as TDS2024.

Timeout — Allowed time to find and connect to instrument

30 (default) | numeric

Allowed time to find and connect to the instrument, specified as a numeric value. Use this property to specify a larger timeout value if your instrument does not connect within the default timeout period of 30 seconds.

Example: dev = ividev("matlabDriver","resourceName",Timeout=45) sets the connection timeout period to 45 seconds.

Data Types: double

Properties

Note

The following properties are common for all ividev objects. To see a full list of driver-specific properties, use the properties function. For example, properties(dev) returns a list of properties for the ividev object dev. You can also click the property links from the object output display.

Model — Instrument model

Read-only: string scalar

This property is read-only.

Instrument model, specified as a string scalar.

Data Types: string

Manufacturer — Instrument manufacturer

Read-only: string scalar

This property is read-only.

Instrument manufacturer, specified as a string scalar.

Data Types: string

SerialNumber — Serial number associated with instrument

Read-only: string scalar

This property is read-only.

Serial number associated with the instrument, specified as a string scalar.

Data Types: string

Resource — Resource name

Read-only: string scalar

This property is read-only.

Resource name, specified as a string scalar.

Data Types: string

VendorDriver — Vendor driver

Read-only: string scalar

This property is read-only.

Vendor driver, specified as a string scalar.

Data Types: string

Object Functions

The object functions for an ividev object are driver-specific. To see a full list of supported object functions, use the methods function. For example, methods(dev) returns a list of object functions for the ividev object dev. You can also click the link from Show all functions in the object output display.

Examples

Connect to IVI Instrument

View a list of installed drivers.

driverList = ividriverlist

driverList =

  15×4 table

             VendorDriver          MATLABDriver            IVIClass                                                       SupportedModels                                               
          __________________    __________________    __________________    ____________________________________________________________________________________________________________

    1     "AgInfiniiVision"     "AgInfiniiVision"     "IVIScope"            {["C7302"    "C7302C"    "C7304"    "C7304C"    "C7312"    "C7312C"    "C7314"    "C7314C"    …          ]}
    2     "IviACPwr"            "IviACPwr"            "IVIACPwr"            {[""                                                                                                      ]}
    3     "IviCounter"          "IviCounter"          "IVICounter"          {[""                                                                                                      ]}
    4     "IviDCPwr"            "IviDCPwr"            "IVIDCPwr"            {[""                                                                                                      ]}
    5     "IviDigitizer"        "IviDigitizer"        "IVIDigitizer"        {[""                                                                                                      ]}
    6     "IviDmm"              "IviDmm"              "IVIDmm"              {[""                                                                                                      ]}
    7     "IviDownconverter"    "IviDownconverter"    "IVIDownconverter"    {[""                                                                                                      ]}
    8     "IviFgen"             "IviFgen"             "IVIFgen"             {[""                                                                                                      ]}
    9     "IviPwrMeter"         "IviPwrMeter"         "IVIPwrMeter"         {[""                                                                                                      ]}
    10    "IviRfSigGen"         "IviRfSigGen"         "IVIRfSigGen"         {[""                                                                                                      ]}
    11    "IviScope"            "IviScope"            "IVIScope"            {[""                                                                                                      ]}
    12    "IviSpecAn"           "IviSpecAn"           "IVISpecAn"           {[""                                                                                                      ]}
    13    "IviSwtch"            "IviSwtch"            "IVISwtch"            {[""                                                                                                      ]}
    14    "IviUpconverter"      "IviUpconverter"      "IVIUpconverter"      {[""                                                                                                      ]}
    15    "tktds1k2k"           "tktds1k2k"           "IVIScope"            {["TB21042"    "TBS1022"    "TBS1032B"    "TBS1042"    "TBS1052B"    "TBS1052B-EDU"    "TBS1062"    …    ]}

View a list of physically connected instruments on your computer.

deviceList = ividevlist

deviceList =

  1×5 table

           MATLABDriver                     ResourceName                    VendorDriver          Model       SerialNumber
         _________________    ________________________________________    _________________    ___________    ____________

    1    "AgInfiniiVision"    "TCPIP0::152.90.186.165::hislip0::INSTR"    "AgInfiniiVision"    "DSOX1204A"    "CN59206154"

Create a connection to your instrument using ividev. In this example, connect to a Keysight^® DSOX1204A oscilloscope using the specified MATLAB driver AgInfiniiVision and resource name TCPIP0::152.90.186.165::hislip0::INSTR.

dev = ividev("AgInfiniiVision","TCPIP0::152.90.186.165::hislip0::INSTR")

dev = 

  AgInfiniiVision with properties:

                    Model: "DSOX1204A" 
             Manufacturer: "KEYSIGHT TECHNOLOGIES" 
             SerialNumber: "CN59206154" 
             ResourceName: "TCPIP0::152.90.186.165::hislip0::INSTR" 
             VendorDriver: "AgInfiniiVision" 
                 Simulate: 0 

               ChannelIDs: ["Channel1", "Channel2", "Channel3", "Channel4"] 
        DigitalChannelIDs: [] 
          MathFunctionIDs: ["Math1", "Math2"] 
           MeasurementIDs: ["Channel1", "Channel2", "Channel3", "Channel4", "FUNC", ... ] 
             SerialBusIDs: [] 
               WaveGenIDs: "WaveGen1" 

    InherentIVIAttributes: [1x1 InherentIVIAttributes] 
              Acquisition: [1x1 Acquisition] 
                  Channel: [1x4 Channel] 
       InstrumentSpecific: [1x1 InstrumentSpecific] 
                  Trigger: [1x1 Trigger] 
      WaveformMeasurement: [1x1 WaveformMeasurement] 

Show all functions

You can explore the instrument's attributes and capabilities by clicking the links from the object output display. Configure these properties using dot notation.

Connect to Simulated IVI Instrument

If you have an IVI-C or VXIplug&play driver installed, but do not have an instrument physically connected to your computer, you can create a simulated instrument using ividev.

View a list of installed drivers.

driverList = ividriverlist

driverList =

  15×4 table

             VendorDriver          MATLABDriver            IVIClass                                                       SupportedModels                                               
          __________________    __________________    __________________    ____________________________________________________________________________________________________________

    1     "AgInfiniiVision"     "AgInfiniiVision"     "IVIScope"            {["C7302"    "C7302C"    "C7304"    "C7304C"    "C7312"    "C7312C"    "C7314"    "C7314C"    …          ]}
    2     "IviACPwr"            "IviACPwr"            "IVIACPwr"            {[""                                                                                                      ]}
    3     "IviCounter"          "IviCounter"          "IVICounter"          {[""                                                                                                      ]}
    4     "IviDCPwr"            "IviDCPwr"            "IVIDCPwr"            {[""                                                                                                      ]}
    5     "IviDigitizer"        "IviDigitizer"        "IVIDigitizer"        {[""                                                                                                      ]}
    6     "IviDmm"              "IviDmm"              "IVIDmm"              {[""                                                                                                      ]}
    7     "IviDownconverter"    "IviDownconverter"    "IVIDownconverter"    {[""                                                                                                      ]}
    8     "IviFgen"             "IviFgen"             "IVIFgen"             {[""                                                                                                      ]}
    9     "IviPwrMeter"         "IviPwrMeter"         "IVIPwrMeter"         {[""                                                                                                      ]}
    10    "IviRfSigGen"         "IviRfSigGen"         "IVIRfSigGen"         {[""                                                                                                      ]}
    11    "IviScope"            "IviScope"            "IVIScope"            {[""                                                                                                      ]}
    12    "IviSpecAn"           "IviSpecAn"           "IVISpecAn"           {[""                                                                                                      ]}
    13    "IviSwtch"            "IviSwtch"            "IVISwtch"            {[""                                                                                                      ]}
    14    "IviUpconverter"      "IviUpconverter"      "IVIUpconverter"      {[""                                                                                                      ]}
    15    "tktds1k2k"           "tktds1k2k"           "IVIScope"            {["TB21042"    "TBS1022"    "TBS1032B"    "TBS1042"    "TBS1052B"    "TBS1052B-EDU"    "TBS1062"    …    ]}

For this example, create a simulated instrument using the tktds1k2k MATLAB driver.

Use the ividev function with the name-value argument Simulate. The resource name can be anything, such as an empty string, but it must still be specified.

dev = ividev("tktds1k2k","",Simulate=true)

dev = 

  tktds1k2k with properties:

                       Model: "TDS 1002" 
                Manufacturer: "TEKTRONIX" 
                SerialNumber: "" 
                ResourceName: "" 
                VendorDriver: "tktds1k2k" 
                    Simulate: 1 

                  ChannelIDs: ["CH1", "CH2", "MATH", "REFA", "REFB"] 
     PowerAnalysisChannelIDs: ["CH1", "CH2"] 

       InherentIVIAttributes: [1x1 InherentIVIAttributes] 
                 Acquisition: [1x1 Acquisition] 
                     Channel: [1x5 Channel] 
                  Triggering: [1x1 Triggering] 
         WaveformMeasurement: [1x1 WaveformMeasurement] 
                        Math: [1x1 Math] 
    PowerAnalysisApplication: [1x1 PowerAnalysisApplication] 
                 DataLogging: [1x1 DataLogging] 
                   LimitTest: [1x1 LimitTest] 
     MiscellaneousAttributes: [1x1 MiscellaneousAttributes] 

Show all functions
 

You can explore the simulated instrument's attributes and capabilities by clicking the links from the object output display. Configure these properties using dot notation.

Version History

Introduced in R2022a